Checkpoints and Rollback zh CN

Checkpoint、恢复与回滚

语言： English · 简体中文

LWC 提供两种不同粒度的恢复边界：

• Checkpoint 是某个 live Wiki 的命名式完整 SQLite 快照；
• Changeset rollback 是一项已提交 changeset 所触及实体的冲突感知 inverse。

应选择与故障范围相符的最小边界。撤销一次逻辑发布时使用 changeset rollback；大范围操作没有准确 inverse 时，事前创建 checkpoint。

何时创建 Checkpoint

以下情况适合先创建 checkpoint：

• 大范围替换已有页面；
• 在 changeset 外执行多来源 ingest；
• 影响面较大的人工恢复或迁移；
• 可能需要还原整个 Wiki 数据库的运维实验。

无需给每条事务命令都套 checkpoint。单次 mutation 本身已经原子提交，频繁快照只会增加存储，不能进一步改善它的安全性。

创建与查看

lwc --scope project checkpoint create before-architecture-refresh
lwc --scope project checkpoint list

创建过程使用 SQLite online backup API，不修改 Wiki 知识。名称必须是安全的本地标识，已有 checkpoint 永远不会被覆盖。

list 按名称稳定排序，并返回每个 checkpoint 的路径与大小。

Checkpoint 只能操作一个 live project 或 global Wiki；不支持 --scope all，也不能在 changeset 草稿中运行。

Checkpoint 包含什么

Checkpoint 会捕获某一提交点的完整规范 Wiki 数据库，包括 Sources、ingest 状态、Pages、provenance、标签、检索状态、反馈、操作历史以及其他 SQLite 记录。

Deployment-local 配置、生成的 Markdown 目录、文档图 sidecar 和 CodeGraph runtime 都不在 wiki.db 中，因此不会随快照复制：

• 当前图配置保持不变；
• Restore 后重新物化 Markdown；
• 已启用的文档图会根据恢复后的规范状态做全量投影；
• CodeGraph 继续作为项目源码的独立索引存在。

安全恢复

lwc --scope project checkpoint restore before-architecture-refresh

Restore 会依次执行：

1. 只读打开指定 checkpoint，并校验 schema 与完整性；
2. 在触碰 live 数据前准备、校验私有恢复 candidate；
3. 为当前 live 数据库新建 pre-restore-* checkpoint；
4. 获取 live write lock；准备期间 live revision 已推进则拒绝恢复；
5. 通过 SQLite backup 替换 live 数据库；
6. 已启用图引擎时排入文档图全量投影；
7. 重新生成物化 Markdown。

响应会同时给出来源 checkpoint 和自动生成的 safety_checkpoint。应把安全快照名称记入事故记录，它代表恢复发生前一刻的状态。

Restore 只等待规范数据库完成替换。图投影仍然属于 Work，需要另外 watch。

恢复后验收

lwc --scope project checkpoint restore before-architecture-refresh
lwc --scope project work watch <graph-work-id>
lwc --scope project lint
lwc --scope project search "known answer" --limit 5
lwc --scope project graph verify

图能力未启用时，响应不会包含 graph_work，此时只跳过 Work 与图检查；规范页面、检索、lint 和物化 Markdown 仍然必须验收。

验收要同时检查“应存在”和“应消失”的状态：确认 checkpoint 之后产生的错误内容已经消失，也确认快照内的预期内容已经恢复。

部分成功错误

规范恢复可能已经成功，后续投影却失败。LWC 会在这种情况下明确返回：

• checkpoint_restored=true；
• 来源 checkpoint 名称；
• 自动生成的安全 checkpoint；
• 图已成功排队时的 graph_work；
• 一条准确的 recovery_command，或一组 recovery_commands。

应原样执行这些命令。不要重复原来的知识 mutation，也不能看到普通错误就假定数据库没有变化。

常见后续命令包括：

lwc --scope project maintenance materialize
lwc --scope project config set --graph grafeo

即使项目图设置继承自 global，恢复命令也会准确作用到刚被恢复的 Wiki scope。

如果 restore 无法安全准备，或无法获得稳定的 live revision，会返回 checkpoint_restored=false。Busy conflict 可以重试，结构损坏的 checkpoint 则不能。

Changeset 回滚

使用 commit 返回的稳定 changeset ID：

lwc --scope project changeset rollback <changeset-id>
lwc --scope project work watch <graph-work-id>
lwc --scope project graph verify

Changeset rollback 比 checkpoint restore 更窄。它使用带 checksum 的 inverse patch，只恢复 touched entities。后来写入已经修改其中任意实体时，rollback 会返回 changeset_rollback_conflict，而不是覆盖新工作。

Source path head、重映射 Source ID、Page 引用、标签和文档图投影都会一致恢复。重复同一 rollback 是幂等的；规范回滚成功但后续清理或投影失败时，也应通过重试它完成恢复。

如何选择

需求	选择
撤销一项已提交的多命令知识更新	Changeset rollback
保留之后发生的无关 live 写入	Changeset rollback
把整个 Wiki 数据库恢复到旧时间点	Checkpoint restore
保护大范围非 changeset ingest 或迁移	操作前创建 checkpoint
只修复派生 Markdown、检索或图状态	使用 maintenance 或图重投影，不做 restore

安全规则

• 禁止手工编辑 checkpoint 数据库或图 sidecar。
• 不要直接复制 WAL 模式下的 live wiki.db 充当备份，应使用 checkpoint create。
• Restore 前记录准确 scope、checkpoint 名称和验收项。
• 把 database_busy 视为并发信号，不能绕过 revision guard。
• Live 验收完成前保留自动安全 checkpoint。
• 不要借 checkpoint restore 切换图引擎或部署配置。

完成证据

恢复满足以下条件才算完成：

• 选择的恢复边界与预期影响范围一致；
• restore 或 rollback 响应能标识对应恢复产物；
• 规范 Pages、Sources、标签和检索符合预期；
• 物化 Markdown 已更新；
• 返回的图 Work 已达到 succeeded；
• 图启用时 graph verify 返回 ok=true；
• 部分成功 recovery command 已执行并复检；
• 完成验收前仍保留恢复前状态。

下一篇：只读可视化界面