Files
knowledge-governance/docs/formal-8088-deployment-plan.md
T
姚章浩 bc49b85b56
build / build (push) Successful in 1m12s
docs(acceptance): 封存闭环进"已完成",补死信最小外部契约
- 矩阵:新增 S06/S06-a/S06-b/V03-c/Neo4j 拒绝行(都有真跑证据);把"封存入口未接线"、
  "CLI 库级窗口"从缺口里移走;排空时序旧结论保留但标注被确定性做法取代。
- 死信解除仍缺产品路径,写出最小外部治理契约(保留原始行、审计、验证真实处理成功后
  按精确项解除、未解除继续阻断)。
- 台账补 0.1.169–0.1.180 的 SHA 与 run(含 211/215 failure、218 cancelled,不涂改)。
- library-capture / 8088 部署方案同步成本轮真实结果。
2026-10-29 06:34:05 +08:00

6.5 KiB
Raw Blame History

本机正式 8088 待验收部署方案(只准备,不执行)

本文是给父会话审查后用的一次性方案:没有替换 8088,没有重启共享业务。 正式栈当前仍是旧版(0.1.114),不得对外声称新版已上线。

1. 版本清单

项 值
当前正式版本 开发版 0.1.114 / 代码 dc9e827(api knowledge-governance-api:library-dc9e8276560d,web knowledge-governance-web:source-dc9e8276560d,worker knowledge-governance-worker:library-dc9e8276560d)
本次候选代码 分支 feat/library-wiki-contribution-diff,最终提交见交付报告(代码提交 + 文档提交分开列 SHA)
开发号 提交后由 scripts/version.py 自动得出(0.1.0 + 自 v0.1.0 起的提交数)
前端产物 npm --prefix web run build → web/dist,由 Dockerfile.web 打进 web 镜像
验收实例(已验证同 SHA) /tmp/kg-e2e/bin/{api,worker} + 候选 libraryctl,go version -m 的 vcs.modified=false

2. 数据库迁移

现状 目标
正式治理库 schema_migrations.max(version)=66 需要依次应用 000067 → 000072
000067_library_release_authorizations   发布授权表
000068_library_restore_kind             作业类型加 restore
000069_library_write_target_mutex       写入目标互斥
000070_library_maintenance              维护窗口表
000071_library_maintenance_level        维护级别(library / instance)
000072_library_instance_maintenance     实例级维护占用
  • 迁移在 api 启动时按 AUTO_MIGRATE 自动执行(与现有部署一致);先备份治理库再起新 api。
  • 回滚顺序:072.down → 071.down → 070.down → 069.down → 068.down → 067.down,仅在新版 api 不再写入这些表之后执行。
  • 这些迁移只新增表/列,不改动既有知识治理数据;但 000068 扩了 library_jobs.kind 的取值。

3. 运行配置(正式栈)

正式 api 现有相关环境变量(docker inspect knowledge-governance-p1-api-1):

PRODUCTION_RELEASE_REQUESTS_ENABLED=true
PRODUCTION_BACKUP_RESTORE_VERIFIED=true
PRODUCTION_WEKNORA_BASE_URL=https://weknora-test.dobot.cn
PRODUCTION_RELEASE_AUTH_TOKEN_FILE=/run/release-secrets/production_release_auth_token
PRODUCTION_WEKNORA_API_KEY_FILE=/run/release-secrets/target_weknora_api_key
LIBRARY_AGENT_SOCKET=/run/library-agent/agent.sock
LIBRARY_ARCHIVE_ROOT=/var/lib/knowledge-governance/library

