崩溃安全深潜:HatchZip 的日志(journal)机制如何让进程被杀后仍逐字节无损恢复
崩溃安全深潜:HatchZip 的日志(journal)机制如何让进程被杀后仍逐字节无损恢复
HatchZip 是一个面向超大压缩包的**原地解压(in-place extraction)**开源工具:解压的同时把压缩包越切越短,磁盘只需要装得下解压输出。而它真正的硬核之处,是围绕这套"边解压边删"设计出的 journal(日志)机制——进程在任意时刻被杀、断电、崩溃,重新运行同一条命令即可从最后确认的字节处继续,输出与正常跑完完全逐字节一致。本文带你深潜这个机制:它记了什么、凭什么"无损"、以及 130 多个测试如何反复杀进程来验证它。
一、为什么原地解压必须配一份"日志"
传统解压缩器的节奏是:读压缩包 → 写出全部文件 → 你手动删压缩包。问题出在最后一步之前:磁盘上同时躺着完整压缩包 + 完整输出。一个 180 GB 的游戏包解压出 200 GB,那个瞬间需要 380 GB 空闲。
HatchZip 的做法反过来:从压缩包尾部开始逐个"单元"(ZIP 是一个文件、7z 是一个 solid 块、tar 是一个条目)解压,每完成一批就把对应的压缩包字节截掉,腾出的空间立刻给下一批用。
但"边解压边销毁自己的输入"意味着任何一步中断都可能是灾难。矛盾尤其尖锐在一点上:
ZIP 和 7z 的索引(目录)都存放在压缩包末尾——恰恰是截断最先吃掉的部分。
于是整个设计浓缩成一条铁律(出自 docs/how-it-works.md):
journal 永远不会在文件落盘持久化之前"认领"它;archive 也永远不会在 journal 认领之前被截断越过某个单元。
二、档案旁边的两个小文件:.hatchzip 与 .hatchzip-tail
开始解压前,HatchZip 会在压缩包旁边生成两个伴生文件(以 game.zip 为例):
| 文件 | 内容 |
|---|---|
game.zip.hatchzip |
journal 本体,一个小型 JSON 文件,记录进度 |
game.zip.hatchzip-tail |
压缩包末尾的"尾巴"(索引),连同样本它的 CRC-32 一并记入 journal |
journal 的每个字段都有明确用途,定义在 crates/core/src/journal.rs:
| 字段 | 作用 |
|---|---|
format |
zip / 7z / tar / tar.gz,恢复时无需从半截文件里猜格式 |
parts |
每个分卷(split archive)及其原始长度,续跑时校验剩余部分是未被破坏的前缀 |
tail_start、tail_crc |
存档尾巴的归属位置与校验和 |
output |
输出目录,防止恢复时指向别处 |
committed_len |
最新一次提交后的档案长度;凡是起点在它之后的单元都已做完,不需要单独的"完成计数器" |
links |
最后才创建的符号链接/硬链接清单 |
resume |
正在流式解压的大文件恢复点(下文详述) |
从此以后,压缩包通过一个"虚拟读取器"解析:tail_start 以下读真实文件,以上从存档尾巴回放(被截掉或打洞的区域读作零)。格式库看到的档案与原始状态一模一样,而零区域天然像"档案结束",解析剩下的部分恰好就是尚未完成的单元。
注意:解压没完成前,千万别手动删掉这两个文件——它们手里握着档案已经失去的索引。
三、一批处理的五步顺序:顺序就是安全
HatchZip 按批次推进(最多 512 个单元或 2 GB),每批严格走这五步,顺序一步都不能错:
- 选批:从下一个未提交单元开始,按当前实际空闲空间(扣除
--keep-free预留)圈定批次 - 并行解压:每个单元由工作线程解码,文件先写成
<名字>.hatchzip-part,解码器边解边验 CRC-32,完成后改名为真实文件名;链接只记录、不创建 - 冲刷(flush):整批强制落物理盘——Linux 一次
syncfs,macOS 用F_FULLFSYNC,Windows 逐文件FlushFileBuffers - 提交(commit):原子更新 journal 里的
committed_len和本批链接 - 截断(truncate):把档案缩短到本批最低单元的起点,空间这才释放给下一批
顺序的深意在于:文件先"落盘持久化"(第 3 步),journal 才"认领"(第 4 步),档案最后才"失血"(第 5 步)。任何一步被打断,磁盘状态必然落在下表的某一格里,而每一格都有对应的恢复动作:
| 中断时机 | 磁盘上的状态 | 续跑做什么 |
|---|---|---|
| 选批 / 解压中 | 存在若干 part 文件或已完成文件,journal 未记录,档案完好 | 删掉这些文件(输出目录必须为空,所以它们必然是 HatchZip 写的),整批重解 |
| 冲刷中 | 同上 | 同上 |
| 提交中 | 原子改名要么发生、要么没发生 | 落入上、下两格之一 |
| 截断中 | journal 已记录本批,档案仍长于 committed_len |
补截断,继续下一批 |
| 末尾建链接 | 所有单元已提交 | 重建全部链接(覆盖已存在的) |
| 删档案和伴生文件 | 档案已消失,journal 还在 | 重建链接,清掉伴生文件 |
关键支撑是"提交"这一步的原子写:crates/core/src/fsutil.rs 里的 write_atomic 先把新内容写进临时文件、sync_all 刷盘、再 rename 覆盖旧文件并刷目录——崩溃后文件里要么是旧内容、要么是新内容,绝无混合体。
四、逐字节恢复的大文件:resume 字段
普通单元"整块提交"之外,还有一种更精细的场景:一个 30 GB 的 ZIP 大文件,若文件系统支持打洞(hole punching,ext4/XFS/btrfs 等),HatchZip 会把它流式解压——每产出 256 MiB、且恰好在"解码可以重新开始的位点"上,执行四步:
- 冲刷 part 文件及其上级目录
- 写入恢复点(
resume字段):已落盘的输出长度written、解码重新开始的比特位置bit、以及前written字节的 CRC-32 - 打洞:从该文件数据起点到
bit所在字节之间的档案字节释放掉(长度不变,读作零) - 如此循环,文件完成后走常规第 3~5 步提交
这里有两个精妙细节:
bit记在比特而非字节:deflate 流的块边界可能落在一个字节中间,所以位置以"距档案起点的比特数"记录。恢复解码器(crates/core/src/archive/resumable.rs)借用 zlib 官方的zran技巧,在任意块边界重启 inflate。- 32 KiB 滑动窗口不进 journal:重启 deflate 需要前序 32 KiB 输出(回溯引用会探到那里),而这 32 KiB 恰好就是 part 文件的尾部——它在恢复点写 journal 之前已冲刷落盘,直接读回即可,无需重复存储。
对于 .tar.gz(整条压缩流只能从头解),resume.stream 还会额外记录 gzip 成员、解码器与 tar 解析器在 bit 处的完整状态。恢复时的容错矩阵同样严格:
| 中断时机 | 磁盘状态 | 续跑做什么 |
|---|---|---|
| 首个恢复点写入前 | 有 part 文件,未打洞 | 删掉,整个文件重新解 |
| 冲刷后、journal 写入前 | part 文件含有超出上一恢复点的输出 | 截回上一恢复点,从那里解码 |
| journal 写入后、打洞前后 | 新恢复点已持久,其前字节可能已释放 | 从新点解码,绝不读取它之前的字节 |
| 改名后、提交前 | 文件已有真实名,journal 仍持旧点 | 改回 part 名,从旧点继续 |
背后规则只有一条:档案永远不会被打洞越过最后一个持久化恢复点,且一个恢复点只有在其担保的输出已落盘后才是"持久的"。
五、版本护栏:新旧版本互相防身
journal 当前是第 3 版(新增 resume)。journal.rs 的 load 先单独解析 version 再决定是否加载:
- 读到更新版本的 journal → 拒绝并提示"请用写出它的那个版本继续",因为新版布局可能包含旧版会误删一半文件的语义;
- 读到旧版(v2)→ 按原样加载;
- 解析
version都失败 → 报"journal 已损坏",而不是抛出令人困惑的字段错误。
这就是为什么升级 HatchZip 后旧任务能续跑、而用旧版打开新任务会被温和地挡在门外。
六、不是纸面安全:用杀进程证明
设计再漂亮,"崩溃安全"也得靠暴力测试背书。HatchZip 的测试套件就是在每个危险时刻反复杀进程:
| 测试文件 | 杀在何时 | 验证什么 |
|---|---|---|
| crates/cli/tests/extract.rs、formats.rs | 批处理的第 3、5 步(flush / truncate)的众多位置,覆盖全部格式与分卷边界 | 续跑后的输出与正常跑完逐字节一致 |
| crates/cli/tests/streaming.rs | 流式恢复点三步(冲刷/写 journal/打洞)的多个位置,含 stored、deflate ZIP 与 tar 条目 | 恢复点之后的内容未被触碰;打了洞的空间确实被归还 |
| crates/cli/tests/restore.rs | restore 流程第 5、6 步之后 |
中断的 restore 可重跑或转回继续解压 |
| crates/core/src/archive/resumable.rs(单元测试) | 从 deflate 流的每一个块边界恢复(压缩级别 6 和 9) | 比特级重启动解码的正确性 |
七、GUI 与善后:restore
如果你用的是桌面版,这些安全机制都是内建的:启动前它先给出完整磁盘空间计划,界面底部明确提示"解压中断后可以继续"。
如果不想继续而是彻底放弃这次解压,运行 hatchzip restore game.zip:档案剩余部分(恰为原始前缀)会被补上一个新索引,变回一个 7-Zip、unzip 都能正常打开的标准压缩包,里面正好是尚未解出的条目;已解出的文件留在原地。restore 自身也是崩溃安全的——它的 journal 会写入 restoring 字段保存即将被覆盖的字节,中断后再跑一次即可收场(见 crates/core/src/restore.rs)。
小结:HatchZip journal 机制的三条设计原则
- 顺序即安全:写文件 → 落盘 → 记 journal → 截档案,四者严格排序,任何中断都落在可识别的状态格子里;
- 原子与校验:journal 永远原子替换,尾巴带 CRC-32,恢复点带 CRC-32,版本不匹配宁可拒绝也不乱动;
- 恢复点即断舍离:打洞永不越过最后一个持久化恢复点,所以被杀之后"丢"的永远只是待重做的部分,而不是已确认的成果。
想深入全部细节,建议直接读 docs/how-it-works.md(含每一步的实测数字),以及 journal.rs、engine.rs、storage.rs 这三个承载核心逻辑的源码文件。

