HatchZip 就地解压实战:边解压边回收归档空间(ZIP/7z/tar/.tar.gz/分卷)

原创2026-10-24 12:17:282,819 阅读
文章标签:桌面应用CLI跨平台开发工具

HatchZip 就地解压实战:边解压边回收归档空间(ZIP/7z/tar/.tar.gz/分卷)

本文以仓库 README.md 为核心脉络,系统讲解 HatchZip 如何在磁盘空间不足时"边解压、边收缩归档":从空间预检、命令行用法、崩溃恢复、安全边界,一直到引擎中的单元切分、日志(journal)、流式解压与空洞回收。读完后你既能照着手册完成安装与日常解压,也能理解 crates/core/src/engine.rs 里每一步写入顺序为何必须如此。

HatchZip 从归档末尾开始解压,并在每个部分完成后从归档文件中截断它,因此磁盘上不会同时存在完整归档与全部输出文件

一、要解决的问题:归档与输出不能同时占满磁盘

常规解压器的行为是:读取归档、写出文件、最后由用户删除归档。在"写出完成、尚未删除归档"的那一刻,磁盘上同时存在完整归档与完整输出。README 给出的典型场景是:一个 180 GB 的游戏下载包解压后为 200 GB,使用 WinRAR、7-Zip 或 unzip 需要 380 GB 空闲空间;而 HatchZip 只需要略多于 200 GB。

HatchZip 的做法是从归档尾部开始解压,每完成一批就把归档截断到该批起始位置,把归还的空间立刻用于下一批输出。由此带来的三个直接结果:

  1. 需要的空闲空间从"归档 + 输出"降为"输出 + 最大可一次性释放单元";
  2. 归档最终被消耗殆尽,结束时磁盘上只剩解压出的文件;
  3. 由于空间是分批归还的,任何时刻都必须有安全检查与可恢复机制,这也是本文后半部分的重点。

README 中用一组同源数据(200 MB 游戏数据,21 个文件,220 MiB 磁盘、约 50 MB 空闲)做了对照,可作为理解设计取舍的入口:

归档 unzip / 7-Zip HatchZip
ZIP,180 MB unzip 在第 6/21 个文件时空间耗尽 完成,每个文件字节一致
7-Zip 25.01 生成的 7z,-ms=20m(10 个固实块) 需要 380 MB 0.64 s 完成,每个文件字节一致
切成 5 卷、每卷 40 MB 的 7z 需要 380 MB 完成;卷逐个删除,峰值占用 210 MB
GNU tar 生成的 200 MB tar 需要 400 MB 0.12 s 完成,每个文件字节一致
7-Zip 默认设置(单一固实块)的 7z 需要 380 MB 在动任何字节之前拒绝:一个固实块必须整块解出才能释放,因此需要 200 MB 空闲

同一组数据还给出了速度与崩溃安全性结论:ZIP 解压 0.25–0.35 s,而 unzip 6.00 为 1.48–1.50 s(HatchZip 还额外做了 unzip 会跳过的 fsync);在每个格式运行的多个位置、批处理的两个不安全时刻杀死进程,恢复后的输出均一致。这些数字来自 README 的实测环境(Fedora 43、Intel Core i7-14700HX、SK Hynix NVMe SSD、热页缓存;空间测试用 220 MiB tmpfs 模拟写满的笔记本磁盘),本文只做转述,不引申为普遍性能承诺。

二、核心设计:把归档拆成"可独立释放的单元"

HatchZip 的引擎不针对某种格式写死逻辑,而是把归档抽象为一组 unit(单元):一段可以独立解码的字节区间,一旦其中的所有文件都安全落盘,就可以从归档中截断掉。README 的 "How it works" 一节给出了这张关键映射表:

格式 单元 布局
ZIP 一个条目(本地头 + 数据) 条目按顺序排列,中央目录(索引)在最后。自解压程序存根可能位于最前。
7z 一个固实块,或非固实归档中的一个文件 32 字节签名头、按顺序排列的打包块,最后是头部(索引)。
tar 一个条目,包含其前的长文件名或 pax 记录 头与数据记录按顺序排列,末尾是零块。没有索引。
.tar.gz 整个归档,改为从前向后解压 一个压缩流承载整个 tar