没有 LIBRARY_TARGET_*(实例级维护目标)与 LIBRARY_PRODUCTION_DATABASE_URL。这必须保持"缺配即拒绝":

  • 缺 LIBRARY_TARGET_* 时,worker 在 prebackup 阶段直接失败并写明 「目标维护未接线,拒绝在挡不住入口/后台写入的情况下写目标」(cmd/worker/library_handlers.go)——不会退化成"库级锁假装维护"。
  • 缺 LIBRARY_PRODUCTION_DATABASE_URL 时 overview/差异按"未接入"显示,不显示 0 或被当成"无变化"。
  • /api/v1/library/maintenance 在实例未配置时返回 instance 缺省、held=false;页面显示「未接入 + 维护类操作 fail closed」。
  • LIBRARY_AGENT_SOCKET 指向的 agent 必须在部署时一起起来(scripts/library-agent-install.sh + 0600 agent.env); 端点/闸门/队列声明与 worker 同源(LIBRARY_TARGET_*)。缺任何一项时封存会在开窗口前被拒并点名缺什么。

新增配置只在需要真正开维护窗口时才加(本机验收实例的取值可作模板,见 evidence-maintenance/harness/candidate-maintenance.env:LIBRARY_TARGET_INSTANCE/PROJECT/WRITERS/NON_WRITERS/DOCKER_SOCKET/INGRESS_*、LIBRARY_TARGET_REDIS_*)。

4. 部署步骤(父审后执行)

  1. 冻结:确认没有在跑的封存/同步/恢复作业(GET /api/v1/library/jobs 无 pending/running)。
  2. 备份治理库 + 归档根:pg_dump 治理库;保持 LIBRARY_ARCHIVE_ROOT 卷原样(版本与 blob 都在里面)。
  3. 构建:从候选 SHA 构建 api/worker/web 三个镜像,tag 里带完整 SHA;不在生产机上另行 build 源码。
  4. 切换:docker compose up -d api worker web(只替换这三个容器;postgres/dingtalk-login/共享 WKNFull-* 不动)。
  5. 健康检查:GET /health、GET /api/v1/library/overview?scope=internal 200、GET /api/v1/library/maintenance?scope=internal 200 且 held=false。
  6. 页面验收(用户现有管理员会话,不再要候选密码):发布管理页 → 两库页签 → 目标维护面板显示"未接入/未占用"、Wiki 差异逐页行、作业进度与阶段。

5. 回滚

触发 动作
api/web/worker 起不来或健康检查失败 三个容器回到 *-dc9e8276560d 镜像;迁移保持已应用(新表空表存在不影响旧代码)
新版写入后需要完全回到旧结构 先停新版 api/worker → 按 072→067 逆序 down → 恢复备份的治理库 → 起旧镜像
归档不可读/版本异常 归档根只读回滚:保留新卷,切回旧卷挂载点

回滚不触碰正式账号、会话、治理库既有业务数据(迁移只加表/列),也不动 WeKnora 侧数据。

6. 正式账号与数据保留

  • 管理员账号/会话在治理库 users/sessions(kg_session cookie)——迁移与镜像切换都不改这些表;不重置口令、不重新初始化。
  • 首页登录沿用现有会话;验收时不要用候选环境的账号。
  • 正式库与归档卷保留原路径,不做"清理/重建"。

7. 已知风险与前置条件(必须先解决或明确接受)

  1. knowledge-governance-p1-release-worker-1 处于重启循环(日志每分钟 connect release target database,RELEASE_WORKER_ENABLED=false)。这是正式栈既有状态,不是本轮引入;部署前需要决定是修配置还是先停掉该服务,否则会持续刷日志。
  2. 封存能力已在本机专用实例验证(2026-10-29:页面入口 → agent → 实例级窗口 → 同步 → 恢复)。 正式部署仍需按同一形状接线:libraryagent(0600 socket)+ agent.env(LIBRARY_TARGET_*)+ LIBRARY_AGENT_SOCKET; 这套接线在正式栈上尚未执行。
  3. 入口排空探针未在最终构建复现(矩阵"已实现·未跑"):正式部署前若要拿这条证据,需要在生产机重复探针,并接受"闸门关得比客户端快"导致上传注入失败的可能。
  4. 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。