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,71 @@
## MODIFIED Requirements
### Requirement: 断点续跑
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。`state.json` 中记录的源连接与目标连接 MUST 采用标准 MySQL DSN 形式(去除密码),例如 `user@tcp(host:3306)/db?charset=utf8mb4`。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式、压缩设置,以及源/目标连接的全部规范化参数(含字符集与排序规则)的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。密码 MUST NOT 计入指纹,也 MUST NOT 写入 `state.json`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。`rows_done` MUST 表示该输出目录累计已提交的行数(含续跑前已提交的部分),MUST NOT 在续跑后被重置为本次运行的行数。
#### Scenario: 配置一致时续跑
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
#### Scenario: 配置被修改
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
#### Scenario: 压缩档位被修改
- **WHEN** 续跑时 `--compress-level` 与 `state.json` 记录不一致,且未传 `--force-resume`
- **THEN** 系统报错并列出 `compress_level` 字段的变化,拒绝开始扫描
#### Scenario: 默认档位兼容存量任务
- **WHEN** `state.json` 由引入压缩档位之前的版本写入,且本次使用默认档位 3
- **THEN** 指纹一致,系统正常续跑
#### Scenario: 连接字符集被修改
- **WHEN** 续跑时 `--source` 的 `charset` 或 `collation` 与 `state.json` 记录不一致,且未传 `--force-resume`
- **THEN** 系统报错并列出 `source` 字段的变化,拒绝开始扫描
#### Scenario: 密码轮换
- **WHEN** 续跑时仅 `--source` 或 `--dest` 的密码与上次运行不同
- **THEN** 指纹一致,系统正常续跑
#### Scenario: 连接信息的存储形态
- **WHEN** 查看任意一次运行生成的 `state.json`
- **THEN** `config.source` 与 `config.dest` 为标准 MySQL DSN,且不包含密码明文
#### Scenario: 续跑后累计行数
- **WHEN** 首次运行提交 10000 行后中断,随后续跑提交剩余 40000 行
- **THEN** 完成后的 `state.json` 中 `rows_done` 为 50000,而不是 40000
#### Scenario: 校验脚本读取累计值
- **WHEN** 一次经过续跑的导出完成后,外部脚本读取 `state.json` 的 `rows_done` 并与源表匹配行数比较
- **THEN** 两者一致,不产生误报
## ADDED Requirements
### Requirement: 运行阶段顺序
系统 SHALL 在运行中维护以下阶段:`probe`、`resume`、`estimate`、`scan`、`file`、`db`、`checkpoint`、`finalize`。启用复制延迟保护时,每个 chunk 拉取前 MUST 进入 `lag-wait` 阶段。单个 chunk 的处理顺序 MUST 为 `lag-wait → scan → file → db → checkpoint`。阶段切换 MUST 对进度输出可见,且任一阶段持续期间 MUST NOT 阻断周期性进度刷新。
#### Scenario: 等待副本延迟
- **WHEN** 副本延迟超过 `--max-lag`
- **THEN** 系统进入 `lag-wait` 阶段并持续输出进度,直到延迟恢复
#### Scenario: 恢复后进入扫描
- **WHEN** 延迟恢复到 `--max-lag` 以下
- **THEN** 系统离开 `lag-wait`,按 `scan → file → db → checkpoint` 处理下一个 chunk
#### Scenario: 长时间扫描
- **WHEN** 路径 B 的单日查询长时间未返回首个 chunk
- **THEN** 阶段保持 `scan`,进度刷新不中断,操作者可观察到阶段耗时增长