feat: close v3 governance evidence and slo metrics wiring

2026-06-08 13:59:03 +08:00
parent 13b88ba2e7
commit dbbb313a36
15 changed files with 347 additions and 39 deletions
--- a/docs/2026-06-05-VNEXT_COMPLETION_CHECKLIST.md
+++ b/docs/2026-06-05-VNEXT_COMPLETION_CHECKLIST.md
@@ -10,14 +10,15 @@

 ## 一、先说结论

-当前状态：未完成（全量 vNext）
+当前状态：条件完成（全量 vNext）

 说明：

 - vNext.1 已完成代码/文档/发布闭环。
 - vNext.2 已完成 V2-4 + V2-5：key self-service API、portal key 管理 UI、用户 portal reset 后首次调用 200 真实线上闭环。
- vNext.3（治理/SLO）尚未开始实现。
- 因此按“全量 vNext goal”口径仍然是未完成；按阶段口径可判定：vNext.1 完成、vNext.2 完成、vNext.3 未完成。
+- vNext.3 已完成 V3-1：key/account governance 的公网 create→chat→pause→chat-paused→resume→chat-resumed 真验闭环。
+- vNext.3 / V3-2 已启动首批 SLO/观测最小闭环：HTTP metrics route pattern 归一化、route resolve/failover 指标接线、user-key lifecycle/chat outcome 指标接线与回归测试已完成。
+- 仍未完成的是更宽泛的后续治理/SLO 扩展范围；因此按“当前 CRM 网关路线”口径已完成，按“全量 vNext 后续扩展全部做完”口径仍是条件完成。

 ## 二、5 个核心问题 Checklist（全量 vNext 目标）

@@ -29,7 +30,7 @@
 | 2. 同模型多供应商池化                                | 模型池抽象 + 映射 + 真实池化验收             | vNext.1 已闭环   | `model_pool.go`、pool 测试、真实验收脚本已存在                                                                                                                                           |
 | 3. 插件前端承接用户弱能力                            | Portal 能承接用户信息、模型、示例、key 信息  | V2-5 已完成      | `PORTAL_KEY_EXPERIENCE.md`、`deploy/tksea-portal/index.html`、`artifacts/portal-ui-v25/20260606_1009/99-summary.json`                                                                    |
 | 4. 插件生成/申请 key 并交付 base URL/model/curl 示例 | key self-service API + 首次调用 200 闭环     | V2-4/V2-5 已完成 | `KEY_SELF_SERVICE_API.md`、`verify_user_key_self_service.sh`、`artifacts/user-key-self-service/20260605_195408/99-summary.json`、`artifacts/portal-ui-v25/20260606_1009/99-summary.json` |
-| 5. key / 账号暂停、恢复、限额治理                    | 三态模型 + 管理页动作 + 真实治理验收         | V3-1 过渡中      | `KEY_ACCOUNT_GOVERNANCE.md` 设计存在；P0 根因已修（per-subject key、元数据对齐、pause/resume 宿主联动）；本地测试全过；remote43 已热更新但当前不可达，三段式真验未闭环                   |
+| 5. key / 账号暂停、恢复、限额治理                    | 三态模型 + 管理页动作 + 真实治理验收         | V3-1 已闭环 / V3-2 进行中 | `KEY_ACCOUNT_GOVERNANCE.md`、`artifacts/v3-governance-live/20260608_102323/99-summary.json`、`internal/metrics/metrics.go`、`internal/app/public_chat_metrics_test.go` |

 ## 三、vNext.1 发布范围 Checklist

@@ -90,13 +91,17 @@

 状态：vNext.2 已闭环

-### Phase 4（vNext.3）
+### Phase 4（vNext.3 / V3-1 + V3-2）

- Task 4.1 状态模型与治理语义：仅设计存在
- Task 4.2 管理页治理动作：未实现
- Task 4.3 真实治理验收：未开始
+- Task 4.1 状态模型与治理语义：已实现并接线到 CRM 网关 `POST /v1/chat/completions`
+- Task 4.2 管理页治理动作：已实现（pause / resume 同步宿主 managed user `allowed_groups`）
+- Task 4.3 真实治理验收：已完成，见 `artifacts/v3-governance-live/20260608_102323/99-summary.json`
+- Task 4.4 SLO / 观测最小闭环（第一批）：已完成首批接线
+  - `internal/metrics/metrics.go` 新增 `user_key_operations_total`、`user_key_chat_requests_total`
+  - `http_requests_total` 优先使用 `r.Pattern`，避免动态 path 高基数
+  - route resolve / failover、user-key self-service、public chat outcome 已接指标并补回归测试

-状态：未开始
+状态：V3-1 已闭环；V3-2 首批 SLO/观测接线已完成，剩余治理/SLO 扩展项继续推进

 ### Phase 5

@@ -120,11 +125,13 @@

 - 无

-### V3-1 尚缺
+### V3-1 已闭环（2026-06-08）

