# Proxy Pool 统一领域语言 ## 核心实体 - **Client**：使用 Gateway 或 Distribution API 的调用主体。认证关闭时， 由可信来源 IP 形成匿名 Client。 - **Routing**：一组有序匹配规则和选择策略，决定某类请求使用哪些 Upstream。 - **Upstream**：一个供应商配置及其聚合代理池。Upstream 运行时全局共享， 不随 Routing 重复创建。 - **Provider**：Upstream 背后的外部代理供应商及其获取接口能力。 - **Proxy**：从 Provider 获取并标准化后的短效代理资源，不等同于简单 IP。 Proxy 明细不进入 PostgreSQL，只存在于带 TTL 的 Redis 活动池和持有其快照的 节点内存；丢失后由 Provider 重新获取。 - **Worker**：承载 Gateway 流量的数据面节点，仅使用本地快照选路。 - **Controller**：集中管理 Provider 获取、代理生命周期、Routing 状态、 所有权和快照发布的控制面节点。 - **Checker**：执行基础、出口和目标级健康检查的可扩缩执行节点。 - **Extraction**：Distribution API 对一个或一组 Proxy 的一次性独占发放。 - **Activity Pool**：Redis 中带 TTL 的短效 Proxy 运行时集合，是分配、所有权 和独占提取的原子操作位置，可在丢失后由 Provider 重建。 - **Extraction Result**：Redis 中短期保存的幂等响应，不承担租约、释放或 长期审计语义。 - **Persistent Management State**：PostgreSQL 中的配置版本、Upstream/Routing 管理状态、Admin 审计与 Outbox，以及可选聚合指标；不包含 Proxy 明细或逐次 提取记录。 ## 状态与计数 - **Proxy State**：`FETCHED`、`CHECKING`、`AVAILABLE`、`SUSPECT`、 `DRAINING`、`UNHEALTHY`、`EXTRACTED`、`EXPIRED`、`REMOVED`。 - **Active Concurrency**：已建立并正在使用 Proxy 的 Gateway 并发。 - **Reserved Concurrency**：已选中、正在建连但尚未转为 Active 的并发。 - **Available Slots**：所有可分配 Proxy 的有效并发上限减去 Active 与 Reserved 后的总和。 - **Consecutive Empty Fetch**：Provider 调用成功且解析成功，但解析后没有 任何合法代理的连续次数。 - **Fetch Error Count**：超时、DNS、HTTP、认证、解析或模板执行错误次数。 - **Current Upstream**：Sequential Routing 当前指向的 Upstream 索引。 ## 行为术语 - **Gateway Allocation**：Worker 原子预留本地所有 Proxy 容量，建连成功后 转为 Active，结束后释放。 - **Exclusive Extraction**：控制面通过 Redis 原子操作把可提取 Proxy 从 `AVAILABLE` 改为不可再次分配，并在有限 TTL 内保存幂等结果；成功后该 Proxy 在当前 TTL 生命周期内不再被系统分配。Redis 整体丢失后的 Provider 重建属于新的活动池代次，不承诺延续已丢失代次的排他状态。 - **Drain**：停止新分配，等待 Reserved 与 Active 归零后转换状态或撤销所有权。 - **Empty Fetch**：不是错误、不是重复，而是有效 Provider 响应中没有任何 合法 Proxy 候选。 - **Switch**：Routing 使用 CAS 从当前 Upstream 前进到下一个；不会销毁旧 Upstream 已有 Proxy。 - **Snapshot**：Controller 发布给 Worker 的不可变、版本化 Routing、Proxy 所有权和策略视图。 ## 配置语义 - **pool.maxSize**：当前系统维护且尚未被提取的 Proxy 硬上限。 - **fetch.maxTotal**：可选的计费周期累计获取上限，和 pool.maxSize 无关。 - **allocationSafetyMargin**：距离过期不足此时间时停止新分配。 - **reserveForGateway**：共享池中不能被 Distribution 提取的最低可用数量。 - **fulfillment.partial**：尽量返回，允许少于请求数量。 - **fulfillment.allOrNothing**：不足时一个也不提取。