proxy-pool/docs/design/product-design.md

Proxy Pool 产品设计文案

1. 产品定位

Proxy Pool 把多个供应商的动态代理统一成一个可运营的资源系统。平台面对 两类不同使用方式：需要平台代转发流量的应用使用 Gateway；需要拿到真实 代理并自行建立连接的应用使用 Distribution API。

两类入口共享 Provider、健康、TTL 和路由配置，但资源分配语义不同：

• Gateway 只在一次请求或隧道生命周期内占用代理并发，结束后释放容量。
• Distribution 一旦返回代理，该代理即永久离开系统可分配池。

2. 目标用户

• 业务调用方：通过稳定入口使用代理，不感知供应商差异。
• 代理直提调用方：按协议、区域、运营商或 Upstream 条件独占提取。
• 平台管理员：管理 Provider、Routing、容量、健康和故障切换。
• SRE：依据低基数指标、管理面审计和运行手册进行容量与故障管理。

3. 核心价值

3.1 供应商差异收敛

Provider Adapter 负责请求格式、认证和响应解析。标准化后，Routing、健康、 容量和业务入口只依赖统一 Proxy 模型，不把供应商字段传入核心域。

3.2 高并发热路径隔离

Gateway Worker 只读取本地不可变快照并维护本地容量计数。供应商延迟、 数据库抖动和控制面重载不会成为每请求依赖。

3.3 明确的资源语义

系统区分“短时使用容量”和“一次性独占提取”。Extraction 只在 Redis 中短期 保存有界幂等结果，不向 PostgreSQL 写逐个 Proxy 的提取事实；系统不追踪 提取后的实际使用，也不存在归还接口。

4. 主要流程

4.1 Gateway 请求

1. 接入层完成认证、来源识别、限流和目标地址检查。
2. Routing 按配置顺序首条命中。
3. 若启用并携带粘性会话头，先在本 Worker 的有界缓存中按认证 Client、Routing 和会话标识查找仍符合当前快照的 Proxy。
4. Dispatcher 从本地快照筛选 Upstream、协议、标签、TTL 和健康条件；失效会话 自动清除并按常规策略重新选择。
5. 原子预留 Proxy 容量，建立到上游代理的连接。
6. 建连成功后转为 Active，并在需要时写入不超过 Proxy 可用期的会话绑定； 传输结束后释放，失败则取消预留并清除该绑定。
7. GET/HEAD 仅在响应提交前按策略重试；CONNECT 建立后不重放。

4.2 独占提取

1. 调用方提交数量、过滤条件和 fulfillment。
2. Controller 校验调用方限额、TTL、健康新鲜度及 Gateway 保留量。
3. 在一个 Redis Lua 脚本、Redis Function 或等价原子操作中筛选候选并执行 AVAILABLE -> EXTRACTED。
4. partial 尽量返回；allOrNothing 数量不足时零提取。
5. 响应返回代理 URL、expiresAt 和 remainingTtlSeconds。

4.3 Sequential 切换

Sequential 至少配置两个 Upstream，初始使用列表第一项。列表耗尽时默认 stop， 也可显式选择 loop 或 stayLast。

1. Provider 响应成功且解析成功，但合法候选为零，才累计 Empty。
2. 网络、认证、HTTP、模板或解析失败只计 Error。
3. 全部候选均重复时计 DuplicateOnly，并重置连续 Empty。
4. 达到阈值后，引用该 Upstream 的 Routing 原子前进一次。
5. 旧 Upstream 已有 Proxy 继续耗尽，不因切换被直接删除。

5. 失败体验

• 无候选时严格执行 Routing 的 reject、wait 或 direct，默认拒绝。
• Distribution 部分满足用 200 返回实际数量；全有或全无不足时返回冲突状态。
• Provider 故障进入退避，不让调用请求触发同步 Provider 获取。
• 快照版本断档时 Worker 保留最后一份完整快照并请求全量重同步。
• 控制面不可用时，现有 Worker 可在快照有效期内继续服务，停止接收新配置。

6. 容量目标与服务指标

• 集群峰值目标：100,000 QPS。
• Worker 副本数：

required_workers = ceil(peak_qps / (measured_worker_qps * target_utilization))
                   + failure_domain_spares

• measured_worker_qps 必须来自目标协议占比、代理 RTT、连接复用率和安全策略 均接近生产的压测。
• 设计阶段不承诺单 Worker QPS，也不以平均值替代 P95/P99 和错误率。

7. 首版范围

首版包含 HTTP 正向代理、HTTPS CONNECT、REST Distribution/Admin、Provider 适配、健康与生命周期、Sequential 等路由策略、PostgreSQL 管理面持久化、 Redis TTL 活动池和集群快照。SOCKS5、跨地域主动主动和高级成本优化保留扩展 边界。