崩溃安全深潜:HatchZip 的日志(journal)机制如何让进程被杀后仍逐字节无损恢复

原创2026-10-25 19:19:001,682 阅读
文章标签:桌面应用CLI跨平台开发工具

崩溃安全深潜:HatchZip 的日志(journal)机制如何让进程被杀后仍逐字节无损恢复

HatchZip 是一个面向超大压缩包的**原地解压(in-place extraction)**开源工具:解压的同时把压缩包越切越短,磁盘只需要装得下解压输出。而它真正的硬核之处,是围绕这套"边解压边删"设计出的 journal(日志)机制——进程在任意时刻被杀、断电、崩溃,重新运行同一条命令即可从最后确认的字节处继续,输出与正常跑完完全逐字节一致。本文带你深潜这个机制:它记了什么、凭什么"无损"、以及 130 多个测试如何反复杀进程来验证它。

一、为什么原地解压必须配一份"日志"

传统解压缩器的节奏是:读压缩包 → 写出全部文件 → 你手动删压缩包。问题出在最后一步之前:磁盘上同时躺着完整压缩包 + 完整输出。一个 180 GB 的游戏包解压出 200 GB,那个瞬间需要 380 GB 空闲。

HatchZip 的做法反过来:从压缩包尾部开始逐个"单元"(ZIP 是一个文件、7z 是一个 solid 块、tar 是一个条目)解压,每完成一批就把对应的压缩包字节截掉,腾出的空间立刻给下一批用。

但"边解压边销毁自己的输入"意味着任何一步中断都可能是灾难。矛盾尤其尖锐在一点上:

ZIP 和 7z 的索引(目录)都存放在压缩包末尾——恰恰是截断最先吃掉的部分。

HatchZip 原地解压原理示意:档案从尾部逐块解压,journal 机制保证进程被杀后逐字节无损恢复

于是整个设计浓缩成一条铁律(出自 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),每批严格走这五步,顺序一步都不能错:

  1. 选批:从下一个未提交单元开始,按当前实际空闲空间(扣除 --keep-free 预留)圈定批次
  2. 并行解压:每个单元由工作线程解码,文件先写成 <名字>.hatchzip-part,解码器边解边验 CRC-32,完成后改名为真实文件名;链接只记录、不创建
  3. 冲刷(flush):整批强制落物理盘——Linux 一次 syncfs,macOS 用 F_FULLFSYNC,Windows 逐文件 FlushFileBuffers
  4. 提交(commit):原子更新 journal 里的 committed_len 和本批链接
  5. 截断(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、且恰好在"解码可以重新开始的位点"上,执行四步:

  1. 冲刷 part 文件及其上级目录
  2. 写入恢复点(resume 字段):已落盘的输出长度 written、解码重新开始的比特位置 bit、以及前 written 字节的 CRC-32
  3. 打洞:从该文件数据起点到 bit 所在字节之间的档案字节释放掉(长度不变,读作零)
  4. 如此循环,文件完成后走常规第 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 图形界面:解压前展示磁盘空间计划,中断的原地解压可恢复且逐字节无损

如果不想继续而是彻底放弃这次解压,运行 hatchzip restore game.zip:档案剩余部分(恰为原始前缀)会被补上一个新索引,变回一个 7-Zip、unzip 都能正常打开的标准压缩包,里面正好是尚未解出的条目;已解出的文件留在原地。restore 自身也是崩溃安全的——它的 journal 会写入 restoring 字段保存即将被覆盖的字节,中断后再跑一次即可收场(见 crates/core/src/restore.rs)。

小结:HatchZip journal 机制的三条设计原则

  1. 顺序即安全:写文件 → 落盘 → 记 journal → 截档案,四者严格排序,任何中断都落在可识别的状态格子里;
  2. 原子与校验:journal 永远原子替换,尾巴带 CRC-32,恢复点带 CRC-32,版本不匹配宁可拒绝也不乱动;
  3. 恢复点即断舍离:打洞永不越过最后一个持久化恢复点,所以被杀之后"丢"的永远只是待重做的部分,而不是已确认的成果。

想深入全部细节,建议直接读 docs/how-it-works.md(含每一步的实测数字),以及 journal.rs、engine.rs、storage.rs 这三个承载核心逻辑的源码文件。

登录后查看全文
hatchzip