HatchZip 就地解压实战:边解压边回收归档空间(ZIP/7z/tar/.tar.gz/分卷)
HatchZip 就地解压实战:边解压边回收归档空间(ZIP/7z/tar/.tar.gz/分卷)
本文以仓库 README.md 为核心脉络,系统讲解 HatchZip 如何在磁盘空间不足时"边解压、边收缩归档":从空间预检、命令行用法、崩溃恢复、安全边界,一直到引擎中的单元切分、日志(journal)、流式解压与空洞回收。读完后你既能照着手册完成安装与日常解压,也能理解 crates/core/src/engine.rs 里每一步写入顺序为何必须如此。
一、要解决的问题:归档与输出不能同时占满磁盘
常规解压器的行为是:读取归档、写出文件、最后由用户删除归档。在"写出完成、尚未删除归档"的那一刻,磁盘上同时存在完整归档与完整输出。README 给出的典型场景是:一个 180 GB 的游戏下载包解压后为 200 GB,使用 WinRAR、7-Zip 或 unzip 需要 380 GB 空闲空间;而 HatchZip 只需要略多于 200 GB。
HatchZip 的做法是从归档尾部开始解压,每完成一批就把归档截断到该批起始位置,把归还的空间立刻用于下一批输出。由此带来的三个直接结果:
- 需要的空闲空间从"归档 + 输出"降为"输出 + 最大可一次性释放单元";
- 归档最终被消耗殆尽,结束时磁盘上只剩解压出的文件;
- 由于空间是分批归还的,任何时刻都必须有安全检查与可恢复机制,这也是本文后半部分的重点。
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):
- 选择批次。 从下一个未提交单元开始,只要其解压后大小能装进"当前空闲空间减去
--keep-free"就继续取。一批最多 512 个单元、2 GiB(BATCH_MAX_UNITS、BATCH_MAX_BYTES)。 - 并行解压。 每个单元由一个工作线程解码,其中每个文件先写入
<name>.hatchzip-part;解码器在流结束时校验 CRC,HatchZip 还会把写出大小与归档声明的大小比对。完成后把 part 文件改名为真实名称。链接此时只记录、不创建。 - 刷盘。 整批强制写入物理磁盘:Linux 上一次
syncfs,其他系统逐文件与目录 fsync(macOS 用F_FULLFSYNC)。 - 提交。 用新的
committed_len与本批链接更新日志。 - 截断。 把归档缩短到
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,在下一个可重启点执行:
- 刷盘 part 文件及其之上各级目录;
- 记录恢复点:输出长度、解码重启的比特位置、当前 CRC-32;
- 打孔:从该文件数据起点一直到承载该比特的字节,归档长度不变,被释放的字节读为零。
文件完成时按普通流程改名并提交,同一次日志写入顺带清空 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) |
几条面向实际使用的经验,均可由上述文档与源码推出:
- 先用
check决定策略。 若拒绝原因是最外层固实块过大,重新以更小的固实块(如 7-Zip 的-ms=20m)压缩,峰值需求会显著下降;README 的对照表已直接展示这一点。 - 难以重新下载的归档加
--verify-first。 归档被逐步销毁意味着"事后重试"不再可能,损坏只能在源头拦下。 - 把输出放在归档同一块磁盘上,否则回收的空间对输出盘无效,
check会提示reclaims == false,此时就地解压失去主要收益。 - 不要把
--keep-free设为 0。 默认 2 GB 的意义是让磁盘永远不被填到零,给系统与日志留出余地;磁盘紧张时再谨慎下调。 - 未完成时不要动
.hatchzip与.hatchzip-tail。 索引只在边车文件中;删掉它们,归档既不能再续跑,也无法被restore修复。 - 不要在脚本中依赖 README 未列出的行为。 例如退出码 5 目前只存在于源码;若你依赖它,请固定版本并阅读 crates/cli/src/cli.rs。
十、许可与参与
HatchZip 采用双许可:Apache License 2.0 或 MIT license,由你选择。欢迎提交缺陷报告,尤其是 CI 未覆盖的文件系统与操作系统;参与前请阅读 CONTRIBUTING.md。按 Apache-2.0 的定义,除非你明确声明,否则有意提交以纳入本项目的贡献将按上述双许可授权,不附加额外条款。
