Files
knowledge-governance/docs/formal-8088-deployment-plan.md
T
姚章浩 f82eb0735f
build / build (push) Successful in 1m14s
docs(acceptance): 矩阵按四段重排,补封存链路缺口与 8088 部署方案
矩阵不再在顶部叠报告:已完成 / 缺代码 / 已实现未跑 / 需授权四段分开,
把本轮 Wiki 撤销真实验收(12 项检查)、贡献级差异、维护面板写进对应行,
并如实记下封存链路缺口(CLI 无入口排空证明、API 封存未接线)、
死信无解除契约、Neo4j 场景与排空探针未跑。

新增正式 8088 待验收部署方案:迁移 067–072、loopback 配置差异、
缺配即拒绝的 fail-closed 规则、回滚与账号数据保留。只准备,未执行。
2026-10-29 05:13:15 +08:00

6.3 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 目前没有运行:POST /api/v1/library/captures 会 503 并写明"未接线",不会假装已封存。

新增配置只在需要真正开维护窗口时才加(本机验收实例的取值可作模板,见 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. 封存能力未接线(见矩阵"缺代码"):正式上线后页面能如实显示"未接入",但"封存测试版本"按钮仍不可用。如果验收要求现场封存,需要先部署 libraryagent(cmd/libraryagent,0600 unix socket)并把 LIBRARY_AGENT_SOCKET 指到它。
  3. 入口排空探针未在最终构建复现(矩阵"已实现·未跑"):正式部署前若要拿这条证据,需要在生产机重复探针,并接受"闸门关得比客户端快"导致上传注入失败的可能。
  4. 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。