用户数据文件
4.0.1 将可变数据放在操作系统的当前用户目录，而不是源码目录或安装包内部。目录由 platformdirs 按平台确定；Windows 的配置通常位于 %APPDATA%\Kder\PyProxySwitch。
| 文件 | 用途 |
|---|---|
PPS.conf | JSON 格式的程序设置 |
proxy.txt | UTF-8 上游代理列表 |
PyProxySwitch.log | 轮转日志；默认位于平台用户日志目录，也可自定义 |
首次运行只创建缺失文件，不覆盖已有配置。程序保存设置与代理列表时使用原子替换，降低写入中断造成文件损坏的风险。
PPS.conf
{
"CONNECT_TIMEOUT": 15,
"DEBUG": 0,
"DEFAULT_ITEM": "NoProxy",
"LANG": "zh_CN",
"LAST_ITEM": "NoProxy",
"LOCAL_ADDRESS": "127.0.0.1",
"LOCAL_PORT": 8888,
"LOG_PATH": "",
"SHOW_WELCOME": 0
}| 配置项 | 说明 |
|---|---|
LOCAL_ADDRESS | 本地监听地址，默认为仅本机可访问的 127.0.0.1 |
LOCAL_PORT | 本地入口端口，范围 1–65535；修改端口需要重新绑定监听套接字 |
CONNECT_TIMEOUT | 建立目标或上游连接的超时秒数，必须大于 0 |
DEFAULT_ITEM / LAST_ITEM | 默认选择和上次选择的代理名称 |
LANG | zh_CN 或 en |
DEBUG | 设为 1 时启用更详细的控制台调试输出 |
LOG_PATH | 空字符串使用平台默认日志目录；也可指定自定义目录 |
proxy.txt
# name address:port [username:password] [HTTP|SOCKS4|SOCKS5]
home proxy.example.com:8080
auth proxy.example.com:3128 alice:secret HTTP
socks socks.example.com:1080 SOCKS5- 代理名称必须唯一，且不能使用
NoProxy、Default、System或None等保留名。 - 端口必须为 1–65535；无效行会被跳过并写入警告日志。
- SOCKS5 认证必须同时提供用户名和密码，每项 UTF-8 编码不超过 255 字节。
- SOCKS4 的“用户名”作为 user ID 使用；HTTP 认证使用 Basic 方式。
监听地址与安全
将 LOCAL_ADDRESS 改为 0.0.0.0 或局域网地址，会让其他设备有机会访问本地代理。PyProxySwitch 的本地入口没有客户端认证或访问控制；仅在受信网络中使用，并通过主机防火墙限制来源。
修改上游代理不会重启监听器；修改 LOCAL_PORT 则必须重新绑定。如果新端口不可用，界面会恢复原配置并报告错误。
连接与转发行为
- 代理核心在独立后台线程的单个 asyncio 事件循环中运行。
- HTTPS CONNECT 与 SOCKS 连接采用双向 TCP 隧道，并使用传输层背压。
- 普通明文 HTTP 请求会显式使用
Connection: close，避免跨主机复用同一代理连接造成错误。 - 上游热切换只影响新连接，保证已建立会话的路由不会中途改变。
日志与排障
日志文件名为 PyProxySwitch.log，单文件最大 5 MiB，保留 3 个轮转备份。连接失败、无效代理行、端口占用和配置写入失败都会记录。临时排障可用：
pyproxyswitch --log-level DEBUG