diff --git a/docs/configuration/reference.md b/docs/configuration/reference.md index 4478109..08fc7e1 100644 --- a/docs/configuration/reference.md +++ b/docs/configuration/reference.md @@ -18,7 +18,8 @@ go run ./cmd/proxy-controller -config CONFIG_FILE 配置路径优先使用 `-config`，未提供时读取 `PROXY_POOL_CONFIG`。该入口已装配 PostgreSQL 管理面迁移、Redis 活动池、Distribution/Admin 独立监听与优雅停机； -Provider 自动补池、Metrics 探针和完整部署拓扑仍在后续实施范围。 +Controller Metrics 独立监听、`/livez`、`/readyz` 和基础 Prometheus 运行时指标； +Provider 自动补池、业务指标和完整部署拓扑仍在后续实施范围。 所有时间值使用 Go duration，例如 `500ms`、`30s`、`5m`。示例中的 `${TOKEN}`、`${PASSWORD}`、`${POSTGRES_URL}` 等由加载器从同名环境变量 @@ -357,6 +358,13 @@ PostgreSQL 只保存配置版本、Upstream/Routing 管理状态、Admin 审计 PostgreSQL 故障本身不应使 Redis 中可完成的 Extract 返回 `503`。Metrics 标签 禁止 Proxy IP、Client ID、Session、完整 URL 和 Request ID。 +Metrics 启用时 `listen` 必须是合法 `host:port`。该入口固定提供 `/livez`、 +`/readyz` 和 `/metrics`，不复用 Distribution/Admin 的认证边界；外部访问必须由 +网络策略限制。当前 `/metrics` 已包含 Go/进程基础指标，Provider、提取和容量等 +业务指标仍在后续实施范围。Distribution 启用时 `/readyz` 只以 Redis 活动池为 +服务流量门槛，PostgreSQL 故障由 Admin 接口独立报告。Metrics 开关或监听地址 +变更需要重启 Controller。 + ## 9. 启动前校验清单 1. `version` 必须为 `1`，未知字段拒绝。 diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index 8cb25bb..991e9ea 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -198,9 +198,11 @@ 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。 +Distribution/Admin 服务构造、错误合并和资源关闭；Provider 调度及完整 HTTP +进程端到端测试仍待实现。Controller Metrics 独立入口现已提供 `/livez`、 +`/readyz` 与基础 Prometheus 运行时指标，三监听器隔离已通过测试；业务指标仍待 +实现。双存储 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 组合 fixture，覆盖 +迁移、启动配置提交、Readiness、Admin Status 和 Metrics 探针。 已新增公用 `domain/activitypool` 契约及并发安全内存参考实现，Provider Reconciler 通过 `UpsertFetched` 写入带供应商 TTL 和分配安全余量的批次；已覆盖 diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md index 4482d8c..ca4a951 100644 --- a/docs/operations/runbook.md +++ b/docs/operations/runbook.md @@ -19,8 +19,9 @@ ## 2. 本地拓扑模板 `cmd/proxy-controller` 已完成配置单次加载、PostgreSQL 迁移、Redis 活动池、 -Distribution/Admin 服务和有界停机装配。Provider 自动补池、Metrics 探针， -以及 Gateway/Checker/Loadgen 三个进程仍属于 `implementation-plan.md` 后续任务。 +Distribution/Admin/Metrics 独立监听和有界停机装配。Provider 自动补池、业务 +指标以及 Gateway/Checker/Loadgen 三个进程仍属于 `implementation-plan.md` +后续任务。 因此 Compose/Kubernetes 资产当前仍用于评审网络、资源、探针和依赖关系，不能 视为完整可运行拓扑。 @@ -63,7 +64,8 @@ tmpfs。`ApplyMigrations` 在同一物理连接上执行仓库内嵌的幂等前 禁止指向开发或生产数据库。 `.\scripts\test-controller.ps1` 同时启动两个隔离 fixture，验证 Controller -bootstrap 的迁移、启动配置提交、Redis Readiness 与 Admin Status。脚本不启动 +bootstrap 的迁移、启动配置提交、Redis Readiness、Admin Status、`/readyz` 与 +Prometheus 输出。脚本不启动 部署模板中的 Controller 容器，也不连接开发或生产存储。 目标拓扑入口： @@ -71,6 +73,7 @@ bootstrap 的迁移、启动配置提交、Redis Readiness 与 Admin Status。 - Gateway：`127.0.0.1:8080` - Distribution：`http://127.0.0.1:8081` - Admin：`http://127.0.0.1:8082` +- Controller Metrics：`http://127.0.0.1:9090` - HAProxy 状态：`http://127.0.0.1:8404/stats` - Prometheus：`http://127.0.0.1:9091` - Grafana：`http://127.0.0.1:3000` @@ -111,6 +114,9 @@ kubectl -n proxy-pool rollout status deployment/proxy-gateway --timeout=10m 的完整 Snapshot 且仍有准入能力时才 Ready。 - Controller 按能力判定就绪：Distribution/Fetch 依赖 Redis 活动池，Admin 持久化 写依赖 PostgreSQL 与兼容迁移。PostgreSQL 故障不得单独使 Extract 返回 503。 +- 同一 Controller 同时启用 Distribution 与 Admin 时，Pod `/readyz` 以 Redis + 活动池为服务流量门槛；PostgreSQL 故障由 Admin 接口独立返回不可用，不把仍可 + 完成的 Extract 从 Service 摘除。Admin-only 进程才同时检查 PostgreSQL 与 Redis。 - Checker 在任务消费与结果上报通道可用时 Ready。 - `/metrics`：独立于业务入口，NetworkPolicy 仅允许监控命名空间访问。 diff --git a/docs/requirements/completion-audit.md b/docs/requirements/completion-audit.md index 3ac78c0..b1d7d54 100644 --- a/docs/requirements/completion-audit.md +++ b/docs/requirements/completion-audit.md @@ -77,12 +77,13 @@ CI 已配置 Linux race job。PostgreSQL 18 和 Redis 8.2 的隔离 Adapter fixt 以下已有设计、接口或部署位置，但尚无端到端生产实现： 1. `cmd/proxy-gateway/checker/loadgen` 进程装配；`proxy-controller` 已完成 - Admin/Distribution 与 PostgreSQL/Redis 启动装配，但 Provider/Metrics 链未闭环。 + Admin/Distribution/Metrics 与 PostgreSQL/Redis 启动装配，但 Provider 和业务 + 指标链未闭环。 2. Gateway 进程装配、生产连接池调优与代表性流量压测。 3. Provider 分布式 singleflight/Leader、长期凭据回收和累计额度执行器。 4. Controller 的 PostgreSQL 连接池、迁移和 pgx Adapter 启动装配已完成； - 公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成，可选聚合指标和 - 完整 HTTP 进程部署验证仍待实现。 + 公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成，Controller + 三监听器与探针集成已完成；可选聚合指标和完整容器进程部署验证仍待实现。 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 7ae07dc..c0ad906 100644 --- a/docs/requirements/traceability.md +++ b/docs/requirements/traceability.md @@ -9,7 +9,7 @@ |---|---|---|---| | 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 | Controller 命令已装配 Distribution/Admin 独立监听；Gateway/Metrics 生产入口待装配 | +| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Controller 命令已装配 Distribution/Admin/Metrics 三个独立监听及联动停机；Gateway 生产入口待装配 | | ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | 单进程 Reconciler、合并通知和切换领域契约已完成；分布式 Leader 与运行装配待完成 | | ARCH-005 | 100k QPS 峰值使用多 Worker 集群 | 当前会话 | 未验证设计目标；待代表性集群负载报告 | @@ -86,5 +86,5 @@ | OPS-001 | 配置校验后构建不可变快照并原子替换 | 8959-8999 | 100k 索引、版本/epoch 与并发 Apply/Acquire 测试 | | OPS-002 | 优雅停机停止新请求/Fetch，等待现有流量后超时关闭 | 8981-9000 | Provider Run 收敛与 `Handler.Shutdown` HTTP 排空、Hijacked CONNECT 超时关闭测试 | | OPS-003 | PostgreSQL 只保存管理修订、Upstream/Routing 状态、Admin 审计与 Outbox | 当前会话 | ADR-006、`adminstate` 公用契约和六表 Schema 边界测试；真实 PostgreSQL 契约待完成 | -| OBS-001 | 指标禁止 Proxy IP、session、Client、完整 URL 高基数标签 | 9001-9029 | 文档和配置已约束；Prometheus 指标模块及描述符测试待实现 | +| OBS-001 | 指标禁止 Proxy IP、session、Client、完整 URL 高基数标签 | 9001-9029 | Controller Prometheus/探针模块已实现且当前只暴露无业务标签的 Go/进程指标；低基数业务 Collector 与描述符测试待实现 | | TEST-001 | 覆盖对话中列出的 11 个关键并发与故障场景 | 9030-9082 | 测试清单；Redis 活动池由 Memory/Redis 公用契约覆盖，跨进程故障场景仍按清单推进 | diff --git a/progress.md b/progress.md index 5c2cce8..105b6c1 100644 --- a/progress.md +++ b/progress.md @@ -2,6 +2,16 @@ ## 2026-07-30 +- 新增公用 `platform/metrics.NewHandler`，固定提供 `/livez`、`/readyz` 与 + `/metrics`；Readiness 失败只返回脱敏状态，不泄露底层存储错误。 +- Metrics 地址进入严格配置校验；Controller Runtime 支持 Metrics-only 和 + Distribution/Admin/Metrics 三监听器隔离、首错联动及统一优雅停机。 +- Controller bootstrap 使用同一根生命周期装配 Prometheus 默认 Gatherer， + Metrics Readiness 按启用能力低成本检查 PostgreSQL/Redis，不触发 Provider 或 + 扫描 Proxy 明细。 +- `go test` 定向包和 `.\scripts\test-controller.ps1` 通过；真实 PostgreSQL 18 + + Redis 8.2 fixture 已验证 `/readyz` 与 Prometheus 输出，临时容器和网络已清理。 + - 新增 `cmd/proxy-controller` 与公用 `controller/bootstrap.Run`；配置只加载一次， 同一快照用于存储连接、PostgreSQL 管理态提交和 HTTP Runtime 构造，避免启动 期间二次读取产生配置撕裂。 diff --git a/task_plan.md b/task_plan.md index bd0f197..934355c 100644 --- a/task_plan.md +++ b/task_plan.md @@ -34,8 +34,8 @@ 12. [进行中] 复核验收清单并收敛既有 Routing/Sequential 与 Proxy 容量边界； 机器契约和文档类滞后勾选已按仓库证据校正 13. [进行中] 落地 `proxy-controller` 进程装配；配置单次加载、PostgreSQL 迁移、 - Redis 活动池、低基数状态聚合、Distribution/Admin 启动与关闭已完成， - 双存储 bootstrap 集成已通过，Provider/Metrics 与完整 HTTP 进程链仍待实现 + Redis 活动池、低基数状态聚合、Distribution/Admin/Metrics 启动与关闭已完成， + 双存储 bootstrap 和探针集成已通过，Provider、业务指标与完整容器进程链仍待实现 ## 串并行关系 @@ -56,8 +56,8 @@ - Docker Compose 配置与 Kubernetes Kustomize 已完成静态渲染验证；Redis 8.2 与 PostgreSQL 18 的隔离 Adapter fixture 已运行，完整目标运行拓扑尚未启动。 -- `cmd/proxy-controller` 已实现 Admin/Distribution 与双存储启动装配；Gateway、 - Checker、Loadgen、Provider Leader/分布式限流、Metrics、Redis 故障转移验证与 - 代表性集群压测属于后续实施范围。 +- `cmd/proxy-controller` 已实现 Admin/Distribution/Metrics 与双存储启动装配； + Gateway、Checker、Loadgen、Provider Leader/分布式限流、业务指标、Redis + 故障转移验证与代表性集群压测属于后续实施范围。 - `implementation-plan.md` 当前按 73 个验收项统计；已校正为 51 项完成， 验收项完成率约 69.9%，不等同于生产就绪度。