从零开始：短效代理水池爬虫教程

这份教程写给第一次接触代理池、断点和 Codex skill 的用户。默认引导模式下，你不需要编写代码、JSON 或命令：用户负责回答和确认，Codex 负责创建文件、修改配置和运行校验。

1. 这个项目到底是什么

这个仓库包含一个 Codex skill。安装后，你可以在 Codex 中输入：

使用 $proxy-pool-web-crawler 帮我设计这个数据采集任务。

Codex 会读取 skill，按照固定流程协助你：

问清任务 → 测试一条链路 → 建立代理水池 → 保存断点
→ 定时检查 → 发现停滞 → 停止或恢复 → 完成审计

它不会自动知道所有网站的 HTML 结构。你或 Codex仍要为目标网站实现适配器，例如：

列表页 URL 怎样组成；
下一页在哪里；
详情 ID 怎样提取；
什么字段必须存在；
哪些响应代表删除，哪些代表失败。

2. 先认识 8 个词

词	大白话解释
代理 IP	由另一台网络节点代你发出请求
短效代理	只能使用几分钟，到期后必须更换的代理
TTL	一个代理大约还能活多久
水池	当前可用代理节点的集合
worker	同时执行请求的工作单元
pending	已发现但还没有成功闭合的任务
checkpoint	记录完成与未完成任务的断点
raw	未解析的原始响应，是复核数据的证据

再认识两个常用指标：

RPS：每秒完成多少次请求；
P95 延迟：95% 的请求都能在这个时间内完成。

3. 安装与检查

3.1 环境要求

Linux、macOS 或 Windows WSL；
Bash；
Python 3.10+；
Codex；
Git。

辅助工具只使用 Python 标准库，不需要 pip install。

3.2 安装

git clone https://github.com/VanZeng/proxy-pool-web-crawler-skill.git
cd proxy-pool-web-crawler-skill
bash install.sh

检查安装：

bash install.sh --check

如果目标位置已存在，脚本会拒绝覆盖。确认要更新后再运行：

bash install.sh --force

旧版本会自动移动到类似下面的备份目录：

~/.codex/skills/proxy-pool-web-crawler.backup-20260717T120000Z

3.3 验证仓库

python -m unittest discover -s tests -v

预期最后出现：

Ran 17 tests
OK

4. 让 Codex 逐步了解任务

安装后，在 Codex 中发送：

使用 $proxy-pool-web-crawler 帮我采集一个已授权的网站。
我是新手，请逐个问我，并替我生成和检查所有配置。

默认引导模式的分工很简单：

参与者	负责什么
你	用自己的话回答问题，确认目标和执行范围，在私密终端设置代理密钥
Codex	阅读工作区、解释术语、提出默认值、创建配置、运行校验、修正错误

Codex 每次只问一个最关键的问题，通常按下面顺序进行：

你获准采集哪个网站和哪些页面；
想得到哪些数据；
怎样才算“抓完整”；
页面是否需要登录，列表和详情怎样关联；
代理套餐的协议、每次提取数量、有效期、频率、并发和白名单；
输出保存位置和哪些情况必须停止。

你可以直接回答“不知道”。对于低风险设置，Codex 应给出推荐默认值；对于代理套餐参数，它应告诉你去套餐页找哪个字段；工作区中已经存在的信息则由它自己读取。

5. 让 Codex 自动创建配置

信息足够后，Codex 先展示一张中文确认卡，例如：

目标与授权：商品列表和详情，不采集用户信息
完整标准：每个列表商品都有详情或明确终态
代理套餐：HTTP，每次 10 个，有效期 1～5 分钟
输出位置：/absolute/path/to/output
停止条件：60 秒无有效数据且失败样本达到阈值
下一步：创建任务契约并做本地校验，暂不联网

你确认后，Codex 应自行完成：

在工作区创建或更新 task-spec.json；
只写代理环境变量名，不写 API、用户名或密码；
运行 validate_spec.py；
根据报错自行修正并重新校验；
告诉你配置路径、关键设置和校验结果。

你不需要编辑 JSON，也不需要运行校验命令。若 Codex 把 JSON 模板或错误信息发给你并要求你自己修改，可以直接回复：

请继续使用小白引导模式。配置文件和校验由你完成，我只回答需要人工确认的问题。

唯一需要你亲自做的私密操作

Codex 会给出一行完整命令，让你在私密终端输入代理提取 API，并从同一环境启动爬虫。输入不会显示在屏幕上：

read -rsp "请输入代理提取 API：" PROXY_PROVIDER_URL; export PROXY_PROVIDER_URL; echo
# 下一行粘贴 Codex 给你的真实爬虫启动命令

另一种方式是先设置变量，再从同一个终端重新启动 Codex。在另一个终端执行 export 不会改变已经运行的 Codex。完成后只回复“已按命令启动”，不要把真实值粘贴回聊天。

高级用户：查看手动任务契约方式

只有明确选择手动模式时，才复制并编辑示例：

