107 lines
5.5 KiB
Markdown
107 lines
5.5 KiB
Markdown
# README 首页重写设计
|
||
|
||
## 1. 目标
|
||
|
||
将根目录 `README.md` 从早期的“设计基线与项目骨架”说明，更新为与当前代码
|
||
一致的工程首页。README 必须让首次访问者在几分钟内回答以下问题：
|
||
|
||
1. Proxy Pool 解决什么问题，为什么区分 Gateway 与 Distribution。
|
||
2. 当前已经实现和验证了哪些能力。
|
||
3. 哪些模块仍是局部实现、协议或部署占位，不能视为生产完成。
|
||
4. 如何验证、配置并启动当前可运行的 Controller。
|
||
5. 后续实现按什么优先级推进。
|
||
|
||
README 不承担完整设计文档职责；细节继续链接到 `docs/` 中的权威文档。
|
||
|
||
## 2. 目标读者
|
||
|
||
- 评估项目能力和成熟度的技术负责人。
|
||
- 部署、维护 Controller 与存储依赖的开发者和 SRE。
|
||
- 需要理解模块边界、测试入口和后续任务的贡献者。
|
||
|
||
内容优先级依次为：事实准确、快速定位、可执行、简洁。README 不采用营销页
|
||
结构，也不宣称未经代表性压测证明的 100,000 QPS 能力。
|
||
|
||
## 3. 内容结构
|
||
|
||
README 按以下顺序组织：
|
||
|
||
1. **项目名称与一句话定位**：多供应商动态代理的集中控制、独占提取和高并发
|
||
转发平台。
|
||
2. **项目背景**：说明供应商响应格式、短 TTL、容量、健康、路由和高并发数据面
|
||
隔离问题。
|
||
3. **使用方式**：明确 Gateway 是平台代转发，Distribution 是一次性独占发放，
|
||
Admin 是管理入口。
|
||
4. **核心能力**：按配置、Provider、活动池、Distribution、Gateway、Admin、
|
||
存储与安全列出已经落地的能力。
|
||
5. **架构概览**：使用一张紧凑 Mermaid 图展示 Client、Gateway、Controller、
|
||
Checker、PostgreSQL、Redis 和 Provider 的关系，并重申 Gateway 热路径边界。
|
||
6. **当前完成度**：展示实施计划 `52/74`、约 `70.3%` 的快照，同时分别列出
|
||
已完成、部分完成和待完成模块。标注统计日期，并链接实施计划，避免把数量
|
||
完成度等同于生产就绪度。
|
||
7. **快速开始**：列出 Go、PostgreSQL、Redis、Docker 等前置条件，提供配置校验、
|
||
全量验证、Redis/PostgreSQL/Controller fixture 和当前 Controller 启动命令。
|
||
8. **关键配置与入口**：链接配置样例、Distribution/Admin API、Metrics 探针和
|
||
Secret 要求，不在 README 复制长配置。
|
||
9. **核心不变量**：保留并完善热路径、容量、独占提取、数据边界、CONNECT
|
||
重试和公开监听保护规则。
|
||
10. **路线图**：按 P0/P1/P2 展示 WorkerControlPlane/Snapshot、Checker/健康链、
|
||
Gateway 进程装配、Routing 运行链、观测部署和代表性集群压测。
|
||
11. **文档导航**：按设计、开发/API、部署运维、审计测试分组，避免单一长列表。
|
||
|
||
## 4. 状态表达规则
|
||
|
||
- **已完成**：生产代码存在，并至少有单元、契约或真实依赖集成证据。
|
||
- **部分完成**：领域内核、Handler、协议或部署清单存在，但进程装配或端到端链路
|
||
尚未闭环。
|
||
- **待完成**：只有计划、配置字段、协议定义或部署占位。
|
||
- `100,000 QPS` 始终表述为集群设计目标，直到存在可复现的代表性负载报告。
|
||
- 不把 Docker Compose/Kubernetes 静态配置验证描述为完整生产部署验证。
|
||
- 不把 protobuf descriptor 编译描述为 gRPC 服务端已经实现。
|
||
- PostgreSQL 只描述管理面数据；Proxy 明细、Worker 运行态和短期幂等仍属于 Redis
|
||
或节点内存。
|
||
|
||
## 5. 快速开始边界
|
||
|
||
README 只提供仓库当前真实可执行的命令：
|
||
|
||
- `go run ./deploy/tools/configcheck deploy/config/local.yaml`
|
||
- `./scripts/verify.ps1`
|
||
- `./scripts/test-redis.ps1`
|
||
- `./scripts/test-postgres.ps1`
|
||
- `./scripts/test-controller.ps1`
|
||
- `go run ./cmd/proxy-controller -config CONFIG_FILE`
|
||
|
||
启动示例必须说明 PostgreSQL、Redis、配置中引用的环境变量，以及 Admin 启用时
|
||
至少 32 字节的 `PROXY_POOL_CONFIG_FINGERPRINT_KEY`。README 不提供不存在的
|
||
`proxy-gateway`、`proxy-checker` 或 `proxy-loadgen` 启动命令。
|
||
|
||
## 6. 路线图
|
||
|
||
- **P0，控制面闭环**：Worker 注册/session、Snapshot ledger、ACK、运行态接收、
|
||
Worker 维度 ownership 索引和 Gateway 快照客户端。
|
||
- **P0，健康链**：Checker 调度、实际探测、Observation reducer、目标健康隔离和
|
||
FETCHED 到 AVAILABLE/SUSPECT/UNHEALTHY 的运行链。
|
||
- **P1，数据面进程**：`proxy-gateway` 命令装配、Routing 五策略和
|
||
`onUnavailable` 运行时、动态降容与 Drain 闭环。
|
||
- **P1，可观测与部署**：低基数业务指标、完整 Compose/Kubernetes 进程拓扑、
|
||
故障转移和恢复演练。
|
||
- **P2，容量证明**：`proxy-loadgen`、HTTP/CONNECT/Extract 分场景压测和
|
||
100,000 QPS 集群报告。
|
||
|
||
## 7. 验收标准
|
||
|
||
1. README 中的命令和路径均指向仓库中的真实目标。
|
||
2. README 相对链接通过 `go test ./docs`。
|
||
3. README 中的配置文件通过现有配置示例测试和 `configcheck`。
|
||
4. 已完成/部分完成/待完成状态与实施计划、完成度审计和代码现状一致。
|
||
5. 全文不包含未完成占位标记、虚假生产就绪声明、Secret 值或代理明细示例。
|
||
6. 文档修改通过 `git diff --check` 和全量 `go test ./...`。
|
||
|
||
## 8. 非目标
|
||
|
||
- 不在本次修改中实现新的运行时功能。
|
||
- 不重写 `docs/` 下已有的详细设计、API 或运维文档。
|
||
- 不生成营销图片、徽章、发布包或未经验证的性能图表。
|
||
- 不改变配置、API、存储 Schema 或部署行为。
|