64 lines
3.8 KiB
Markdown
64 lines
3.8 KiB
Markdown
# 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**：不足时一个也不提取。
|