Proxy Pool 项目架构

1. 仓库结构

proxy-pool/
├── cmd/
│   ├── proxy-gateway/       # 数据面进程
│   ├── proxy-controller/    # 控制面与 HTTP API
│   ├── proxy-checker/       # 健康检查执行器
│   └── proxy-loadgen/       # 可复现容量测试
├── internal/
│   ├── config/              # 严格配置解析和校验
│   ├── domain/              # 无传输、无存储依赖的领域模型
│   ├── gateway/             # snapshot、dispatch、server、transport
│   ├── controller/          # provider、pool、routing、extraction、health、runtime
│   ├── adapters/            # PostgreSQL、Redis、Provider API、内存适配
│   └── platform/            # HTTP、安全、日志、指标、停机和进程装配
├── api/                     # OpenAPI 与 Protobuf 契约
├── configs/                 # 默认配置
├── examples/                # 可校验配置场景
├── deploy/                  # Compose 与 Kubernetes
├── docs/                    # 设计、开发、API、测试、运维
├── diagrams/                # Mermaid 图集
├── scripts/                 # 验证和生成脚本
└── test/                    # fixture、集成、端到端和负载测试

2. 进程边界

proxy-gateway

gateway -> dispatch -> transport 是数据面主调用链。dispatch 包含筛选、选择、session 与重试资格等热路径决策；transport 独占连接池、上游握手和隧道生命周期。任何包都不得从热路径反向调用 Controller 存储。

proxy-controller

Controller 是首版模块化单体。Provider、Pool、Routing 和 Extraction 共享运行时策略和状态演进，但不建立 PostgreSQL/Redis 跨存储事务。对外端口定义在领域或控制器模块，具体 PostgreSQL/Redis/HTTP 实现在 adapters。

proxy-checker

Checker 只产生 Observation。最终状态迁移由 Controller 的确定性 reducer 完成，避免多个检查实例同时写 Proxy 状态。

proxy-loadgen

负载工具生成 HTTP、CONNECT、连接复用与故障注入场景，输出延迟分位数、错误类别、连接数、CPU、RSS、GC 与吞吐。它是 100k QPS 结论的证据工具，不是业务进程。

3. 依赖方向

cmd -> controller/gateway/checker -> domain
                    |
                    +------------> port interfaces
adapters -------------------------> port interfaces
platform -------------------------> standard library / observability SDK

硬性规则：

domain 不导入 HTTP、SQL、Redis、配置或平台包。
gateway/dispatch 只依赖本地 Snapshot 与领域类型。
adapters 实现端口，不被领域层反向引用。
配置先解析、校验、编译为运行时对象，再原子发布。
Secret 仅通过引用进入运行时，不进入唯一键、指标或日志字段。

4. 数据所有权

PostgreSQL：配置版本、Upstream/Routing 管理状态、Admin 审计与 Outbox，以及可选的无 Proxy 明细聚合指标。
Redis：带 TTL 的短效 Proxy 活动池及其状态、所有权和过期时间；同时保存 Provider Leader、分布式速率、Worker 心跳和短期提取幂等结果。
Worker：仅拥有分配给自己的 Proxy 本地容量计数和不可变快照。
Controller：拥有 Provider 调度、Routing 运行态与 Worker 所有权编排。
Checker：不拥有 Proxy 状态，只拥有执行中的检查任务。

Proxy 明细不进入 PostgreSQL。Redis 活动池丢失后由 Provider 重新获取并重建，节点内存中的旧快照随版本或有效期失效，不能把 PostgreSQL 当成恢复来源。

5. 一致性边界

Extraction 在 Redis 内原子完成候选筛选、排他状态迁移和短期幂等结果写入，成功后才响应；该路径不访问 PostgreSQL。
Worker 所有权采用 worker + epoch + version + expiry，同一 Proxy 至多归属一个 Worker。
从 Worker 回收 Proxy 时先 Drain，等待 ACK 且 Active/Reserved 为零，再解除所有权；只有无所有权 Proxy 能被 Distribution 提取。
Snapshot 为整代不可变对象，通过校验和和严格版本序列原子替换。
PostgreSQL 故障会影响管理状态变更和 Admin 审计，但不应阻断 Redis 中可完成的独占提取；Redis 故障则使活动池暂不可用，并触发 Provider 重建。

6. 扩展规则

新 Provider：增加 Adapter，不修改 Proxy/Pool/Routing 领域语义。
新入口协议：在 Gateway 增加 ingress adapter；只有存在第二种上游协议执行方式时再抽象 egress adapter。
新路由策略：实现同一策略端口，并提供确定性单测和并发不变量测试。
新存储：实现已有 repository port，不把驱动类型泄漏到控制器。

4.8 KiB Raw Blame History Unescape Escape