用户数据文件
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、::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
legacy socks4.example.com:1080 alice: SOCKS4- 代理名称必须唯一，且不能使用
NoProxy、Default、System或None等保留名。 - 端口必须为 1–65535 的整数；小数端口不会再被静默截断，无效行会被跳过并写入警告日志。
- SOCKS5 认证必须同时提供用户名和密码，每项 UTF-8 编码不超过 255 字节。
- SOCKS4 的“用户名”作为 User ID 使用，不支持密码；HTTP 认证使用 Basic 方式，不受 SOCKS5 帧字段的 255 字节上限约束。
监听地址与安全
PyProxySwitch 的本地入口没有客户端认证或访问控制，应用因此拒绝 0.0.0.0、局域网地址和其他非回环监听配置。若需要跨设备共享，请在外部部署具备认证与来源 ACL 的代理入口，不要尝试直接开放本地端口。
修改上游代理不会重启监听器；修改 LOCAL_PORT 则必须重新绑定。如果新端口不可用，界面会恢复原配置并报告错误。
连接与转发行为
- 代理核心在独立后台线程的单个 asyncio 事件循环中运行，按方向使用 64 KiB 分块和 512 KiB 写缓冲高水位。
- HTTPS CONNECT 与 SOCKS 连接采用双向 TCP 隧道，并使用传输层背压。
- 通过 SOCKS4/5 上游建立 SOCKS 隧道时，上游返回的绑定地址和端口会透传给本地客户端。
- 普通明文 HTTP 请求会显式使用
Connection: close，避免跨主机复用同一代理连接造成错误。 - Windows Python 3.14 使用 SelectorEventLoop 并将有效连接上限限制为 200；其他支持环境保持默认事件循环和 512 上限。
- 上游热切换只影响新连接，保证已建立会话的路由不会中途改变。
日志与排障
日志文件名为 PyProxySwitch.log，单文件最大 5 MiB，保留 3 个轮转备份。连接失败、无效代理行、端口占用和配置写入失败都会记录。临时排障可用：
python -m pyproxyswitch --log-level DEBUG