Files
knowledge-governance/docs/OPERATIONS_RUNBOOK.md
T
狐友 GXXP & Miku ad02e8bb9c
build / build (push) Successful in 1m43s
feat(settings): 页面录入测试/生产 WeKnora 连接与密钥并收敛可达性判定
连接(地址 + 写-only 密钥)从文件引用搬进治理库:AES-GCM 密文 + 独立 0600 主密钥,
页面与接口只回显尾 4 位;测试连接真实列库并区分 地址不可达/密钥无效/无权限/成功,
换地址或换密钥必须测通才能保存(迁移 000083)。

可达性判定收敛为 weknora.HTTPAllowed,客户端与监控探活共用;新增
WEKNORA_ALLOW_PRIVATE_HTTP 只放行 RFC1918/回环/链路本地。生产绑定只保留下拉,
保存后回报冻结/未冻结条数,已冻结目标不被改写。
2026-11-22 15:18:34 +08:00

20 KiB
Raw Blame History

现行用户操作流程(Runbook)

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

管理员配置连接和发布授权,文档工程师维护资料,只读成员查看进度。先确定要操作的环境,再按下面的接线与验收步骤进入业务流程。

入口与反向代理

请求从哪里发出 地址或路径 实际目的地
已接入内网的运维电脑 http://100.85.111.121:8088/ 云测试治理主站
开发电脑的浏览器 http://127.0.0.1:28189/ SSH 转发到测试机回环 28189,由候选 Web 提供静态资源
测试候选 Nginx(host 网络) /api/、/health 测试机 127.0.0.1:18099 候选 API
同一候选 Nginx /api/v1/qa-ops/ai/ 测试机 127.0.0.1:18098 现用治理 API,负责模型配置和连接验证
标准 Compose Web(容器网络) /api/、/health Docker DNS 解析 api:8080。静态资源和 SPA 回退由同一 Web 提供

在开发电脑恢复验收入口。 前提是 SSH 别名 weknora-test 能登录测试机。先查远端服务,再查本机监听。本机端口空闲且远端正常时,在独立终端运行第三条命令,保留该终端。在另一终端执行最后一条并用浏览器打开同一地址。

ssh weknora-test 'curl -fsS --max-time 5 http://127.0.0.1:28189/health'
ss -ltn 'sport = :28189'
ssh -NT -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 127.0.0.1:28189:127.0.0.1:28189 weknora-test
curl -fsS --max-time 5 http://127.0.0.1:28189/health

为内网域名配置 HTTPS。 在能访问测试主站的受信任反代机上配置证书、内部 DNS 和访问范围。以下片段放入已有 HTTPS server,完整保留 URI、Host 和会话 Cookie。上游应选治理 Web 入口,使 /assets/、/api/、/health 走同一域名。若该入口的内层代理也设置 X-Forwarded-Proto,联调时检查其保留受信任 TLS 终止层的协议值以及登录回调的实际 URL。