cp examples/task-spec.example.json task-spec.json
python proxy-pool-web-crawler/scripts/validate_spec.py task-spec.json

任务契约包含目标与完整性、代理套餐限制以及运行停止条件，但只能保存秘密对应的环境变量名。

6. 第一次 smoke test

smoke test 是“小规模证明流程能跑通”，不是正式采集结果。

建议严格按下面顺序：

6.1 直连基线

保存一个可信的直连响应样本，记录：

HTTP 状态；
最终 URL；
正文长度；
对象 ID；
页面或 JSON 的稳定结构；
必填字段和对象数量。

6.2 单代理测试

用一个代理访问同一个 URL。代理响应应满足与直连相同的业务契约。代理返回 200 但正文更短、跳到登录页或解析为零，都算失败。

6.3 小批代理测试

提取一个小批次，例如 10 个，分别记录：

完整成功 / 连接失败 / TLS 失败 / 超时 / 截断 / 业务拒绝

不要根据一个成功节点直接推断整个套餐都可用。

6.4 一条完整提交

一条 accepted 数据应在同一事务中关联：

任务 ID + raw 路径 + 解析结果 + checkpoint 状态

6.5 中断恢复

主动在小样本运行中停止一次，再恢复。确认：

done 不会重新抓；
in-flight 会恢复为 pending；
没有双写和重复唯一键；
raw 仍能回连。

7. 正式运行与监控

7.1 为什么用 tmux

预计超过 5 分钟的任务应放在 tmux 或等价的长任务管理器中。断开 SSH 后进程仍能运行，用户也能重新进入查看。

通用示例：

tmux new-session -s crawler

在 tmux 中启动你的爬虫；按 Ctrl-b，再按 d 离开，不会停止任务。

重新进入：

tmux attach -t crawler

7.2 每次巡检看什么

每 10–60 秒检查：

精确 crawler 进程是否存在；
accepted/done 是否增长；
pending 是否下降；
checkpoint 是否可读；
新 accepted 是否有关联 raw；
代理池的 healthy、leased、in-flight 和 target；
P50/P95、超时、TLS、内容拒绝和 HTTP 状态分布。

7.3 一次只调一个参数

不要同时提高并发、缩短间隔、降低超时和扩池。否则速度变化后无法判断是哪一个参数造成的。

推荐顺序：

先测 P95 和完整响应率；
调整请求超时；
调整 worker；
再调整水池目标和补水低水位；
观察至少一个节点寿命周期。

8. 出错了怎么查

情况 A：状态是 running，数据不增长

检查顺序：

精确工作进程，而不是 monitor 是否存在；
updated_at 是否陈旧；
accepted 和 pending 的前后快照；
补水线程是否还在；
失败是否集中在一个类型；
SQLite integrity_check；
最后一个真实错误和原响应。

情况 B：电脑直连成功，代理失败

对同一个 URL 比较：

直连状态 / 代理状态
直连最终 URL / 代理最终 URL
直连正文长度 / 代理正文长度
直连对象 ID / 代理对象 ID

如果大量代理都是 TLS、CONNECT 或截断失败，问题在代理传输能力或目标对代理出口的差异，不是白名单本身。

情况 C：healthy=0

检查：

代理协议是否写对；
当前机器公网出口是否在白名单；
提取接口是否返回合法节点；
节点是否已经过期；
真实预检 URL 是否要求 Cookie 或会话；
供应商区域是否能访问目标。

启动等待必须有上限，不能无限提取。

情况 D：只剩少量任务时卡住

这叫“尾部问题”。此时应：

停止旧大池和旧租约；
确认 in-flight 已恢复为 pending；
用一个真实剩余 URL 预检；
缩小池和 worker；
根据尾部 P95 调整超时；
最多自动切换一次，再次停滞则停止。

情况 E：反复出现同一个 401/404

不要直接把它们全部标成删除。终态必须事先写进任务契约，并使用多个独立路由或可信基线交叉确认。保存每个对象的原始响应；只要有一个实际业务响应不一致，就否决整批终态化。

9. 怎样确认数据能用

报告完成前至少检查：

pending=0、in_flight=0；
done = accepted + terminal_rejected；
total = done + pending + failed + in_flight；
checkpoint 完整性正常；
accepted 均有 raw，文件存在且可解压；
唯一键无重复，父子关系无孤儿；
页码或游标连续；
终态拒绝有原因和原响应；
日志没有密钥、Cookie、完整代理地址和带凭据 URL；
从断点重新汇总后统计一致。

最终报告要分别写清：

业务接受多少条
终态拒绝多少条
仍未完成多少条
平台实际可访问窗口是什么
输出和复现命令在哪里

10. 下一步学什么

完成第一次 smoke test 后，再阅读：

如果你只想让 Codex 帮忙，记住最重要的一句话：

先证明一条完整链路，再扩大；只看有效数据增量，不看进程是否活着。

FilesExpand file tree

getting-started.zh-CN.md

Latest commit

History