单元按其在文件中的位置逆序处理:先处理偏移最大的单元,每批结束后把归档截断到该批中最低单元的起点。这正是"从末尾开始"能成立的根本原因——ftruncate、SetEndOfFile 这类"从尾部缩短文件"的操作在所有操作系统和文件系统上都可用;而从头部或中间移除字节需要空洞打孔(Linux 的 fallocate、Windows 的 FSCTL_SET_ZERO_DATA、macOS 的 F_PUNCHHOLE),FAT32 与 exFAT 根本不支持,各系统行为也不一致。

固实 7z 块只能从块首解码,因此必须整块解出后才能释放——这解释了上表中"默认单一固实块"的拒绝行为:它使就地解压毫无收益。README 也点明了额外空间的经验公式:超出输出的额外空间约等于 HatchZip 一次能释放的最大单元大小(ZIP 与 tar 是一个文件,7z 是一个固实块);对于可打孔文件系统上的 ZIP 大文件或 tar 大文件,这条经验可以进一步收紧,详见第七节。

源码层面,这个抽象落在 crates/core/src/archive/mod.rs:Unit 记录了单元的起始偏移 start、格式私有句柄 key、内部条目 items 与是否加密;Format trait 除了提供 worker() 解码器外,还通过 stream() 声明"某个单元是单个可从中途恢复的文件",通过 solid() 声明"整个归档是一个只能从头解码的压缩流"。引擎只依赖这些接口,因此新增格式不必理解截断与日志细节。

三、安装:桌面应用、命令行与源码构建

3.1 桌面应用

README 面向不写代码的用户,提供各平台安装包:

系统 文件
Windows 10 / 11(x64) HatchZip-x64-setup.exe:按用户安装,无需管理员权限,并安装右键菜单
macOS Apple Silicon HatchZip-aarch64.dmg
macOS Intel HatchZip-x86_64.dmg
Debian、Ubuntu hatchzip_amd64.deb
Fedora、openSUSE hatchzip-x86_64.rpm
任意 Linux HatchZip-x86_64.AppImage

安装器还会把 hatchzip 以及短名 hz 放入 PATH。Windows 安装包与 macOS 应用目前未做代码签名:Windows 上需在"Windows 保护的电脑"提示中选择"更多信息 → 仍要运行";macOS 15 及以后需先打开一次应用,再到"系统设置 → 隐私与安全性"中放行。

桌面端的使用路径有三条:右键归档 → HatchZip → Extract here(Windows 11 在"显示更多选项"下);或从开始菜单打开 HatchZip、选择归档、点击 Extract;或在终端使用命令行。图形界面与命令行共享同一套规划逻辑——见 crates/gui/src/backend.rs 与 crates/core/src/session.rs,session::plan() 是两者唯一的空间结论来源,避免两个前端给出不同答案。右键菜单的注册则位于 crates/shell/src/lib.rs。

3.2 仅命令行安装

Linux 与 macOS:

curl -fsSL https://raw.githubusercontent.com/xevrion/hatchzip/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/xevrion/hatchzip/main/install.ps1 | iex

两个脚本都会下载对应机器的构建产物,用发布页的 SHA-256 校验和验证,然后仅为当前用户安装 hatchzip 与 hz,并附带 man 手册与 shell 补全,无需 root 或管理员权限。

3.3 通过 Cargo 安装

cargo install hatchzip

这会从 crates.io 构建命令行工具;引擎本身也是库 hatchzip-core,可被其他程序复用。工作区结构见 Cargo.toml:crates/core、crates/cli、crates/gui、crates/shell 四个成员,版本 0.1.2,Rust edition 2024,rust-version = "1.93"。

3.4 从源码构建

git clone https://github.com/xevrion/hatchzip.git
cd hatchzip
cargo build --release

产物是 target/release/hatchzip 与 target/release/hatchzip-gui(Windows 上带 .exe)。Rust 版本固定于 rust-toolchain.toml 并会自动安装。在 Linux 上构建桌面应用需要 fontconfig 头文件(libfontconfig1-dev 或 fontconfig-devel)。

3.5 补全脚本与 man 手册

hatchzip completions bash > ~/.local/share/bash-completion/completions/hatchzip
hatchzip completions zsh > "${fpath[1]}/_hatchzip"
hatchzip completions fish > ~/.config/fish/completions/hatchzip.fish
hatchzip completions powershell >> $PROFILE

hatchzip man > ~/.local/share/man/man1/hatchzip.1    # 然后: man hatchzip

