部署与运维实操

拓扑：四个容器，数据落在哪

compose 栈一共四个服务，职责和依赖关系是固定的： postgres（业务表 + pgvector 向量 + 全文检索同实例）→ db-init（一次性灌入 BIRD 金融演示数据，幂等）→ backend（trove serve，纯 JSON API，全部路由在 /v1 下）→ frontend（nginx 托管 SPA 并反代 /v1）。

数据落点决定了备份什么、迁移带什么：

日常操作：起停、重建、看日志

docker compose up --build        # 构建并启动（后端 :8000 仅调试，前端 :8080）
docker compose build frontend    # 只重建前端镜像（前端改动不动后端）
docker compose build backend     # 只重建后端镜像
docker compose restart backend   # 只重启后端，前端容器不受影响
docker compose logs -f backend   # 跟后端日志
docker compose down              # 停止并移除容器（保留 pgdata 卷与 .trove 挂载）

健康检查与监控

GET /v1/health 是存活 + 真实依赖检查，三种结果：

$ curl -s localhost:8000/v1/health
{"status":"ok",
 "checks":{
   "storage":{"ok":true},
   "datasources":{"financial":{"ok":true,"readonly":{"basis":"grants"}},
                  "demo":{"ok":true,"readonly":{"verified":null,"basis":"not_probed"}}},
   "llm":{"mock":false,"target":"deepseek/deepseek-reasoner","providers":0}}}

LLM 一栏只报事实（mock / target / providers）， 不做计费探测，也不下「能不能用」的结论——凭证是否可用的最终判定 是一次真实提问（见故障表「问答不可用」一行）。

GET /v1/metrics 输出 Prometheus 文本格式，直接可被 Prometheus / VictoriaMetrics 抓取。运维上最该关注的几个族：

生产配置清单

备份与升级

备份什么

升级步骤

# 1. 先备份（见上表）
pg_dump "$TROVE_STORAGE_URL" > trove-$(date +%F).sql
tar czf kb-$(date +%F).tar.gz .trove/

# 2. 拉新代码，重建镜像，滚动起来
git pull
docker compose build
docker compose up -d

# 3. 验证
curl -s localhost:8000/v1/health        # 应为 ok / degraded
# 管理台登录 → 数据源健康 → 问一个已知问题对照答案

内部状态的库表迁移是版本化、幂等、自动应用的：新代码第一次 打开旧库会自动迁移到位，中途失败会回滚且不推进版本。KB 的 SQLite 检索镜像 是派生物，走重建而不是迁移——升级后如果检索异常，重跑一次 KB 初始化即可，YAML 真源不受影响。

故障排查对照表

相关页面