bc49b85b56
build / build (push) Successful in 1m12s
- 矩阵:新增 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 部署方案同步成本轮真实结果。
6.5 KiB
6.5 KiB
本机正式 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+ 0600agent.env); 端点/闸门/队列声明与 worker 同源(LIBRARY_TARGET_*)。缺任何一项时封存会在开窗口前被拒并点名缺什么。
新增配置只在需要真正开维护窗口时才加(本机验收实例的取值可作模板,见
evidence-maintenance/harness/candidate-maintenance.env:LIBRARY_TARGET_INSTANCE/PROJECT/WRITERS/NON_WRITERS/DOCKER_SOCKET/INGRESS_*、LIBRARY_TARGET_REDIS_*)。
4. 部署步骤(父审后执行)
- 冻结:确认没有在跑的封存/同步/恢复作业(
GET /api/v1/library/jobs无 pending/running)。 - 备份治理库 + 归档根:
pg_dump治理库;保持LIBRARY_ARCHIVE_ROOT卷原样(版本与 blob 都在里面)。 - 构建:从候选 SHA 构建 api/worker/web 三个镜像,tag 里带完整 SHA;不在生产机上另行 build 源码。
- 切换:
docker compose up -d api worker web(只替换这三个容器;postgres/dingtalk-login/共享 WKNFull-* 不动)。 - 健康检查:
GET /health、GET /api/v1/library/overview?scope=internal200、GET /api/v1/library/maintenance?scope=internal200 且held=false。 - 页面验收(用户现有管理员会话,不再要候选密码):发布管理页 → 两库页签 → 目标维护面板显示"未接入/未占用"、Wiki 差异逐页行、作业进度与阶段。
5. 回滚
| 触发 | 动作 |
|---|---|
| api/web/worker 起不来或健康检查失败 | 三个容器回到 *-dc9e8276560d 镜像;迁移保持已应用(新表空表存在不影响旧代码) |
| 新版写入后需要完全回到旧结构 | 先停新版 api/worker → 按 072→067 逆序 down → 恢复备份的治理库 → 起旧镜像 |
| 归档不可读/版本异常 | 归档根只读回滚:保留新卷,切回旧卷挂载点 |
回滚不触碰正式账号、会话、治理库既有业务数据(迁移只加表/列),也不动 WeKnora 侧数据。
6. 正式账号与数据保留
- 管理员账号/会话在治理库
users/sessions(kg_sessioncookie)——迁移与镜像切换都不改这些表;不重置口令、不重新初始化。 - 首页登录沿用现有会话;验收时不要用候选环境的账号。
- 正式库与归档卷保留原路径,不做"清理/重建"。
7. 已知风险与前置条件(必须先解决或明确接受)
knowledge-governance-p1-release-worker-1处于重启循环(日志每分钟connect release target database,RELEASE_WORKER_ENABLED=false)。这是正式栈既有状态,不是本轮引入;部署前需要决定是修配置还是先停掉该服务,否则会持续刷日志。- 封存能力已在本机专用实例验证(2026-10-29:页面入口 → agent → 实例级窗口 → 同步 → 恢复)。
正式部署仍需按同一形状接线:
libraryagent(0600 socket)+agent.env(LIBRARY_TARGET_*)+LIBRARY_AGENT_SOCKET; 这套接线在正式栈上尚未执行。 - 入口排空探针未在最终构建复现(矩阵"已实现·未跑"):正式部署前若要拿这条证据,需要在生产机重复探针,并接受"闸门关得比客户端快"导致上传注入失败的可能。
- 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。