这些文本不是单独维护的副本:命令行定义在 crates/cli/src/cli.rs,补全脚本由 clap_complete 现场生成、man 页由 clap_mangen 现场渲染(见 crates/cli/src/main.rs),因此三者不会互相矛盾。另外,若以短名 hz 调用,生成的自定义补全脚本会命名为 hz。

四、日常使用:先 check,再 extract

4.1 判断空间是否够用

hatchzip check game.zip

输出示例(取自 README):

game.zip  180.2 MB zip, 200.0 MB uncompressed in 22 entries
  available                    50.5 MB
  standard extraction needs    200.0 MB
  required                     29.9 MB (+5.0 MB reserved)
  available after              30.6 MB

check 只读取归档索引和磁盘空闲空间,不修改任何东西。这四项数字的含义值得逐条理解:

  • available:输出所在文件系统的可用空间;续跑时还会加上崩溃遗留、即将被删除的过期输出(session::plan 中的 stale)。
  • standard extraction needs:普通解压器所需的空闲空间,即剩余输出总大小。
  • required:HatchZip 在最紧张时刻需要消耗的空闲空间,由引擎逐单元回放得出,而不是总量相减。
  • (+5.0 MB reserved):--keep-free 的值,默认 2GB,可用 --keep-free 500MB 或 --keep-free 10GB 调整。

源码中这份输出的字段来自 crates/core/src/session.rs 的 SpacePlan,打印逻辑在 crates/cli/src/main.rs。当目的地与归档不在同一磁盘时,会额外提示"删除归档不会为目的地释放空间"(reclaims == false);当文件系统不能释放文件内部空间时,会提示归档必须整份保留到最后(archive_kept_whole);当缺口主要来自一个固实块时,会提示用更小的固实块重新压缩可显著降低需求(solid_block_bound)。

4.2 执行解压

hatchzip extract game.zip                 # 解压到 ./game/
hatchzip extract game.zip -o D:\Games\Foo # 输出到别处
hatchzip x game.7z.001                    # 分卷归档,任意一卷的名字都可以

extract 会打印与 check 相同的空间计划,请求确认,然后开始解压。完成后归档已被删除,文件位于输出目录。分卷归档中,每一卷在被完全解出后立即删除。

选项 作用
-o, --output <dir> 输出目录。默认是与归档同级的同名目录。它必须为空或尚不存在。
--keep-free <size> HatchZip 永不使用的空闲空间,例如 500MB 或 10GB。默认 2GB,因此磁盘不会被填到零。
--verify-first 在删除任何内容之前,完整读取归档并校验每个文件的校验和。耗时更长,建议用于难以重新下载的归档。
-y, --yes 跳过确认提示。非终端环境下必须显式给出。
-q, --quiet 只打印错误与提示。

关于默认输出目录,crates/core/src/session.rs 的实现比手册描述更细:先去掉 .001 这类至少三位数字的分卷后缀,再依次尝试剥离 .zip、.7z、.tar、.tar.gz、.tgz、.exe;若剥离后与原文件名相同,则追加 -extracted。因此 game.7z.001、game.tar.gz 都会解到 game。

关于 --keep-free 的取值,crates/cli/src/cli.rs 使用十进制单位(KB=1e3、MB=1e6、GB=1e9、TB=1e12),支持小数与空格,如 1.5 TB;未知单位会报错并提示可用单位。这与 HatchZip 自身打印尺寸的口径一致,避免与 KiB 语义混淆。

需要注意:输出目录必须为空或不存在,且 HatchZip 从不覆盖已有文件。session::check_collisions 会在开始前逐一检查归档条目与目标路径的冲突,包括"归档需要目录但那里是文件"的情况。这条约束同时也是崩溃恢复的前提——因为输出目录原本为空,崩溃后发现的多余文件一定属于本次运行,可以安全删除。

4.3 暂停与续跑

按一次 Ctrl+C,HatchZip 会写完当前文件、保存进度后退出;再按一次立即退出,这也同样是安全的。要继续,只需重新执行同一条命令:

hatchzip extract game.zip

崩溃、断电,或磁盘被其他程序占满后也一样适用。进度保存在归档旁边的两个小文件里:game.zip.hatchzip 与 game.zip.hatchzip-tail。解压未完成时不要删除它们:它们保存着归档的索引,而索引已经不在归档自身之中了。

第二次运行时,session::open 会加载日志并校验:卷列表长度之和必须等于"尾部起点 + 尾部长"、尾部 CRC-32 必须与日志记录一致(crates/core/src/journal.rs);若归档比日志记录的 committed_len 还短,则拒绝修改;若更长(说明上次提交后没来得及截断),则先截断到 committed_len。续跑还要求输出目录与日志中记录的一致,防止把提取结果写到别处。

