Files
knowledge-governance/deploy/cloud-test/README.md
T
姚章浩 e6472b0ec6 feat(library): 云测试发布目标接入的角色分离、快照搬运与图谱门禁
为什么改:发布执行链是"与目标同机"假设写死的(本机 docker.sock、本机 drain.json、
本机 Redis/PG),把目标换成云测试不能只改展示 URL;直接搬整套 worker 又会抢走
本机封存/QA/周报队列并按本机配置写错目标。所以先把"谁消费哪段队列"变成显式角色,
再补齐跨主机搬运与目标侧门禁。

角色(LIBRARY_WORKER_ROLE=full/release-executor/capture)不只影响 handler 列表,
还决定是否拥有 DDL(release-executor 只读校验迁移版本,落后即拒绝启动)、
收拾哪些 library_jobs.kind、是否跑 release 接管扫描、是否起 scheduler/QA/周报/探测。
capture 保留本机原有全部业务;release-executor 只挂 sync/restore/recover/baseline。

快照跨主机:新增内容寻址的 bundle(版本清单先落、blob 按 sha256 命名、清单最后
Link 作提交点),pack/unpack 幂等且拒绝覆盖与同名不同内容;执行器使用前仍逐 blob
重算 sha256,因此传输不可变有两道证据。

目标侧门禁:目标知识库 graph_enabled=true 时拒绝发布(发布只写 PG/ES/OSS,不写
Neo4j;未知也拒绝),只读检测、不改目标配置、不做图谱迁移。

云端入口:新增 drain 感知的 ingress 闸门(建连超时与读超时分离,半关闭单向传播,
SIGTERM 排空后写 drain.json 并 exit 0/2)、compose 叠加片段(app 不再发布端口、
frontend 与 adapter 的入口收敛到闸门、指向真实网络 weknora-test-v071-network)、
执行器启动脚本与治理 PG 反向隧道脚本(默认 unix socket,不占 TCP)。

验证:deploy/cloud-test/test_gate.py 13 项全 PASS(含 12 秒静默流、半关闭、2MiB 完整、
排空 exit 0/active_at_close=1、排空超时 exit 2、上游不可达不挂住);go test 相关包全绿;
scripts/ci_checks.py 16 项全部 success(EXIT=0,1241 用例通过/0 失败/191 已声明可选集成跳过);
云测试只读预检 17 项 / 6 FAIL,FAIL 项即当前部署缺口(无闸门、app 仍发布端口、
adapter 与 frontend 仍直连 app、云端归档根未建),未部署、未改云端任何状态。
2026-10-30 18:38:38 +08:00

