147 lines
10 KiB
Markdown
147 lines
10 KiB
Markdown
# 交付完成度审计
|
||
|
||
本文区分设计证据、机器契约、已运行验证和后续实施，防止把架构目标描述成
|
||
已完成产品。
|
||
|
||
## 1. 本次已交付
|
||
|
||
### 设计与开发文档
|
||
|
||
- 全量需求追踪、覆盖关系和统一领域语言。
|
||
- 产品设计、总体架构、项目结构、四项 ADR。
|
||
- 开发、配置、Distribution/Admin API、控制面协议、安全、测试、运维文档。
|
||
- 20 个配置场景和 35 张 Mermaid 架构/流程/状态/故障图。
|
||
- `scripts/package-docs.ps1` 可生成版本化 ZIP，包含 README、文档、图表、OpenAPI、Proto
|
||
契约，以及带 Git revision 和 SHA-256 的文件清单。
|
||
|
||
### 机器契约
|
||
|
||
- Distribution OpenAPI：一次性独占提取、partial/allOrNothing、幂等键、
|
||
Redis TTL 活动池原子语义、TTL/健康过滤结果与标准错误。
|
||
- Admin OpenAPI：状态、按 ID 游标分页的权威审计查询、Upstream 启停、Routing
|
||
切换和配置重载。
|
||
- 两份 OpenAPI 已进入 Go/CI 结构门禁，覆盖本地引用闭合、operationId、响应和
|
||
security scheme；固定版本的 Redocly CLI 还会按 OpenAPI 3.1 最小规则集验证两份文档，
|
||
并把 Tag 描述提升为错误。
|
||
- 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`：首条命中规则、Provider 空结果驱动的 Controller
|
||
Sequential 切换及末端 stop 已接入权威管理状态；跨 Controller 通过 PostgreSQL
|
||
`ExpectedCurrent` CAS 收敛，切换/停用均刷新本进程 Worker Snapshot。
|
||
- `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 已实现；Admin 审计查询以有界 `afterId` 游标读取 PostgreSQL 权威记录，
|
||
不读取 Proxy 或 Redis 活动池。共享认证、CIDR、可信代理、Client ID、凭据级
|
||
固定权限、Distribution 凭据级提取数量/Upstream/地区限制、Gateway 凭据级
|
||
Routing 限制与本地准入保护链已接入，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
|
||
bounded gateway microbenchmarks PASS (local baseline only)
|
||
```
|
||
|
||
Windows 环境为 `CGO_ENABLED=0` 且没有 C 编译器，`go test -race` 在本机未执行；
|
||
CI 已配置 Linux race job。PostgreSQL 18 和 Redis 8.2 的隔离 Adapter fixture
|
||
已经运行；本地 Compose 已声明 Controller、两个独立 Gateway 身份和一个 Checker 的
|
||
mTLS 运行拓扑，并由配置、证书、命令装配和部署契约测试覆盖。Kubernetes base 刻意不直接
|
||
启用 Checker；`development-mtls` Overlay 已为单副本 Controller、Gateway 和 Checker
|
||
提供固定开发证书、运行时身份派生、mTLS Secret 挂载、最小出站 NetworkPolicy 与渲染/配置契约验证。
|
||
其 ConfigMap 使用内容哈希以在配置变化时触发三个工作负载滚动；固定名称的外部 Secret 仍要求
|
||
受控轮换和显式重启。
|
||
Controller、Gateway 与 Checker 的叶证书和信任根已在每个新 TLS 握手时重载，文件短暂
|
||
不一致时保留最后一次有效材料。Gateway、Checker 启动派生和 Controller 授权共用同一
|
||
SPIFFE URI 解析器：X.509-SVID 叶证书必须且只能包含一个 URI SAN，并精确匹配其角色。
|
||
生产环境仍必须通过独立 Overlay 为每个弹性 Worker 注入唯一 SPIFFE URI，且容器端到端
|
||
启动仍待具备镜像网络的环境验证。
|
||
|
||
运维手册已覆盖管理面/活动池恢复顺序、发布与兼容回滚、Secret 轮换、容量计算，以及
|
||
主机内核、文件描述符、NAT/conntrack 的只读基线和证据采集要求；这些文档不替代真实环境
|
||
的备份恢复、驱逐或容量演练。
|
||
|
||
仓库审计会拒绝生产源和部署清单中的 `TODO`、`TBD`、`FIXME` 与私钥材料；原有 OpenAPI、
|
||
Queue、配置、指标和部署契约分别锁定一次性 Extract、队列容量、库存/累计获取边界及
|
||
低基数标签。根 `.dockerignore` 还会从镜像构建上下文排除本地控制面证书、私钥、环境文件和
|
||
构建产物。开发示例、环境变量引用和 CI fixture 不被视为生产 Secret 或未实现占位。
|
||
|
||
## 3. 后续实现范围
|
||
|
||
以下已有设计、接口或部署位置，但尚无端到端生产实现：
|
||
|
||
1. 已实现的 Controller、Gateway、Checker 和 Loadgen 进程仍需在实际容器网络中完成
|
||
mTLS、DNS、Redis/PostgreSQL 连通性、健康探针和优雅停机的端到端验证。
|
||
2. Gateway 已支持连接池、每 Host 连接上限、握手/空闲超时、隧道缓冲、请求生命周期指标
|
||
与 p99 告警；仍需代表性环境的流量压测和容量报告。
|
||
3. Provider 长期凭据回收与累计额度的生产运营策略仍需结合实际供应商合同、失效时间和
|
||
密钥平台完成演练。
|
||
4. Kubernetes 的开发 mTLS Overlay 已覆盖单副本开发证书身份派生和 Checker 出站
|
||
NetworkPolicy；生产环境仍需要按工作负载身份系统提供证书轮换、每副本唯一 Worker ID
|
||
与可弹性扩缩容的身份注入，base 清单不假定或伪造这些能力。
|
||
5. Redis/PostgreSQL 故障转移、控制面断线恢复、Snapshot 回滚、Drain 回收和 Extract
|
||
库存不足的完整故障演练。
|
||
6. 10k 稳态、100k 峰值、CONNECT 活跃连接和建连速率的代表性集群负载测试。
|
||
## 4. 容量结论
|
||
|
||
100,000 QPS 是集群设计输入，不是本次验证结果。只有实现上述运行时，并在
|
||
记录协议比例、代理 RTT、连接复用、Worker 规格、故障域、CPU/RSS/FD、延迟
|
||
分位数和错误率的环境中通过持续压测后，才能声明已验证容量。
|