对于加密归档,密码永不保存,因此续跑时会再次询问;也可用 --password 或环境变量 HATCHZIP_PASSWORD。密码会在删除任何内容之前,用最小的加密单元验证一次(最多读取 64 MiB,避免巨大固实块拖慢启动),ZipCrypto 那种"约 1/256 概率误判"的情况会因实际解密校验而被排除——实现见 crates/core/src/engine.rs。非终端环境最多尝试三次,之后以退出码 5 结束。

4.4 彻底放弃:restore

如果不想继续,而是想让归档恢复成普通归档:

hatchzip restore game.zip

归档剩余部分会变成一个正常归档,精确包含尚未解出的条目,7-Zip、WinRAR、unzip、tar 都能像往常一样打开;已解出的文件保留在输出目录。restore 只在尾部追加一个新索引,因此只需要该索引占用的空间;如果中途被打断,再次运行即可完成(也可以改为继续 extract)。

4.5 列表与校验

hatchzip list game.7z    # 里面有什么,含大小
hatchzip test game.7z    # 读取每个文件并校验校验和,不写出任何内容

list 会按 Size / Name 打印条目,并对目录追加 /、对符号链接与硬链接标注目标(crates/cli/src/main.rs)。test 只接受尚未开始解压的归档;对于部分解压的归档会提示改用 extract 续跑或 restore 撤销。纯 tar 没有文件内容校验和,因此对 tar 执行 test 只能证明每个文件都能被完整读出。

4.6 退出状态

代码 含义
0 成功
1 失败。若解压已开始,进度已保存。
2 命令行无效
3 空闲空间不足。未做任何更改。
4 归档损坏。未删除任何内容。
130 用 Ctrl+C 暂停。运行同一命令继续。

实现中还存在一个 README 表格未列出的状态码:5 表示需要密码或密码错误(crates/cli/src/cli.rs 的 EXIT_PASSWORD,以及 crates/cli/src/main.rs 的映射)。在脚本里处理加密归档时,应当把它与 1、3、4 区分开。

五、安全边界:破坏性操作如何保证不丢文件

HatchZip 在解压过程中销毁归档,因此整个设计围绕"绝不丢失尚未安全落盘的文件"展开。README 列出四条核心保证:

  • 方案不合适就什么都不改。 空间检查在写入第一个字节前完成,并且重放整个解压过程找出占用空闲空间最多的时刻,而不只是比较总量。
  • 文件先写入、刷到物理磁盘、改名就位,然后才截掉归档中承载它的那部分。 任何时刻崩溃,结果要么是文件存在,要么其字节仍在归档中,绝不会两者皆无。
  • 损坏就地停止。 每个文件的 CRC-32 在解压时校验;损坏的文件不会被写出,且它与之前的内容一起留在归档里。
  • 恶意归档在删除任何内容前被拒绝:逃出输出目录的路径、互相重叠的条目、重复出现的条目。setuid/setgid 位从不恢复;符号链接仅在所有普通文件写完后创建,因此无法借链接写出目录之外。

它无法防护的情形也写得很明确:如果下载本身已损坏,损坏点之前的文件会被解出,归档也已部分消失——此时应使用 --verify-first。在 btrfs 或 APFS 上,包含归档的快照所持有的空间在快照删除前不会释放。

这些保证在源码中对应具体的检查点:

  • 路径重名(忽略大小写)在构建单元列表时即被拒绝,因为并行批次中两个条目会争抢同一文件(crates/core/src/engine.rs)。
  • 符号链接与硬链接在解压阶段只被记录,统一在全部单元提交后创建(make_links),硬链接在 FAT32/exFAT 上退化为复制(crates/core/src/engine.rs)。
  • 空间不足、归档损坏、密码缺失分别以独立错误类型上报,命令行据此映射为 3 / 4 / 5,而"损坏"类错误保证不删除任何内容。

六、支持的格式与边界

README 的格式矩阵是判断"这个归档能不能用 HatchZip"的第一手依据:

