Gotham 运维监控 · LightGotham

1. 页面概览

1.1 是什么

「运维监控」页面（页面内标题为 部署运维监控，TAD-14）是 LightGotham 的部署运维工作台，提供两项能力：健康检查（逐组件探测数据库 / 图存储 / 事件总线并落库）与数据备份（手动触发备份并查看备份记录）。页面是对 Palantir Gotham 运维底座（健康检查、备份、进程监管）的前端承接，聚焦「看得见状态、留得住数据」。

1.2 核心价值

维度	说明
组件健康	总体 + 数据库 + 图存储 + 事件总线四项状态徽标（healthy/degraded/unhealthy），检查结果落库可追溯
一键刷新	「刷新」按钮执行一次实时健康检查并重载备份列表
手动备份	「立即备份」触发全量备份（默认 target=manual），完成后展示路径与大小
备份记录	目标/类型/状态/路径/大小/开始/完成/错误完整落表，失败记录带 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 + 检查时间             │
│ ② 数据备份 [立即备份|备份中...]                                 │
│    #/目标/类型/状态/路径/大小/开始/完成/错误                     │
└──────────────────────────────────────────────────────────────┘

健康检查卡片：页头「总体状态」徽标为汇总值；卡片内按组件（总体/数据库/图存储/事件总线）网格展示各自状态、详情与检查时间。
数据备份卡片：右上「立即备份」按钮，下方备份记录表完整列出每次备份的执行结果。

4. 交互元素

控件	位置	含义与作用
总体状态徽标	页头右侧	汇总健康状态：正常/降级/异常/启动中/停止中，颜色随状态变化
「刷新」按钮	页头右侧	并行执行健康检查与加载备份记录；执行中显示「检查中...」，完成后提示「运维状态已刷新」
组件状态徽标	健康检查卡片	各组件状态：healthy（正常）/degraded（降级）/unhealthy（异常）/starting（启动中）/stopping（停止中）
「立即备份」按钮	数据备份卡片右上	触发一次全量备份；执行中显示「备份中...」，成功后提示「备份已触发：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`	查询单个备份记录

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 字段携带原因。
定时备份：后端支持 robfig/cron 定时触发备份（记录 target=scheduled），本页仅展示其结果，不提供定时配置入口。

6. 权限与安全

认证：全部 /ops/* 端点位于 protected 组，JWT 无效一律 401，前端自动刷新/跳登录。
数据落库：健康检查结果与备份记录均写入数据库表，可审计追溯，页面只读展示。
写操作范围：本页唯一写操作是「立即备份」，仅触发复制动作，不删除、不覆盖既有数据，无二次确认弹窗。

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 尚未统计或复制的文件为空。处理：稍后刷新备份记录；检查后端配置的备份源文件路径是否真实存在。

8. 已知缺陷与边界

边界	说明
定时备份	页面仅展示 scheduled 备份结果，不提供 cron 定时配置入口（后端支持）
增量备份	`delta` 增量类型为预留，当前备份均为 `full` 全量
进程监管	Launcher（启动/停止/崩溃自动重启/熔断）为后端能力，本页不暴露
记录条数	备份列表固定取最近 50 条（`?limit=50`），更早记录需后端分页参数
总体口径	总体状态依赖 `OverallStatus` 汇总规则，单组件「降级」即可能导致整体非 healthy