From ef7131c15bb5f0aa34542885e1682adae9a95b10 Mon Sep 17 00:00:00 2001 From: sunlei Date: Thu, 18 Jun 2026 14:15:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85Jenkins=E5=92=8CK8s?= =?UTF-8?q?=E5=8F=AA=E8=AF=BB=E8=A7=82=E6=B5=8B=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...6-18-admin-environment-dashboard-design.md | 59 ++++++++++++------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md b/docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md index ccd199d..4888cbf 100644 --- a/docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md +++ b/docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md @@ -11,9 +11,9 @@ Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、 - Admin `/dashboard/analytics` 当前是静态页面，可整体替换。 - Admin 已有 QQBot、插件任务、系统日志、Blog/Asset 等 API wrapper，但没有统一环境状态 wrapper。 - API 已有 runtime health、系统日志、QQBot 汇总、NapCat runtime、插件平台、插件任务、MinIO 和 WordPress 信号源。 -- API 源码内没有 Jenkins/K8s/部署状态 Controller 或 Service；实时部署观察目前主要靠 `mcp/ktWorkflow` 与 NAS/K8s 外部命令。 +- API 源码内没有 Jenkins/K8s/部署状态 Controller 或 Service；实时部署观察目前主要靠 `mcp/ktWorkflow` 与 NAS/K8s 外部命令。本轮需要补齐 Jenkins/K8s 只读观测适配器，但只允许读取发布证据，不允许执行部署或 K8s 写操作。 -因此第一版必须采用“API 统一聚合合同 + Admin 拓扑消费”的结构：页面不散拼多个旧接口；API 不伪造未接入的环境状态；高风险动作先显式禁用或跳转，不直接执行。 +因此第一版必须采用“API 统一聚合合同 + Admin 拓扑消费”的结构：页面不散拼多个旧接口；API 不伪造环境状态；Jenkins/K8s 作为只读观测节点接入；高风险动作先显式禁用或跳转，不直接执行。 ## 已确认决策 @@ -23,7 +23,7 @@ Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、 4. 第一版只允许低风险动作：刷新、执行只读自检、打开日志、跳转到已有管理页、打开外部只读入口。 5. 重启 Pod、触发 Jenkins 部署、DB 写入、重建 NapCat 容器、启停插件或定时任务等高风险动作，第一版只能作为 disabled action 展示原因和未来入口。 6. API 聚合接口必须受 Admin JWT 保护，返回 Vben 统一响应，不泄露密钥、token、原始 env、QQBot 大字段或未脱敏日志。 -7. Jenkins/K8s 如果暂时没有可由 API 安全读取的凭据或适配器，也必须在拓扑中显示为 `unknown` / `unwired`，不能从页面消失或伪造成正常。 +7. Jenkins/K8s 第一版必须接入只读观测：Jenkins 读取最近构建、提交、结果和时间；K8s 读取 Deployment、Pod、镜像、ready 数、restartCount 和事件摘要。缺配置或读取失败时显示 `unknown` / `down` 与失败证据，不能显示 `unwired` 或伪造成健康。 ## 目标 @@ -32,15 +32,16 @@ Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、 - 把现有分散信号源收敛到一个只读聚合服务，保持每个信号源可独立降级。 - 在 UI 上明确区分 `ok`、`degraded`、`down`、`blocked`、`unknown`、`unwired`。 - 用证据字段解释每个状态来自哪里、何时检查、是否实时、是否缓存、失败原因是什么。 -- 为后续接入 Jenkins/K8s 只读观测、部署记录、任务运行历史和自动化恢复留出合同扩展点。 +- 接入 Jenkins/K8s 只读观测，展示线上部署链路状态，但不提供任何操作能力。 +- 为后续部署记录历史、任务运行历史和自动化恢复留出合同扩展点。 ## 非目标 - 不在第一版执行部署、重启、数据库写入、插件启停、NapCat 容器重建等高风险动作。 - 不把 Admin 页面做成营销式图表页或静态展示页。 - 不绕过现有 QQBot、NapCat、插件平台、WordPress、MinIO 的业务边界。 -- 不要求 API Pod 内直接持有生产 kubeconfig、Jenkins 写权限或 NAS SSH 写权限。 -- 不把外部不可读的 Jenkins/K8s 状态假装成健康。 +- 不要求 API Pod 内持有 Jenkins 写权限、K8s 写权限或 NAS SSH 写权限。 +- 不把 Jenkins/K8s 读态失败、凭据缺失或 RBAC 缺失假装成健康。 - 不在本轮新增长期运行的后台巡检任务或历史表，除非后续实施计划明确需要。 ## 信息架构 @@ -126,7 +127,7 @@ QQBot 层 - `external-link`：只能提供外部入口，API 不能直接读取。 - `unwired`：设计中必须存在，但当前未接入真实信号。 -拓扑节点不得因为没有接入真实读取就隐藏。未接入的 Jenkins/K8s 节点第一版应显示为 `unknown` 或 `unwired`，并在证据抽屉写明“API 当前没有只读观测适配器”。 +拓扑节点不得因为没有接入真实读取就隐藏。Jenkins/K8s 在第一版必须接入只读观测适配器；如果配置、网络、凭据或 RBAC 缺失，节点状态应为 `unknown` 或 `down`，证据抽屉写明具体失败点，不能再标为 `unwired`。 ## API 合同 @@ -407,8 +408,10 @@ blocked > down > degraded > unknown/unwired > ok 来源： -- 第一版默认 `unwired` / `external-link`。 -- 如果后续配置只读 Jenkins token、只读 K8s service account 或 deploy-observation evidence 文件，才能升级为 `live` 或 `cached`。 +- Jenkins 只读 API：读取指定 job 的最近 build number、result、building、timestamp、duration、commit/hash、branch 和构建 URL。 +- K8s 只读 API：读取指定 namespace/deployment 的 generation、observedGeneration、replicas、updatedReplicas、readyReplicas、availableReplicas、镜像、Pod phase、restartCount 和最近 warning event 摘要。 +- Deploy observation evidence：如果已有 `mcp/ktWorkflow deploy-observation` 产物或等价线上证据文件，可作为 `cached` 证据补充 Jenkins/K8s live 读取。 +- 外部链接：Jenkins/K8s Dashboard 链接只作为跳转，不替代只读状态读取。 节点： @@ -420,15 +423,26 @@ blocked > down > degraded > unknown/unwired > ok 第一版行为： - 拓扑上显示节点。 -- 提供外部链接或“未配置只读观测适配器”的证据。 +- Jenkins/K8s/NAS 节点必须有只读观测证据或明确的读取失败证据。 +- 只允许 `GET` / list/watch 等只读能力；K8s RBAC 必须限制为 deployment、pod、event、replicaset 等观测资源的 `get/list/watch`。 +- Jenkins 凭据必须是只读账号或只读 token，不允许 job build、replay、configure、credential 相关权限。 - 高风险动作如“触发部署”“重启 Pod”“查看敏感 Secret”全部 disabled。 -后续扩展： +读取字段： -- 新增只读 deploy evidence adapter。 -- 读取最近 Jenkins build number、commit、result。 -- 读取 K8s deployment generation/ready/updated/pod restartCount。 -- 只读证据仍必须脱敏，不暴露 kubeconfig、token、Secret。 +- Jenkins：jobPath、buildNumber、result、building、branch、commitSha、commitMessageSummary、startedAt、durationMs、url。 +- K8s Deployment：namespace、name、generation、observedGeneration、replicas、updatedReplicas、readyReplicas、availableReplicas、currentImage、desiredImage。 +- K8s Pod：podName、phase、ready、restartCount、image、nodeName 可选、startedAt、lastWarningReason。 +- NAS Runtime：第一版只展示 `external-link` 或 cached deploy-observation 证据，不执行 SSH；如果没有可读证据，状态为 `unknown` 且写明未配置只读 NAS 证据源。 + +失败语义： + +- Jenkins token 缺失或 403：`unknown`，evidence 写明 `jenkins-readonly-auth-missing` 或 `jenkins-readonly-forbidden`。 +- Jenkins 最近 build failed：`down` 或 `degraded`，按是否影响当前线上镜像判断。 +- K8s RBAC 403：`unknown`，evidence 写明 `k8s-readonly-rbac-forbidden`。 +- Deployment 未就绪：`down`。 +- Pod restartCount 增长或 warning event：`degraded`。 +- 只读证据必须脱敏，不暴露 kubeconfig、token、Secret、完整 Jenkins console log。 ## 安全总控 Action Catalog @@ -509,7 +523,8 @@ apps/web-antdv-next/src/api/system/environment.ts - 新增或触碰函数、方法、handler、job 必须补 JSDoc，参数说明要写来源和用途。 - 不泄露 secrets、token、password、raw env、kubeconfig、SSH 信息、QQBot 大字段。 - QQBot 摘要不得返回 `replyText`、base64 图片或过长日志。 -- Jenkins/K8s 未接入时返回 `unwired`，不得伪造健康。 +- Jenkins/K8s 必须接入只读观测；读取失败时返回 `unknown` / `down` 和失败证据，不得退回 `unwired` 或伪造健康。 +- Jenkins/K8s 适配器必须在代码和权限上只读：不得调用 Jenkins build/configure/replay，不得调用 K8s create/update/patch/delete/exec/log secret 等写入或敏感接口。 ## 缓存与成本 @@ -520,6 +535,7 @@ apps/web-antdv-next/src/api/system/environment.ts - NapCat/account runtime 读取复用现有 TTL，不强制刷新所有账号。 - WordPress/MinIO 外部探测设置独立短超时。 - Loki summary 查询失败时只降级日志节点。 +- Jenkins/K8s 只读探测设置独立短超时，读取失败只降级部署层节点。 缓存返回需要在 evidence 中标注： @@ -539,7 +555,8 @@ apps/web-antdv-next/src/api/system/environment.ts - `GET /system/environment/dashboard` 本地真实请求返回 Vben 包装。 - 响应中包含 summaryCards、topology.nodes、topology.edges、actions、recentEvents。 -- Jenkins/K8s 未配置时显示 `unwired` 或 `external-link`，不导致接口失败。 +- Jenkins/K8s 节点由只读适配器提供 build/deployment/pod 证据；缺配置、403 或超时时显示 `unknown` / `down` 与原因，不导致接口失败。 +- Jenkins/K8s 适配器没有任何部署、重启、patch、delete、exec 或 secret 读取路径。 - 任一可模拟信号源失败时接口仍 200，并将对应节点标为 `unknown` / `degraded` / `down`。 - 不返回敏感字段或 QQBot 大字段。 @@ -558,13 +575,15 @@ apps/web-antdv-next/src/api/system/environment.ts - 线上 Admin 页面可打开。 - 线上 dashboard 接口 200。 - 线上页面至少展示 API Runtime、System Logs、QQBot、NapCat、Plugin Platform、MinIO、WordPress、Jenkins/K8s 节点。 -- 对未接入的 Jenkins/K8s 节点，页面明确展示未接入证据而非健康假象。 +- 线上页面的 Jenkins/K8s 节点展示真实只读观测证据：Jenkins 最近 build、commit、result；K8s Deployment ready/updated、Pod image、restartCount。 +- Jenkins/K8s 操作项只展示 disabled，不允许触发部署、重启 Pod、修改资源或读取 Secret。 ## 测试计划方向 实施计划阶段应覆盖： -- API service 单测：状态严重度聚合、partial failure、unwired 节点、action catalog。 +- API service 单测：状态严重度聚合、partial failure、unwired 节点、action catalog、Jenkins/K8s read-only failure mapping。 +- API Jenkins/K8s adapter 单测：只允许只读路径，覆盖 200、403、timeout、failed build、deployment not ready、pod restart warning。 - API controller contract spec：鉴权路由、Vben response shape、self-check 只读行为。 - Admin API wrapper Vitest：请求路径和响应类型。 - Admin 页面组件测试：拓扑节点、证据抽屉、disabled actions。 @@ -576,8 +595,6 @@ apps/web-antdv-next/src/api/system/environment.ts 后续可以在不破坏第一版合同的基础上增加： -- 只读 Jenkins build adapter。 -- 只读 K8s deployment/pod adapter。 - deploy observation evidence 入库或文件读取。 - 安全动作审计表。 - 二次确认和权限码控制的高风险动作。