格式 状态 释放粒度
ZIP、ZIP64、自解压 .exe ZIP 支持。已测试 Stored、Deflate、Deflate64、bzip2、LZMA、PPMd、Zstandard,包括 7-Zip 自己生成的归档,以及超过 4 GiB 标记的条目。XZ 由同一库解码但尚未在此测试。 一个文件
7z,固实与非固实 支持。已用 7-Zip 25.01 生成的归档测试:LZMA2(其默认)、LZMA、BCJ + LZMA2、bzip2、Deflate、PPMd。Zstandard 由同一库解码但未测试。 一个固实块
tar(未压缩) 支持,包括长文件名、符号链接与硬链接 一个文件
.tar.gz、.tgz 支持,包括多成员 gzip(bgzip、pigz -i)与分卷 .tar.gz.001 集合。从前向后解压,在文件系统可打孔处释放解码器后方的压缩字节;动任何内容前校验每个 gzip 的 CRC-32 与长度。已用 GNU tar + gzip、pigz 测试。在其他文件系统(FAT32、exFAT)上仍可解压与续跑,但需要同时容纳归档与全部文件,check 会明确说明。 每 256 MiB 输出
分卷归档(.001、.002……,7-Zip 形式)的 ZIP 或 7z 支持 一个文件或块;每卷清空后即删除
受密码保护的 ZIP(ZipCrypto 与 AES)与 7z(AES,含加密文件列表) 支持。会询问密码,或读取 --password / HATCHZIP_PASSWORD,并在删除任何内容前用一个文件验证。密码不保存,续跑需再次输入。 与未加密相同
.tar.zst、.tar.xz 解压前拒绝,已列入计划;见 格式说明
单个超大固实 7z 块 可用,但需要整块大小的空闲空间;块内释放属于计划中的技术
RAR、原生分卷 ZIP(.z01) 计划中

技术细节可从 docs/formats.md 继续深入:.tar.xz 的候选恢复点是块起点(xz 5.8.2 默认多线程会写出许多块),.tar.zst 通常只有一个帧、帧内重启需要 2–128 MiB 窗口与熵表状态,因此难度更大;7z 的块内释放受限于 LZMA2 的完整重置块。这些都是"研究记录",仓库并未声称已实现。

七、深入原理:一次解压究竟发生了什么

以下内容主要来自 docs/how-it-works.md,并对照 crates/core/src/engine.rs 的实现确认。

7.1 保存尾部(the saved tail)

ZIP 与 7z 把索引放在末尾,而末尾正是截断最先破坏的部分。因此在第一次截断之前,HatchZip 把"最后一个单元数据之后的所有内容"(尾部)复制到 <archive>.hatchzip-tail,并把其 CRC-32 记入日志;对 tar 而言,尾部只是结尾的零块。

此后归档通过 storage::Reader 解析:尾部偏移以下读实际卷,以上读保存的尾部,于是格式库看到的归档与原始完全一致。已被截掉的区域读为零——zip 库向后扫描结尾记录时,零永远不会命中签名;对 tar 来说,零读起来就像归档结束,因此解析剩余部分恰好得到"尚未处理"的单元。这一"零即边界"的技巧是整套方案能对多种格式通用的关键。

7.2 日志文件

<archive>.hatchzip 是一个小 JSON 文件,字段如下(见 crates/core/src/journal.rs):

字段 含义
format zip、7z、tar 或 tar.gz,续跑时无需从"被啃了一半"的文件猜测格式
parts 每个卷及其原始长度
tail_start、tail_crc 保存的尾部应归属的位置及其校验和
output 输出目录,续跑不能被指向别处
total_size 输出总大小,用于进度显示
committed_len 最近一次提交后的归档长度。起始偏移大于等于它的单元都已完成。
links 最后才创建的符号链接与硬链接
resume 大文件流式解压进行中时:所属单元、已刷盘字节数、解码重启的比特位置、当前 CRC-32;对压缩 tar 还有 stream(解码器与 tar 解析器状态)

日志自 resume 加入后为版本 3;版本 2 的日志可按原样加载,而旧版程序会拒绝版本 3——这点很重要,否则它们会删除那个"归档字节已被释放"的半写文件。源码中 VERSION = 3、READABLE = [2, 3],加载时先只解析 version 字段再决定是否继续,从而给出"由更新/更旧版本写入"的清晰错误,而不是令人困惑的解析失败。

日志中没有单独的"完成计数":单元起始偏移互不相同,仅凭 committed_len 就能判断哪些已完成。日志始终原子替换:写入临时文件、刷盘、改名覆盖旧文件、再刷目录。

7.3 一批处理的五个步骤

