docs: 设计Admin全环境状态总控面板

2026-06-18 14:05:38 +08:00 · 2026-06-18 14:05:38 +08:00 · bb76476213
commit bb76476213
parent 2a890d894d
1 changed files with 587 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md
+++ b/docs/superpowers/specs/2026-06-18-admin-environment-dashboard-design.md
@ -0,0 +1,587 @@
+# Admin 全环境状态总览总控面板设计
+
+## 背景
+
+Admin 当前 `/dashboard/analytics` 仍是 Vben 示例页，展示用户量、访问量、下载量和图表等静态演示数据。它没有反映线上真实环境，也不能帮助判断 API、QQBot、NapCat、插件平台、系统日志、MinIO、WordPress、Jenkins/K8s 等链路的当前状态。
+
+用户已确认将分析页改造成线上全环境状态总览总控面板，并选择方案 B：**总览 + 安全总控**，同时增加**环境拓扑**作为主视图。这个页面的目标不是“再做一个漂亮 Dashboard”，而是把线上环境状态、证据来源、可执行的低风险动作和高风险动作边界集中展示出来，让后续排障、上线观察和 QQBot 闭环不再靠散落入口。
+
+本设计基于主线程和两个只读 subagent 的盘点结果：
+
+- 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 统一聚合合同 + Admin 拓扑消费”的结构：页面不散拼多个旧接口；API 不伪造未接入的环境状态；高风险动作先显式禁用或跳转，不直接执行。
+
+## 已确认决策
+
+1. `/dashboard/analytics` 改造成环境状态总览总控面板，不继续保留 Vben 示例图表。
+2. 采用方案 B：顶部总览、环境拓扑、右侧安全总控、底部最近事件/证据。
+3. 环境拓扑必须是第一屏核心区域，展示从入口、网关、Admin、API、数据层、对象存储、日志、WordPress、QQBot、NapCat、插件平台、定时任务到 Jenkins/K8s 的链路。
+4. 第一版只允许低风险动作：刷新、执行只读自检、打开日志、跳转到已有管理页、打开外部只读入口。
+5. 重启 Pod、触发 Jenkins 部署、DB 写入、重建 NapCat 容器、启停插件或定时任务等高风险动作，第一版只能作为 disabled action 展示原因和未来入口。
+6. API 聚合接口必须受 Admin JWT 保护，返回 Vben 统一响应，不泄露密钥、token、原始 env、QQBot 大字段或未脱敏日志。
+7. Jenkins/K8s 如果暂时没有可由 API 安全读取的凭据或适配器，也必须在拓扑中显示为 `unknown` / `unwired`，不能从页面消失或伪造成正常。
+
+## 目标
+
+- 将 Admin 分析页变成可用于线上日常观察的环境总览入口。
+- 提供统一 API 合同，输出状态卡片、拓扑节点、拓扑边、操作目录和最近事件。
+- 把现有分散信号源收敛到一个只读聚合服务，保持每个信号源可独立降级。
+- 在 UI 上明确区分 `ok`、`degraded`、`down`、`blocked`、`unknown`、`unwired`。
+- 用证据字段解释每个状态来自哪里、何时检查、是否实时、是否缓存、失败原因是什么。
+- 为后续接入 Jenkins/K8s 只读观测、部署记录、任务运行历史和自动化恢复留出合同扩展点。
+
+## 非目标
+
+- 不在第一版执行部署、重启、数据库写入、插件启停、NapCat 容器重建等高风险动作。
+- 不把 Admin 页面做成营销式图表页或静态展示页。
+- 不绕过现有 QQBot、NapCat、插件平台、WordPress、MinIO 的业务边界。
+- 不要求 API Pod 内直接持有生产 kubeconfig、Jenkins 写权限或 NAS SSH 写权限。
+- 不把外部不可读的 Jenkins/K8s 状态假装成健康。
+- 不在本轮新增长期运行的后台巡检任务或历史表，除非后续实施计划明确需要。
+
+## 信息架构
+
+页面仍使用 `/dashboard/analytics` 路由，但语义改为“环境总览”。布局从上到下为：
+
+1. **全局状态条**
+   - 当前环境总体状态。
+   - 最近检查时间。
+   - 降级节点数量。
+   - 阻断节点数量。
+   - 未接入节点数量。
+   - 一键刷新和只读自检入口。
+
+2. **核心指标卡**
+   - API Runtime。
+   - 日志/Loki。
+   - QQBot 在线账号与发送状态。
+   - NapCat 登录态/容器态。
+   - 插件平台与定时任务。
+   - 存储/WordPress。
+   - 部署链路。
+
+3. **环境拓扑主视图**
+   - 使用横向分层拓扑，不使用营销图表。
+   - 节点展示状态、短指标、来源标识和最近检查时间。
+   - 边展示调用关系、依赖关系或部署关系。
+   - 点击节点打开右侧证据抽屉。
+
+4. **安全总控面板**
+   - 展示 action catalog。
+   - 可执行项仅限刷新、只读自检、打开日志、跳转页面、打开外链。
+   - 高风险项以 disabled 状态展示原因、所需权限和后续实施条件。
+
+5. **最近事件/证据流**
+   - 聚合系统日志状态、插件 runtime event、QQBot/NapCat 关键错误摘要。
+   - 不展示 QQBot `replyText`、base64 图片、大段日志正文或敏感配置。
+
+## 环境拓扑
+
+第一版拓扑节点按区域分组：
+
+```text
+入口层
+  admin.kwitsukasa.top / blog / API public route
+  -> Caddy / TLS / reverse proxy
+
+前端层
+  -> Admin static site
+  -> Blog public frontend
+
+服务层
+  -> API Runtime
+  -> Runtime Config
+  -> Auth/Admin Platform Config
+
+数据与观测层
+  -> MySQL
+  -> Redis / BullMQ
+  -> Loki / System Logs
+  -> MinIO
+  -> WordPress
+
+QQBot 层
+  -> QQBot Core
+  -> OneBot Reverse WS
+  -> NapCat Accounts
+  -> Plugin Platform
+  -> Plugin Scheduled Tasks
+
+部署层
+  -> Jenkins
+  -> K8s Deployment
+  -> API Pod
+```
+
+节点的状态来源分为：
+
+- `live`：API 当前请求中实时读取。
+- `cached`：API 使用已有缓存或短 TTL 运行态证据。
+- `derived`：从其他信号推导，例如 QQBot 汇总推导 bus 状态。
+- `configured`：只知道配置存在或缺失。
+- `external-link`：只能提供外部入口，API 不能直接读取。
+- `unwired`：设计中必须存在，但当前未接入真实信号。
+
+拓扑节点不得因为没有接入真实读取就隐藏。未接入的 Jenkins/K8s 节点第一版应显示为 `unknown` 或 `unwired`，并在证据抽屉写明“API 当前没有只读观测适配器”。
+
+## API 合同
+
+新增受保护接口：
+
+```text
+GET /system/environment/dashboard
+POST /system/environment/self-check
+```
+
+`GET /system/environment/dashboard` 返回当前聚合状态。`POST /system/environment/self-check` 只执行同一批只读检查，不执行写入、重启、部署或容器重建；它可以返回新的检查结果和本次 `checkRunId`，但第一版不要求落库。
+
+建议目录：
+
+```text
+src/modules/admin/platform-config/environment-dashboard/
+  contract/
+    environment-dashboard.controller.ts
+    dto/
+      environment-dashboard.dto.ts
+  application/
+    environment-dashboard.service.ts
+    environment-dashboard-status.mapper.ts
+    environment-dashboard-action.catalog.ts
+  domain/
+    environment-dashboard.types.ts
+  infrastructure/
+    environment-dashboard-signal.collector.ts
+```
+
+该模块属于 Admin Platform Config，因为它面向后台环境观测和安全总控，不属于 QQBot、Blog、Asset 任一业务域。
+
+### DTO
+
+```ts
+type EnvironmentHealthStatus =
+  | 'ok'
+  | 'degraded'
+  | 'down'
+  | 'blocked'
+  | 'unknown'
+  | 'unwired';
+
+interface EnvironmentDashboardDto {
+  checkedAt: string;
+  checkRunId: string;
+  overallStatus: EnvironmentHealthStatus;
+  summaryCards: EnvironmentSummaryCardDto[];
+  topology: EnvironmentTopologyDto;
+  actions: EnvironmentActionDto[];
+  recentEvents: EnvironmentEventDto[];
+}
+
+interface EnvironmentSummaryCardDto {
+  key: string;
+  title: string;
+  status: EnvironmentHealthStatus;
+  primaryMetric: string;
+  secondaryMetric?: string;
+  source: EnvironmentSignalSourceDto;
+  route?: string;
+}
+
+interface EnvironmentTopologyDto {
+  nodes: EnvironmentNodeDto[];
+  edges: EnvironmentEdgeDto[];
+}
+
+interface EnvironmentNodeDto {
+  id: string;
+  label: string;
+  group: 'entry' | 'frontend' | 'service' | 'data' | 'observability' | 'qqbot' | 'deploy';
+  status: EnvironmentHealthStatus;
+  sourceKind: 'live' | 'cached' | 'derived' | 'configured' | 'external-link' | 'unwired';
+  metrics: EnvironmentMetricDto[];
+  evidence: EnvironmentEvidenceDto[];
+  links: EnvironmentNodeLinkDto[];
+  lastCheckedAt?: string;
+}
+
+interface EnvironmentEdgeDto {
+  id: string;
+  source: string;
+  target: string;
+  relation: 'routes-to' | 'depends-on' | 'observes' | 'deploys' | 'connects';
+  status: EnvironmentHealthStatus;
+}
+
+interface EnvironmentActionDto {
+  key: string;
+  label: string;
+  description: string;
+  kind: 'refresh' | 'self-check' | 'open-route' | 'open-url' | 'disabled-future';
+  riskLevel: 'safe' | 'medium' | 'high';
+  enabled: boolean;
+  targetRoute?: string;
+  targetUrl?: string;
+  disabledReason?: string;
+  requiredPermission?: string;
+}
+
+interface EnvironmentEventDto {
+  id: string;
+  source: string;
+  level: 'info' | 'warn' | 'error' | 'fatal';
+  title: string;
+  message: string;
+  happenedAt: string;
+  route?: string;
+}
+```
+
+实现时应使用项目现有 class DTO 风格，不需要逐字照搬 interface；上述结构是合同语义。
+
+### 状态归一规则
+
+- `ok`：信号源明确可用，关键指标正常。
+- `degraded`：信号源可读，但存在局部异常，例如少量账号离线、日志查询降级、插件部分失败。
+- `down`：信号源明确不可用，例如 MinIO 检查失败、WordPress auth check 失败。
+- `blocked`：存在会阻断业务闭环的问题，例如 API runtime 配置缺失、QQBot worker 阻塞。
+- `unknown`：检查失败、超时或没有足够证据判断。
+- `unwired`：设计上存在该节点，但当前版本尚未接入读取能力。
+
+总体状态按严重度聚合：
+
+```text
+blocked > down > degraded > unknown/unwired > ok
+```
+
+`unknown` 和 `unwired` 不应覆盖真实 `down` 或 `blocked`，但必须在 UI 上单独计数，避免被误认为健康。
+
+## 信号源映射
+
+### Runtime/API
+
+来源：
+
+- `RuntimeHealthService.getRuntimeHealth()`
+- `RuntimeConfigService` 配置检查结果
+
+节点：
+
+- API Runtime
+- Runtime Config
+- MySQL
+- Loki configured
+- MinIO configured
+- WordPress configured
+- QQBot/NapCat configured
+
+注意：
+
+- `/health/runtime` 是无鉴权 plain JSON，新的 Admin 聚合接口不能直接 HTTP 调自己，应直接调用 service。
+- 返回给 Admin 的证据必须脱敏，保留 configured/missing 语义即可。
+
+### 系统日志/Loki
+
+来源：
+
+- `SystemLogService`
+- `/system/logs/status`
+- `/system/logs/summary`
+
+节点：
+
+- Loki / System Logs
+
+事件：
+
+- 最近错误等级摘要。
+- 日志查询状态。
+
+注意：
+
+- 不返回大段原始日志。
+- 页面跳转到现有系统日志页面时可附带 level/source filter。
+
+### QQBot Core / NapCat
+
+来源：
+
+- `QqbotDashboardService.summary()`
+- `QqbotAccountService` 或账号列表已有 runtime append 结果
+- `QqbotNapcatAccountRuntimeService`
+- NapCat runtime detail 现有摘要
+
+节点：
+
+- QQBot Core
+- OneBot Reverse WS
+- NapCat Accounts
+
+指标：
+
+- 账号总数。
+- 在线账号数。
+- 启用账号数。
+- 发送成功/失败。
+- bus/runtime 状态。
+- NapCat 容器/WebUI/QQ 登录态分布。
+
+注意：
+
+- 账号列表可能触发 runtime TTL 检查，聚合服务需要短超时和并发限制。
+- OneBot reverse WS 心跳不能被当作 QQ 登录成功，拓扑证据必须区分容器、OneBot、WebUI、QQ 登录态。
+
+### 插件平台与定时任务
+
+来源：
+
+- Plugin Platform installations/capabilities/operations/runtime events。
+- Plugin Task page/status service。
+
+节点：
+
+- Plugin Platform
+- Plugin Operations
+- Plugin Scheduled Tasks
+
+指标：
+
+- 已安装插件数量。
+- enabled 插件数量。
+- operation 数量。
+- worker/runtime event 最近异常。
+- 定时任务总数、启用数、最近失败数。
+
+注意：
+
+- 第一版面板不执行插件 enable/disable、task run、cron 修改。
+- 相关操作只跳转到插件管理或插件任务页。
+
+### MinIO / Asset
+
+来源：
+
+- `MinioClientService.checkConnection(bucketName?)`
+- `/minio/check` 现有能力对应的 service。
+
+节点：
+
+- MinIO
+
+指标：
+
+- bucket 名称。
+- bucket 是否存在。
+- 连接检查状态。
+
+注意：
+
+- 不在 Dashboard 创建 bucket。
+- `createAssetBucket`、上传、删除都不是第一版安全动作。
+
+### WordPress / Blog
+
+来源：
+
+- `WordpressService.checkAuth()`
+- WordPress theme/blog theme config 读取能力。
+
+节点：
+
+- WordPress
+- Blog Frontend
+
+指标：
+
+- WordPress auth check。
+- theme config 读取状态。
+- public blog route 可用性如果 API 内有 service 可读，则作为 live；否则第一版仅展示 configured/external-link。
+
+注意：
+
+- 不执行 WordPress import、sync 或写入。
+
+### Jenkins / K8s / NAS
+
+来源：
+
+- 第一版默认 `unwired` / `external-link`。
+- 如果后续配置只读 Jenkins token、只读 K8s service account 或 deploy-observation evidence 文件，才能升级为 `live` 或 `cached`。
+
+节点：
+
+- Jenkins
+- K8s Deployment
+- API Pod
+- NAS Runtime
+
+第一版行为：
+
+- 拓扑上显示节点。
+- 提供外部链接或“未配置只读观测适配器”的证据。
+- 高风险动作如“触发部署”“重启 Pod”“查看敏感 Secret”全部 disabled。
+
+后续扩展：
+
+- 新增只读 deploy evidence adapter。
+- 读取最近 Jenkins build number、commit、result。
+- 读取 K8s deployment generation/ready/updated/pod restartCount。
+- 只读证据仍必须脱敏，不暴露 kubeconfig、token、Secret。
+
+## 安全总控 Action Catalog
+
+第一版 enabled actions：
+
+- `refresh-dashboard`：重新请求 dashboard。
+- `run-readonly-self-check`：调用 `POST /system/environment/self-check`，只执行只读检查。
+- `open-system-logs`：跳转系统日志页。
+- `open-qqbot-dashboard`：跳转 QQBot Dashboard。
+- `open-napcat-runtime`：跳转 NapCat runtime/账号详情相关页面。
+- `open-plugin-platform`：跳转插件平台页。
+- `open-plugin-tasks`：跳转插件任务页。
+- `open-asset-page`：跳转资产/MinIO 相关页面。
+- `open-wordpress-page`：跳转 Blog/WordPress 管理页。
+- `open-jenkins`：如果配置外链则打开 Jenkins。
+- `open-k8s-dashboard`：如果配置外链则打开 K8s Dashboard。
+
+第一版 disabled actions：
+
+- `restart-api-pod`
+- `trigger-jenkins-deploy`
+- `run-db-migration`
+- `recreate-napcat-container`
+- `plugin-enable-disable`
+- `plugin-task-run-once`
+- `minio-create-bucket`
+- `wordpress-import`
+
+每个 disabled action 必须返回：
+
+- `riskLevel: 'high'`
+- `enabled: false`
+- `disabledReason`
+- `requiredPermission`
+- 后续所需安全条件，例如二次确认、审计日志、回滚路径、只读预检。
+
+## 前端设计
+
+改造位置：
+
+```text
+apps/web-antdv-next/src/views/dashboard/analytics/index.vue
+apps/web-antdv-next/src/views/dashboard/analytics/components/
+apps/web-antdv-next/src/api/system/environment.ts
+```
+
+路由：
+
+- 保留 `/dashboard/analytics`，避免菜单和固定 tab 入口失效。
+- 菜单文案可改为“环境总览”或“环境状态”。
+- 如果后台菜单组件选择依赖 `componentKeys`，需要补齐 `/dashboard/` 组件扫描。
+
+页面结构：
+
+- 使用 `Page autoContentHeight`。
+- 使用 Ant Design Vue Next 的 `Card`、`Statistic`、`Tag`、`Button`、`Tooltip`、`Drawer`、`Timeline`、`Alert`、`Descriptions`。
+- 拓扑可使用 DOM + CSS grid/SVG edge overlay 实现，不引入重量图表库。
+- 每个拓扑节点使用固定尺寸，避免状态文字变化导致布局跳动。
+- 节点点击打开证据抽屉，抽屉展示 metrics、evidence、links、lastCheckedAt。
+- 安全总控按钮必须用图标 + tooltip；高风险 disabled action 不隐藏。
+- 页面禁止使用旧示例中的营销图表和静态数据。
+
+视觉原则：
+
+- 运维工具风格，信息密度高、层级清晰、颜色克制。
+- 不做 hero，不做装饰渐变，不做大面积单色主题。
+- `ok/degraded/down/blocked/unknown/unwired` 使用一致的状态色和文字。
+- 拓扑主视图必须在桌面第一屏可见；移动端可纵向分组堆叠。
+
+## 后端实现约束
+
+- Controller 使用 `JwtAuthGuard`。
+- 返回 `vbenSuccess(data)`。
+- Aggregator 通过 service 直接调用现有能力，不通过 HTTP 请求本 API。
+- 每个信号源独立 timeout、独立 `Promise.allSettled`，单点失败不能拖垮整个 dashboard。
+- 信号源失败必须变成节点 evidence，而不是抛出 500。
+- 只有认证、参数、系统级不可恢复错误才让接口失败。
+- 新增或触碰函数、方法、handler、job 必须补 JSDoc，参数说明要写来源和用途。
+- 不泄露 secrets、token、password、raw env、kubeconfig、SSH 信息、QQBot 大字段。
+- QQBot 摘要不得返回 `replyText`、base64 图片或过长日志。
+- Jenkins/K8s 未接入时返回 `unwired`，不得伪造健康。
+
+## 缓存与成本
+
+建议第一版采用短 TTL 聚合缓存：
+
+- 默认 dashboard TTL：10-30 秒。
+- `self-check` 可绕过 dashboard TTL，但仍给单个信号源设置 timeout。
+- NapCat/account runtime 读取复用现有 TTL，不强制刷新所有账号。
+- WordPress/MinIO 外部探测设置独立短超时。
+- Loki summary 查询失败时只降级日志节点。
+
+缓存返回需要在 evidence 中标注：
+
+- `checkedAt`
+- `sourceKind`
+- `ttlMs`
+- `isStale`
+
+## 验收标准
+
+### 设计验收
+
+- 用户确认本 spec 后，进入 Superpowers writing-plans。
+- 实施计划必须拆 API 合同、API 聚合、Admin 页面、测试/线上闭环四部分。
+
+### API 验收
+
+- `GET /system/environment/dashboard` 本地真实请求返回 Vben 包装。
+- 响应中包含 summaryCards、topology.nodes、topology.edges、actions、recentEvents。
+- Jenkins/K8s 未配置时显示 `unwired` 或 `external-link`，不导致接口失败。
+- 任一可模拟信号源失败时接口仍 200，并将对应节点标为 `unknown` / `degraded` / `down`。
+- 不返回敏感字段或 QQBot 大字段。
+
+### Admin 验收
+
+- `/dashboard/analytics` 不再展示 Vben 示例静态图表。
+- 第一屏展示总体状态、拓扑和安全总控。
+- 节点点击能打开证据抽屉。
+- enabled action 可执行刷新、只读自检或跳转。
+- disabled high-risk action 可见且说明禁用原因。
+- 页面切换无 Vue `non-element root node` / transition 空白问题。
+
+### 线上验收
+
+- API/Admin 推送部署后，Jenkins/K8s 发布状态需按现有 deploy observation 流程验证。
+- 线上 Admin 页面可打开。
+- 线上 dashboard 接口 200。
+- 线上页面至少展示 API Runtime、System Logs、QQBot、NapCat、Plugin Platform、MinIO、WordPress、Jenkins/K8s 节点。
+- 对未接入的 Jenkins/K8s 节点，页面明确展示未接入证据而非健康假象。
+
+## 测试计划方向
+
+实施计划阶段应覆盖：
+
+- API service 单测：状态严重度聚合、partial failure、unwired 节点、action catalog。
+- API controller contract spec：鉴权路由、Vben response shape、self-check 只读行为。
+- Admin API wrapper Vitest：请求路径和响应类型。
+- Admin 页面组件测试：拓扑节点、证据抽屉、disabled actions。
+- 本地真实接口请求：启动或复用 API 服务调用 dashboard 接口。
+- 本地浏览器 smoke：打开 `/dashboard/analytics`，检查 console、首屏、抽屉和动作。
+- 线上 smoke：部署后调用线上接口和页面。
+
+## 后续扩展
+
+后续可以在不破坏第一版合同的基础上增加：
+
+- 只读 Jenkins build adapter。
+- 只读 K8s deployment/pod adapter。
+- deploy observation evidence 入库或文件读取。
+- 安全动作审计表。
+- 二次确认和权限码控制的高风险动作。
+- 环境变更历史趋势。
+- 定时自检和告警推送。
+
+这些扩展必须继续遵守：读态优先、动作分级、证据脱敏、失败局部降级、高风险动作有审计与回滚路径。