135 lines
9.1 KiB
Markdown
135 lines
9.1 KiB
Markdown
# 交付完成度审计
|
||
|
||
本文区分设计证据、机器契约、已运行验证和后续实施，防止把架构目标描述成
|
||
已完成产品。
|
||
|
||
## 1. 本次已交付
|
||
|
||
### 设计与开发文档
|
||
|
||
- 全量需求追踪、覆盖关系和统一领域语言。
|
||
- 产品设计、总体架构、项目结构、四项 ADR。
|
||
- 开发、配置、Distribution/Admin API、控制面协议、安全、测试、运维文档。
|
||
- 20 个配置场景和 35 张 Mermaid 架构/流程/状态/故障图。
|
||
|
||
### 机器契约
|
||
|
||
- Distribution OpenAPI：一次性独占提取、partial/allOrNothing、幂等键、
|
||
Redis TTL 活动池原子语义、TTL/健康过滤结果与标准错误。
|
||
- Admin OpenAPI：状态、Upstream 启停、Routing 切换和配置重载。
|
||
- 两份 OpenAPI 已进入 Go/CI 结构门禁，覆盖本地引用闭合、operationId、响应和
|
||
security scheme；完整标准工具验证仍待补齐。
|
||
- Protobuf：Worker 注册、全量/增量 Snapshot、`usable_until`、ACK、运行态/
|
||
结果上报、Checker 任务与 Observation。
|
||
|
||
### 核心参考实现
|
||
|
||
- `CFG-*`：YAML v4 未知字段拒绝、监听保护、引用/上限/认证边界校验，21 份
|
||
配置持续测试。
|
||
- `PROXY-* / CAP-*`：唯一键、TTL 优先级、状态迁移与 Active/Reserved 打包
|
||
原子计数；1,000 goroutine 不超卖，以及 Cancel、重复终结、错误顺序、并发
|
||
Commit/Cancel/Release 计数守恒测试。
|
||
- `ROUTE-001 / ROUTE-004`：首条命中规则与进程内 Concurrent Sequential 单次
|
||
切换；策略运行时接线、持久化恢复和跨实例 CAS 尚未完成。
|
||
- `FETCH-005 / FETCH-006`：Valid、Empty、DuplicateOnly、Error 分类。
|
||
- `DIST-001..003 / DIST-006..007`：内存活动池参考实现验证独占提取、满足模式、
|
||
TTL、健康时效与 Gateway 保留量；1,000 并发不重复。
|
||
- `OPS-001`：完整 Snapshot 目标、epoch/version、校验和验证及原子替换。
|
||
- `CAP-001 / GW 热路径边界`：本地 Dispatch 条件过滤与原子容量预留。
|
||
- `GW-*`：HTTP 正向代理、HTTPS CONNECT、双向 Tunnel、超时、重试、保护链与
|
||
优雅停机 Handler 已实现并通过定向测试。`proxy-gateway` 已装配本地 HTTP/Metrics
|
||
监听、快照就绪探针、显式控制面拨号和 Register/Watch/ACK/Runtime/Outcome 会话；本地 gRPC
|
||
集成测试验证收到有效 Snapshot 后才 Ready，并可完成 direct 路由。
|
||
- `PROVIDER-*`：Provider HTTP Client、严格响应上限、模板解析安全边界、凭据
|
||
引用 Store 与 Reconciler Adapter 已实现。
|
||
- `DIST/Admin HTTP`：严格 JSON、Request ID、Problem 响应及 Distribution/Admin
|
||
Handler 已实现；共享认证、CIDR、可信代理、Client ID 与本地准入保护链已接入，
|
||
Controller Runtime 已将二者装配到独立监听器并支持联动优雅停机。
|
||
- `Redis Activity Adapter`：真实 Redis 8.2 已覆盖 Provider Upsert、健康更新、
|
||
原子独占提取、短期幂等、Worker ownership、库存和有界过期清理，Memory/Redis
|
||
运行同一公用契约。
|
||
- `WorkerControlPlane`：Register、已签发 Snapshot 的 ACK 和完整稀疏 Runtime
|
||
报告已通过 gRPC、Memory 与 Redis 8.2 契约验证；session、ACK、报告均使用 Redis
|
||
服务端 TTL，负向 ACK 会关闭 Runtime 写入栅栏。Controller 已装配 loopback
|
||
plaintext fixture 与 SPIFFE mTLS 服务端；基础 Snapshot 流和 Gateway 的
|
||
Register/Watch/ACK/Runtime 会话协调已实现。Redis 以 Worker 可下发 ownership
|
||
索引构建已归属 Proxy payload，并以租约收紧可用期；凭据材料按引用去重并与 Proxy/
|
||
Routing 一起纳入 Snapshot checksum，仅在 mTLS 和 Gateway 当前内存 View 中处理。Gateway
|
||
Routing payload 已由配置顺序和 Admin 当前状态合成并覆盖 Snapshot checksum，其运行时消费、
|
||
Outcome 已实现为 Gateway 本地有界队列、微批确认重试和 Controller 的 session/sequence/
|
||
摘要 Redis 栅栏；原始事件不落 Redis 或 PostgreSQL。Checker 已有全局健康 Reducer
|
||
与 Memory/Redis 原子状态提交基础；TARGET Profile 以独立、随代理 TTL 过期的 Redis
|
||
记录归并，不改写 Proxy 全局状态。Controller 公用 Reducer 已作为 Observation 的唯一状态
|
||
归并边界，Checker Observation RPC 已在同一控制面监听以独立 SPIFFE 身份接入；有界任务领取、
|
||
租约归属与任务期凭据传输已由通用契约和 gRPC 往返测试覆盖。Redis 共享 due-index、
|
||
任务/租约持久化、按上游的 in-flight 限制以及独立 Checker 的 HTTP/HTTPS/SOCKS5 BASIC/EGRESS/TARGET 执行
|
||
进程已经闭环；EGRESS 已具备多维任务索引、出口身份响应解析与生产调度；TARGET 已按
|
||
`(routing_name, target_url)` 的独立有界索引和调度组进入生产链。Snapshot 签发在 Redis 中原子匹配当前
|
||
`session_id`，重注册会清除旧引用，迟到旧 Stream 不会覆盖新 session。Controller
|
||
在最近成功下发的 Snapshot `valid_until` 到达时关闭流；Gateway 的公用
|
||
`SessionSupervisor` 已实现可恢复错误的有界退避重连。Gateway 会校验并执行 Snapshot
|
||
整体 `valid_until`，过期视图不再分配新 Proxy。
|
||
- `PostgreSQL 管理面`：已定义 `adminstate` 事务 seam、并发安全 MemoryStore、
|
||
公用契约、100 并发 Routing CAS、租约 Outbox 和只含六张管理表的 Schema；pgx
|
||
Adapter 已在真实 PostgreSQL 18 上通过同一契约、迁移幂等、审计/Outbox
|
||
故障回滚、原子批量 ACK 和 `information_schema` 数据边界验证。
|
||
Admin Handler 已向 mutation 传播 Actor/SourceIP。Admin ApplicationService 已
|
||
完成管理 mutation 映射、权威/运行态 Status 聚合、严格配置加载和持久化成功后
|
||
的原子发布；边界测试禁止其依赖 Redis Extract 或 Proxy 明细包。
|
||
|
||
## 2. 已执行验证
|
||
|
||
```text
|
||
go test ./... PASS
|
||
go vet ./... PASS
|
||
go build ./... PASS
|
||
PostgreSQL 18 shared contract PASS
|
||
protoc descriptor compilation PASS (local script; CI enforcement pending)
|
||
docker compose config PASS
|
||
kubectl kustomize PASS
|
||
configuration examples 21/21 PASS
|
||
Mermaid blocks 35
|
||
```
|
||
|
||
Windows 环境为 `CGO_ENABLED=0` 且没有 C 编译器，`go test -race` 在本机未执行；
|
||
CI 已配置 Linux race job。PostgreSQL 18 和 Redis 8.2 的隔离 Adapter fixture
|
||
已经运行；当前 Docker 镜像和激活的 Compose/Kubernetes 清单只包含已实现的
|
||
Controller/Gateway 入口，完整 mTLS 运行时拓扑仍只有静态验证。
|
||
|
||
## 3. 后续实现范围
|
||
|
||
以下已有设计、接口或部署位置，但尚无端到端生产实现：
|
||
|
||
1. `proxy-loadgen` 已提供有界 HTTP、HTTP Gateway CONNECT 长连接和 Distribution Extract
|
||
响应校验场景；`proxy-checker` 的 BASIC 任务进程已经完成，
|
||
`proxy-controller` 已完成
|
||
Admin/Distribution/Metrics 与 PostgreSQL/Redis 启动装配，`proxy-gateway` 已完成
|
||
HTTP/Metrics 与控制面 Session 装配；Checker、Gateway Outcome、Drain、Provider、
|
||
Extraction 与 Capacity 的低基数业务指标已闭环，密钥安全的结构化日志仍待补齐。
|
||
2. Gateway 的生产连接池调优与代表性流量压测。
|
||
3. Provider 分布式 singleflight/Leader、长期凭据回收和累计额度执行器。
|
||
4. Controller 的 PostgreSQL 连接池、迁移和 pgx Adapter 启动装配已完成；
|
||
公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成，Controller
|
||
三监听器与探针集成已完成；可选聚合指标和完整容器进程部署验证仍待实现。
|
||
5. Worker Register/ACK/Runtime gRPC 接收路径、Redis 服务端 TTL 会话生命周期、
|
||
SPIFFE mTLS 校验和 Controller 生命周期接线已完成；Redis Provider Leader、
|
||
分布式请求额度、Distribution Client 限制和 Provider 状态丢失重建已完成。
|
||
6. Worker 基础网络快照流、Proxy/Gateway Routing/凭据 Snapshot payload、Gateway Snapshot
|
||
客户端和进程装配、同版本 Routing 编译/动态匹配、五种策略上游选择与 reject/wait/direct 已完成；
|
||
Outcome 上报已完成基础观测链；Redis ownership drain/ACK/过期回收及按 Worker 的可下发索引已完成。
|
||
7. BASIC Checker 调度与 HTTP/HTTPS/SOCKS5 探测器、全局与 TARGET Profile 的 Memory/Redis
|
||
原子归并、Controller Reducer 和 Observation 上报 RPC 已完成；EGRESS、TARGET
|
||
生产任务调度与 REMOVE 编排仍待实现。
|
||
8. Admin/Distribution 细粒度授权和审计查询；Distribution 分布式限流已完成。
|
||
9. 真实 Compose/Kubernetes 集成、故障演练和代表性集群负载测试。
|
||
10. 将 reject/wait/direct 接入 Distribution 运行链，补齐 Sequential 持久化恢复、跨实例 CAS
|
||
和 disabled candidate 语义。
|
||
11. 补齐 Proxy Capacity 动态降容契约、Reservation 全生命周期观测；短 TTL
|
||
Proxy 的零计数运行态已在后续 Snapshot Apply 中回收。
|
||
|
||
## 4. 容量结论
|
||
|
||
100,000 QPS 是集群设计输入，不是本次验证结果。只有实现上述运行时，并在
|
||
记录协议比例、代理 RTT、连接复用、Worker 规格、故障域、CPU/RSS/FD、延迟
|
||
分位数和错误率的环境中通过持续压测后，才能声明已验证容量。
|