feat(library): 快照搬运先于维护、双向校验与云端版本回传

为什么改:云端 release-executor 与目标同机后,本机封存的快照必须"先到、先验证"
才允许开维护窗口。此前只有 pack/unpack 两条人工命令:UI 点发布时执行器读到的是
本机归档路径,云端根本没有这份快照,作业只能在装配阶段失败;而预备份落在云端,
本机页面也读不到。用户已批准补齐这条链路。

搬运(新包 internal/libraryhandoff):本机 Load 逐 blob 重算 → Pack → SSH 流式写入
云端暂存 → 原子改名 → 云端 snapshot-unpack 再逐 blob 校验 → 读回版本清单摘要自证 →
scope/tenant/知识库身份与治理库作业一致。只有全部通过才投递 library.sync|restore,
失败时发布作业根本不存在(目标不进维护、不写知识)。远端命令是固定 argv,容器名与
路径只来自部署配置;同 ID 异内容拒绝;同一快照本机 flock 串行化;暂存 bundle 用后即删,
归档本体永不自动清理。

回传:capture 角色按已成功作业的 snapshot_id 扫描,把本机缺失的云端快照 Fetch 回来
(云端 pack → SSH 流回 → 本机 Unpack 逐 blob 校验)。回传成功后 API/页面既有的列表、
详情、差异、存储与历史恢复路径读到的就是真实字节;失败则版本不出现在本机,不会被误报成可恢复。

角色:搬运与回传只注册在 capture;若接线到 full(同时消费发布作业)启动即失败,
避免与云端执行器抢同一批作业。release-executor 仍不拥有治理库 DDL,也不消费
QA/邮件/来源扫描。

验证:internal/libraryhandoff 全绿(跨进程 push/fetch、身份不符拒绝、幂等复用、
并发串行、篡改与未知快照不落版本、路径穿越拒绝、远端错误不当作"没有");
cmd/worker 在隔离 fixture 库(独立测试 PG)上验证"校验通过才入队发布、失败不入队";
httpapi 队列决策单测;相关包 go test 全绿;go vet 全仓通过。

未部署、未推送、未构建镜像:云端接线与验收仍由父执行。真实云链路(含 SSH 通道)
本轮没有云侧写操作,只有本机跨进程与隔离 fixture 证据。
This commit is contained in:
姚章浩
2026-10-30 18:56:26 +08:00
parent e6472b0ec6
commit 6400fd1bbe
18 changed files with 1801 additions and 12 deletions
+10 -1
View File
@@ -58,4 +58,13 @@ LIBRARY_AGENT_SOCKET=
# 这两个开关只是"本进程允许写"的部署声明;真正的授权是治理库里与快照绑定的
# release 授权行。任何一道为 false,发布会在维护窗口之前被拒绝。
PRODUCTION_RELEASE_REQUESTS_ENABLED=true
PRODUCTION_BACKUP_RESTORE_VERIFIED=true
PRODUCTION_BACKUP_RESTORE_VERIFIED=true
# ---- 快照搬运(本机 API + capture worker 侧配置;执行器不消费这组变量)----
# 只写在这里作对照:真正的 LIBRARY_HANDOFF_* 配在**本机** api/worker 容器,
# 执行器只需要 LIBRARY_ARCHIVE_ROOT 与 BUNDLE_DIR 对应的宿主机目录存在。
# LIBRARY_HANDOFF_SSH_CONFIG=/run/secrets/backup-host/ssh_config
# LIBRARY_HANDOFF_TARGET=weknora-test
# LIBRARY_HANDOFF_EXECUTOR=kgtest-release-executor
# LIBRARY_HANDOFF_BUNDLE_DIR=/srv/knowledge-governance/bundles
# LIBRARY_HANDOFF_REMOTE_ARCHIVE=/var/lib/knowledge-governance/library
# LIBRARY_HANDOFF_STAGING_DIR=/var/lib/knowledge-governance/handoff-staging