Files
knowledge-governance/docs/OPERATIONS_RUNBOOK.md
T
姚章浩 a1d04f07ec docs(runbook): 现行用户操作流程(含本期新增/变化速查)
按实际干活顺序:开工自检(含 dws 凭据续期)→ 取件 → 标注 → 发布准备 → 待入库处理 →
发布前留档 → 授权发布 → 回滚/重排 → 系统设置维护项 → 备份恢复运维 → 按事故恢复。
末节给出 7 条与旧流程的差异对照。
2026-10-09 14:44:45 +08:00

8.6 KiB
Raw Blame History

现行用户操作流程(Runbook)

按"实际干活顺序"排列的现在的操作流程。标注:**【新】本期新增(含本次会话与 f4e1ecc/6496ee3/9155bd3 的 dws 取件)|【变】既有流程本期有改动|【既有】**未变,仍照旧走。 逐条验收证据请看 docs/USER_FLOWS_ACCEPTANCE.md;细节规则看各自专题文档。

统一入口 http://127.0.0.1:8088/(测试栈,右侧面板可直接操作)。角色:管理员 / 文档工程师 / 只读。


0. 开工前:环境与凭据自检

项 怎么做 成功标志
测试/生产 WeKnora 系统设置 → 服务配置 生产端"已启用 · 可提交生产请求";测试端探测正常
钉钉取件凭据 【新】 容器内 HOME=/data/home dws auth status --readonly -f json authenticated:true、refresh_token_valid:true(必须带 HOME=/data/home,否则误报未登录)
备份主机接线 系统设置 → 存储与备份 "目标主机 weknora-test · 已连接"

【新】dws 凭据续期(30 天轮换,到期前 7 天)

dws auth login --device     # 目标机执行,本人浏览器授权
dws wiki +space-list --limit 1 -f json   # 真实调用验证,期望 ok:true

出现 code=credentials → 立即停批,不要重试风暴;授权后 --retry-failed 续跑。


1. 取件(内容进来)【变:钉钉优先走 dws】

  1. 登录 → 来源与目录 → 选内容来源(钉钉知识库 / 国内工业 AList / PP 清单)。
  2. 展开目录、勾选要取的条目 → 取件(后台入队)。
  3. 看 解析监控:应出现"处理中"。
  • 钉钉来源现在优先用 dws 取字节(adoc→导出 docx,axls→转 xlsx,其余→drive 直下),不再依赖浏览器扫码会话;仅当 dws 报可重试错误(429/5xx/超时/连接层/服务端导出失败/dws 缺失)才回落老路径。
  • 平台侧判定全部保留(后缀路由、PPT 必须 PDF 双胞胎、magic、大小上限、sha256、spool 原子写、空壳检查)——dws 只取字节。
  • 想强制只用 dws 或完全绕过:ARTIFACT_DINGTALK_FETCHER=dws|legacy(默认 auto)。
  • 在线文档并发不要超过 4(当前配置 2 ✓)。
  • 失败进 死信,可"重排";轮次键 artifact-fetch:<version>:r<n>。

2. 标注与目录范围 【既有】

来源与目录 → 勾选 → 标记 对内 / 对外 / 不需要(目录级标记决定整目录)。

  • 路由到哪个测试库由 系统设置 → 测试知识库绑定 决定;不需要 不入库。

3. 发布准备:修订 → 审核 → 密封 → 批次 → 锁定 【既有】

发布管理 → 生成新版本 → 批准 / 驳回 → 创建草稿批次 → 密封 → 锁定。

  • 密封后批次不可改;锁定后才能授权生产发布。

4. 待入库 → 处理 【既有】

文档工作台/待入库列表 → 选中 → 开始处理 → 上传 → 解析 → 索引 → completed。

  • 监控在 解析监控:处理中 / 需要你出手 / 需下架 / 死信 / 已完成 / 知识库差异 / 知识库解析进度。

5. 发布/导入之前:必须先留档(硬门禁)****【新】

目标库现场必须先留档,否则发布被拒(release_target_snapshot_missing,不可重试,目标库一行不碰)。

bash scripts/target_kb_snapshot.sh          # 默认云内执行;PG 8 表 + 该库在 ES 的全部文档
  • 产出:$KB_BACKUP_ROOT/target-kb-snapshots/<UTC>-<kb8>/(PG JSONL + es_documents.jsonl.gz + MANIFEST.json(sha256/每库 ES 计数) + export.sql + README.md)。
  • 实测:2 分 52 秒(ES 字节留目标主机);PULL_ES=1 拉回本机则 19 分 40 秒。
  • 门禁自动核验"覆盖该库 + 24h 内 + PG 与 ES 两层齐备 + 哈希可校验";复核用 go run ./cmd/guardcheck <快照根> <kb_id>。

