7.6 KiB
可恢复的文件归档作业
orbit-admin retention archive 自动按已保存的保留策略分批导出，并把每个批次可靠写入本地持久目录。它面向持有数据库运维权限的操作者，复用控制台导出的候选保护和版本核对，记录 archive:<job_id> 审计身份；不需要控制台 Cookie，也不向业务 SDK 增加管理权限。数据库业务记录始终保留。
本页介绍可独立运行的有限批次 CLI 执行器。周期触发、控制台作业列表与人工重试见周期归档管理；对象存储和源数据清理尚未接入。
配置与启动
先在控制台“保留策略”保存所需窗口并允许导出，记下命名空间 ID 和策略版本。为每次扫描选择独立目录，父目录需提前创建，数据目录应位于受备份保护的持久卷中；进程会创建权限为 0700 的作业子目录和 0600 文件。
# 按实际数据库注入 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；每个新批次在事务内核对应用、命名空间启用状态和当前策略版本。不能使用已关闭或改版的策略继续生成新批次。
输出为摘要，不包含正文、凭据或游标：
{"job_id":"<固定作业ID>","completed":false,"batches":10,"roots":200,"bytes":1234567,"last_sha256":"<清单及批次链的末端摘要>"}
命令达到 --max-batches 后正常返回；completed=false 明确表示尚未导出完。使用相同目录、命名空间、类型、版本和批量再次运行，自动校验已有批次后接续。可提高本次批数/容量/时间上限，不会改写已发布文件。已完成作业再次运行只验证，不再从头导出。
作业执行中遇到数据库错误、策略变更、文件损坏、权限问题或容量不足时输出最后已确认进度并以非零状态退出。参数或数据库连接等启动前校验失败只报错，不输出成功状态；此时可用离线核验命令读取已保存进度。调用方必须同时检查退出码和 completed，不能把“进程结束”当成“作业完成”。
文件结构与恢复
/srv/orbit-archives/tasks-20260923/
├── .lock # 非阻塞进程文件锁；进程退出后自动释放
├── manifest.json # 不可变范围、随机作业ID及清单版本
├── batch-000001.json # 输入游标、服务端原始快照、上一文件摘要
├── batch-000002.json
└── ...
写入顺序是：数据库读取并记录导出审计 → 私有临时文件 → 文件同步 → 原子发布且拒绝覆盖 → 同步目录 → 原字节回读。没有独立的可变游标文件；连续且校验通过的批次本身就是检查点。
- 文件发布前退出：残留
.write.tmp不算成功，恢复时清理该临时文件并重新导出同一输入游标。 - 文件发布后、进程报告成功前退出：新进程读取已发布批次，从其下一游标恢复。
- 缺少批次、摘要不一致、混入其他作业、符号链接、非私有文件或未知文件：立即停止，不跳过、不覆盖原档案。
- 数据库导出已记审计、随后磁盘写入失败：可能多出一次导出审计；审计不表示文件持久化成功。源数据不变，恢复后从最后文件继续。
- 相同目录的并发进程：后进入者立即失败，避免两个进程同时推进。
首批绑定清单原字节摘要，后续每批绑定前一文件的摘要，快照正文另按服务端 SHA-256 校验。保留窗口截止时间跨批固定；每批使用独立数据库快照，整个作业不承诺全库同一时间点。期间解除保护的旧记录可能需要下一次独立扫描。
离线核验
不需要数据库连接或网络：
./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 字段中，仍遵循归档接口的 format_version/sha256/content 协议。
Docker 运行
把持久卷挂载到容器目录，并确保镜像内 UID 65532 有权限创建 0700 子目录。数据库和路径按目标环境配置；使用当前服务相同的不可变镜像版本：
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 批。该归档不是数据库备份，也不构成源数据删除授权。
周期触发、控制台作业列表与人工重试已由 Schema 31 增加，见周期归档管理。本页 CLI 仍可独立使用；独立 CLI 作业不会自动注册到管理列表。