28 KiB
ProxyCat 使用手册
重要事项
- Python 需要 3.10 及以上（3.8 / 3.9 会在导入阶段直接报错）；Docker 镜像基于 Python 3.11。
- Releases 中为较为稳定的打包版本，不一定是最新。
- API 接口返回的内容按行解析：可一次给出多条代理地址，未写协议的行按 http 补全，格式非法的行会被跳过；需要为取回的地址统一附加账号密码时填写
proxy_username/proxy_password（两者都非空才生效）。 - 随仓库发布的
config/config.ini已按作者调优，个别项的取值与程序内置默认不同；本手册不重复逐项配置说明，每个键的含义、默认值、生效方式与权威参考见详细配置。
安装部署
源码部署
Windows 与 Mac：浏览器访问位于 Github 的源码存储库并下载：ProxyCat
Linux：通过 Git 方法拉取项目到本地
git clone https://github.com/honmashironeko/ProxyCat.git
安装 Python 依赖（需要 Python 3.10 及以上：源码大量使用运行时求值的 X | Y 联合类型注解，3.9 及更早版本会在导入阶段就报 TypeError）
pip install -r requirements.txt
# 或使用国内源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
进入 config 文件夹内找到 config.ini 配置文件，按照自己拥有的资源选择不同的代理服务器获取方法：
（1）如果您的代理服务器地址为固定的连接，不需要动态更换，可以使用本地 ip.txt 的方式提供，每行一条 协议://[账号:密码@]地址:端口，支持 http/https/socks5 三种代理服务器地址与账号密码校验，格式如下所示
socks5://neko:[email protected]:7890
https://neko:[email protected]:7890
http://neko:[email protected]:7890
socks5://127.0.0.1:7890
https://127.0.0.1:7890
http://127.0.0.1:7890
...
（2）如果您是通过 API 方式获取代理地址，在 config.ini 中把 proxy_source_mode 改为 api 并填写 api_proxy_url（配置后不再读取 ip.txt）；接口返回按行解析，需要统一为取回的地址附加账号密码时填写 proxy_username 与 proxy_password（两者都非空才生效）。
当您配置完成之后就可以运行工具了，两个入口的区别与选择见运行方式。
Docker 部署
Windows 可以下载 Docker 官方工具：Docker Desktop
Linux 可以通过清华大学源提供的脚本一键安装：清华大学安装脚本
安装完成后请先测试 docker、docker compose 是否安装成功。
Windows 与 Linux 进入 ProxyCat 文件夹下（在此之前请先根据源码部署一节完成 config.ini 的基本参数修改），运行以下命令进行部署：
# 进入 ProxyCat 文件夹中并构建镜像和启动容器
docker compose up -d --build
Compose 会构建镜像并启动容器，两个端口分别是：
| 端口 | 用途 |
|---|---|
1080 |
代理监听端口（HTTP 与 SOCKS5 共用） |
5001 |
Web 面板端口 |
三个目录通过 bind mount 挂到宿主，数据和配置不会随容器销毁而丢失：config/、logs/、modules/proxypool/data/。镜像自身不带 config.ini（构建时删除），首次启动会在挂载目录里生成它。
部署前必须知道的四件事
这四条都是先出症状、后找原因的典型，建议先看一遍：
1. 面板打不开，返回 401
面板页面本身也要校验 token，所以设置了 token 时必须带上 ?token= 才能打开。仓库自带的 config/config.ini 里 token 不是空的，直接访问 http://127.0.0.1:5001/ 会在跳转后得到 401。正确地址：
http://127.0.0.1:5001/?token=honmashironeko
这个 token 是公开在仓库里的，对外使用前请务必换掉：面板不提供 token 的编辑入口，请直接改 config.ini 的 [Server] token，改完约 1 秒内随热重载生效 —— 旧 token 随即失效，记得换用带上新 token 的地址打开。
2. 容器起来了，但写不进配置或日志
容器以非 root 用户运行，其 UID/GID 必须与宿主上 config/、logs/、modules/proxypool/data/ 三个目录的属主一致，否则容器内写不进去。原因是镜像里对挂载点的 chown 对宿主目录无效，而镜像自身又不带 config.ini（构建时删掉了），首启要在挂载目录里生成它。宿主 UID/GID 不是 1000 时，在同目录的 .env 里设置：
PUID=你的UID
PGID=你的GID
3. 重启后丢了最后一批数据
容器停止时应用需要排空写队列，stop_grace_period 已放宽到 60 秒。Docker 默认的 10 秒会被 SIGKILL，最后一批验证结果与访问记录会丢失。请不要改小它。
4. 改了 web_port 之后容器变成 unhealthy
健康检查是按 config.ini 里实际的 web_port 现读现探的，不是写死的 5001。所以改完端口必须重启进程，并同步 docker-compose.yml 里的端口映射。
Docker 常用命令
# 停止服务和启动服务
docker compose down
docker compose up -d
# 查看日志信息
docker compose logs -f proxycat
# 修改了 Dockerfile 或依赖后重新构建并启动
docker compose up -d --build
# docker 端口默认为 1080 和 5001，1080 为监听端口，5001 为 Web 面板
# 如需其他端口请对应修改端口映射并放行
哪些改动需要重启容器：只有 port / web_port 这类在服务启动时绑定的项需要重启 —— web_port 改了必须重启整个应用并同步 docker-compose.yml 里的端口映射；port 可以不动进程，在面板里重启一次代理服务即可按新端口生效。其余配置项无论是在面板里保存还是手工编辑 config.ini，都会由热重载生效，不需要重启容器（热加载的完整边界见运行方式）。
运行方式
项目有两个入口，按需要选一个：
| 入口 | 启动内容 | 适用场景 |
|---|---|---|
python app.py |
Web 面板 + 出口代理服务（+ 代理池，按来源自动启动） | 日常使用，推荐 |
python ProxyCat.py |
出口代理服务（+ 代理池，按来源自动启动），纯命令行、无面板 | 服务器上不需要面板时 |
命令行入口支持 -c 指定配置文件，默认读 config/config.ini：
python ProxyCat.py -c config/config.ini
# Windows 上命令名为 python，写成 python ProxyCat.py 即可
两个入口都会读取同一份 config.ini。命令行入口的 display_level（0-2）控制控制台详细程度：1 是带倒计时的进度条，2 会额外显示耗时与错误详情。在容器里进度条会换成周期性日志行，没有看到进度条不等于故障。
热加载的边界（容易踩）：
- 从面板保存的配置即时生效，两个入口都是。
- 手工编辑
config.ini时，两个入口都会重载[Server]段：app.py有后台线程按秒巡检配置文件，约 1 秒内生效；ProxyCat.py同样在状态轮询里发现改动后重载，倒计时模式下约 1 秒，loadbalance或非按时间轮换（interval为0）时最多约 5 秒。[Pool]段同样会热加载，两个入口都会在约 3 秒内生效。port与web_port只在服务启动时绑定：web_port改了必须重启整个应用（面板只在保存时给出告警）；port可以不动进程，在面板里重启一次代理服务即可按新端口生效。
面板使用
面板是一个单页，地址 http://127.0.0.1:5001/web（记得带 ?token=），左侧四个页签：
| 页签 | 在这里做什么 | 背后由什么支撑 |
|---|---|---|
| 代理配置 | 切换代理来源（本地 / API / 代理池）、改轮换模式与间隔、编辑本地代理列表、保存 API 凭据、调日志与统计开关；并发等调优项在「性能」与「高级选项」组里 | [Server] 段配置 |
| 代理池 | 见下方三个子视图 | [Pool] 段配置 + /api/pool/* |
| 访问控制 | 用户管理（出口认证账号）、IP 黑白名单与优先级、代理绕过白名单 | [Users] 段与 config/ 下的名单文件 |
| 运行日志 | 按类别看实时日志、浏览历史日志文件、看访问统计与访问明细 | logs/ 下的日志与两个统计库 |
「代理池」页签下有三个子视图：
| 子视图 | 在这里做什么 |
|---|---|
| 代理管理 | 看抓到的代理（协议 / 真实 IP / 归属地 / 延迟 / 健康分 / 匿名度）、按条件筛选、批量验证与删除、导入导出、手动触发插件抓取 |
| 池设置 | 调代理池自身的运行参数（验证并发与超时、抓取周期、自动重验证、自动清理、使用反馈、写队列） |
| 数据库维护 | 数据库统计与优化、备份列表与恢复、离线归属地库的更新与重算 |
下面逐页签展开。
代理配置
图中是「代理配置」页签：页头是服务控制（启动 / 停止 / 重启）、两个监听地址与代理状态；下面可在「本地代理 / API 代理 / 维护池代理」三种来源间切换，左侧是配置分组导航，右侧是当前分组的表单。截图选中的是「维护池代理」来源的「来源设置」组 —— 该组只显示当前来源用得上的字段。
配置项按用途分为七组：
- 来源设置：只显示当前来源用得上的字段；
- 监听端口：端口被占用时才需要改；
- 出口轮换：一个出口用多久、同时用几个；
- 可用性检测：什么样的代理能进池；
- 性能与并发：本机能同时扛多少请求；
- 日志与记录：记什么、留多久；
- 高级选项：需要理解内部机制的调优项集中在这里。
「来源设置」里的「远程代理池地址」（pool_remote_url）是取用接口，不是管理接口：它只对填写的地址发一次 GET，把响应体里的每一行解析成一个代理地址（例如 http://1.2.3.4:8080），不做任何管理操作；返回 404 表示暂时没有可用代理。留空则使用进程内的内置代理池；来源切到「维护池代理」而池没在跑时，会自动把它拉起来（见代理池使用）。
「出口轮换」组里的 mode 在两种来源下问的是两件不同的事：本地来源问「挑谁」——cycle 按清单顺序使用（忽略负载，前一条满了才用下一条）、loadbalance 谁压力小先用谁；API 与维护池来源问「什么时候换」——request（触发更换）排在列表前面，只在收到新任务时取货、换出口，没有任务时到期的出口直接移除、池子会空掉，下一个请求到达时才重新取货填满；continuous（持续更换）与有没有流量无关，后台按寿命主动换掉到期的并补满。切换来源时，若当前值不属于新来源那一组，会自动归一到该组的首项 —— api / pool 组归一到 request。两种更换节奏的取舍见常见问题 Q&A。
本地代理列表就在这个页签里编辑，保存即重载名册；列表下方的「检测代理」检测的是源清单（local 来源下即 ip.txt 里的全部条目），所以已经被停用的坏出口也查得到。
「性能与并发」组管本机能同时扛多少请求：全局并发上限是所有出口合计的上限，超出后在信号量上排队；单出口并发上限 0 表示不限，此时并发只受全局并发上限约束；设成非 0 后，总上游并发约等于 出口数 × 本值（仍受全局上限封顶）。截图里的提示「扩容只在单出口并发上限不为 0 时有意义」正是自动扩容的开关条件 —— 填 0 时不扩，但已经张开的膨胀状态照常收回。扩容与收回为什么看两个不同的数、放宽单出口额度为什么是最后手段，见上游出口与并发。
每个配置项的含义、默认值与生效方式（即时 / 需重启）以详细配置为准；面板表单本身带校验，保存即生效，推荐日常在这里修改。
代理池
代理管理
截图自上而下是：统计卡（代理总数 / 有效 / 失效 / 可用率）、插件管理表（每个插件的状态、抓取周期、上次与下次运行、重验证策略，以及「抓取」「测试地址」「重载」按钮）、带筛选的代理列表（协议、代理地址、真实 IP、地区、延迟、健康分、匿名度，右上角有导入 / 导出 / 复制取用链接）。
在这里可以：按协议 / 有效性 / 匿名度 / 来源筛选（还有高级筛选），对选中的代理批量验证与删除，导入与导出代理，手动触发插件抓取。列表里还提示了匿名度是实测还是推算 —— 拿不到回显证据的代理只能给推算值。
池设置
池设置按用途分为八组：数据库 / 代理验证 / 抓取插件 / 自动重新验证 / 自动清理 / 使用反馈 / 写入队列 / 日志，每个组内的调优项折叠在「高级选项」里。截图选中的是「数据库」组，管自动备份的开关、间隔（小时）与保留天数 —— 自动备份关掉后不再生成新备份，保留天数决定能恢复到多久以前。每个字段的说明以详细配置的 [Pool] 段落为准。
数据库维护
截图自上而下是：数据库统计（代理总数 / 有效 / 失效 / 数据库体积）与「优化数据库」按钮；历史备份列表（时间、大小，最新一份带「最新」标记），每份备份都能一键「恢复」；底部的归属地库 —— 显示离线库可用状态、数据文件与修改时间，以及「更新归属地库」与「重算归属地」两个动作。
- 「优化数据库」会重建数据库索引并压缩文件，期间写入会短暂等待；
- 「恢复」会用该备份覆盖当前数据库：代理池会先停止，恢复完成后自动重启；
- 归属地库离线可用时，中国城市级解析用纯真库（
qqwry.ipdb），其余用 GeoLite2（GeoLite2-City.mmdb）；「更新归属地库」需要联网下载（约 104MB，需数分钟），「重算归属地」则对存量记录重新解析，有待重算记录时才可用。
访问控制
截图分三块：左上「用户管理」列出出口认证账号（截图中是仓库自带的 k 与 neko 两个账号，可改密码与增删用户）；右上是 IP 访问控制的白名单与黑名单，底部下拉选择同时命中时的优先级，点「保存名单」落盘；下方是代理绕过白名单，命中的目标地址直连、不经过上游代理，支持通配符。
- 用户管理编辑的是
[Users]段（「账号 = 密码」一行一个）：账号表为空时代理不要求身份鉴别。程序内置默认没有[Users]段、不要求认证；仓库自带的config.ini里出厂账号是k = 123与neko = 123456，所以不带认证的请求会得到 407。请通过面板的用户管理修改账号 —— 手工编辑config.ini的[Users]段同样会随配置热重载生效（约 1 秒内）。 - 白名单 / 黑名单文件固定从
config/目录读取；同时命中时按ip_auth_priority（whitelist放行 /blacklist拦截）决定。 - 三份名单的文件名与匹配规则见详细配置。
运行日志
截图顶部是两排过滤：类别（全部 / 主程序 / 代理 / 访问 / 池）与级别（全部 / 重要 / 信息 / 警告 / 错误 / 严重错误）；右侧可切换实时日志与历史日志文件，以及自动刷新、跟随、导出、清除日志。日志列表中的每行带时间、级别与类别。
- 「访问」类别下有按代理汇总的访问统计与逐条访问明细，见日志与访问记录；
- 日志级别与访问日志是联动的：成功访问行是 INFO，级别调到 WARNING 及以上后访问日志里只会剩失败与错误，面板会就地给出提示；
- 历史文件回看、导出与清理都作用于
logs/下的日志文件。
语言切换按钮在侧边栏底部，它改的是服务端设置：切换后面板文案、接口错误文案、导出文件的表头都会一起变（命令行入口的控制台横幅只在启动时打印一次，不会跟着重印）。
代理池使用
什么时候启动
内置代理池只在真的要用它当代理来源时才启动，由 [Server] 的 proxy_source_mode 决定：
proxy_source_mode |
池是否随服务启动 |
|---|---|
pool（维护池） |
启动 |
local（本地文件） |
不启动 |
api（API 获取） |
不启动 |
配了 pool_remote_url（接入外部代理池）时也不启动 —— 那种情况根本不走进程内这一个。注意它是外部池的取用接口而不是管理接口，细节见代理配置。
用本地文件或 API 取代理时，池跑着只是白耗资源去联网抓取和验证代理，所以默认不起。如果在面板里把来源切换成「维护池代理」，而池当前没在跑，会自动把它拉起来；反过来切换走不会自动停，避免误停正在提供代理的池 —— 需要停的时候在「代理池」页签里手动停。
插件管理
抓取插件放进 modules/proxypool/plugins/ 后，重启池服务生效（目录只在池服务启动时扫描一次）；已在列表中的插件改了代码，可在面板「代理池 → 代理管理」的插件列表里点「重载」热加载，也可以在那里单独设置某个插件的抓取周期与检测地址。两条最容易踩的约定：
- 抓取失败必须抛出异常。返回空列表会被当作「抓取成功但这一轮没抓到」，于是错误被吞掉、调度周期照常推进，表现为永远抓不到东西。
- 插件的文件名（不含扩展名）就是它的标识，配置、调度与来源记录都用这个名字。
插件列表里还能为单个插件配置重验证策略，甚至「跳过入库验证，抓到就直接入库」——适合按请求计费、有效性由供应商保证的代理源；这类记录没有出口 IP、匿名度与健康分，建议同时关闭重验证，否则它仍会被定时检测并产生费用。完整的插件编写契约见代理池模块文档。
批量验证
- 代理管理页可对选中的代理执行「验证有效性」，工具栏另有「验证全部有效」「验证全部失效」「全面检测」三个批量动作。
- 验证强度分三档：
liveness只判通不通、identity补身份信息、full全量评估。面板上的批量验证可手选liveness/full，传auto表示仍按策略决定（identity不是批量接口的可选值）。 - 被使用反馈标记失效的代理会被列入下一轮自动重验证的候选，重验证测通后可用状态自动翻回来；不想等的话，也可以在「代理管理」里点「验证全部失效」立刻手动重验。
- 「检测代理」按钮检测的是源清单（local 来源下即
ip.txt里的全部条目），它和池内的批量验证是两回事。
导入导出
- 「导入」：粘贴要导入的代理地址，导入的代理会先逐个验证，只有确认可用的才会入库；归属地在入库后自动异步查询。
- 「导出」：导出范围与当前的筛选条件一致，导出前会提示将导出多少条。
- 「复制取用链接」：按当前筛选条件生成代理池的取用接口链接并复制到剪贴板，供外部程序或另一个 ProxyCat 实例按需取用代理。
数据库备份与恢复
- 池设置的「数据库」组控制自动备份：开关、备份间隔（小时）与备份保留（天）。
- 在「代理池 → 数据库维护」里可以看到历史备份列表（时间、大小），每份都能「恢复」：将用该备份覆盖当前数据库；代理池会先停止，恢复完成后自动重启。
- 需要立刻压缩数据库时点「优化数据库」：重建索引并压缩文件，期间写入会短暂等待。
日志与访问记录
四类日志文件
日志按用途分流到 logs/ 下的四个文件，互不混杂，各自按大小轮转：
| 文件 | 内容 |
|---|---|
logs/main.log |
主程序：启动、配置、面板地址、关闭 |
logs/access.log |
代理请求：时间、客户端、上游代理、目标域名、成败、耗时 |
logs/proxy.log |
代理生命周期：加载、切换、验证、重试 |
logs/error.log |
以上各类别中 ERROR 及以上的汇总，排障时先看这里 |
代理池自身的日志仍写在 modules/proxypool/logs/proxy_pool.log。
日志级别、单个文件大小上限与轮转保留份数等开关见详细配置。
访问日志怎么看
访问日志每行形如：
2026-09-14 20:03:31 - INFO - [成功] 客户端 127.0.0.1/neko 上游 socks5://1.2.3.4:1088 目标 www.example.com:443 CONNECT 235ms 状态 200
2026-09-14 20:03:19 - WARNING - [失败] 客户端 127.0.0.1/neko 上游 socks5://5.6.7.8:3128 目标 www.baidu.com:443 CONNECT 36080ms 状态 504 原因 Connection Timeout
上游代理地址中的密码一律以 *** 替代后落盘，不会记录明文凭据。
每行有三种结果，含义各不相同：
| 结果 | 含义 |
|---|---|
[成功] |
请求确实走通了（HTTPS 隧道要等上游有数据回来才算，仅写回 200 不算） |
[失败] |
这次请求失败，原因写在行尾 |
[中断] |
请求在没有得出成败结论前就结束（如客户端未发数据就断开、隧道双方都没传过数据、请求被取消），不计入成功率与失败率 |
状态 一栏是写回给客户端的 HTTP 状态码。注意它可能与结果不一致：[成功] 行记录的是上游原样返回的状态码，上游回 4xx/5xx 也会记为 [成功]；[中断] 行会保留已经写回的状态码（如 200），但结果既不算成功也不算失败；而隧道已建立但上游从不发送数据这类 [失败]，写日志时不再保留状态码，状态显示为 -。因此看结果列，不要只看状态码。
访问统计与明细
在「运行日志」页签切到「访问」类别时，下方会显示访问统计表。它按上游代理汇总，展开某个代理可以看到该代理访问过的每个域名：
出口地址 成功 失败 合计 成功率 最后访问 最后失败原因
▼ socks5://13.125.44.24:80 [4] 6 0 6 100% 2026-09-14 21:26:33 --
example.com 1 0 1 100% 2026-09-14 21:26:33 --
www.baidu.com 2 0 2 100% 2026-09-14 21:26:32 --
聚合键是「域名 × 上游代理」而不是只看域名 —— 同一个域名经不同代理访问的结果可能完全不同，只看域名会把「这个代理访问不了这个站」这条最有用的信息抹平。统计结果落 SQLite 持久化，重启后累计值不丢。
除汇总外还有逐条访问明细：每次代理请求一行，可按时间 / 上游 / 目标 / 结果过滤，并导出 CSV / JSON。
访问统计与访问明细的保留策略（域名统计保留 30 天、明细保留 7 天且上限 200000 行，0 表示不清理）等配置见详细配置。
常见问题 Q&A
Q：为什么运行后我的 XXX 工具代理还是没换？
A：ProxyCat 并不是全局代理工具，需要 XXX 工具支持使用代理，将流量发送到 ProxyCat 的本地监听端口才会经过代理池。
Q：为什么倒计时结束后代理没有更换？
A：出口到期后什么时候被换掉由来源与运行模式决定：API / 维护池来源的「持续更换」模式由后台按寿命主动换掉到期的出口，与有没有流量无关；本地来源与「触发更换」模式只在有流量经过时才处理到期的出口（空闲时到期的出口会被直接移除，池子在下一次请求到达时重新取货填满）。这样空闲时就不去联网取货，减少资源浪费，可以部署一次、长期可用。
Q：为什么我用 getip 方式获取代理地址的时候，首次运行会报 None，没有可用的代理地址？
A：为了防止资源浪费，通过 getip 获取的情况一般是付费购买静态短效 IP，运行就获取的话会浪费大量资源从而导致资金损耗，为避免这种情况发生，默认的「触发更换」模式首次运行不会主动获取，您只需要正常使用发包，ProxyCat 会自动获取并发送。（若在面板把模式切成「持续更换」，则与有没有流量无关，后台按寿命主动取货，启动后不久就会请求接口。）
Q：我自己有静态 IP 提供地址该怎么用？
A：固定不变的代理地址请按源码部署中的本地列表格式写进 config/ip.txt，并把 proxy_source_mode 设为 local，每行一条 协议://[账号:密码@]地址:端口；api_proxy_url 要填的是「按行返回代理地址的取用接口 URL」，直接填一条代理地址会被当成接口去请求而取不到代理。地址若由接口返回，需要统一附加账号密码时填写 proxy_username、proxy_password。（面板上这两项合成了一行「代理认证」，写成 用户名:密码 即可）
Q：为什么我会遇到 XXX 报错？为什么不能用？
A：可先看《排查手册》，无法修复的情况下可以找作者询问，提问前请先支付 50 元作为时间的购买费用，如果您的问题属于百度可查或手册中有的，费用将不会返还；如果属于工具 BUG 或功能建议，费用将全额返还并将您列入本项目的感谢名单中。（实在是太多人多在问一些非常简单且写在帮助中的问题，时间被极大的浪费了，同时有很多态度非常恶劣的人，这不是我所想要的）
Q：面板打不开，跳转后返回 401？
A：面板页面本身也要校验 token，设置了 token 时必须带上 ?token= 才能打开；仓库自带的 config.ini 里 token 是公开的默认值，对外使用前请改掉（面板没有 token 编辑入口，改文件后约 1 秒热重载生效，旧 token 随即失效）。详见部署前必须知道的四件事。
Q：改完配置需要重启吗？
A：只有 port / web_port 这类在服务启动时绑定的项需要重启（web_port 要重启整个应用并同步端口映射，port 在面板里重启一次代理服务即可）；其余配置项无论是在面板保存还是手工改 config.ini，都会热重载生效。完整边界见运行方式。
Q：把日志级别调高后，为什么访问日志里的成功记录不见了？
A：成功访问行是 INFO 级别，级别调到 WARNING 及以上会把它们一并过滤掉，访问日志里只剩失败与错误；面板在保存级别时会就地给出提示。要保留成功记录请把级别调回 INFO。