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 部署方案同步成本轮真实结果。
93 lines
6.5 KiB
Markdown
93 lines
6.5 KiB
Markdown
# 本机正式 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. 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。 |