55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# Proxy Pool 统一领域语言
|
||
|
||
## 核心实体
|
||
|
||
- **Client**：使用 Gateway 或 Distribution API 的调用主体。认证关闭时，
|
||
由可信来源 IP 形成匿名 Client。
|
||
- **Routing**：一组有序匹配规则和选择策略，决定某类请求使用哪些 Upstream。
|
||
- **Upstream**：一个供应商配置及其聚合代理池。Upstream 运行时全局共享，
|
||
不随 Routing 重复创建。
|
||
- **Provider**：Upstream 背后的外部代理供应商及其获取接口能力。
|
||
- **Proxy**：从 Provider 获取并标准化后的代理资源，不等同于简单 IP。
|
||
- **Worker**：承载 Gateway 流量的数据面节点，仅使用本地快照选路。
|
||
- **Controller**：集中管理 Provider 获取、代理生命周期、Routing 状态、
|
||
所有权和快照发布的控制面节点。
|
||
- **Checker**：执行基础、出口和目标级健康检查的可扩缩执行节点。
|
||
- **Extraction**：Distribution API 对一个或一组 Proxy 的一次性独占发放。
|
||
- **Extraction Record**：Extraction 的审计事实，不承担租约或释放语义。
|
||
|
||
## 状态与计数
|
||
|
||
- **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**：控制面原子把可提取 Proxy 从 `AVAILABLE` 改为
|
||
`EXTRACTED`，成功后该 Proxy 永不再次被系统分配。
|
||
- **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**：不足时一个也不提取。
|
||
|