单元按批处理,每批严格按以下顺序执行(源码中的 Run::commit 与 next_batch):

  1. 选择批次。 从下一个未提交单元开始,只要其解压后大小能装进"当前空闲空间减去 --keep-free"就继续取。一批最多 512 个单元、2 GiB(BATCH_MAX_UNITS、BATCH_MAX_BYTES)。
  2. 并行解压。 每个单元由一个工作线程解码,其中每个文件先写入 <name>.hatchzip-part;解码器在流结束时校验 CRC,HatchZip 还会把写出大小与归档声明的大小比对。完成后把 part 文件改名为真实名称。链接此时只记录、不创建。
  3. 刷盘。 整批强制写入物理磁盘:Linux 上一次 syncfs,其他系统逐文件与目录 fsync(macOS 用 F_FULLFSYNC)。
  4. 提交。 用新的 committed_len 与本批链接更新日志。
  5. 截断。 把归档缩短到 committed_len,即本批最低单元的起点。释放出的空间供下一批使用。

全部完成后,先创建链接,再删除归档残余(至多是一个自解压存根或 7z 签名头),最后删除两个边车文件。

批大小的取舍写在源码注释里:批次越大并行越充分,批次越小崩溃后重做越少、归档收缩越细。缓冲区为 1 MiB(BUF_SIZE),恢复步长为 256 MiB(STREAM_STEP)。

7.4 大文件内部的空洞回收

一个单元只有在提交时才释放其归档字节,所以一个 30 GB 的文件在释放任何字节前都需要 30 GB 空闲。当归档所在文件系统支持打孔时,满足条件的单元会被流式处理:ZIP 中 Stored 或 Deflate 的单个文件、tar 中的任意普通文件,且大小至少 512 MiB(stream_threshold() 为两步长),并且"整体放入当前空闲空间放不下"时触发。

每产出 256 MiB,在下一个可重启点执行:

  1. 刷盘 part 文件及其之上各级目录;
  2. 记录恢复点:输出长度、解码重启的比特位置、当前 CRC-32;
  3. 打孔:从该文件数据起点一直到承载该比特的字节,归档长度不变,被释放的字节读为零。

文件完成时按普通流程改名并提交,同一次日志写入顺带清空 resume。数据之前的本地头或 tar 头从不打孔,以保证续跑时归档仍可解析。

Stored 数据可在任意字节重启;Deflate 流可在任意块边界重启(zlib 的 examples/zran.c 技术),使用 zlib-rs 的 C API(inflatePrime、inflateSetDictionary、Z_BLOCK)。边界可能落在字节内部,因此位置按比特记录;解码器还需要该点之前 32 KiB 的输出(后向引用会用到),这份窗口不写入日志,而是从已刷盘的 part 文件末尾读回——这正是 read_window() 的用途。

打孔能力通过"在归档旁打孔一个 1 MiB 临时文件并测量其分配量是否下降"来探测,因为某些调用可能成功却不真正释放空间。若探测失败(FAT32、exFAT、HFS+),所有单元都整份解压。7z 固实块目前尚不支持流式处理。

下表说明流式过程中的崩溃语义(摘自设计文档):

中断时机 磁盘状态 续跑行为
第一个恢复点写入日志之前 有 part 文件,未打孔 删除它,从头开始
刷盘之后、写日志之前 part 文件含超出上一恢复点的输出,但上一恢复点仍有效 把 part 文件裁回上一恢复点并从那里解码;所需数据仍在归档中
写日志之后、打孔前后 恢复点已持久,其前的字节可能已释放 裁到该点并从该点解码,绝不读取该点之前的数据
改名之后、提交之前 文件已有真实名称,日志仍持上一恢复点 改回 part 名并从该点继续

核心规则一句话:归档永远不会被打孔到最后一个持久恢复点之后,而一个恢复点只有在它所担保的输出已刷盘后才算持久。 半流式的文件绝不会被当作未提交输出删除;restore 也会拒绝日志中含恢复点的归档,因为带空洞的条目无法还原。测试用例 crates/cli/tests/streaming.rs 在这三个步骤与最终提交前后反复杀进程;单元测试 crates/core/src/archive/resumable.rs 从每个 Deflate 块边界恢复(级别 6 与 9)。

还需注意一个现实限制:Deflate 块的长度由编码器决定,zlib-ng 与 zlib-rs 在级别 1 会写出单个块,除了起点没有任何恢复点,这样的文件在结束前释放不了空间;若空间先耗尽,运行会停止并告知还需多少。文档明确指出其他编码器未做测量。

