96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# Proxy Pool 项目架构
|
||
|
||
## 1. 仓库结构
|
||
|
||
```text
|
||
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/HTTP 实现在 `adapters`。
|
||
|
||
### proxy-checker
|
||
|
||
Checker 只产生 Observation。最终状态迁移由 Controller 的确定性 reducer
|
||
完成，避免多个检查实例同时写 Proxy 状态。
|
||
|
||
### proxy-loadgen
|
||
|
||
负载工具生成 HTTP、CONNECT、连接复用与故障注入场景，输出延迟分位数、
|
||
错误类别、连接数、CPU、RSS、GC 与吞吐。它是 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：Proxy 生命周期、Extraction 审计、配置版本和 Outbox 的权威源。
|
||
- Redis：Leader、分布式速率、Worker 心跳等可丢失且可重建状态。
|
||
- Worker：仅拥有分配给自己的 Proxy 本地容量计数和不可变快照。
|
||
- Controller：拥有 Provider 调度、Routing 运行态与 Worker 所有权编排。
|
||
- Checker：不拥有 Proxy 状态，只拥有执行中的检查任务。
|
||
|
||
## 5. 一致性边界
|
||
|
||
- Extraction 使用 PostgreSQL 单事务和行锁跳过锁定候选，提交后才响应。
|
||
- Worker 所有权采用 `worker + epoch + version + expiry`，同一 Proxy 至多归属
|
||
一个 Worker。
|
||
- 从 Worker 回收 Proxy 时先 Drain，等待 ACK 且 Active/Reserved 为零，再
|
||
解除所有权；只有无所有权 Proxy 能被 Distribution 提取。
|
||
- Snapshot 为整代不可变对象，通过校验和和严格版本序列原子替换。
|
||
|
||
## 6. 扩展规则
|
||
|
||
- 新 Provider：增加 Adapter，不修改 Proxy/Pool/Routing 领域语义。
|
||
- 新入口协议：在 Gateway 增加 ingress adapter；只有存在第二种上游协议
|
||
执行方式时再抽象 egress adapter。
|
||
- 新路由策略：实现同一策略端口，并提供确定性单测和并发不变量测试。
|
||
- 新存储：实现已有 repository port，不把驱动类型泄漏到控制器。
|