From 1b58bf936477377d8b7c50d09872284b023eb0a5 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Wed, 18 Mar 2026 16:06:31 +0800 Subject: [PATCH] docs(10): capture phase context for proxy pool --- .planning/phases/10-proxy-pool/10-CONTEXT.md | 108 +++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 .planning/phases/10-proxy-pool/10-CONTEXT.md diff --git a/.planning/phases/10-proxy-pool/10-CONTEXT.md b/.planning/phases/10-proxy-pool/10-CONTEXT.md new file mode 100644 index 0000000..bf8de10 --- /dev/null +++ b/.planning/phases/10-proxy-pool/10-CONTEXT.md @@ -0,0 +1,108 @@ +# Phase 10: Proxy Pool (代理池管理) - Context + +**Gathered:** 2026-03-18 +**Status:** Ready for planning + + +## Phase Boundary + +建立代理池基础设施，支持多代理配置、自动轮换和健康检查。此阶段不涉及请求行为伪装（Phase 11）和验证码处理（Phase 12）。 + +核心能力： +- 从配置文件加载多个代理地址 +- 每次请求自动轮换代理 +- 代理健康检查（被动检测） +- 失效代理自动切换和恢复 + + + + +## Implementation Decisions + +### 代理池配置方式 +- **配置来源**: YAML 文件（`~/.kb_proxies.yaml`） +- **配置格式**: 简单 URL 列表，认证信息嵌入 URL + ```yaml + proxies: + - "http://user:pass@proxy1.example.com:8080" + - "http://proxy2.example.com:3128" + - "socks5://user:pass@proxy3.example.com:1080" + ``` +- **向后兼容**: 如果未配置代理池文件，自动回退到现有的 `HTTP_PROXY` 环境变量（单代理模式） +- **支持的协议**: HTTP、HTTPS、SOCKS5 + +### 轮换策略 +- **策略**: 顺序轮换（Round-Robin） +- **时机**: 每次请求自动轮换到下一个代理 +- **实现**: 维护一个索引指针，每次请求后递增并循环 + +### 健康检查机制 +- **检测方式**: 被动检测（请求失败时标记） +- **失效判断**: 连续 3 次请求失败后标记为失效 +- **失败类型**: 网络超时、连接失败、代理返回错误 + +### 失效代理处理 +- **策略**: 暂时移除 + 冷却恢复 +- **冷却时间**: 5 分钟后自动恢复到轮换池 +- **全失效处理**: 所有代理都失效时，回退到第一个代理继续尝试请求 + +### Claude's Discretion +- 冷却时间的具体实现方式（定时器 vs 惰性检查） +- 代理统计信息的记录格式（可选功能） +- 日志输出的详细程度 +- 失效代理的具体判断条件（HTTP 状态码范围） + + + + +## Specific Ideas + +- 配置文件示例: + ```yaml + # ~/.kb_proxies.yaml + proxies: + - "http://127.0.0.1:7890" # 本地代理 + - "http://user:pass@proxy.example.com:8080" # 带认证 + - "socks5://127.0.0.1:1080" # SOCKS5 + ``` +- 轮换实现: `current_index = (current_index + 1) % len(available_proxies)` +- 冷却检查: `if now() - proxy.failed_at > 300: proxy.available = True` + + + + +## Existing Code Insights + +### Reusable Assets +- `kb_workflow/crawler/config.py` — CrawlerConfig、ProxyConfig 类，已有单代理支持 +- `kb_workflow/crawler/config.py` — `to_playwright_format()` 方法，代理格式转换 +- `kb_workflow/crawler/zhihu_crawler.py` — ZhihuCrawler 类，使用代理配置 +- `kb_workflow/pipeline/config.py` — KBSettings 配置类，pydantic-settings 模式 + +### Established Patterns +- 配置管理: pydantic BaseModel + 环境变量 + YAML 文件 +- 浏览器代理: Playwright `browser.new_context(proxy=...)` +- 配置文件位置: `~/.kb_*` 命名约定 + +### Integration Points +- ProxyPool 类替换现有的单代理逻辑 +- CrawlerConfig 扩展支持代理池 +- ZhihuCrawler._start_browser_with_proxy() 改为从代理池获取代理 +- 配置文件加载: 启动时读取 `~/.kb_proxies.yaml` + + + + +## Deferred Ideas + +- **API 获取代理** — 从代理服务商 API 自动获取代理，推迟到后续版本 +- **加权轮换** — 根据代理质量/速度加权，推迟到后续版本 +- **代理统计面板** — 展示每个代理的成功率、响应时间，推迟到后续版本 +- **配置热加载** — 运行时检测配置文件变化并重新加载，推迟到后续版本 + + + +--- + +*Phase: 10-proxy-pool* +*Context gathered: 2026-03-18*