docs: record controller metrics delivery

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`，未知字段拒绝。

docs/development/implementation-plan.md

@@ -198,9 +198,11 @@ Admin `ApplicationService` 已将 mutation、权威管理快照、低基数运
 聚合与配置重载接到同一公用 seam；严格文件加载、脱敏管理摘要及原子配置发布
 已通过失败路径和并发测试。`cmd/proxy-controller` 与公用 `controller/bootstrap`
 已完成配置单次加载、PostgreSQL 连接/迁移、Redis 活动池、状态聚合、
-Distribution/Admin 服务构造、错误合并和资源关闭；Provider 调度、Metrics 探针
+Distribution/Admin 服务构造、错误合并和资源关闭；Provider 调度及完整 HTTP
-及完整 HTTP 进程端到端测试仍待实现。双存储 bootstrap 已通过 PostgreSQL 18 +
+进程端到端测试仍待实现。Controller Metrics 独立入口现已提供 `/livez`、
-Redis 8.2 组合 fixture，覆盖迁移、启动配置提交、Readiness 与 Admin Status。
+`/readyz` 与基础 Prometheus 运行时指标，三监听器隔离已通过测试；业务指标仍待
+实现。双存储 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 组合 fixture，覆盖
+迁移、启动配置提交、Readiness、Admin Status 和 Metrics 探针。
 
 已新增公用 `domain/activitypool` 契约及并发安全内存参考实现，Provider
 Reconciler 通过 `UpsertFetched` 写入带供应商 TTL 和分配安全余量的批次；已覆盖

docs/operations/runbook.md

@@ -19,8 +19,9 @@
 ## 2. 本地拓扑模板
 
 `cmd/proxy-controller` 已完成配置单次加载、PostgreSQL 迁移、Redis 活动池、
-Distribution/Admin 服务和有界停机装配。Provider 自动补池、Metrics 探针，
+Distribution/Admin/Metrics 独立监听和有界停机装配。Provider 自动补池、业务
-以及 Gateway/Checker/Loadgen 三个进程仍属于 `implementation-plan.md` 后续任务。
+指标以及 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 仅允许监控命名空间访问。
 

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 双存储集成，可选聚合指标和
+   公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成，Controller
-   完整 HTTP 进程部署验证仍待实现。
+   三监听器与探针集成已完成；可选聚合指标和完整容器进程部署验证仍待实现。
 5. Redis Provider Leader、分布式速率与 Client 限制、Worker 心跳和自动重建；
    TTL 活动池、原子提取和 Worker ownership 已完成。
 6. Worker 网络快照流；Redis ownership drain/ACK/过期回收已完成。

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 公用契约覆盖，跨进程故障场景仍按清单推进 |

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 构造，避免启动
   期间二次读取产生配置撕裂。

task_plan.md

@@ -34,8 +34,8 @@
 12. [进行中] 复核验收清单并收敛既有 Routing/Sequential 与 Proxy 容量边界；
     机器契约和文档类滞后勾选已按仓库证据校正
 13. [进行中] 落地 `proxy-controller` 进程装配；配置单次加载、PostgreSQL 迁移、
-    Redis 活动池、低基数状态聚合、Distribution/Admin 启动与关闭已完成，
+    Redis 活动池、低基数状态聚合、Distribution/Admin/Metrics 启动与关闭已完成，
-    双存储 bootstrap 集成已通过，Provider/Metrics 与完整 HTTP 进程链仍待实现
+    双存储 bootstrap 和探针集成已通过，Provider、业务指标与完整容器进程链仍待实现
 
 ## 串并行关系
 
@@ -56,8 +56,8 @@
 
 - Docker Compose 配置与 Kubernetes Kustomize 已完成静态渲染验证；Redis 8.2
   与 PostgreSQL 18 的隔离 Adapter fixture 已运行，完整目标运行拓扑尚未启动。
-- `cmd/proxy-controller` 已实现 Admin/Distribution 与双存储启动装配；Gateway、
+- `cmd/proxy-controller` 已实现 Admin/Distribution/Metrics 与双存储启动装配；
-  Checker、Loadgen、Provider Leader/分布式限流、Metrics、Redis 故障转移验证与
+  Gateway、Checker、Loadgen、Provider Leader/分布式限流、业务指标、Redis
-  代表性集群压测属于后续实施范围。
+  故障转移验证与代表性集群压测属于后续实施范围。
 - `implementation-plan.md` 当前按 73 个验收项统计；已校正为 51 项完成，
   验收项完成率约 69.9%，不等同于生产就绪度。