Files
knowledge-governance/deploy/cloud-test
姚章浩 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
..

云测试发布目标:部署与验证(父执行)

目标:把本机治理平台的"整库发布执行"搬到云测试主机,与目标容器同机; 本机只保留封存源、平台与 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:

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 全项目(那会把无关服务一起重建)。

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. 快照(本机打包 → 云端导入)

# 本机(只读归档;输出了每个 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 后建反向转发:

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. 执行器

# 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. 只读预检(任何时候都可跑)

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. 回退

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 无法判断"该去哪台机器取"; ③ 拉取失败必须与"目标已进维护窗口"的时序绑定,不能先开窗口再发现取不到。 这三条都要父拍板,属于新协议而非配置。