176 lines
10 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.
# 云测试发布目标:部署与验证(父执行)
目标:把本机治理平台的"整库发布执行"搬到云测试主机,与目标容器同机;
本机只保留封存源、平台与 capture 角色的 worker。本文所有命令都在**目标机上**执行,
除了明确标注"本机"的两步。
## 0. 前置(缺一条都别继续)
- 云端 compose 项目 `weknora-test-v071` 当前健康,且已确认 `weknora-test.dobot.cn` 的维护窗口可接受。
- 已交付镜像:`knowledge-governance-worker:<与验收提交同 sha>`(含 `/app/libraryctl`)。
- `/srv/kgtest-gate/{gate.py,state}`、`/srv/knowledge-governance/{library,target-journal,bundles,release-executor.env}`。
- 治理库接入方式已定:SSH 加密反向隧道(`deploy/cloud-test/pg-forward.sh`,默认 streamlocal
unix socket)。本机 PG 在 Docker 内、无 5432 宿主机发布,**不要**写 `localhost:5432`。
## 1. 云端入口闸门(一次)
**先做 compose 身份核对(不能盲 `compose up`)**:父的现场记录里,某历史容器的 label
引用了已不存在的 `/tmp/weknora-test-compose.wiki-graph.yaml`。对这类容器执行
`docker compose up` 会让 compose 按"缺失的配置链"重建它,等于在没有可验证配置的情况下
重建业务容器。先逐容器读回配置链,只对**配置链文件都在**的服务做 `up -d`:
```bash
for c in $(docker ps -q --filter label=com.docker.compose.project=weknora-test-v071); do
docker inspect "$c" --format '{{.Name}} files={{index .Config.Labels "com.docker.compose.project.config_files"}}'
done
```
规则:`app`/`frontend` 的配置链齐全才允许 `up -d`;`ingress` 是本片段新增,没有历史包袱。
任何服务的 config_files 里有缺失文件 → **停手**,先补回可验证配置(或让父按运维流程处理),
不要用 `compose up` 把它"顺便"重建。只用显式服务名 `up -d app ingress frontend`,
不要 `up -d` 全项目(那会把无关服务一起重建)。
```bash
install -d -m 0755 /srv/kgtest-gate /srv/kgtest-gate/state
install -m 0644 deploy/cloud-test/gate.py /srv/kgtest-gate/gate.py
# 叠加片段来自本仓库 deploy/cloud-test/compose.release-overlay.yaml
cd /opt/weknora-test-v071 # 现有 compose.yaml 所在目录
docker compose -f compose.yaml -f /path/to/compose.release-overlay.yaml config >/dev/null
docker compose -f compose.yaml -f /path/to/compose.release-overlay.yaml up -d app ingress frontend
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health # 期望 200
docker inspect weknora-test-v071-app-1 --format '{{json .HostConfig.PortBindings}}' # 期望 null
```
要点:`app` 不再发布宿主机端口(写入者发布端口 = 绕开闸门的直连,拓扑校验会拒绝);
`ingress` 是宿主机 8080 上唯一的 HTTP 入口,`SIGTERM` 后写 `drain.json` 并 `exit 0`;
`restart: "no"` 保证维护窗口停下的入口不会被 Docker 自己拉回来。
### 1.1 入口不止 frontend:四条路径都要落到闸门上
只把 frontend 改成 `APP_HOST=ingress` **不等于**入口唯一。现场实测四条能到 app 的路径:
| 入口 | 现状 | 必须改成 | 谁做 |
|---|---|---|---|
| 宿主机 nginx `weknora-test.dobot.cn` → `127.0.0.1:8088` | frontend | 不用改;frontend 的 `/api` 由 `APP_HOST` 决定 | 父不改 |
| frontend 容器 → `app:8080` | `APP_HOST=app` | overlay 已改为 `APP_HOST=ingress` | overlay |
| knowledge-adapter 容器 → `http://app:8080`(双网络) | 直连 app | adapter 的 `WEKNORA_BASE_URL=http://ingress:8080` | 父改 adapter 部署 |
| DobotAI(host 网络)→ `http://127.0.0.1:8080` | 走宿主机发布端口 | 不用改;overlay 后该端口就是闸门 | 无 |
`scripts/verify_cloud_release_target.py` 的 `entry/*` 三项就是在核对这张表
(adapter 仍指 `app:8080` 时报 FAIL —— 它就是一条真实存在的绕闸通道)。
## 2. 快照(本机打包 → 云端导入)
```bash
# 本机(只读归档;输出了每个 blob 的 sha256,可与云端对拍)
libraryctl snapshot-pack -snapshot <snapshot_id> -bundle /var/tmp/<snapshot_id>.tar
# 传到云端
scp /var/tmp/<snapshot_id>.tar weknora-test:/srv/knowledge-governance/bundles/
# 云端:校验 + 原子装入(版本清单是提交点;重复导入幂等)
docker run --rm \
-v /srv/knowledge-governance/library:/var/lib/knowledge-governance/library \
-v /srv/knowledge-governance/bundles:/bundles:ro \
knowledge-governance-worker:<sha> \
/app/libraryctl snapshot-unpack \
-archive /var/lib/knowledge-governance/library \
-bundle /bundles/<snapshot_id>.tar \
-snapshot <snapshot_id>
```
导入失败时不会留下版本:blob 以 sha256 命名且先落盘,版本清单最后才 Link。
执行器每次使用快照前还会 `Load` 逐 blob 重算 sha256,所以"传输不可变"有两道证据。
## 2.5 治理库连接(SSH 加密反向隧道)
本机治理 PG 在 Docker 内且没有 5432 宿主机发布,不能写 `localhost:5432`。
`deploy/cloud-test/pg-forward.sh`(本机运行)解析 PG 容器的真实 IP 后建反向转发:
```bash
MODE=streamlocal bash deploy/cloud-test/pg-forward.sh # 推荐:云侧只出现 unix socket
MODE=tcp bash deploy/cloud-test/pg-forward.sh # 云侧 127.0.0.1:15433,仅宿主进程可用
```
- **streamlocal(默认)**:云侧生成 `/run/kgtest-pg/pg.sock`,执行器容器把该目录挂进去,
`DATABASE_URL` 用 `host=/run/kgtest-pg/pg.sock`。没有 TCP 端口、不受"容器看不到宿主
127.0.0.1"影响。
- **tcp**:`ssh -R 127.0.0.1:15433` 只在云**宿主机** loopback 上;执行器容器里的
127.0.0.1 是它自己,**不能**直接用。要用就必须在云侧再加 docker bridge → 127.0.0.1
的桥接(socat/haproxy),那是父的运维决定,脚本不替你开。
- 隧道断 = 执行器拿不到租约 = 作业 fail-closed,目标保持维护态(不会"假装成功")。
## 3. 执行器
```bash
# 1) 填写 /srv/knowledge-governance/release-executor.env(0600 root),
# 字段见 deploy/cloud-test/release-executor.env.example。
# 2) 先让本机变成 capture 角色(否则两边都注册 release,谁抢到按谁的配置执行):
# 本机 compose 加 LIBRARY_WORKER_ROLE=capture 重启 worker,日志应出现
# role=capture release=false source=true。
# 3) 起云端执行器:
RELEASE_EXECUTOR_IMAGE=knowledge-governance-worker:<sha> bash deploy/cloud-test/run-release-executor.sh
docker logs --tail 30 kgtest-release-executor # 期望:execution domain admitted / role=release-executor
```
## 4. 只读预检(任何时候都可跑)
```bash
python3 scripts/verify_cloud_release_target.py --host weknora-test --snapshot <snapshot_id>
```
判据:ssh、项目服务清单、写入者无发布端口、闸门 healthy 且发布 8080、经闸门 /health=200、
drain 目录可写且无残留、redis/ES/RDS 可达、归档根 0700、快照清单摘要自证、执行器角色。
`MANUAL target-graph` 必须人工确认目标 KB `graph_enabled=false`(发布路径不写 Neo4j)。
有 FAIL 即退出码 1。
## 5. 回退
```bash
docker rm -f kgtest-release-executor
# 本机 worker 改回 LIBRARY_WORKER_ROLE=full(或保持 capture)并重启
cd /opt/weknora-test-v071
docker compose -f compose.yaml -f /path/to/compose.release-overlay.yaml down # 或去掉 -f overlay 重新 up:
docker compose -f compose.yaml up -d app frontend
```
治理库不需要回滚:维护记录与版本证据都带 `target_fingerprint` 与实例身份,
跨目标不会被误认。云端归档里的快照与预备份保留,不自动删除。
## 6. 已知边界(交付时写明,不当成已完成)
- 本机 UI 的"版本与快照"读的是本机归档:云端预备份/快照原件在页面上看不到,
只能看到治理库里的版本证据行。需要页面展示云端原件时再单独做只读读回链路。
- 目标 KB `graph_enabled` 没有 fail-closed 检查(当前只有源侧导出拒绝)。
- 维护窗口内 `weknora-test.dobot.cn` 会不可用(这是语义正确的关闭)。
- **归档自动传输未实现**:今天只有 `libraryctl snapshot-pack / snapshot-unpack`(人工两步)。
UI 里点"发布/恢复"不会把本机快照送到云端执行器,也不会把云端预备份读回本机页面。
一致寻址的现状与阻塞见本文 §7。
## 7. 归档寻址:现状、缺口与阻塞(不许当成已完成)
**寻址口径(现状)**:快照是内容寻址的(`snapshot_id` = 版本清单 sha256),本机与云端
各自有独立 `LIBRARY_ARCHIVE_ROOT`;治理库的版本证据行记录 `snapshot_id` 与 `source_job_id`。
因此"这份版本是谁"跨主机一致,而"这份版本的字节现在在哪台机器"**没有**被记录。
后果(真实缺口):
1. 本机页面能看到云端执行器登记的版本证据行,但**看不到云端预备份/快照原件**;
点"按历史版本恢复"时,若该快照不在执行器所在机器上,作业会在装配阶段失败
(`librarysnapshot.Load` 读不到),错误信息只会说"快照不可读"。
2. UI 无法触发传输:本机 API 没有读归档/推送归档的接口,云端也**不能**主动连本机
(公网 22 关闭、无入站);今天唯一通路是人工 `pack` → `scp` → `unpack`。
**为什么不用脚本硬糊**:定时 rsync/scp 无法保证"版本清单与 blob 同时可见 + 字节可校验",
而发布前的 `Load` 会逐 blob 重算 sha256,半拷贝的归档会让发布在维护窗口内失败,
正好落在最不该失败的时刻。
**建议的最小协议(未实现,需父批准)**:给执行器一条**出站**拉取路径 ——
`GET /api/v1/library/snapshots/{id}/bundle`(本机 API 侧,仅服务已封存且未过期的快照,
返回带 sha256 的流)+ 在版本证据里补 `archive_host` 字段。执行器在装配前若本地缺快照,
按证据里的 `archive_host` 标记走到该 API 拉取并复用 `Unpack` 的校验/原子落位。
工作量约:API 1 个只读端点 + 证据字段 + 执行器一次拉取调用(~300 行 + 权限/审计)。
通路本身可以复用已有的 `ssh -R`(再加一条把本机 API 映到云侧 loopback/unix socket 的
反向转发),所以阻塞不在"连不上",而在:① 该端点等于让云侧凭据读走整库快照,
需要单独的鉴权与审计口径;② 版本证据要新增 `archive_host`,否则 UI 无法判断"该去哪台机器取";
③ 拉取失败必须与"目标已进维护窗口"的时序绑定,不能先开窗口再发现取不到。
这三条都要父拍板,属于新协议而非配置。