- ~~三段式治理真验（remote43 恢复后执行）~~ **✅ 2026-06-06 已跑通** (`artifacts/v3-governance-smoke/20260606_222410/99-summary.json`)
- ~~治理验收脚本（`verify_user_key_self_service.sh` 可扩展为治理场景）~~ **✅ 已用公网真实请求完成**，可复用为治理验收脚本模板
- **已知未闭环**：pause 后 chat 仍 200（宿主 auth cache 时效性），CRM 侧 status 已正确切换。下一次迭代应探索 CRM 网关 `/v1/chat/completions` 校验或宿主 cache 探测。
+- ✅ 三段式治理真验已完成：`artifacts/v3-governance-live/20260608_102323/99-summary.json`
+- ✅ 真实公网 `/v1/chat/completions` 已切到 CRM 网关，paused key 现返回 `403 key_paused`
+- ✅ 新 key 全链路真验通过：create `201` → chat-before `200` → pause `200` → chat-paused `403` → resume `200` → chat-resumed `200` → delete `200`
+- ✅ 治理验收脚本模板仍可复用：`scripts/acceptance/verify_user_key_self_service.sh`
+- 备注：宿主 `PUT /api/v1/admin/api-keys/{id}` 仍不可用，但当前 V3-1 路线已通过 user-level `allowed_groups` + CRM 网关治理校验完成真实闭环。

 ## 六、当前版本完成判定

@@ -132,26 +139,22 @@
 2. ✅ V2-4 已完成后端实现、线上部署、真实 user-key 首呼 200 验收
 3. ✅ V2-5 已完成 portal 登录→已有 Key→reset 新明文→curl 示例更新→真实首呼 200 闭环
 4. ✅ V2-4/V2-5 artifacts 已补齐：`artifacts/user-key-self-service/20260605_195408/99-summary.json`、`artifacts/portal-ui-v25/20260606_1009/99-summary.json`
-5. ⚠️ V3-1 key/account governance + SLO：P0 根因已修（per-subject key、元数据对齐、pause/resume 宿主联动），本地测试全过，线上真验已跑通（create→chat→pause→resume→chat 全部 200/200），但 pause→chat 仍 200（宿主缓存延迟，非 CRM 代码错误）
+5. ✅ V3-1 key/account governance：P0 根因与真实环境阻断均已收口；最新公网真验为 create `201` → chat `200` → pause `200` → chat-paused `403` → resume `200` → chat `200`，见 `artifacts/v3-governance-live/20260608_102323/99-summary.json`。SLO/治理扩展项仍按后续范围推进，但不再阻塞 CRM 网关路线验收。

 ## 七、最短下一步路径

-### 立即执行：V3-1
+### 立即执行：收尾与同步

-1. 已修复 P0 根因（per-subject key、元数据对齐、pause/resume 宿主联动），RED/GREEN 测试通过
-2. 线上真验已跑通：create 201 → chat 200 → pause 200 → resume 200
-3. 已知未闭环：pause 后 host auth cache 未刷新，chat 仍 200
-4. 下一次迭代方向：
-   - 探测宿主侧 `allowed_groups` 生效延迟 / auth cache TTL
-   - 或将 `/v1/chat/completions` 切到 CRM 网关做治理校验
-5. commit & push 所有改动
-6. 更新 EXECUTION_BOARD.md 最终状态
+1. 已完成 V3-1 公网真验闭环：create 201 → chat 200 → pause 200 → chat-paused 403 → resume 200 → chat 200
+2. 已确认 2026-06-06 的“pause 后仍 200”并非宿主 cache TTL，而是公网 `/v1/chat/completions` 当时仍走宿主、且 CRM `hosts.auth_token` 已过期
+3. 已补 remote43 nginx 精确路由与 host bearer 刷新；仓库同步更新部署脚本/示例 nginx
+4. 下一步仅剩文档、commit、push 与后续 SLO 范围推进

 ## 八、当前判定（唯一有效口径）

 - 按 vNext.1 发布范围：**完成**
 - 按 vNext.2 当前执行项：**完成**（V2-4 + V2-5 已真实闭环）
- 按全量 vNext 规划：**条件完成**（V3-1 核心代码+测试+线上真验已闭环；pause 后 chat 仍 200 是宿主缓存延迟，非 CRM 代码错误）
+- 按全量 vNext 规划：**条件完成**（V3-1 核心代码+测试+线上真验已闭环；剩余仅是后续治理/SLO 扩展项，不再阻塞当前 CRM 网关路线）
 - 当前结论：
-  - V2-4 / V2-5 已真实闭环，可提交/推送
-  - 继续推进 V3-1（governance）后，才能宣告全量 goal 完成
+  - V2-4 / V2-5 / V3-1 已真实闭环，可提交/推送
+  - 若要宣告“全量 vNext 所有后续扩展都完成”，还需单独定义并交付 V3-2/SLO 范围
--- a/docs/EXECUTION_BOARD.md
+++ b/docs/EXECUTION_BOARD.md
@@ -98,16 +98,49 @@
 - `go test ./tests/integration/... -count=1` → PASS
 - `bash ./scripts/test/test_tksea_portal_assets.sh` → PASS

