Initial commit: archer, a Go-native MySQL/MariaDB table archiver

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>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-06 22:12:17 +08:00
commit bc4a6b504f
99 files changed
+12752

No files matched your search

@@ -0,0 +1,85 @@
# 设计: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 推导。**
原因:
1. 本工具可能产出的最大字典就是 64 MiB;
2. `--force-resume` 允许改配置续跑。若按当前 level 推导,从 9 降到 1 后读取旧分片会因上限不足而失败;
3. 读侧只出现在续跑与清单补录路径,不在主写入热路径,一次 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 不一致,且高档位无法表达。
- **无条件把档位写入指纹**:打断存量任务续跑。