feat: add resumable file archive jobs and offline verification
This commit is contained in:
113
docs/api/retention-jobs.md
Normal file
113
docs/api/retention-jobs.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# 可恢复的文件归档作业
|
||||
|
||||
`orbit-admin retention archive` 自动按已保存的保留策略分批导出，并把每个批次可靠写入本地持久目录。它面向持有数据库运维权限的操作者，复用控制台导出的候选保护和版本核对，记录 `archive:<job_id>` 审计身份；不需要控制台 Cookie，也不向业务 SDK 增加管理权限。数据库业务记录始终保留。
|
||||
|
||||
本次提供的是可重复运行的有限批次作业执行器。周期触发、控制台作业列表、对象存储和清理执行器尚未接入；不能把它描述为已部署的定时归档服务。
|
||||
|
||||
## 配置与启动
|
||||
|
||||
先在控制台“保留策略”保存所需窗口并允许导出，记下命名空间 ID 和策略版本。为每次扫描选择独立目录，父目录需提前创建，数据目录应位于受备份保护的持久卷中；进程会创建权限为 `0700` 的作业子目录和 `0600` 文件。
|
||||
|
||||
```sh
|
||||
# 按实际数据库注入 ORBIT_MYSQL_DSN，不要把密码放入版本库。
|
||||
export ORBIT_MYSQL_DSN='operator:password@tcp(127.0.0.1:3306)/orbit'
|
||||
mkdir -p /srv/orbit-archives
|
||||
chmod 700 /srv/orbit-archives
|
||||
|
||||
./bin/orbit-admin retention archive \
|
||||
--namespace 11111111111111111111111111111111 \
|
||||
--kind tasks \
|
||||
--revision 1 \
|
||||
--directory /srv/orbit-archives/tasks-20260923 \
|
||||
--batch-size 20 \
|
||||
--max-batches 10 \
|
||||
--max-bytes 268435456 \
|
||||
--timeout 5m
|
||||
```
|
||||
|
||||
ID、日期、版本均为示例，使用当前环境的值。目录也可通过 `ORBIT_ARCHIVE_DIRECTORY` 配置，显式 `--directory` 优先；该环境变量只供归档 CLI 使用，不会使 Orbit 服务后台自动开始归档。
|
||||
|
||||
| 参数 | 默认/约束 |
|
||||
| --- | --- |
|
||||
| `--namespace` | 必填，32 位小写十六进制命名空间 ID |
|
||||
| `--kind` | 必填，`tasks/workflows/events/audit/deliveries/inbox/idempotency` |
|
||||
| `--revision` | 必填，已保存的非零策略版本 |
|
||||
| `--directory` | 必填绝对路径，或设置 `ORBIT_ARCHIVE_DIRECTORY`；每个作业独立私有目录 |
|
||||
| `--batch-size` | 默认 20，1–100；与范围一同固定在清单，恢复时不可更改 |
|
||||
| `--max-batches` | 默认 10，1–1000；本次调用最多新增的批次数 |
|
||||
| `--max-bytes` | 默认 256 MiB，1 MiB–100 GiB；本作业清单及已发布批次文件的总上限 |
|
||||
| `--timeout` | 默认 5 分钟，1 秒–1 小时；单批数据库读取仍受 10 秒截止及原有行数/正文限制 |
|
||||
|
||||
所有调用仍核对数据库 Schema；每个新批次在事务内核对应用、命名空间启用状态和当前策略版本。不能使用已关闭或改版的策略继续生成新批次。
|
||||
|
||||
输出为摘要，不包含正文、凭据或游标：
|
||||
|
||||
```json
|
||||
{"job_id":"<固定作业ID>","completed":false,"batches":10,"roots":200,"bytes":1234567,"last_sha256":"<清单及批次链的末端摘要>"}
|
||||
```
|
||||
|
||||
命令达到 `--max-batches` 后正常返回；`completed=false` 明确表示尚未导出完。使用**相同目录、命名空间、类型、版本和批量**再次运行，自动校验已有批次后接续。可提高本次批数/容量/时间上限，不会改写已发布文件。已完成作业再次运行只验证，不再从头导出。
|
||||
|
||||
作业执行中遇到数据库错误、策略变更、文件损坏、权限问题或容量不足时输出最后已确认进度并以非零状态退出。参数或数据库连接等启动前校验失败只报错，不输出成功状态；此时可用离线核验命令读取已保存进度。调用方必须同时检查退出码和 `completed`，不能把“进程结束”当成“作业完成”。
|
||||
|
||||
## 文件结构与恢复
|
||||
|
||||
```text
|
||||
/srv/orbit-archives/tasks-20260923/
|
||||
├── .lock # 非阻塞进程文件锁；进程退出后自动释放
|
||||
├── manifest.json # 不可变范围、随机作业ID及清单版本
|
||||
├── batch-000001.json # 输入游标、服务端原始快照、上一文件摘要
|
||||
├── batch-000002.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
写入顺序是：数据库读取并记录导出审计 → 私有临时文件 → 文件同步 → 原子发布且拒绝覆盖 → 同步目录 → 原字节回读。没有独立的可变游标文件；连续且校验通过的批次本身就是检查点。
|
||||
|
||||
- 文件发布前退出：残留 `.write.tmp` 不算成功，恢复时清理该临时文件并重新导出同一输入游标。
|
||||
- 文件发布后、进程报告成功前退出：新进程读取已发布批次，从其下一游标恢复。
|
||||
- 缺少批次、摘要不一致、混入其他作业、符号链接、非私有文件或未知文件：立即停止，不跳过、不覆盖原档案。
|
||||
- 数据库导出已记审计、随后磁盘写入失败：可能多出一次导出审计；审计不表示文件持久化成功。源数据不变，恢复后从最后文件继续。
|
||||
- 相同目录的并发进程：后进入者立即失败，避免两个进程同时推进。
|
||||
|
||||
首批绑定清单原字节摘要，后续每批绑定前一文件的摘要，快照正文另按服务端 SHA-256 校验。保留窗口截止时间跨批固定；每批使用独立数据库快照，整个作业不承诺全库同一时间点。期间解除保护的旧记录可能需要下一次独立扫描。
|
||||
|
||||
## 离线核验
|
||||
|
||||
不需要数据库连接或网络：
|
||||
|
||||
```sh
|
||||
./bin/orbit-admin retention verify-archive \
|
||||
--directory /srv/orbit-archives/tasks-20260923
|
||||
|
||||
# 推荐另外保存成功输出中的 last_sha256，再以可信摘要核对完整链。
|
||||
./bin/orbit-admin retention verify-archive \
|
||||
--directory /srv/orbit-archives/tasks-20260923 \
|
||||
--expected-sha256 '<另行保存的64位小写摘要>'
|
||||
```
|
||||
|
||||
核验输出与执行输出结构相同；部分作业也可以核验，`completed=false` 时仍未完成。`--expected-sha256` 可发现文件与摘要整体重写或尾部截断；前提是期望摘要保存在档案目录之外的可信位置。未提供期望摘要时只能验证文件之间的内部一致性，不能证明来源真实性。
|
||||
|
||||
单批快照在 `batch-*.json` 的 `snapshot` 字段中，仍遵循[归档接口](retention.md)的 `format_version/sha256/content` 协议。
|
||||
|
||||
## Docker 运行
|
||||
|
||||
把持久卷挂载到容器目录，并确保镜像内 UID 65532 有权限创建 `0700` 子目录。数据库和路径按目标环境配置；使用当前服务相同的不可变镜像版本：
|
||||
|
||||
```sh
|
||||
docker run --rm --network orbit-network \
|
||||
--env-file /secure/orbit-archive.env \
|
||||
--mount type=bind,src=/srv/orbit-archives,dst=/archives \
|
||||
--entrypoint /usr/local/bin/orbit-admin orbit:local retention archive \
|
||||
--namespace 11111111111111111111111111111111 --kind tasks --revision 1 \
|
||||
--directory /archives/tasks-20260923
|
||||
|
||||
# 离线核验也需要文件锁，挂载目录需允许打开锁文件；不连接数据库。
|
||||
docker run --rm --network none \
|
||||
--mount type=bind,src=/srv/orbit-archives,dst=/archives \
|
||||
--entrypoint /usr/local/bin/orbit-admin orbit:local retention verify-archive \
|
||||
--directory /archives/tasks-20260923
|
||||
```
|
||||
|
||||
当前文件执行器支持 Linux/macOS 本地 POSIX 文件锁、硬链接原子发布及文件/目录同步语义；其他系统显式拒绝。不同节点独立磁盘不共享进度；网络共享文件系统必须验证上述语义后才能使用，当前没有跨节点自动接管承诺。
|
||||
|
||||
容量上限覆盖一个作业的清单和已发布批次，不是整个卷的配额；还需预留一个临时批次空间。已有档案不会自动删除腾空间，不会自动生成新目录重试。每个作业最多 10000 批。该归档不是数据库备份，也不构成源数据删除授权。
|
||||
Reference in New Issue
Block a user