docs: refresh project README
This commit is contained in:
youfak
parent
be596294c0
commit
6257265e14
222
README.md
222
README.md
@ -1,58 +1,202 @@
|
||||
# Proxy Pool
|
||||
|
||||
面向多供应商代理资源的集中管理与高并发转发平台。系统同时提供：
|
||||
## 项目定位
|
||||
|
||||
- **Gateway**：系统选择上游代理并代转发 HTTP 与 HTTPS CONNECT。
|
||||
- **Distribution API**：把真实代理一次性、独占地发放给调用方。
|
||||
- **Admin API**：查询、启停、切换和配置重载。
|
||||
- **Controller / Checker**：管理供应商获取、健康、容量、状态与数据面快照。
|
||||
面向多供应商动态代理资源的集中控制、独占提取与高并发转发平台。
|
||||
|
||||
> 当前仓库交付的是从 `对话内容.md` 全量重建的设计基线、机器契约、
|
||||
> 项目骨架和关键并发领域实现。100,000 QPS 是集群设计目标，尚需在目标
|
||||
> 网络和代理规模下完成压测证明。
|
||||
Proxy Pool 将供应商接入、短 TTL 代理活动池和管理状态集中到 Controller，
|
||||
同时提供三类边界清晰的访问方式。集群 `100,000 QPS` 是设计目标，尚未经过
|
||||
代表性环境的负载测试证明。
|
||||
|
||||
## 快速导航
|
||||
## 项目背景
|
||||
|
||||
不同代理供应商的响应格式、鉴权方式、计费方式和代理存活时间并不一致；部分
|
||||
代理只有几十秒有效期。系统还需要同时处理容量预留、健康状态、路由切换、
|
||||
一次性提取和高并发转发。
|
||||
|
||||
Proxy Pool 用 Controller 协调这些变化，并让 Gateway 数据面只消费节点内存中的
|
||||
不可变快照，避免在转发热路径查询 PostgreSQL、Redis 或 Provider API。
|
||||
|
||||
## 使用方式
|
||||
|
||||
- **Gateway**：调用方连接平台，由平台选择上游代理并转发 HTTP 或 HTTPS
|
||||
CONNECT。当前已有传输、调度和保护链组件，命令进程与控制面快照客户端待装配。
|
||||
- **Distribution**：调用方按条件提取真实代理；成功提取即独占消费，不支持归还、
|
||||
续租或状态查询。
|
||||
- **Admin**：运维人员查询状态、启停 Upstream、切换 Routing，并触发严格配置
|
||||
重载。Admin 与 Distribution 已由 Controller 运行在独立监听器上。
|
||||
|
||||
## 核心能力
|
||||
|
||||
- **严格配置**：配置版本 1、YAML 未知字段拒绝、Secret 引用解析、公开监听保护、
|
||||
引用和容量边界校验。
|
||||
- **Provider 获取与协调**：Provider HTTP Client、响应上限、模板解析、分布式
|
||||
Leader/请求额度、退避和补池 Supervisor 已接入 Controller。
|
||||
- **Redis 活动池**：短 TTL Proxy Upsert、去重、健康更新、Worker ownership、
|
||||
库存、过期清理、Distribution 幂等与分布式限流均使用原子操作或有界流程。
|
||||
- **Distribution**：支持 `partial` / `allOrNothing`、TTL 与健康过滤、Gateway
|
||||
库存预留，以及 `AVAILABLE -> EXTRACTED` 的一次性独占提取。
|
||||
- **Controller 入口**：`proxy-controller` 已装配 Distribution、Admin、Metrics、
|
||||
PostgreSQL 迁移与 Redis 活动池，并支持联动优雅停机。
|
||||
- **PostgreSQL 管理面**：持久化配置版本、Upstream/Routing 管理状态、Admin
|
||||
审计与 Outbox；不保存 Proxy 明细或逐次提取记录。
|
||||
- **Gateway 组件**：HTTP 正向代理、HTTPS CONNECT、双向 Tunnel、重试、超时、
|
||||
目的地址保护、本地快照存储和容量调度已有实现与定向测试，但尚无
|
||||
`proxy-gateway` 命令和控制面客户端。
|
||||
- **安全边界**：Gateway、Distribution 与 Admin 使用各自的认证语义，并支持
|
||||
CIDR、可信代理、严格请求解析和敏感信息最小化。
|
||||
|
||||
## 架构概览
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client[调用方] -->|HTTP / CONNECT| Gateway[Gateway<br/>进程待装配]
|
||||
Client -->|独占提取| Distribution[Distribution]
|
||||
Operator[运维人员] -->|管理操作| Admin[Admin]
|
||||
subgraph CP[proxy-controller 已运行]
|
||||
Distribution --> Controller[Controller]
|
||||
Admin --> Controller
|
||||
end
|
||||
Controller -->|Fetch| Provider[Provider API]
|
||||
Controller --> Redis[(Redis)]
|
||||
Controller --> PostgreSQL[(PostgreSQL)]
|
||||
Checker[Checker<br/>健康链待闭环] -. Observation .-> Controller
|
||||
Controller -. Snapshot 链待闭环 .-> Gateway
|
||||
```
|
||||
|
||||
- **PostgreSQL** 只保存管理面状态，不保存 Proxy 明细或逐次提取记录。
|
||||
- **Redis** 保存短 TTL Proxy 活动池、Provider 协调、Distribution 幂等与分布式
|
||||
限流等可重建的短期状态。
|
||||
- **Gateway 热路径** 只读取节点内存，不查询 PostgreSQL、Redis 或 Provider API。
|
||||
|
||||
## 当前完成度
|
||||
|
||||
截至 **2026-07-30**，实施计划检查项为 **52 / 74（70.3%）**。详情见
|
||||
[实施计划](docs/development/implementation-plan.md)和
|
||||
[交付完成度审计](docs/requirements/completion-audit.md)。
|
||||
|
||||
- **已完成**：严格配置、Provider 获取与协调、Redis 活动池、Distribution 原子
|
||||
提取与限流、Controller 的 Admin/Distribution/Metrics 监听，以及 PostgreSQL
|
||||
管理状态。
|
||||
- **部分完成**：Gateway 传输与调度组件、Snapshot 本地存储、Worker ownership
|
||||
与运行态领域组件、Docker Compose/Kubernetes 静态部署清单和 protobuf 契约。
|
||||
- **待完成**：WorkerControlPlane gRPC session/snapshot/ACK 闭环、Checker 调度与
|
||||
健康状态链、Gateway 进程与快照客户端、完整 Routing 运行链，以及 loadgen 和
|
||||
代表性集群压测。
|
||||
|
||||
检查项数量不等于生产就绪度。静态部署清单与 protobuf descriptor 验证也不代表
|
||||
端到端拓扑已经完成；`100,000 QPS` 仍只是待验证的集群设计目标。
|
||||
|
||||
## 快速开始
|
||||
|
||||
前置条件为 Go 1.26、PowerShell，以及用于 fixture 测试的 Docker。先在当前
|
||||
PowerShell 会话设置本地占位凭据；这些值仅用于本地验证：
|
||||
|
||||
```powershell
|
||||
$env:PROXY_POOL_GATEWAY_PASSWORD = "LOCAL_GATEWAY_PASSWORD"
|
||||
$env:PROXY_POOL_EXTRACT_TOKEN = "LOCAL_EXTRACT_TOKEN"
|
||||
$env:PROXY_POOL_ADMIN_TOKEN = "LOCAL_ADMIN_TOKEN"
|
||||
$env:PROVIDER_A_TOKEN = "LOCAL_PROVIDER_A_TOKEN"
|
||||
$env:PROVIDER_B_TOKEN = "LOCAL_PROVIDER_B_TOKEN"
|
||||
$env:PROXY_POOL_CONFIG_FINGERPRINT_KEY = "LOCAL_HIGH_ENTROPY_KEY_AT_LEAST_32_BYTES"
|
||||
```
|
||||
|
||||
`PROXY_POOL_CONFIG_FINGERPRINT_KEY` 在 Admin 启用时必须至少为 32 字节，并与业务
|
||||
Secret 分离管理。
|
||||
|
||||
校验配置并执行仓库验证：
|
||||
|
||||
```powershell
|
||||
go run ./deploy/tools/configcheck deploy/config/local.yaml
|
||||
./scripts/verify.ps1
|
||||
```
|
||||
|
||||
Redis、PostgreSQL 和 Controller fixture 脚本会使用 Docker 启动隔离依赖：
|
||||
|
||||
```powershell
|
||||
./scripts/test-redis.ps1
|
||||
./scripts/test-postgres.ps1
|
||||
./scripts/test-controller.ps1
|
||||
```
|
||||
|
||||
PostgreSQL 与 Redis 是 Controller 的启动依赖。确保它们在
|
||||
[`deploy/config/local.yaml`](deploy/config/local.yaml) 配置的地址可达后，启动
|
||||
当前已实现的 Controller 进程：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/proxy-controller -config deploy/config/local.yaml
|
||||
```
|
||||
|
||||
本地配置中的 `.invalid` Provider URL 是故障演示占位，不会提供真实代理。
|
||||
当前仓库没有 Gateway、Checker 或 loadgen 命令，因此不提供对应启动命令。
|
||||
|
||||
## 关键配置与入口
|
||||
|
||||
- [本地配置](deploy/config/local.yaml)与
|
||||
[完整配置参考](docs/configuration/reference.md)
|
||||
- [Distribution API](docs/api/distribution.md)：默认本地入口
|
||||
`http://127.0.0.1:8081`
|
||||
- [Admin API](docs/api/admin.md)：默认本地入口 `http://127.0.0.1:8082`
|
||||
- Controller Metrics：默认本地入口 `http://127.0.0.1:9090`，提供 `/livez`、
|
||||
`/readyz` 和 `/metrics`
|
||||
- [控制面协议](docs/api/control-plane.md)：Worker/Checker 的 protobuf 契约；
|
||||
gRPC 运行链尚未闭环
|
||||
- [运维手册](docs/operations/runbook.md)：依赖、探针、发布边界与故障处置
|
||||
|
||||
## 核心不变量
|
||||
|
||||
1. Gateway 热路径只读节点内存，不访问 PostgreSQL、Redis 或 Provider API。
|
||||
2. Proxy 容量使用 `Reserved -> Active` 原子转换，禁止超卖。
|
||||
3. Distribution 成功时原子执行 `AVAILABLE -> EXTRACTED`；提取后不归还、不续租。
|
||||
4. `pool.maxSize` 是当前未提取库存硬上限；`fetch.maxTotal` 是 Redis generation
|
||||
内的累计获取停止阈值。
|
||||
5. CONNECT 向客户端提交 `200` 后不透明重放。
|
||||
6. 公开监听必须有认证或 CIDR 访问保护。
|
||||
7. PostgreSQL 只保存管理面状态；Proxy 明细只存在于 Redis 短 TTL 活动池和节点
|
||||
内存，Redis 中的短期状态可由 Provider 重建。
|
||||
|
||||
## 路线图
|
||||
|
||||
- **P0 - Worker 控制面闭环**：Worker session、Snapshot ledger、ACK、运行态接收、
|
||||
ownership 索引，以及 Gateway 快照客户端。
|
||||
- **P0 - Checker 健康链**：Checker 调度、实际探测、Observation reducer，以及
|
||||
`FETCHED -> AVAILABLE / SUSPECT / UNHEALTHY` 状态链。
|
||||
- **P1 - Gateway 与 Routing**：`proxy-gateway` 命令、五种 Routing 策略、
|
||||
`onUnavailable`、动态容量调整和 Drain 闭环。
|
||||
- **P1 - 可观测与部署**：低基数业务指标、完整 Compose/Kubernetes 进程拓扑，
|
||||
以及故障转移和恢复演练。
|
||||
- **P2 - 容量证明**：`proxy-loadgen`、HTTP/CONNECT/Extract 分场景压测，以及
|
||||
可复现的代表性 `100,000 QPS` 集群报告。
|
||||
|
||||
## 文档导航
|
||||
|
||||
**设计与需求**
|
||||
|
||||
- [产品设计](docs/design/product-design.md)
|
||||
- [总体架构](docs/design/architecture.md)
|
||||
- [项目结构](docs/design/project-structure.md)
|
||||
- [需求追踪](docs/requirements/traceability.md)
|
||||
- [交付完成度审计](docs/requirements/completion-audit.md)
|
||||
- [架构决策记录](docs/adr/README.md)
|
||||
|
||||
**开发与 API**
|
||||
|
||||
- [开发指南](docs/development/guide.md)
|
||||
- [实施计划](docs/development/implementation-plan.md)
|
||||
- [配置参考](docs/configuration/reference.md)
|
||||
- [Distribution API](docs/api/distribution.md)
|
||||
- [Admin API](docs/api/admin.md)
|
||||
- [控制面协议](docs/api/control-plane.md)
|
||||
- [安全模型](docs/security/security-model.md)
|
||||
- [测试策略](docs/testing/strategy.md)
|
||||
|
||||
**部署与运维**
|
||||
|
||||
- [本地配置](deploy/config/local.yaml)
|
||||
- [运维手册](docs/operations/runbook.md)
|
||||
- [生产就绪检查](docs/operations/production-readiness.md)
|
||||
- [安全模型](docs/security/security-model.md)
|
||||
|
||||
## 本地验证
|
||||
**审计与测试**
|
||||
|
||||
```powershell
|
||||
go mod tidy
|
||||
go test ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
```
|
||||
|
||||
Windows PowerShell 可运行：
|
||||
|
||||
```powershell
|
||||
./scripts/verify.ps1
|
||||
```
|
||||
|
||||
竞态检测需要启用 CGO 并提供可用的 C 编译器；CI 的 Linux race job 负责
|
||||
执行该质量门禁。
|
||||
|
||||
## 不变量
|
||||
|
||||
1. Gateway 热路径不访问 PostgreSQL、Redis 或 Provider API。
|
||||
2. Proxy 容量使用 `Reserved -> Active` 原子转换，禁止超卖。
|
||||
3. Distribution 成功时原子执行 `AVAILABLE -> EXTRACTED`，不提供 Lease、
|
||||
Release 或 Renewal。
|
||||
4. `pool.maxSize` 是当前未提取库存硬上限；`fetch.maxTotal` 是 Redis generation
|
||||
内的累计获取停止阈值。
|
||||
5. CONNECT 向客户端提交 200 后不透明重放。
|
||||
6. 公开监听必须有认证或 CIDR 访问保护。
|
||||
- [交付完成度审计](docs/requirements/completion-audit.md)
|
||||
- [测试策略](docs/testing/strategy.md)
|
||||
- [详细测试策略](docs/testing/test-strategy.md)
|
||||
- [故障注入](docs/testing/failure-injection.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user