045fc44f0e
build / build (push) Failing after 19s
- libraryctl:status/preflight/capture/list/verify/recover,只读来源会话、
结清检查、契约推导、维护窗口内停写者、导出十表+索引+对象+Wiki、封存候选后恢复
- libraryfreeze.ProjectController:按 Compose 项目逐服务声明固定身份,
未声明服务/容器重建即拒绝,仅 SIGTERM,恢复后必须 healthy
- httpapi:GET /api/v1/library/snapshots[/{id}] 只读列出封存产物
- web:「整库版本」页(只读、未接线显示原因、无假按钮)
- api:LIBRARY_ARCHIVE_ROOT + 归档根只读挂载
- docs/library-capture.md:运维手册与 2026-10-28 两次真实封存实测
不代表整库业务验收通过:内容/问答/性能验收、跨系统切点、Wiki 删除语义重算、
生产预备份/恢复演练/双闸/同步协调仍未完成。
69 lines
4.5 KiB
Markdown
69 lines
4.5 KiB
Markdown
# 整库封存(libraryctl)运维手册
|
||
|
||
本文只讲**测试库**的整库封存链:怎么跑、它证明了什么、它**没有**证明什么。生产发布与恢复、清理不在本文范围。
|
||
|
||
## 它做什么
|
||
|
||
`libraryctl capture -scope internal|external`:
|
||
|
||
1. 从**本机真实测试栈**(默认 Compose 项目 `weknora071full`)读来源配置:容器环境里的数据库/检索/对象存储参数,运行时读取,不落盘、不回显。
|
||
2. 用**只读会话**(`default_transaction_read_only=on`)连来源 PostgreSQL;连接串只在进程内存里。
|
||
3. 核对来源已结清:所有文档 `parse_status=completed`、无待处理操作、无死信(任一不满足就拒绝,不看其他 KB 的局部状态)。
|
||
4. 从持久数据推出兼容契约:迁移版本、dirty、租户、Embedding 模型与维度、检索引擎、索引名、索引映射摘要(`text-embedding-v4` / 1024 维 / schema 74)。
|
||
5. 在**维护窗口**内停住声明过的写入者(只对声明为 writer 的服务发 SIGTERM,等它真的停下),导出 PostgreSQL 十表 + Elasticsearch 正文与向量 + 对象资源,做双向覆盖与摘要核验,封存为内容寻址产物。
|
||
6. 无论成败都恢复写入者并等到 healthy;崩溃留下的日志用 `libraryctl recover` 收尾。
|
||
7. 打印快照 ID、分项(kind/name/数量/字节/SHA256)与兼容契约。
|
||
|
||
## 写入者声明(安全边界)
|
||
|
||
`scripts/library-capture.sh` 里逐项声明了项目内**每一个**服务:一个 writer(`app`),其余每个都写了"为什么它不会写知识"。`ProjectController` 的规则:
|
||
|
||
- 整个 Compose 项目被枚举(含停止的),只按声明停机;
|
||
- 项目里出现未声明的服务 → **拒绝执行**,不会"只停已知的那几个";
|
||
- 首次清点后固定容器 ID,容器被重建(同名新实例)→ 拒绝,避免停到一个没被声明的实例;
|
||
- 只发 SIGTERM,没有会在恢复后才触发的 SIGKILL 定时器;
|
||
- 启动后必须等到 healthy 才算恢复。
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
# 接线与来源探针(只读,不停服务)
|
||
./scripts/library-capture.sh status
|
||
# 预检:读来源 + 结清检查 + 候选校验,不写盘、不停服务
|
||
./scripts/library-capture.sh preflight -scope internal
|
||
# 真实封存(停 app → 导出 → 恢复 app)
|
||
./scripts/library-capture.sh capture -scope internal
|
||
./scripts/library-capture.sh capture -scope external
|
||
# 已封存产物
|
||
./scripts/library-capture.sh list
|
||
./scripts/library-capture.sh verify -snapshot <id>
|
||
# 崩溃后的收尾(恢复写入者)
|
||
./scripts/library-capture.sh recover
|
||
```
|
||
|
||
产物默认写到 `~/.local/share/knowledge-governance/library`(0700),日志写到 `~/.local/share/knowledge-governance/freeze`(0700)。api 容器只以只读方式挂载前者,「整库版本」页据此展示;页面**没有**封存按钮,因为封存要维护窗口与来源凭据,只能在目标主机执行。
|
||
|
||
## 2026-10-28 实测(本机测试栈)
|
||
|
||
| 项 | 对内 | 对外 |
|
||
| --- | --- | --- |
|
||
| 快照 | `f992d64ea45bf737a0721a465b5aef2b150ef7757157eb84f3aaf8b6972d98f9` | `01343b0b310b3977c2fdda05f5b8a6272148c4f7bfa124a6c5944123cf0c51c3` |
|
||
| 文档 / 分块 / 索引 | 4 / 38 / 122 | 0 / 0 / 0 |
|
||
| 资源 / Wiki 页 | 21 / 31 | 0 / 1 |
|
||
| 分项数 / 逻辑字节 | 32 / 55,309,044 | 13 / 1,121 |
|
||
| 策略 | artifact-acceptance-v1 | artifact-acceptance-v1 |
|
||
|
||
两次封存都记录了 `stop_verified=true`、`restored=true`,`WKNFull-app` 恢复后 healthy;来源未做任何写操作。
|
||
|
||
## 它证明了什么 / 没有证明什么
|
||
|
||
已证明:这一份整库内容在**写入者停住**之后被完整导出,PostgreSQL 与 Elasticsearch 双向覆盖、生成问题、资源与摘要逐项核验通过,产物可寻址、可复读、可校验。
|
||
|
||
没有证明(不要把候选当版本):
|
||
|
||
- **内容/问答/性能验收**没有做,也没有把结果绑定到快照;
|
||
- **跨 PG / ES / 资源的一致切点**只是在维护窗口里取得,没有独立的切点证据;
|
||
- **Wiki 删除贡献的语义重算**没有做;Wiki 队列空不等于语义正确;
|
||
- 对外库当前是空的(0 文档 1 Wiki 页),这份快照只说明"它当时确实是空的";
|
||
- 生产备份/恢复、双闸授权、整库同步与失败续作都没有接线,本文不涉及;
|
||
- 上游父子分块漏正文索引的风险仍在:本次候选通过是因为库里现有数据已补齐,**以后再重解析**仍可能漏项,届时封存会因覆盖核验失败而阻断(这是设计如此)。 |