6. 授权发布 → 读回验证 【变:页面通道】

发布管理 → 授权发布 → 逐字输入确认语句 publish-to-production → 确认执行。

  • 双闸(请求门禁 + 备份恢复门禁)+ 执行门禁;页面不录入/不显示 token,也没有"一键发布"。
  • 执行完成后看 查看结果:completed + verified;目标库出现该文档。

7. 回滚 / 重排 【变:页面通道】

  • 回滚:查看结果 → 回滚 → 确认语句 rollback-production-release。回滚后目标库该知识停用(不删知识行),wiki 页保持。
  • 重排失败执行:失败项 → 重排 → 确认语句 retry-production-release(只重置失败项;verified/rolled_back 保持;不改写历史 AuthorizedBy)。

8. 系统设置里现在要维护什么

分区 谁 现在要管什么
服务配置 管理员 测试地址 / 生产地址 / 生产 ID / 知识库 ID(保存时真探活,无效才拒)
测试知识库绑定 管理员 标注往哪个测试库路由(对内 ≠ 对外)
生产知识库绑定 管理员 源库 → 目标库映射(发布写哪个生产库)
存储与备份 【新】 管理员 定时时间 + 储存天数(+每月归档、启用开关)→ 保存并下发到主机;另有 重新下发当前设置、立即备份一次;页面显示主机上实际生效的计划、cron 条目、最近一次结果与"已一致/待下发"
刷新策略 文档工程师 文档/资源刷新间隔、停滞判定、finalizing 时长(版本化 + 原子切换)
成员与角色 管理员 成员与 viewer/engineer/admin

9. 备份与恢复运维 【新】

层 怎么做 频率/现状
导入前留档(PG 行 + ES 文档) scripts/target_kb_snapshot.sh 每次发布前(2m52s)
硬门禁 自动(发布链已内置) 每次写目标库前
整库逻辑备份(自管,落在自己机器) 页面 立即备份一次,或主机 logical-backup.sh 每天 03:30 / 保留 7 天 / 每月另留 3 份(33 秒 / 742.6 MiB / 8 库 / 失败 0)
ES 快照 仓库 kb_backup + SLM kb-hourly(3 天)/kb-daily(7 天) 自动;首个快照 36 秒 / 4.7 GB
OSS 版本控制 桶 dobot-weknora-test 已开启 覆盖/删除可按 VersionId 回滚
RDS 托管备份 阿里云控制台自管(按决定:本期不做) —
目录契约 【新】 scripts/backup_layout.sh(任意主机同一份) /srv/kb-backups/{target-kb-snapshots,rds-logical,es-snapshots,logs}
回填演练 【新】 python3 scripts/restore_drill.py --snapshot-dir <留档> --target-url <本地测试库> 13,539 行回填、抽样逐字段一致、残留 0

换主机(测试云主机 → 未来生产云主机):① 新机跑同一份 backup_layout.sh;② compose 的 ES 挂载源与留档挂载源指向 $KB_BACKUP_ROOT;③ 门禁配置 target_snapshot.root 保持容器内路径不用改;④ 授权发布前先跑一次留档。

10. 出事了怎么恢复(按事故类型,越快越靠前)

事故 首选 耗时
某 KB 的 wiki/元数据被覆盖 留档回填(restore_drill.py 同法,或快照 README.md 的 SQL) 秒~分钟
检索/向量异常、索引误删 ES 快照 restore(kb_backup)或按 es_documents.jsonl.gz 以 _id 重建 分钟
OSS 对象被覆盖/删除 OSS 版本控制回滚单对象/前缀 秒~分钟
整库改坏要带走一份 自管逻辑备份 pg_restore -d <库> -j4 <库>.dir 分钟~十分钟
整实例级、要回到某个时刻 RDS 快照 / PITR → 新实例 → 按 KB 取行 10~30 分钟

本次新增/变化速查(对照旧流程)

# 变化 影响你的操作
1 钉钉取件走 dws 【新】 取件不再依赖扫码会话;但凭据 30 天要续期(runbook 见 §0)
2 发布前必须留档(PG+ES)【新】 发布前多一步 target_kb_snapshot.sh,否则门禁拒发
3 整库逻辑备份定时 【新】 在 系统设置 → 存储与备份 设时间与储存天数(保存即下发主机 cron)
4 生产动作页面通道 【变】 授权发布/重排/回滚在页面上、各需逐字确认语句
5 目标知识库可选 【变】 生产库绑定里可分别指定对内/对外目标库(不再要求同 ID)
6 wiki 归属门禁 【变】 共享知识库发布不再整库清空:只替换本包拥有的页面
7 回填演练 + 目录契约 【新】 出事可验证地回填;换机器只改一处配置