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

90 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 本机正式 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. 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。