7.5 .tar.gz:只能从前向后的压缩流

.tar.gz 是一个(或多个 gzip 成员首尾相接的)Deflate 流,承载整个 tar,只能从头解码,因此不做"从尾部按单元解压",而是整个归档作为一个单元、从前向后解压,并用打孔释放解码器后方的压缩字节。

在动任何内容之前,HatchZip 会完整解码一遍(targz::open):列出条目以供安全校验、核对每个 gzip 成员的 CRC-32 与长度(对照其 trailer)、测量空间检查所需数据。这一步发现损坏会在不修改归档的前提下拒绝;随后解压会再解码一遍。续跑时从恢复点开始的这一遍同样如此,因此续跑时发现的损坏也会在修改任何内容前停止。

恢复点可以是任意 Deflate 块边界或任意 gzip 成员起点(但不能落在条目的头部记录内部)。每 256 MiB 输出,在下一个这样的点:刷盘(Linux 上一次 syncfs)、写入 resume 与 resume.stream(是否成员起点、该成员已产出部分的 CRC-32 与长度、成员最后 32 KiB 输出即 Deflate 窗口、tar 内偏移、以及该点落在何处:条目之间、文件数据内部、填充或零数据中、还是结束标记之后)、然后把归档从上次打孔处打到承载该比特的字节(一次运行的首个打孔从 0 开始,以覆盖上次停在"写日志"与"打孔"之间的情形)。

窗口之所以要写进日志(以 64 KiB 十六进制形式),是因为它跨越 tar 头与多个文件,无法像单个 ZIP 条目那样从一个输出文件末尾读回。相关实现见 Run::stream_solid 与 save_point。

若文件系统不支持打孔,流仍按同样方式解压、恢复点照常记录(崩溃仍可续跑),但直到结束才释放任何空间;空间检查会要求"归档 + 每个文件"的容量,check 会解释原因。若输出在另一块磁盘上,同样不打孔,因为对那里没有帮助。

7.6 空间检查是如何算出那个数字的

在写出第一个字节之前,HatchZip 逐个单元重放整个解压过程,累计每一步增加的部分(该单元的文件,每个向上取整到 4 KiB 块)与释放的部分(该单元在归档中的跨度),再加上开始时写出的尾部。这个累计值的最高点就是所需的空闲空间;若磁盘空闲量不足"该值 + --keep-free",则拒绝开始。

可流式处理的单元最多按"一步输出(256 MiB)+ 1 MiB 读缓冲 + 打孔区间两端文件系统可能保留的分配量 + 输出超出压缩数据的部分"计算,且不超过整个单元大小。两端的保留量按平台不同(文档给出 64 KiB、NTFS 1 MiB、ZFS 16 MiB、btrfs 128 MiB,因为 btrfs 按整 extent 释放)。对 Deflate,最后一项以最终值为上界(编码器宁可退化为 stored 块也不会让数据膨胀),再加 1/1024 的块头余量。

这些估算不是纯理论:README 记录了一组 950 MiB tmpfs 上的实测——一个含 600 MiB 条目的 ZIP,Stored 情况下检查要求 269.6 MB(上一版本要求 629.1 MB 并拒绝),运行中每 10 ms 采样的最低空闲为 367.0 MB 中的 98.5 MB,峰值占用 268.5 MB;Deflate(多为不可压缩数据,归档 498.1 MB)要求 401.3 MB,峰值 324.4 MB,两者输出均字节一致。文档同时强调"实际运行从不超过检查承诺的数字":批次大小总是对着当时测得的空闲空间来定;若运行中其他程序占满磁盘,HatchZip 会在下一个单元前停下、保存进度并告知需释放多少。

7.7 restore 的实现路径

hatchzip restore 把半解压的归档变回普通归档。归档剩余部分是原始文件的前 committed_len 字节,恰好是尚未解出的单元且未被改动;缺的只是索引,因此 restore 在其后追加新索引。committed_len 以下不移动任何字节,所以只需要新索引所需的空闲空间。各格式写入内容不同:

格式 restore 写入
ZIP 一个中央目录,保存剩余条目的记录并原样复制(其本地头偏移仍指向相同字节),然后写结束记录,必要时写 ZIP64 记录;自解压存根保留在最前,偏移沿用原始约定。
7z 为剩余块(即签名头之后最前面的那些块)及其文件写新头部;由 sevenz-rust2 的写入器编码,块数据原样传递、不再写出(因为它已位于写入器会放置的位置),并重写签名头指向新头部。
tar 为"已被截断但目标仍在归档中"的硬链接写条目,然后写结束 tar 的两个零块。