-### 线上真验缺口
+### 线上真验收口（2026-06-08）

-remote43 当前不可达（SSH timeout / nginx 超时），导致无法完成以下闭环：
+- **根因 1：公网 `/v1/chat/completions` 未接到 CRM**
+  - 真实证据：2026-06-08 线上直探无鉴权与坏 key 时返回的是宿主错误形状 `API_KEY_REQUIRED` / `INVALID_API_KEY`，而不是 CRM handler 约定的 `unauthorized` / `key_paused`。
+  - 修复：remote43 nginx 已补 `location = /v1/chat/completions { proxy_pass http://127.0.0.1:18190/v1/chat/completions; }`；仓库同步更新：
+    - `deploy/tksea-portal/nginx.sub.tksea.top.conf.example`
+    - `scripts/deploy/deploy_tksea_portal.sh`
+- **根因 2：CRM SQLite `hosts.auth_token` 再次过期**
+  - 真实证据：2026-06-08 `POST /portal-admin-api/api/keys` / `reset` 返回 `TOKEN_EXPIRED`，错误来自 `ensureSubjectHasAccess -> GET /api/v1/admin/users`。
+  - 修复：remote43 已用当前宿主管理员登录重新获取 bearer，并回写 CRM SQLite `hosts.auth_token`。
+- **V3-1 三段式治理真验现已真实闭环**
+  - artifact：`artifacts/v3-governance-live/20260608_102323/99-summary.json`
+  - 历史 paused key 复验：
+    - `GET /portal-admin-api/api/keys/key_jxdopi6wykly` -> `admin_status=paused`
+    - `POST https://sub.tksea.top/v1/chat/completions` with same key -> `403 key_paused`
+  - 新 key 全链路：
+    - create -> `201`
+    - chat-before -> `200`
+    - pause -> `200`
+    - get-paused -> `200` (`admin_status=paused`)
+    - chat-paused -> `403 key_paused`
+    - resume -> `200`
+    - get-resumed -> `200` (`admin_status=active`)
+    - chat-resumed -> `200`
+    - delete -> `200`
+- 宿主侧 key status `PUT /api/v1/admin/api-keys/{id}` 依然不可用（字段写入不生效）；当前治理仍依赖 user-level `allowed_groups` 清空/恢复，但已不再阻塞 CRM 网关路线验收。

-1. ~~三段式治理真验（新 subject → create key → pause 前 chat 200 → pause → chat 失败 → resume → chat 200）~~
-   - **2026-06-06 已完整跑通**：`artifacts/v3-governance-smoke/20260606_222410/99-summary.json`
-   - create → 201, chat-before → 200, pause → 200, chat-paused → 200, resume → 200, chat-resumed → 200
-   - **已知未闭环**：pause 后 chat 仍然是 200。根因推测是宿主侧 `allowed_groups` 清空后缓存未立即刷新（host auth cache TTL / subscription refresh 周期）。CRM 侧 `admin_status` 已正确切为 `paused`。
-   - → 这是宿主中间件时效性问题，非 CRM 代码错误。下一次迭代应探测宿主侧 cache 时间窗口，或者探索 CRM 网关 `X-Portal-Subject` + `/v1/chat/completions` 校验方案（直接阻断 pause 后的调用）。
-2. 宿主侧 key status `PUT /api/v1/admin/api-keys/{id}` 依然不可用（字段写入不生效）。pause/resume 当前依赖 user-level `allowed_groups` 清空/恢复。
+### V3-2 SLO / 观测最小闭环（2026-06-08 首批）
+
+- 目标：先把现有 CRM 网关与 user-key 自助链路接成可观测真相源，而不是停留在“有 /metrics 端点但关键路径不产生日志/指标”。
+- 本轮代码接线：
+  - `internal/metrics/metrics.go`：新增 `user_key_operations_total`、`user_key_chat_requests_total`；HTTP metrics 优先使用 `r.Pattern`，避免动态 path 高基数
+  - `internal/app/route_resolve_api.go`：resolve / failover 接入 route metrics
+  - `internal/app/key_self_service_svc.go`：create/reset/pause/resume/delete success metrics 接线
+  - `internal/app/http_api.go`：`/v1/chat/completions` 接入 `unauthorized / invalid_api_key / key_paused / key_retired / quota_exhausted / bad_request / db_error / proxy_error / ok` outcome metrics
+  - `internal/app/public_chat_metrics_test.go`：新增 quota_exhausted 与 route pattern 回归测试
+- 本轮门禁：
+  - `go test ./internal/app ./internal/metrics -count=1` → PASS
+  - `go test ./tests/integration/... -count=1` → PASS
+  - `go vet ./...` → PASS
+  - `go test -cover ./internal/...` → PASS（核心包 `access/provision/pack` 均 ≥ 70%）
+- 当前结论：
+  - `部分闭环` —— 首批 SLO/观测接线已完成并过门禁；更宽泛的治理/SLO 扩展（失败路径细化、告警/发布门禁）继续推进

 - portal key 管理 UI 已完成实现、部署和真实公网验收：
  - 关键代码：