Renamed from arcdb: module path, cmd/archer, internal/archererr, docs, build scripts and ARCHER_* environment variables. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4.2 KiB
设计:xz 压缩与统一压缩档位
依赖选择
采用 github.com/ulikunitz/xz(纯 Go、BSD-3、读写齐全)。
| 方案 | 结论 |
|---|---|
klauspost/compress |
不支持 xz |
| cgo 绑定 liblzma | 破坏交叉编译与"纯 Go 构建"约束 |
外部 xz 进程 |
额外运行时依赖、错误处理与安全面变大 |
ulikunitz/xz |
唯一可行,本机 module cache 已有 v0.5.17 |
档位模型:1–9 是语义档位,不是原生级别
zstd 库没有连续 1–22 级别,只有 4 个 EncoderLevel;xz 库没有 preset 参数。因此 1–9 被定义为跨格式语义档位,各格式显式映射,9 表示该格式最强:
| level | gzip (flate) | zstd | xz 字典 |
|---|---|---|---|
| 1 | 1 | SpeedFastest | 1 MiB |
| 2 | 2 | SpeedFastest | 2 MiB |
| 3 | 3 | SpeedDefault | 4 MiB |
| 4 | 4 | SpeedDefault | 4 MiB |
| 5 | 5 | SpeedDefault | 8 MiB |
| 6 | 6 | SpeedBetterCompression | 8 MiB |
| 7 | 7 | SpeedBetterCompression | 16 MiB |
| 8 | 8 | SpeedBetterCompression | 32 MiB |
| 9 | 9 | SpeedBestCompression | 64 MiB |
默认 3:gzip 与现行 NewWriterLevel(3) 一致;zstd 的 SpeedDefault 与现行代码一致;xz 无历史行为。
xz 映射只设置 WriterConfig.DictCap,其余使用库默认(CRC64、hash-table matcher)。这与 xz -N 的字典表一致,但不比特级复刻 xz-utils 的 preset(matcher 不同,压缩率略低),文档需说明产物仍是标准 xz。
xz 读取的字典上限
ulikunitz/xz 的 reader 默认 DictCap = 8 MiB;读取 level 9(64 MiB 字典)的流会失败。
决定:xz reader 固定使用 64 MiB 上限,而不是按当前 level 推导。
原因:
- 本工具可能产出的最大字典就是 64 MiB;
--force-resume允许改配置续跑。若按当前 level 推导,从 9 降到 1 后读取旧分片会因上限不足而失败;- 读侧只出现在续跑与清单补录路径,不在主写入热路径,一次 64 MiB 缓冲可接受。
checkpoint 会产生多 stream
Writer.Checkpoint() 关闭当前压缩流、记录偏移,再在偏移处开启新流。gzip 多 member、zstd 多 frame、xz 多 stream 都是合法拼接;ulikunitz/xz 的 SingleStream 默认 false,会解码全部 stream,xz -dc 同样如此。
要求:必须有测试覆盖"checkpoint 后的 xz 分片能被完整读回",防止 --purge 场景下静默丢行。
指纹兼容性
现有 state.json 的指纹里没有 compress_level。无条件加字段会让本功能上线前启动的任务全部续跑失败。
决定:仅当 compress != none && level != 3 时把 compress_level 加入指纹。
- 老任务(无键)+ 新进程默认 3 → 哈希输入逐字节不变,无缝续跑;
- 非默认档位才出现新键,
DiffFields会显示compress_level: "5" -> (absent)并拒绝; - 从 5 改回 3 也因键消失被识别。
compress == none 时档位不参与哈希,因为不影响产物。
none 与 level 的组合
compress == none && level != 3 → 配置错误;level == 3(默认值)静默接受。这样既能拒绝无意义组合,又不会惩罚"只是没传"的用户。
崩溃恢复识别 .xz
manifest.go 的 shardNameRE 目前只列 \.gz|\.zst,且 Adopt 用 mt[3] != comp.Ext 过滤。不加 \.xz 时,崩溃在 rename 与 manifest 追加之间的 xz 分片不会被计入 maxSeq,续跑会重算序号并覆盖已封分片。
决定:正则与扩展名判断都识别 .xz,并补一条针对性测试。
Compressor 结构与扩展名收敛
Compressor 从 {Name, Ext} 扩展为 {Name, Ext, Level},构造签名改为 NewCompressor(name string, level int)。gzip/zstd/xz 都从同一个对象取 Ext。
app/dryrun.go 的 compressExt() 是第二份扩展名表,改成复用 Compressor.Ext,避免新增格式时漏改一处。
被否决的方案
- 把 zstd 暴露为 1–22:与 gzip/xz 的 1–9 不一致,校验和文档复杂度上升;zstd
best已足够,空间优先交给 xz。 - 按当前 level 推导 reader 字典:与
--force-resume降级续跑冲突。 - xz 使用默认 8 MiB 字典:level 3 与 xz preset 3 不一致,且高档位无法表达。
- 无条件把档位写入指纹:打断存量任务续跑。