From 78fba161153f45f852412697205465f7b843ee62 Mon Sep 17 00:00:00 2001 From: youfak Date: Thu, 30 Jul 2026 11:38:57 +0800 Subject: [PATCH] docs: record controller bootstrap delivery --- docs/configuration/reference.md | 15 +++++++++++++-- docs/design/project-structure.md | 2 +- docs/development/implementation-plan.md | 12 +++++++++--- docs/operations/runbook.md | 12 +++++++++--- docs/requirements/completion-audit.md | 9 +++++---- docs/requirements/traceability.md | 4 ++-- docs/testing/strategy.md | 6 ++++++ docs/testing/test-strategy.md | 10 ++++++++++ progress.md | 18 ++++++++++++++++++ task_plan.md | 8 ++++++-- 10 files changed, 79 insertions(+), 17 deletions(-) diff --git a/docs/configuration/reference.md b/docs/configuration/reference.md index dbb598c..4478109 100644 --- a/docs/configuration/reference.md +++ b/docs/configuration/reference.md @@ -10,8 +10,15 @@ go run ./deploy/tools/configcheck deploy/config/local.yaml ``` -规划中的生产入口为 `proxy-controller -config CONFIG_FILE`；该命令完成实现和 -进程级测试前，不作为当前可执行能力。 +Controller 入口已实现，源码运行方式为： + +```powershell +go run ./cmd/proxy-controller -config CONFIG_FILE +``` + +配置路径优先使用 `-config`，未提供时读取 `PROXY_POOL_CONFIG`。该入口已装配 +PostgreSQL 管理面迁移、Redis 活动池、Distribution/Admin 独立监听与优雅停机； +Provider 自动补池、Metrics 探针和完整部署拓扑仍在后续实施范围。 所有时间值使用 Go duration，例如 `500ms`、`30s`、`5m`。示例中的 `${TOKEN}`、`${PASSWORD}`、`${POSTGRES_URL}` 等由加载器从同名环境变量 @@ -28,6 +35,10 @@ go run ./deploy/tools/configcheck deploy/config/local.yaml 新配置任何一步失败时保留旧快照。删除或禁用 Upstream 只停止新 Fetch 和新 分配，已有连接进入 Drain，不强制中断。 +当前 Controller 启动时使用同一份不可变快照完成存储、入口和提取策略装配。 +Admin 重载会原子提交新配置、审计并发布到配置 Store；监听地址、存储连接和 +已构造的安全/提取策略尚未自动重建，这些字段变更后需要重启 Controller。 + ## 2. 根结构 ```yaml diff --git a/docs/design/project-structure.md b/docs/design/project-structure.md index e80c569..ea4fbdd 100644 --- a/docs/design/project-structure.md +++ b/docs/design/project-structure.md @@ -13,7 +13,7 @@ proxy-pool/ │ ├── config/ # 严格配置解析和校验 │ ├── domain/ # 无传输、无存储依赖的领域模型 │ ├── gateway/ # snapshot、dispatch、server、transport -│ ├── controller/ # provider、pool、routing、extraction、health、runtime +│ ├── controller/ # provider、pool、extraction、operations、runtime、bootstrap │ ├── adapters/ # PostgreSQL、Redis、Provider API、内存适配 │ └── platform/ # HTTP、安全、日志、指标、停机和进程装配 ├── api/ # OpenAPI 与 Protobuf 契约 diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index b704bff..8cb25bb 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -37,7 +37,7 @@ internal/ domain/extraction/{extraction.go,store.go} domain/client/client.go gateway/{server,dispatch,snapshot,transport}/ - controller/{provider,pool,routing,extraction,health,distribution}/ + controller/{provider,pool,routing,extraction,health,distribution,operations,runtime,bootstrap}/ adapters/{memory,postgres,redis,providerapi}/ platform/{logging,metrics,shutdown}/ api/{openapi,proto}/ @@ -196,14 +196,20 @@ Admin/Distribution 必需依赖。共享 `platform/httpserver` 与 Repeatable Read 快照、`SKIP LOCKED`、原子 ACK、审计/Outbox 故障回滚和数据边界。 Admin `ApplicationService` 已将 mutation、权威管理快照、低基数运行态 聚合与配置重载接到同一公用 seam；严格文件加载、脱敏管理摘要及原子配置发布 -已通过失败路径和并发测试。生产命令入口及其连接池/迁移启动装配仍待实现。 +已通过失败路径和并发测试。`cmd/proxy-controller` 与公用 `controller/bootstrap` +已完成配置单次加载、PostgreSQL 连接/迁移、Redis 活动池、状态聚合、 +Distribution/Admin 服务构造、错误合并和资源关闭；Provider 调度、Metrics 探针 +及完整 HTTP 进程端到端测试仍待实现。双存储 bootstrap 已通过 PostgreSQL 18 + +Redis 8.2 组合 fixture，覆盖迁移、启动配置提交、Readiness 与 Admin Status。 已新增公用 `domain/activitypool` 契约及并发安全内存参考实现，Provider Reconciler 通过 `UpsertFetched` 写入带供应商 TTL 和分配安全余量的批次；已覆盖 `usableUntil` 向 Worker Snapshot 的传播与 Gateway 本地截止过滤、 重复刷新、过期淘汰、独占提取、短期幂等及 Worker ownership 互斥。生产 Redis Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆盖提取、所有权和 -有界清理。Redis Sentinel/故障转移验证与代表性多节点压测仍待实施。 +有界清理。新增低基数 StateInventory Hash，五类写脚本在同一原子边界维护状态 +计数，读取不扫描 Proxy 明细；过期清理积压或负计数时 fail-closed。Redis +Sentinel/故障转移验证与代表性多节点压测仍待实施。 ## Task 11: Checker and Health Reducer diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md index d83f800..4482d8c 100644 --- a/docs/operations/runbook.md +++ b/docs/operations/runbook.md @@ -18,9 +18,11 @@ ## 2. 本地拓扑模板 -当前仓库交付设计、契约、部署拓扑和关键领域实现；`cmd/proxy-*` 的完整运行时 -装配属于 `implementation-plan.md` 后续任务。此处 Compose/Kubernetes 资产用于 -评审网络、资源、探针和依赖关系，当前只执行静态渲染，不把模板写成可运行服务。 +`cmd/proxy-controller` 已完成配置单次加载、PostgreSQL 迁移、Redis 活动池、 +Distribution/Admin 服务和有界停机装配。Provider 自动补池、Metrics 探针， +以及 Gateway/Checker/Loadgen 三个进程仍属于 `implementation-plan.md` 后续任务。 +因此 Compose/Kubernetes 资产当前仍用于评审网络、资源、探针和依赖关系，不能 +视为完整可运行拓扑。 ### 2.1 前置条件 @@ -60,6 +62,10 @@ tmpfs。`ApplyMigrations` 在同一物理连接上执行仓库内嵌的幂等前 每个契约创建唯一 Schema，结束时只删除该 Schema 和临时 Compose 项目。该脚本 禁止指向开发或生产数据库。 +`.\scripts\test-controller.ps1` 同时启动两个隔离 fixture，验证 Controller +bootstrap 的迁移、启动配置提交、Redis Readiness 与 Admin Status。脚本不启动 +部署模板中的 Controller 容器，也不连接开发或生产存储。 + 目标拓扑入口： - Gateway：`127.0.0.1:8080` diff --git a/docs/requirements/completion-audit.md b/docs/requirements/completion-audit.md index e2df54d..3ac78c0 100644 --- a/docs/requirements/completion-audit.md +++ b/docs/requirements/completion-audit.md @@ -76,12 +76,13 @@ CI 已配置 Linux race job。PostgreSQL 18 和 Redis 8.2 的隔离 Adapter fixt 以下已有设计、接口或部署位置，但尚无端到端生产实现： -1. `cmd/proxy-gateway/controller/checker/loadgen` 进程装配。 +1. `cmd/proxy-gateway/checker/loadgen` 进程装配；`proxy-controller` 已完成 + Admin/Distribution 与 PostgreSQL/Redis 启动装配，但 Provider/Metrics 链未闭环。 2. Gateway 进程装配、生产连接池调优与代表性流量压测。 3. Provider 分布式 singleflight/Leader、长期凭据回收和累计额度执行器。 -4. PostgreSQL 连接池、迁移和 pgx Adapter 的生产命令启动装配，以及可选聚合指标； - Schema、领域 seam、Memory/pgx Adapter、真实 PostgreSQL 18 契约和 Admin - 应用层接线已经完成。 +4. Controller 的 PostgreSQL 连接池、迁移和 pgx Adapter 启动装配已完成； + 公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成，可选聚合指标和 + 完整 HTTP 进程部署验证仍待实现。 5. Redis Provider Leader、分布式速率与 Client 限制、Worker 心跳和自动重建； TTL 活动池、原子提取和 Worker ownership 已完成。 6. Worker 网络快照流；Redis ownership drain/ACK/过期回收已完成。 diff --git a/docs/requirements/traceability.md b/docs/requirements/traceability.md index 4b15758..7ae07dc 100644 --- a/docs/requirements/traceability.md +++ b/docs/requirements/traceability.md @@ -7,9 +7,9 @@ | ID | 最终需求 | 来源 | 验证证据 | |---|---|---|---| -| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；四个 `cmd/proxy-*` 构建产物待实现 | +| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；Controller 命令已实现，Gateway/Checker/Loadgen 构建产物待实现 | | ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | Snapshot/Dispatch 及依赖边界已验证；完整 Gateway 进程与代表性性能剖析待完成 | -| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Distribution/Admin 独立监听已测试；Gateway/Metrics 生产入口待装配 | +| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Controller 命令已装配 Distribution/Admin 独立监听；Gateway/Metrics 生产入口待装配 | | ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | 单进程 Reconciler、合并通知和切换领域契约已完成；分布式 Leader 与运行装配待完成 | | ARCH-005 | 100k QPS 峰值使用多 Worker 集群 | 当前会话 | 未验证设计目标；待代表性集群负载报告 | diff --git a/docs/testing/strategy.md b/docs/testing/strategy.md index c2d52b7..2da5c23 100644 --- a/docs/testing/strategy.md +++ b/docs/testing/strategy.md @@ -50,6 +50,12 @@ go build ./... 该 fixture 使用唯一命名空间，不执行 `FLUSHDB`，并关闭 AOF、RDB 与数据卷； 测试结束后按命名空间清理活动池、所有权和幂等键。 +Controller 的 PostgreSQL + Redis 启动组合测试使用： + +```powershell +.\scripts\test-controller.ps1 +``` + 单条测试命令超时 60 秒。依赖真实等待的用例必须改为 fake clock；集成和 soak 测试单独标记，不混入快速单测。 diff --git a/docs/testing/test-strategy.md b/docs/testing/test-strategy.md index 59b783e..62ce053 100644 --- a/docs/testing/test-strategy.md +++ b/docs/testing/test-strategy.md @@ -108,6 +108,16 @@ Routing CAS、Repeatable Read 快照、审计分页、Routing no-op、`SKIP LOCK 数据卷。静态与 `information_schema` 双重检查证明只存在六张管理表，且没有 Proxy、凭据、逐次提取、Worker ownership 或幂等明细列。 +Controller bootstrap 的双存储组合验证命令是： + +```powershell +.\scripts\test-controller.ps1 +``` + +该 fixture 同时启动 PostgreSQL 18 与 Redis 8.2，验证迁移、启动配置提交、 +Redis Readiness 和 Admin Status；HTTP Runner 使用测试 Adapter，避免占用业务 +监听端口。测试数据仅存在于隔离 Compose 项目和 PostgreSQL tmpfs。 + Admin 应用层测试覆盖 typed-nil 依赖、Actor/SourceIP 映射、Routing CAS 错误、 权威管理快照与低基数运行态聚合、未知字段拒绝、主配置/Secret 文件 I/O 分类、 持久化失败不发布、幂等重放发布、脱敏管理摘要和原子配置 Store 并发读写。静态 diff --git a/progress.md b/progress.md index 6d9a635..5c2cce8 100644 --- a/progress.md +++ b/progress.md @@ -2,6 +2,24 @@ ## 2026-07-30 +- 新增 `cmd/proxy-controller` 与公用 `controller/bootstrap.Run`；配置只加载一次， + 同一快照用于存储连接、PostgreSQL 管理态提交和 HTTP Runtime 构造，避免启动 + 期间二次读取产生配置撕裂。 +- Bootstrap 已封装 PostgreSQL Ping/迁移/pgx Adapter、Redis Ping/活动池、 + Distribution/Admin 服务构造、运行错误与关闭错误合并；`main` 仅处理 + `-config`、`PROXY_POOL_CONFIG`、信号上下文和退出码。 +- 活动池新增公用 `StateInventoryReader`；Memory/Redis 使用同一契约，Redis + 通过低基数 Hash 和五个原子 Lua 维护七类状态计数，不扫描 Proxy 明细。 +- 新增 `controller/operations.Reader`，把当前配置中的 Upstream 与活动状态映射到 + Admin Status；Worker/Snapshot 与 Provider 统计尚无来源时保持空/零，不用 + `Managed` 冒充 `Available`。 +- Redis 状态读取在有界过期清理仍有积压或检测到负计数时 fail-closed，避免 + Admin 返回包含失效代理或损坏计数的成功响应。 +- 本轮全仓 `go test -count=1 -timeout 60s ./...`、`go vet ./...`、 + `go build ./cmd/proxy-controller` 与 `git diff --check` 通过；新加的 Redis + backlog/负计数场景也已通过真实 Redis 8.2 fixture。 +- 新增 `test-controller.ps1` 双存储 fixture；真实 PostgreSQL 18 + Redis 8.2 已 + 通过迁移、启动配置提交、Redis Readiness 与 Admin Status 组合验证。 - 固定 `github.com/jackc/pgx/v5 v5.6.0`，实现封装在 `adminstate.Store` 后的 PostgreSQL 深适配器；配置、Upstream、Routing mutation 在同一事务中提交 revision、管理状态、审计与 Outbox，数据库错误不泄漏 DSN、SQL 或参数。 diff --git a/task_plan.md b/task_plan.md index 5eace91..bd0f197 100644 --- a/task_plan.md +++ b/task_plan.md @@ -33,6 +33,9 @@ 和真实 PostgreSQL 18 集成测试已完成 12. [进行中] 复核验收清单并收敛既有 Routing/Sequential 与 Proxy 容量边界； 机器契约和文档类滞后勾选已按仓库证据校正 +13. [进行中] 落地 `proxy-controller` 进程装配；配置单次加载、PostgreSQL 迁移、 + Redis 活动池、低基数状态聚合、Distribution/Admin 启动与关闭已完成， + 双存储 bootstrap 集成已通过，Provider/Metrics 与完整 HTTP 进程链仍待实现 ## 串并行关系 @@ -53,7 +56,8 @@ - Docker Compose 配置与 Kubernetes Kustomize 已完成静态渲染验证；Redis 8.2 与 PostgreSQL 18 的隔离 Adapter fixture 已运行，完整目标运行拓扑尚未启动。 -- `cmd/proxy-*`、PostgreSQL 管理面 Adapter、Provider Leader/分布式限流、 - Checker 运行时、Redis 故障转移验证与代表性集群压测属于后续实施范围。 +- `cmd/proxy-controller` 已实现 Admin/Distribution 与双存储启动装配；Gateway、 + Checker、Loadgen、Provider Leader/分布式限流、Metrics、Redis 故障转移验证与 + 代表性集群压测属于后续实施范围。 - `implementation-plan.md` 当前按 73 个验收项统计；已校正为 51 项完成， 验收项完成率约 69.9%，不等同于生产就绪度。