1. 页面概览
1.1 是什么
「运维监控」页面（页面内标题为 部署运维监控，TAD-14）是 LightGotham 的部署运维工作台，提供三项能力：健康检查（逐组件探测数据库 / 图存储 / 事件总线并落库）、定时备份调度（配置/启停 cron 表达式，展示下次触发时间）与数据备份（手动触发备份并查看备份记录）。页面是对 Palantir Gotham 运维底座（健康检查、备份、进程监管）的前端承接，聚焦「看得见状态、留得住数据」。
1.2 核心价值
| 维度 | 说明 |
|---|---|
| 组件健康 | 总体 + 数据库 + 图存储 + 事件总线四项状态徽标（healthy/degraded/unhealthy），检查结果落库可追溯 |
| 一键刷新 | 「刷新」按钮执行一次实时健康检查并重载备份列表 |
| 手动备份 | 「立即备份」触发全量备份（默认 target=manual），完成后展示路径与大小 |
| 定时备份 | cron 表达式配置表单：启用/改期/停止调度，展示当前表达式与下次触发时间 |
| 备份记录 | 目标/类型/状态/路径/大小/开始/完成/错误完整落表，失败记录带 error 可排错 |
1.3 一句话总结
打开页面点「刷新」看各组件是否正常、点「立即备份」给当前数据留一份底——Gotham 的部署状态与数据兜底都在这一个页面完成。
2. 访问入口
2.1 路由与菜单
- 路由：
/gotham/ops；路由名称：GothamOps - 路由 meta：
title: Gotham 运维监控，requiresAuth: true，挂在父路由/gotham（GothamLayout）下 - 菜单位置：Gotham 左侧边栏「运维监控」
- 前端源码：
action/web/src/views/GothamOpsPage.vue - API 客户端：
action/web/src/api/gothamClient.js
2.2 认证与权限
- 路由挂
requiresAuth: true，未登录访问被全局守卫重定向到/login。 - 请求走 gothamClient：请求拦截器自动附带
Authorization: Bearer <aip_token>；响应拦截器遇 401 时用gotham_refresh_token调POST /auth/refresh换发新 token 并重放原请求，refresh 失败才清令牌跳登录。
2.3 端口与 API 前缀
- Gotham 后端端口：18083（Vite 将
/gotham-api前缀代理到该端口并重写为/api/v1）。 - API 前缀：
/gotham-api/v1（gothamClient 的 baseURL）。
3. 界面布局
页面单栏纵向布局，自上而下两张卡片：
┌──────────────────────────────────────────────────────────────┐
│ 部署运维监控 [总体状态：正常/降级/异常] [刷新|检查中...] │
│ [alert 操作结果提示条（可关闭）] │
│ ① 健康检查（组件状态：healthy / degraded / unhealthy，已落库） │
│ [总体][正常] [数据库][正常] [图存储][降级] [事件总线][正常] │
│ 每个组件块：组件名 + 状态徽标 + detail + 检查时间 │
│ ② 定时备份（cron 调度） │
│ [运行中|未启用] 当前表达式 0 2 * * * · 下次触发 2026-.. │
│ [cron 表达式输入框] [启用调度|更新调度] [停止调度] │
│ ③ 数据备份 [立即备份|备份中...] │
│ #/目标/类型/状态/路径/大小/开始/完成/错误 │
└──────────────────────────────────────────────────────────────┘- 健康检查卡片：页头「总体状态」徽标为汇总值；卡片内按组件（总体/数据库/图存储/事件总线）网格展示各自状态、详情与检查时间。
- 定时备份卡片：一行状态（运行中/未启用 + 当前表达式 + 下次触发时间）、一行表单（表达式输入框 + 启用/更新按钮 + 停止按钮）。
- 数据备份卡片：右上「立即备份」按钮，下方备份记录表完整列出每次备份的执行结果。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 总体状态徽标 | 页头右侧 | 汇总健康状态：正常/降级/异常/启动中/停止中，颜色随状态变化 |
| 「刷新」按钮 | 页头右侧 | 并行执行健康检查与加载备份记录；执行中显示「检查中...」，完成后提示「运维状态已刷新」 |
| 组件状态徽标 | 健康检查卡片 | 各组件状态：healthy（正常）/degraded（降级）/unhealthy（异常）/starting（启动中）/stopping（停止中） |
| 调度状态徽标 | 定时备份卡片 | 运行中（后端 active=true）/未启用：分别展示当前表达式与下次触发时间，或提示「未配置定时备份，备份仅可手动触发」 |
| cron 表达式输入框 | 定时备份卡片 | 填写 5/6 段 cron（如 0 2 * * *）或 @every 描述符（如 @every 24h）；启用中会回填当前生效表达式；为空时前端拦截提示 |
| 「启用调度/更新调度」按钮 | 定时备份卡片 | 已启用时文案为「更新调度」且弹二次确认；提交 PUT /ops/schedule {spec, enabled:true}，成功后重载配置并提示「定时备份已启用：<spec>」 |
| 「停止调度」按钮 | 定时备份卡片 | 未启用时禁用；点击弹确认框，提交 PUT /ops/schedule {enabled:false}，成功后清空输入框并提示「定时备份调度已停止」 |
| 「立即备份」按钮 | 数据备份卡片右上 | 触发一次全量备份；执行中显示「备份中...」，成功后提示「备份已触发：target=manual，path=...」并刷新记录 |
| 备份记录表 | 数据备份卡片 | 展示目标/类型/状态/路径/大小/开始/完成/错误；大小为 B/KB/MB/GB 自动换算，错误列红色截断展示 |
组件名与状态文案对照（前端逐字展示）：
| 组件标识 | 中文名 | 状态值 → 中文 |
|---|---|---|
| overall | 总体 | healthy→正常 / degraded→降级 / unhealthy→异常 |
| database | 数据库 | 另含 starting→启动中、stopping→停止中 |
| graph_store | 图存储 | 未知值原样展示，缺省「-」 |
| event_bus | 事件总线 | 徽标颜色随 healthy/degraded/unhealthy 变化 |
5. 后端关联
5.1 API 客户端
- 文件：
action/web/src/api/gothamClient.js；baseURL/gotham-api/v1，超时 30000ms。 - 加载备份列表时带
?limit=50；统一响应体{code: 0, data: ...}，前端取res.data.data。
5.2 端点表
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /ops/health | 执行健康检查并返回逐组件状态（overall + components + generated_at），同步更新 Prometheus 健康指标 |
| GET | /ops/backups | 备份记录列表（?limit= 可选，默认 50） |
| POST | /ops/backups | 手动触发备份（?target= 可选，默认 manual），返回 BackupRecord |
| GET | /ops/backups/:id | 查询单个备份记录 |
| GET | /ops/schedule | 读取定时备份调度配置（spec/enabled/active/next_run_at） |
| PUT | /ops/schedule | 写入定时备份调度配置（{spec, enabled}，启用改期/停止；非法表达式 400） |
5.3 响应结构
健康检查（GET /ops/health）与备份记录：
{ "code": 0, "data": { "overall": "degraded",
"components": [ { "id": 12, "component": "database", "status": "healthy",
"detail": "ok", "created_at": "2026-08-30T09:00:00Z" },
{ "component": "graph_store", "status": "degraded", "detail": "neo4j slow" } ],
"generated_at": "2026-08-30T09:00:00Z" } }
{ "code": 0, "data": { "id": 5, "target": "manual", "type": "full",
"path": "temp/backup/20260830T0900/", "size": 1048576, "status": "success",
"started_at": "...", "finished_at": "..." } }5.4 关键机制
- 健康检查语义：
CheckHealth逐组件探测（关系数据库 / 图存储 / 事件总线）并写入gotham_health_records表；overall由OverallStatus(records)汇总（全部正常=healthy、非核心组件异常=degraded、核心组件异常=unhealthy）。每次「刷新」都会落库一条新检查记录。 - 备份语义：
RunBackup把配置文件、图存储 JSON、SQLite 库复制到备份目录（temp/backup/<timestamp>/）并记录累计字节数；type固定为full（全量，delta 增量预留）；status为 success/failed，失败时error字段携带原因。 - 定时备份调度语义：
ScheduleBackups向平台统一调度器注册 job 名ops:backup（支持 5/6 段 cron 与@every描述符），触发时执行RunBackup(ctx, "scheduled")，记录target=scheduled；UpdateBackupSchedule负责改期（先停旧任务再启动）与停止（反注册并清除scheduler_jobs持久行）；非法表达式回滚原配置并返回 400。NewServer组装阶段调用RestoreScheduler，按scheduler_jobs持久行恢复调度，重启后 cron 配置不丢（页面无需重新配置）。
6. 权限与安全
- 认证：全部
/ops/*端点位于 protected 组，JWT 无效一律 401，前端自动刷新/跳登录。 - 数据落库：健康检查结果与备份记录均写入数据库表，可审计追溯，页面只读展示。
- 写操作范围：写操作有两类——「立即备份」（仅触发复制动作，不删除、不覆盖既有数据，前端无确认弹窗）与「启用/更新/停止调度」（
PUT /ops/schedule，改期与停止均弹二次确认；后端按ops.backup / execute:write走 ABAC PEP 默认放行语义）。
7. 常见问题与排错
问题一：点「刷新」后健康检查卡片仍显示「暂无健康检查记录」
现象：刷新后组件网格为空。原因：请求失败或后端未启动（18083 无响应）。处理：检查 Gotham 后端进程是否在运行；查看 alert 提示条的具体报错；用 curl -H "Authorization: Bearer <aip_token>" http://localhost:18083/api/v1/ops/health 直连验证。
问题二：总体状态显示「异常」，但数据库等组件全正常
现象：overall 为 unhealthy 而组件明细正常。原因：overall 汇总包含未展示的组件（如事件总线）或检查记录中的异常项被分页截断。处理：看每个组件卡片的 detail 与检查时间；确认事件总线（event_bus）是否启动；必要时刷新多次观察是否恢复。
问题三：备份记录出现 failed，错误列有内容
现象：备份记录状态为 failed。原因：备份目标目录不可写、磁盘空间不足或图存储文件缺失。处理：读取错误列原文；确认 temp/backup/ 目录存在且可写；清理空间后重新点「立即备份」。
问题四：点「立即备份」无反应或一直「备份中...」
现象：按钮长时间保持备份中。原因：备份耗时长或接口异常未返回。处理：等待几秒后刷新备份表确认是否已写入记录；若仍无记录，用 POST 接口直接调用排查后端日志。
问题五：备份大小始终显示「0 B」
现象：备份成功但 size 为 0。原因：备份刚触发即返回，size 尚未统计或复制的文件为空。处理：稍后刷新备份记录；检查后端配置的备份源文件路径是否真实存在。
问题六：点「启用调度」提示「调度配置失败：非法 cron 表达式 ...」
现象：提交 cron 表达式后报非法。原因：表达式不满足 5/6 段 cron 或 @every 描述符语法（如 not-a-cron、字段数不足）。处理：按提示修正表达式（如 0 2 * * * 表示每天 02:00、@every 24h 表示每 24 小时）；失败不会影响原有调度（后端已回滚），修正后重试即可。
问题七：重启后端后页面显示「未启用」，之前的调度没了
现象：重启后调度配置丢失。原因：之前在页面上点过「停止调度」（会清除 scheduler_jobs 持久行，重启不再恢复）。处理：重新填写表达式并点「启用调度」；日常重启（未主动停止）不会丢配置。
8. 已知缺陷与边界
| 边界 | 说明 |
|---|---|
| 定时备份调度持久化范围 | 表达式持久在 scheduler_jobs 表（RestoreScheduler 启动恢复），但不回写 config.yaml 的 backup.schedule，也不能只靠配置文件声明调度；「停止调度」会清除持久行，重启不会自动恢复（符合用户主动停用预期） |
| 增量备份 | delta 增量类型为预留，当前备份均为 full 全量 |
| 进程监管 | Launcher（启动/停止/崩溃自动重启/熔断）为后端能力，本页不暴露 |
| 记录条数 | 备份列表固定取最近 50 条（?limit=50），更早记录需后端分页参数 |
| 总体口径 | 总体状态依赖 OverallStatus 汇总规则，单组件「降级」即可能导致整体非 healthy |
注：「立即备份」无确认已于 2026-09-06 修复（补 confirm 弹窗防重复点击；loading 防重原有）。