八个步骤(含"先撤销上次被中断的 restore"与"写完新索引后用与解压相同的解析器校验条目恰好是剩余那些")见设计文档;其中第 7 步的校验尤为关键:若解析结果不符,就撤销并停止。任何打开"日志中 restoring 已置位"的归档的运行(无论 restore 还是 extract)都会先把归档裁回 committed_len、并放回被覆盖的字节,因此被中断的 restore 可以再跑一次,也可以改为继续解压。测试见 crates/cli/tests/restore.rs。

八、跨平台差异

引擎把所有系统相关逻辑收敛在 crates/core/src/platform/ 下,每个系统一个文件:

行为 Linux macOS Windows
批次刷盘 一次 syncfs 每文件 F_FULLFSYNC 每文件 FlushFileBuffers
目录刷盘 目录 fsync 目录 fsync 不可行;NTFS 会记录改名日志
同盘判断 设备 ID 设备 ID 规范化路径的卷前缀
Unix 权限 恢复,但不含 setuid、setgid、sticky 同上 忽略
符号链接 创建 创建 写成保存目标的小文本文件,类似未开开发者模式的 Git
硬链接 创建;无此能力的文件系统(FAT32、exFAT)上复制 同上 同上

因此 README 中"在能够收缩文件的任何文件系统上工作"这句是准确表述:ext4、btrfs、XFS、NTFS、APFS,以及 exFAT 与 FAT32 U 盘。区别只在于能省多少空间:可打孔的文件系统能进一步降低大文件与 .tar.gz 的峰值需求,而 FAT32/exFAT 只能靠"从尾部截断",因此 .tar.gz 必须整份保留到最后。

九、源码导航与实践建议

想继续深入或参与改进,可按以下顺序阅读:

关注点 位置
单元抽象、格式接口、错误类型 crates/core/src/archive/mod.rs
引擎主循环、批次、流式、空间模型 crates/core/src/engine.rs
日志格式、版本兼容、尾部校验 crates/core/src/journal.rs
分卷拼接、读取、截断 crates/core/src/archive/storage.rs
各格式解析 crates/core/src/archive/zip.rs、sevenz.rs、tar.rs、targz.rs
Deflate/ gzip 的可恢复解码 crates/core/src/archive/resumable.rs
打开归档与空间规划(CLI 与 GUI 共用) crates/core/src/session.rs
restore 实现 crates/core/src/restore.rs
命令行定义与尺寸解析 crates/cli/src/cli.rs
命令行主流程、确认、进度、退出码 crates/cli/src/main.rs
崩溃/恢复/流式/restore 测试 crates/cli/tests/(extract.rs、streaming.rs、targz.rs、restore.rs、formats.rs、large.rs、password.rs)

几条面向实际使用的经验,均可由上述文档与源码推出:

  1. 先用 check 决定策略。 若拒绝原因是最外层固实块过大,重新以更小的固实块(如 7-Zip 的 -ms=20m)压缩,峰值需求会显著下降;README 的对照表已直接展示这一点。
  2. 难以重新下载的归档加 --verify-first。 归档被逐步销毁意味着"事后重试"不再可能,损坏只能在源头拦下。
  3. 把输出放在归档同一块磁盘上,否则回收的空间对输出盘无效,check 会提示 reclaims == false,此时就地解压失去主要收益。
  4. 不要把 --keep-free 设为 0。 默认 2 GB 的意义是让磁盘永远不被填到零,给系统与日志留出余地;磁盘紧张时再谨慎下调。
  5. 未完成时不要动 .hatchzip 与 .hatchzip-tail。 索引只在边车文件中;删掉它们,归档既不能再续跑,也无法被 restore 修复。
  6. 不要在脚本中依赖 README 未列出的行为。 例如退出码 5 目前只存在于源码;若你依赖它,请固定版本并阅读 crates/cli/src/cli.rs。

十、许可与参与

HatchZip 采用双许可:Apache License 2.0 或 MIT license,由你选择。欢迎提交缺陷报告,尤其是 CI 未覆盖的文件系统与操作系统;参与前请阅读 CONTRIBUTING.md。按 Apache-2.0 的定义,除非你明确声明,否则有意提交以纳入本项目的贡献将按上述双许可授权,不附加额外条款。

登录后查看全文
hatchzip