location / {
    proxy_pass http://100.85.111.121:8088;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

在反代机执行 nginx -t 校验待应用配置。入口启用后,通过该域名验证登录、一次 /api/ 请求和首页实际引用的 JS/CSS。index.html 应重新校验,带哈希的资源可长期缓存,缺失的 JS 返回 404。候选切换前后分别记录通用上游和 AI 专用上游。现场可在测试机用以下只读命令查看,容器名以当时部署为准。仓内同源配置见 deploy/nginx.conf。

docker exec kg-test-storage-ui-6444814 nginx -T 2>&1 | grep -E 'listen .*28189|location /api/v1/qa-ops/ai/|set \$(api|health)_upstream|proxy_pass http://127[.]0[.]0[.]1:18098'
docker inspect -f '{{.Name}} {{index .Config.Labels "release"}}' kg-test-storage-ui-6444814 kg-accept-090-api

现场版本与回退。 本次在测试机读到 Web 标签 4b615abe534b、API 标签 341c3154ac91。完整候选包的 current 链接位于 /opt/knowledge-governance/acceptance/090/current,单独切换的 Web 位于同级 web-only/4b615abe534b/dist,实际反代配置位于 integration/28189.conf。切换前记录这三处、容器标签与旧 Web 名称。静态页回退时恢复上次的 Web 资源和对应代理配置。完整候选回退按同批装配工具的 deploy/accept-090/README.md 执行。回退后用浏览器重新验证首页资源、模型连接和列库。数据库迁移另按备份与恢复方案处理。

本次已核实共享测试治理库到 000082。对内、对外独立启用的实现依赖 000083,待独立库联调或共享库迁移获准后,再验证单侧暂停、保存和刷新。生产 070 不在该套验收范围。

下文系统设置中的绑定、盘点和模型连接步骤适用于上表的测试候选版本。根据现场标签选择对应版本的代码和交付物。

接入外部平台

平台与用途 管理员或运维怎样接 接通的证据
钉钉知识库,取目录和文件 系统设置 → 数据源配置 → 钉钉授权。用 DWS 设备授权,以来源账号选择组织、空间和范围。API 与 worker 使用部署约定的 DWS 身份目录 登录后读回预期空间,选一个有权限的目录校验。登记来源、扫描完成和文件取件分别核验。
AList,取工业或教育资料 按来源登记服务根地址和允许的目录。普通 worker 读取专用令牌文件。目录接口 POST /api/fs/list 使用 X-Gateway-Token 在来源页扫描已知根目录,对照一个子目录和一份文件。下载遵循来源签名链接,凭据和签名 URL 仅留在受控运行环境。目录与取件
PP 资料门户 在数据源配置填写 HTTPS 根地址和来源账号,点「测试连接」后「保存并校验」。API 和 worker 共享 PP_AUTH_STATE_FILE 所在目录 真实登录并读取一条目录记录,刷新后核对生效配置。超时或限流时查看待验证状态。
WeKnora 测试 090,处理与验收 系统设置 → 知识库绑定 → 测试 090。当前测试 API 地址 http://127.0.0.1:8092,由治理服务器访问。输入该实例的专用 Key 或使用已配置凭据 「验证并读取知识库」能列出预期库。核对名称和 ID,为对内、对外选择不同的目标,保存后刷新读回
WeKnora 生产 090,列库与映射 在同页切到生产 090,使用下节的转发入口与生产专用 Key。新连接的安全存储由 WEKNORA_BINDING_MASTER_KEY_FILE 提供 读取生产目录并核对两个目标 ID,保存后重新进入生产页核实。执行发布另按 §5–6 授权
问答 AI 模型 系统设置 → AI 模型连接,填写 OpenAI 兼容基础地址(含服务要求的 /v1)、模型名及专用 Key。API 与普通 worker 使用同一 QA_AI_MASTER_KEY_FILE 点「测试连接」等待成功,需生效时再保存并刷新检查模型名。存储密钥、权限与 DNS 配置见 README

生产 090 的两段地址。 生产机私网 IP 为 172.29.151.11,其 WeKnora API 对宿主回环发布 127.0.0.1:18092。测试治理机上已有 SSH 本地转发,治理 API 使用 host 网络,故页面的生产服务地址填写 http://127.0.0.1:18092。请求从治理 API 发出,经测试机的回环监听到生产机的回环 API。浏览器所在电脑的 127.0.0.1:28189 则用于打开治理页面。迁到 bridge 网络时要从新 API 容器重新验证上游可达性。

在测试治理机上检验已有通道。/health 返回 200 证明转发可用,无凭据列库返回 401 表明请求已到认证层。接着在治理页面安全输入该实例的 Key 并验证真实库列表。本次核验时,生产通道探活成功,匿名列库返回 401。带生产凭据列库和保存映射仍待验收。

ss -ltnp 'sport = :18092'
curl --noproxy '*' --max-time 5 -sS -o /dev/null -w 'health %{http_code}\n' http://127.0.0.1:18092/health
curl --noproxy '*' --max-time 5 -sS -o /dev/null -w 'catalog %{http_code}\n' http://127.0.0.1:18092/api/v1/knowledge-bases

开发测试和现场验收

  1. 在开发机运行 make list 查看门禁,make verify 做整套检查。以 ci-report.json 的 commit_sha 对照 git rev-parse HEAD,记录失败或跳过项。前端启动和组件测试见 开发与 CI。
  2. 针对后端改动,在独立测试逻辑库核对 SELECT current_database(), max(version) FROM schema_migrations; 与候选版本的迁移目录。云端多个候选可能共用治理 RDS。只改静态页面时单独切换 Web,保留原资源和代理配置供回滚。
  3. 在指定入口以真实账号分别验证。来源页读取一条已知记录,模型页测试到成功终态,知识库绑定在正确环境列库,保存后刷新核对。存储页按最近批次和子库目录分别与 du -sB1 -- <目录> 对账。记录入口、Web/API 提交、时间和结果。
  4. 候选备份页读取宿主采集的 metadata.json,API 只读挂载输出目录。「重新盘点」只重读文件。超过 BACKUP_HOST_METADATA_MAX_AGE 时,目录、占盘和预测转为未知。宿主重新采集后核对采集时间是否前进、批次是否恢复。测试现场使用按次采集、15 分钟有效期。采集脚本和挂载参数以同批测试候选交付物为准。
症状 第一步怎么查 如何判定
浏览器连接被拒 对照本机 28189 监听和测试机 /health 远端正常、本机无监听时恢复本机 SSH 转发
页面打开,某个 API 404 或 502 查浏览器请求路径、Nginx 生效上游及对应 API 版本 404 先查路由是否存在,502 先查上游是否可达。AI 页单独核对 18098
能探活,列库仍灰或返回 401 核对选中环境、凭据配置状态、容器运行 UID 与凭据文件可读性 用该环境的专用身份实际列库。检查过程只记录状态码和可读性
历史可读,计划或配额显示未知 核对快照年龄、执行主机连接与配额字段 盘点、SSH 计划、配额分别验证。只有主机实际读回 cron 才能报告下一次执行时间

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. 发布准备:勾选 → 建批 → 锁定 【变:P0-1 建批时冻结 + P0-2 自动批准】

发布管理 → 审核要发布的知识:

  • 最快路径(推荐,单个或几条):在已批准那条上直接点 发布到生产 → 输入固定语句 → 提交。服务端在同一个动作里完成「建批(冻结+锁定)→ 授权生产发布」,无需填批次名、无需先建批再锁定。
  • 需要一批多条时:勾选 → 填批次名 → 创建并锁定清单(建批即锁定),再到发布清单点 授权发布。
  • 不再需要 生成新版本 / 确认冻结:服务端在"建批这一下"把当前实时计划冻结成一份已确认版本并绑定该批次。 语义不变——批一旦建立,清单/摘要/验收轮次/目标库绑定全部不可变、回滚按它走;变的只是"谁在什么时候按固化键"。
  • 同一份计划复用同一版本(摘要一致即复用),所以连续建批不会堆版本;计划变了才新建一版。
  • 审核:TEST_AUTO_REVIEW_POLICY = off | internal(默认,仅对内)| all。默认下对内知识验收通过即由系统批准 (审核记录 reviewer_ref=system:auto),对外仍需人工;策略可在容器环境变量调整,界面上只读展示当前值。 人工随时可驳回/改判;系统只允许写"第一条"审核,永远不会覆盖人工结论。
  • 建批即锁定:清单在建批那一刻冻结并立即密封,批次不可再改;锁定后才能授权生产发布。锁定 ≠ 上线。
  • 批量批准按人工身份记录(reviewer=当前登录人),人工可以推翻自己先前的驳回;系统自动批准(system:auto)永远只写第一条、不覆盖任何人工结论。

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. 系统设置里现在要维护什么

审核策略目前由容器环境变量 TEST_AUTO_REVIEW_POLICY 控制(api 与 worker 共用 compose 锚点,默认 internal)。 界面上「审核要发布的知识」标题下方会显示当前生效值。

分区 谁 现在要管什么
服务配置 管理员 测试地址 / 生产地址 / 生产 ID / 知识库 ID(保存时真探活,无效才拒)
测试知识库绑定 管理员 顶部连接卡:测试地址 + API Key(测试连接 → 保存;只回显尾4位);下方标注往哪个测试库路由(对内 ≠ 对外)
生产连接 管理员 生产地址填同网段反代 http://172.29.151.11:18093(需要 WEKNORA_ALLOW_PRIVATE_HTTP=true),密钥录入后只回显尾4位;停止 ssh -L 18092 隧道后仍可用
生产知识库绑定 管理员 源库 → 目标库映射(发布写哪个生产库);选项来自生产实例真实库,禁止手填 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 回填演练 + 目录契约 【新】 出事可验证地回填;换机器只改一处配置