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

204 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 现行用户操作流程(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` 能登录测试机。先查远端服务,再查本机监听。本机端口空闲且远端正常时,在独立终端运行第三条命令,保留该终端。在另一终端执行最后一条并用浏览器打开同一地址。
```bash
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。
```nginx
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](../deploy/nginx.conf)。
```bash
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 仅留在受控运行环境。[目录与取件](SOURCE_CATALOG_LIVE_ROUTING_ACCEPTANCE.md) |
| 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](../README.md#问答运营模型配置) |
**生产 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。带生产凭据列库和保存映射仍待验收。
```bash
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](../README.md#开发与-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 天)**
```bash
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
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 | 回填演练 + 目录契约 **【新】** | 出事可验证地回填;换机器只改一处配置 |