# Proxy Pool 总体架构设计 ## 1. 范围 Proxy Pool 是多供应商代理聚合平台，同时提供： - **Gateway**：接受 HTTP/HTTPS CONNECT 请求，选择上游代理并代转发。 - **Distribution API**：一次性独占发放真实代理地址，发放后不再管理其使用。 - **Admin API**：查询状态、启停 Upstream、切换 Routing、触发重载。 - **Control Plane**：Provider 获取、健康、生命周期、容量、切换、持久化与分发。 首要容量目标是集群峰值 100,000 QPS。该数字是设计目标，必须通过后续 容量测试证明，不能由文档直接宣称实现。 ## 2. 选择的方案 采用“独立数据面 + 集中控制面 + 独立健康执行器”： ```mermaid flowchart LR C[Clients] --> LB[HAProxy / Envoy / LVS] LB --> G1[Gateway Worker] LB --> GN[Gateway Worker N] G1 --> PX[Owned Proxies] GN --> PX E[Extract Clients] --> D[Distribution API] A[Operators] --> ADM[Admin API] D --> CP[Controller] ADM --> CP CP --> PG[(PostgreSQL)] CP --> R[(Redis)] CP --> F[Provider APIs] CP --> CK[Checker Workers] CP --> G1 CP --> GN ``` ### 2.1 为什么不用单体 Provider、数据库和健康探测是不可控 I/O。把它们和 Gateway 放在一个进程， 会让供应商抖动、配置重载和数据库故障直接污染 100k QPS 热路径。 ### 2.2 为什么不全面微服务化 Provider、Pool、Routing、Distribution 在首版需要共享事务和一致性规则。 先保持 Controller 模块化单体，避免提前引入事件顺序和分布式事务；Checker 因负载特征不同独立扩缩，Gateway 因热路径独立部署。 ## 3. 进程与职责 ### 3.1 proxy-gateway - Client 认证、CIDR 访问控制和租户限流。 - HTTP 正向代理与 HTTPS CONNECT。 - 首条命中 Routing、Upstream 选择和 Proxy least-connections 选择。 - 本地原子容量预留、建连、Active 计数和结果上报。 - 本地不可变 Snapshot；热路径无数据库/Redis/Provider API。 - 独立的控制面 SessionSupervisor；快照流到期或中断后以有界退避重建会话。 - SSRF 与 DNS Rebinding 防护。 ### 3.2 proxy-controller - 配置加载、校验、热更新和版本管理。 - Upstream/Provider fetch Leader、独立限流、singleflight 和退避。 - Proxy 解析、去重、TTL、状态机、pool.maxSize 与 fetch.maxTotal。 - Routing Sequential 当前选择和原子切换。 - Worker 所有权/容量切片、Snapshot 发布、ACK 和重同步。 - Distribution 与 Admin HTTP 接口。 - PostgreSQL 管理面持久化和 Redis TTL 活动池。 ### 3.3 proxy-checker - 消费检查任务，执行基础连接、出口和目标级探测。 - 使用 jitter、maxInFlight、超时和分级复检。 - 只上报 Observation，不直接修改最终状态。 - Controller 的确定性 reducer 根据 Observation 更新状态。 ### 3.4 proxy-loadgen - 当前实现 HTTP 请求场景：固定请求数或固定时长，受限并发与可选目标 QPS；可配置方法、 重复请求头和请求体。HTTPS 目标经 HTTP Gateway 时由 Transport 走 CONNECT。 - 输出场景、延迟分位上界、错误分类、吞吐和 Go 内存/GC 快照。CONNECT 长连接、 Extract 并发、进程 CPU/RSS/句柄与网络采样仍需补齐。 ## 4. 模块边界 ```text domain/ proxy Proxy、状态机、TTL、唯一键、容量 routing 规则、匹配、策略与 Sequential 状态 upstream Provider 能力、Fetch 分类与 Pool 需求 activitypool 短效 Proxy、TTL、所有权和独占消费 extraction 独占提取命令与结果 client 认证主体、权限与限制 gateway/ ingress HTTP/CONNECT 接入 dispatch Routing、Proxy 选择、容量预留、重试资格 transport 上游连接复用、握手、隧道和失败阶段 snapshot 版本校验、后台构建和原子切换 controller/ provider Fetch 计划、限流、singleflight、错误分类 pool Pool reconcile、生命周期和所有权 health 任务计划和 Observation reducer routing Sequential 原子切换和恢复 extraction Redis 活动池批量原子提取与短期幂等 distribution Worker 注册、Snapshot/Delta 与结果上报 adapters/ postgres, redis, grpc, http, provider_template ``` 领域模块不导入 HTTP、gRPC、SQL、Redis 或模板引擎。Adapter 依赖领域接口， 进程装配只发生在 `cmd`。 ## 5. Proxy 模型 ```go type Proxy struct { ID ProxyID Scheme Scheme Host string Port uint16 Username string CredentialVersion string SecretRef string SourceUpstream UpstreamID CreatedAt time.Time ExpiresAt *time.Time UsableUntil *time.Time LastCheckedAt *time.Time LastSuccessAt *time.Time Latency time.Duration MaxConcurrency int64 State ProxyState Tags map[string]string } ``` 密码不参与日志可见唯一键；`CredentialVersion` 区分同一用户名的凭据轮换。 唯一键不包含 Upstream：多个供应商返回同一唯一键时，当前生命周期的首个来源 保持归属，其他来源只计重复且不得覆盖 TTL；原来源硬过期淘汰后可重新归属。 运行态 `active` 与 `reserved` 存在 Worker 本地、按 Proxy ID 分片，不写入 不可变 Snapshot。 Worker 以有界周期批量上报运行态，而不是在每个 Gateway 请求上写 Redis。 报告通过公用 `workerruntime` seam 表达为完整稀疏替换：Gateway 从打包原子计数 读取同一时刻的 Active/Reserved；已从当前 Snapshot 移除但仍有连接的 Proxy 继续以 draining 状态上报。Controller 使用 session、单调 report sequence、 ownership epoch、Controller 已 ACK 的 snapshot/epoch 上界和 Redis 服务端 TTL 共同校验；缺失、过期或超前报告按零可用容量 fail-closed。运行态报告扫描有界 当前 Snapshot，并以分片索引补充已移除但仍非零的 runtime；移除 Proxy 会先停止新 预留，Active/Reserved 归零后在后续 Snapshot Apply 回收历史 Capacity。注册表仍有 硬上限，避免短 TTL Proxy 持续轮换导致心跳扫描与内存无界增长。 ## 6. Proxy 状态机 ```mermaid stateDiagram-v2 [*] --> FETCHED FETCHED --> CHECKING CHECKING --> AVAILABLE: basic check passed CHECKING --> UNHEALTHY: check exhausted AVAILABLE --> SUSPECT: first meaningful failure SUSPECT --> AVAILABLE: recheck passed SUSPECT --> UNHEALTHY: consecutive failures AVAILABLE --> DRAINING: TTL margin / disable / ownership revoke DRAINING --> EXPIRED: no active or reserved capacity AVAILABLE --> EXTRACTED: atomic exclusive extraction UNHEALTHY --> REMOVED EXTRACTED --> EXPIRED: expires EXPIRED --> REMOVED ``` `ACTIVE` 与 `BUSY` 不是持久状态，而是容量计数。一个 AVAILABLE Proxy 可以 同时承载多个 Gateway 请求，直到有效并发上限。 ## 7. Gateway 热路径 ```mermaid sequenceDiagram participant C as Client participant G as Gateway participant D as Dispatch participant T as Transport participant P as Upstream Proxy C->>G: HTTP / CONNECT G->>G: auth + access + admission G->>D: RouteRequest D->>D: first-match route + local candidate filter D->>D: CAS reserved +1 D-->>G: Allocation G->>T: execute allocation T->>P: dial / proxy handshake alt connected T->>D: reserved -1, active +1 T-->>C: response / tunnel T->>D: active -1 + outcome else failed before commit T->>D: reserved -1 + failure G->>D: optional safe retry with exclusion end ``` ### 7.1 Dispatch 接口 ```go type Dispatcher interface { Acquire(context.Context, RouteRequest) (*Allocation, error) Commit(*Allocation) error Release(*Allocation, Outcome) } ``` 不变量： - `Acquire` 只读本地 Snapshot 与本地分片运行态。 - `Allocation` 创建前必须 CAS 预留成功。 - Commit 将 Reserved 恰好一次转换为 Active。 - 未 Commit 的失败释放 Reserved；已 Commit 的结束释放 Active。 - Release 重复调用安全但产生错误指标。 ### 7.2 重试提交点 - HTTP：响应头写给 Client 前可按方法与失败阶段重试。 - CONNECT：上游 CONNECT 成功且向 Client 写 200 后不可重试。 - GET/HEAD 默认最多尝试 2 个不同 Proxy。 - POST/PUT/PATCH/DELETE 默认不自动重试。 ## 8. Provider Fetch ```mermaid flowchart TD S[Capacity signal] --> SF{singleflight running?} SF -->|yes| W[Coalesce signal] SF -->|no| R[Read current demand] R --> L[Acquire Provider leader] L --> C{Below refill target and under maxSize/maxTotal?} C -->|no| X[Stop] C -->|yes| I[Wait requestInterval] I --> M[Acquire maxInFlight] M --> API[Call Provider API] API --> CL{Classify} CL -->|error| BO[Backoff + fetchErrorCount] CL -->|empty| EC[emptyCount++] CL -->|valid| DD[Deduplicate + reset empty] DD --> HC[Create FETCHED and schedule check] ``` 每个 Upstream 的 Leader、最小请求间隔和在途 Permit 由同一个 Redis 原子协调 模块维护。Leader 租约使用 generation + 单调 epoch fence；Redis 状态整体丢失后 生成新 generation 并重新竞选。任何续租不确定、记录损坏或 Redis 断连均 fail-closed，不回退为本地 Leader。补池使用 minimum/target 双水位迟滞，库存 复核期间若仍有 pending Fetch，则等待下一轮再同步 Managed，避免重复计数。 Controller Bootstrap 通过 `Provider Supervisor` 按权威配置和 PostgreSQL 管理状态 维护每个 Upstream 的独立 `UpstreamRuntime`，再与 HTTP Runtime 通过公用 lifecycle Group 联动启动、取消和等待。Admin disable 会通知 Supervisor 取消对应 Runtime； reload 在提交前预检新 Runtime，并在发布后逐个取消、替换或新增。低频对账用于修复 丢失通知。每个 Leader 任期重新创建本地补池预算与合并信号；Redis 是 requestInterval、maxInFlight 和 maxTotal 的唯一分布式裁决者。本地预算只负责 pool.maxSize。 maxTotal 使用 Redis generation 内的累计值与 pending expected 原子预留。调用结果 不确定、解析失败或结算丢失时按 expected 保守记账，换主后旧 Permit 仍可幂等结算。 如果 Provider 单次实际返回量超过 `estimatedIPsPerCall`，账本按实际合法数量记账并 停止后续调用，但该次可能越过停止阈值；严格硬封顶需要 Provider API 支持可控批量。 响应中携带的代理凭据先进入有界内存凭据表，Redis Activity Adapter 复制凭据材料 进入 TTL 活动记录后立即按版本 fence 释放临时引用；解析中途失败也会回收已写引用。 因此短 TTL、持续轮换的新代理地址不会耗尽启动时的凭据容量。Provider 结果只记录 每个 Upstream 的低基数 Empty/Error 计数，不保留响应体、代理地址或错误对象。 补池读取 `pool.InventoryReader` 返回的权威 `Managed` 与 `AvailableSlots`，不使用 AVAILABLE Proxy 数量乘固定并发的近似值。Available Slots 同时计入 Proxy 状态、 TTL safety margin、MaxConcurrency、Worker Active/Reserved 和当前 ownership； 未知 Worker 运行态贡献零槽位。Redis 只扫描目标 Upstream 的未分配/已分配 AVAILABLE 索引，Managed 读取已有权威计数；该读取属于 Controller 冷路径， Gateway 热路径仍只访问本地 Snapshot 和本地原子计数。 ### 8.1 Empty、Duplicate 与 Error - **Empty**：HTTP/认证成功、模板执行成功，解析后合法 Proxy 数为 0。 - **Duplicate-only**：合法 Proxy 数大于 0，但去重后新增为 0；不计 Empty， 重置 Empty 连续计数并增加 duplicate 指标。 - **Error**：超时、DNS、非预期 HTTP、认证、响应超限、模板或解析异常； Empty 计数保持不变，增加 Error 并进入退避。 - **Success**：至少一个合法候选；Empty 计数归零。是否最终入池由去重、 maxSize、TTL 和健康结果决定。 ## 9. Sequential 切换 ```mermaid sequenceDiagram participant F as Provider Controller participant U as Upstream Runtime participant R as Routing Runtime participant DB as PostgreSQL F->>U: EmptyFetch U->>U: consecutiveEmpty++ alt below threshold U-->>F: continue current else threshold reached U->>DB: persist depleted generation DB-->>R: notify affected routings R->>DB: CAS current index A -> B DB-->>R: switched once R->>R: old A proxies drain naturally end ``` Upstream 的 Empty 事实全局共享；每条 Routing 独立 CAS 当前索引。多个并发 协程只能有一个成功从 A 切到 B，其他协程读取新版本，不会再切到 C。 Sequential 至少配置两个 Upstream；列表耗尽后的默认行为是 `stop`，`loop` 和 `stayLast` 必须显式配置。disabled Upstream 不参与新分配，其运行时跳过与权威 游标持久化仍由后续 Routing Runtime 完成。 ## 10. Exclusive Extraction ### 10.1 核心流程 ```mermaid sequenceDiagram participant C as Extract Client participant API as Distribution API participant CP as Controller participant W as Gateway Worker participant R as Redis Activity Pool C->>API: POST extract(count, filters) API->>API: auth + access + limits API->>CP: Extract command CP->>R: atomic select eligible unowned proxies alt candidate owned by Worker CP->>W: revoke and drain W-->>CP: active=0, reserved=0, ownership released end CP->>R: AVAILABLE -> EXTRACTED + bounded idempotency result R-->>CP: consumed proxies CP-->>API: proxy + expiry API-->>C: requested/returned/proxies ``` ### 10.2 原子批量提取 Redis Adapter 使用单个 Lua 脚本或等价原子命令，选择满足以下条件的活动池 条目，并同时完成状态迁移和带 TTL 的幂等结果写入： - State 为 AVAILABLE。 - 未分配 Worker 所有权，Reserved/Active 为 0。 - 剩余 TTL 不低于 `minRemainingTTL`。 - 健康检查时间不早于 `maxHealthCheckAge`。 - 提取后仍保留 `reserveForGateway`。 - 符合 protocol、region、carrier 与 allowedUpstreams。 `partial` 原子消费实际可得数量；`allOrNothing` 数量不足时不改变任何条目。 Proxy 地址、凭据和逐次提取明细不写 PostgreSQL。 ### 10.3 与 Gateway 共池 Controller 优先维护两类库存：Worker-owned Gateway 容量和 unowned Extract 库存。Distribution 只直接提取 unowned Proxy。需要从 Gateway 回收时，先 发布 DRAINING、等待 Worker ACK 和容量归零，再清除所有权并提取。这样避免 Snapshot 传播延迟造成同一 Proxy 同时被 Gateway 新分配和 API 发放。 ## 11. Cluster 所有权 ```mermaid flowchart LR CP[Controller] -->|capacity lease| W1[Worker 1] CP -->|capacity lease| W2[Worker 2] P1[Proxy set A] --> W1 P2[Proxy set B] --> W2 U[Unowned extract reserve] --> CP ``` - 同一个 Proxy 同一时刻只归一个 Worker 所有。 - Worker 仅对自身 Proxy 做本地原子计数。 - 所有权租约有 epoch 与过期时间；Worker 失联后先等待租约过期，再分配给 其他 Worker，避免双主。 - Snapshot 包含 Worker 专属 Proxy 集、Routing、策略、`ExpiresAt`、 `UsableUntil` 和版本校验和。Worker 在 `UsableUntil` 到达后立即停止新分配， 不等待供应商硬过期时间 `ExpiresAt`。 - Worker 断开控制面后在 `maxStaleAge` 内使用最后快照；超限停止接收新流量， 已有隧道排空。Gateway 会把 Controller Snapshot 的整体 `valid_until` 保存在 本地视图；该期限到达后本地调度不再为新请求分配 Proxy。 ## 12. 存储与一致性 ### 12.1 PostgreSQL 持久化配置版本、Upstream/Routing 管理状态、Admin 审计和管理事件 outbox， 以及可选的不含 Proxy 明细的聚合指标。PostgreSQL 不保存 Proxy 地址、凭据、 生命周期、Worker 所有权或逐次提取记录。 ### 12.2 Redis 保存带 TTL 的短效 Proxy 活动池、生命周期、Worker 所有权、独占提取状态和 短期幂等结果，并承载 Provider Leader、分布式限流、singleflight 信号、 短期 Client 限流和 Worker 心跳。Redis 丢失后由 Provider 重新获取代理重建， 不会从 PostgreSQL 恢复旧 Proxy。 ### 12.3 Outbox 管理状态变更在 PostgreSQL 事务内同时写 outbox。活动池变更通过 Redis 事件流 通知 Controller 构建 Snapshot，不跨 PostgreSQL/Redis 双写 Proxy；Worker 使用 epoch/version 幂等应用，缺口时从当前活动池构建完整 Snapshot。 ## 13. 健康模型 Health Observation 包含 Proxy、检查层级、Routing/目标组、阶段、结果、延迟、 出口信息与时间。Reducer 规则： - 新 Proxy 必须通过基础检查才可 AVAILABLE。 - 第一次有意义失败进入 SUSPECT，不立即删除。 - 连续失败达到配置阈值进入 UNHEALTHY。 - SUSPECT 复检成功恢复 AVAILABLE。 - 目标级失败只影响对应 Routing/Target Profile，不直接全局删除。 - 任务按稳定哈希分散，并对 interval 加 jitter。 ## 14. 配置热更新 ```mermaid flowchart LR F[Read file] --> P[Parse] P --> V[Validate references and regex] V --> B[Build immutable config] B --> D[Diff old/new] D --> S[Atomic swap] S --> G[Drain removed tasks/resources] ``` 热更新规则： - 删除/禁用 Upstream：停止 Fetch 和新分配，已有 Proxy/连接 Drain。 - Checker 调度监督器在下一轮停止禁用 Upstream 的新任务，并发现新启用 Upstream；有效 `check` 策略在同一轮重新解析，已有租约由租约期自然收敛。 - 减小 maxSize：不强杀连接，停止补池并按策略自然缩容。 - Routing 立即对新请求生效；旧请求持有旧 Snapshot 完成。 - 修改 API 地址或凭据版本会重建 Provider Adapter，但不会把错误计成 Empty。 - 新配置任何校验失败时，保留旧版本并报告完整错误。 - 多 Controller 以 PostgreSQL 中的 HMAC-SHA-256 完整配置指纹检测修订；HMAC 密钥由外部 Secret 注入且所有副本一致。副本从共享配置源读取相同 revision， 预检后通过单调 revision 栅栏原子发布。权威指纹已变化但本地源仍旧时，旧 Provider fail-closed 停止，避免旧 URL/Secret 在 Leader 换主后继续使用。 - PostgreSQL 瞬时读取失败时沿用 last-known Provider Runtime 并重试，不连带终止 Distribution、Admin 或 Metrics。 ## 15. 安全 - Gateway、Distribution、Admin 认证相互独立。 - `auth.mode` 支持 none、usernamePassword、apiKey、bearer、ipWhitelist 与组合 any。 - `access.allowCIDRs` 独立于认证；代理头只在来源属于 trustedProxies 时接受。 - 严格模式下，非回环监听且 auth=none、allowCIDRs 为空时启动失败。 - 目的地址解析前后都拒绝 loopback、private、link-local、metadata 和配置禁区。 - Secret 使用环境变量或文件引用；日志统一 Secret 类型脱敏。 - Provider 模板只能使用白名单纯函数，禁止文件、网络和环境变量读取。 - Distribution 返回真实凭据属于 Raw 弱控制模式，文档必须明确其风险。 ## 16. 可观测性 关键指标： - Gateway 请求、连接、建连、字节、延迟、重试和拒绝。 - Routing 当前 Upstream、切换、无可用和策略选择。 - Upstream Proxy 状态、Available Slots、Active、Reserved、Pending Fetch。 - Provider Fetch 成功、Empty、Duplicate、Error、429、退避和耗时。 - Extraction requested、returned、insufficient、atomic conflict 和幂等缓存失败。 - Snapshot epoch/version、陈旧时长、应用耗时和重同步。 Prometheus 标签不包含 Proxy IP、Client ID、session、完整 URL 或 request ID。 这些信息进入受控、脱敏、可采样日志。 ## 17. 性能与容量 ### 17.1 集群容量公式 ```text worker_replicas = ceil(peak_qps / (tested_worker_qps * target_utilization)) + largest_failure_domain_replicas ``` 默认 `peak_qps=100000`、`target_utilization<=0.60`。单 Worker 能力必须在相同 CPU、内存、网络、Go 版本、配置和上游响应模型下测得。 ### 17.2 热路径预算 - Dispatch 无 I/O、无全局锁；100k Proxy Snapshot 下的设计预算为 p99 小于 100 微秒，仍需分位数基准验证。 - 所有队列、buffer、重试和日志均有界。 - Listener、Client、Routing、Worker 和 Proxy 均有独立准入限制。 - 过载在路由/建连前快速拒绝，不允许请求堆积耗尽内存。 - 结果上报批量、异步、有界，不反压请求热路径。 ### 17.3 独立场景 必须分别测试：10k 稳态 QPS、100k 峰值 QPS、活跃 CONNECT、建连速率、 大 Snapshot 更新、Provider 故障、Controller 断线和 Worker 故障域丢失。 ## 18. 故障行为 | 故障 | 行为 | |---|---| | Provider 超时/500 | 计 Error、退避；不计 Empty，不影响已有 Proxy | | Provider 合法空响应 | Empty++；达到阈值触发相关 Routing 原子切换 | | Redis 不可用 | Gateway 暂用未过期快照；停止 Fetch 入池、Extract 和所有权变更 | | PostgreSQL 不可用 | Gateway 与 Redis Extract 不受影响；停止管理写入，Provider 沿用 last-known 状态并重试 | | Controller 断线 | Worker 在 maxStaleAge 内继续；超限拒绝新流量并排空 | | Worker 崩溃 | 所有权租约过期后重新分配；期间不双重所有 | | Checker 积压 | 降低普通复检频率，优先新 Proxy 与 SUSPECT，不无限排队 | | Snapshot 缺版本 | 丢弃增量并请求完整 Snapshot | | 所有 Upstream 不可用 | 执行显式 onUnavailable，默认 reject | ## 19. 交付边界 项目架构必须包含四个命令、领域模块、Gateway/Controller/Checker 模块、 存储/协议 Adapter、OpenAPI/Proto、配置样例、Compose/Kubernetes、监控、 迁移、测试 fixture、负载场景和开发文档。目录存在但没有契约或测试不算完成。