111 lines
5.6 KiB
Markdown
111 lines
5.6 KiB
Markdown
# Proxy Pool 项目架构
|
||
|
||
## 1. 仓库结构
|
||
|
||
```text
|
||
proxy-pool/
|
||
├── cmd/
|
||
│ ├── proxy-gateway/ # 数据面进程
|
||
│ ├── proxy-controller/ # 控制面与 HTTP API
|
||
│ ├── proxy-checker/ # 健康检查执行器
|
||
│ └── proxy-loadgen/ # 可复现容量测试
|
||
├── internal/
|
||
│ ├── config/ # 严格配置解析和校验
|
||
│ ├── domain/ # 无传输、无存储依赖的领域模型
|
||
│ ├── gateway/ # bootstrap、snapshot、dispatch、server、transport
|
||
│ ├── controller/ # provider、pool、extraction、operations、runtime、bootstrap
|
||
│ ├── 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 存储。
|
||
|
||
`gateway/bootstrap` 只在进程启动时加载配置、建立 gRPC 控制面 Session、组装 HTTP
|
||
代理与 Metrics 监听；请求热路径只读取本地 Snapshot。`/readyz` 要求当前 Snapshot
|
||
尚未到期，控制面断开期间以有界退避重连而不访问 Redis/PostgreSQL。
|
||
|
||
### proxy-controller
|
||
|
||
Controller 是首版模块化单体。Provider、Pool、Routing 和 Extraction 共享
|
||
运行时策略和状态演进，但不建立 PostgreSQL/Redis 跨存储事务。对外端口定义
|
||
在领域或控制器模块，具体 PostgreSQL/Redis/HTTP 实现在 `adapters`。
|
||
|
||
### proxy-checker
|
||
|
||
Checker 只产生 Observation。它从认证 gRPC 流领取有界任务，用固定 worker-pool 在任务
|
||
deadline 内执行 HTTP/HTTPS/SOCKS5 BASIC、EGRESS 和 TARGET 探测并微批上报；EGRESS 的
|
||
任务 URL 仅在执行期使用，回传全局事实不包含该 URL。最终状态迁移仍由 Controller 的
|
||
确定性 reducer 完成，避免多个检查实例同时写 Proxy 状态。Checker 不访问 Redis 或 PostgreSQL。
|
||
|
||
### proxy-loadgen
|
||
|
||
负载工具当前生成有界 HTTP 请求，支持经 Gateway 请求 HTTPS 目标、固定请求数或时长、
|
||
目标 QPS、可重复请求头和请求体、连接复用和 JSON 指标输出。延迟统计使用固定大小直方图，不会因长时间高 QPS
|
||
运行积压样本。CONNECT 长连接、Extract 和故障注入场景仍待补齐；它是 100k QPS 结论的
|
||
证据工具，不是业务进程。
|
||
|
||
## 3. 依赖方向
|
||
|
||
```text
|
||
cmd -> controller/gateway/checker -> domain
|
||
|
|
||
+------------> port interfaces
|
||
adapters -------------------------> port interfaces
|
||
platform -------------------------> standard library / observability SDK
|
||
```
|
||
|
||
硬性规则：
|
||
|
||
1. `domain` 不导入 HTTP、SQL、Redis、配置或平台包。
|
||
2. `gateway/dispatch` 只依赖本地 Snapshot 与领域类型。
|
||
3. `adapters` 实现端口，不被领域层反向引用。
|
||
4. 配置先解析、校验、编译为运行时对象，再原子发布。
|
||
5. 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，不把驱动类型泄漏到控制器。
|