feat: add resumable file archive jobs and offline verification

2026-09-23 10:50:49 +08:00
parent 2d8467e50c
commit 6eb429e21f
19 changed files with 1160 additions and 15 deletions
--- a/docs/07-data-model.md
+++ b/docs/07-data-model.md
@@ -262,3 +262,7 @@ Event.WorkflowID为只读STORED生成列，从原不可变事件派生流程归
 000029增加 `orbit_console_users` 和 `orbit_console_sessions`，只保存控制台账号的 bcrypt 哈希、绑定凭据及 HttpOnly 会话摘要；不保存密码或令牌原文。控制台继续单管理员模型，服务层每次修改前核对会话、命名空间和绑定凭据权限。

 000030增加 `orbit_retention_policies`，按命名空间保存归档开关、幂等/任务/流程/事件/交付/Inbox/审计窗口、修订号及时间。所有字段都有中文 COMMENT，策略不含外键或级联。数据库策略优先于部署默认值；默认关闭归档，配置变化不触发删除。服务层用同一事务完成版本核对、幂等回执和审计快照，并在归档预览/导出时保护未确认交付、未知效果、未结束流程和有效幂等身份。具体窗口、候选目录和控制台接口见[数据保留与归档策略](api/retention.md)。
+
+## 文件归档作业模型
+
+`internal/retention` 中的 `JobSpec`、`JobManifest`、`JobBatch` 和 `JobStatus` 定义固定作业范围、不可变清单、连续批次及汇总状态；各持久字段提供中文注释。它们只存入私有归档目录，不新增数据库表。连续文件与摘要链就是恢复检查点，作业 `JobID` 进入现有管理审计的执行者身份。协议与失败边界见[文件归档作业](api/retention-jobs.md)。
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -109,7 +109,7 @@ P4/P5定时等待与后续查询轮次的实现及回归记录见[时钟报告](
 1. 已补[首批可复现故障工具](reports/phase-6-fault-boundaries.md)：A04“派发已提交但消息尚未送达”、W01/W13事务提交结果不明，以及W16最终回执/旧PENDING结果重放/下一轮竞争。迁移器同时提供当前版本无外键新装基线；每个切点必须有实际数据库或进程证据，不能用响应错误推断事务是否已提交，也不能用普通SIGNAL竞争替代最终查询场景。数据库事务封装另对提交前 MySQL 1205/1213 做最多两次短退避重试，Commit 回执不明保持原身份核对语义，真实锁环回归见[P7当前回归状态](reports/phase-7-regression-status.md)。
 2. 已实现[基础运行观测](api/observability.md)及[有界业务状态与事件采样](reports/phase-6-business-observability.md)：HTTP/WS、数据库连接池、后台批次、固定任务/交付/流程/Inbox状态计数、最近事件类别、终态耗时样本、固定事件阶段耗时、最早年龄、截断/新鲜度指标、提交前 MySQL 事务重试/耗尽计数和可离线验证的告警规则；独立采集监听默认关闭，固定指标目录拒绝动态标签；发布前只读结构核验由[`orbit-admin verify`](api/operations.md)提供，运维人员也可用 `orbit-admin observe snapshot` 获取同一有界单节点快照；后台循环间隔、批量上限、Worker/Event连接上限、Hub领取协程和有界内存排队均支持有界环境配置，并在启动日志和固定指标中记录。跨节点重连风暴、慢消费者、真实锁等待/死锁、磁盘增长已经加入定向回归入口；目标拓扑的全局持久吞吐、锁等待/死锁告警阈值和生产采集/通知验证仍需环境验收。
 3. 已补齐受保护管理环境中的固定凭据操作文件、轮换、撤销、提交不明故障切点、幂等回执和脱敏管理审计；轮换保留授权绑定并要求新令牌重新建立会话，旧 Worker 会话被排空且立即过期，撤销允许在停用范围内执行且不改写历史记录。已用一次性 MySQL 定向验证旧令牌失效、新令牌重绑和零外键；仍需多节点安全重绑演练、凭据最小权限配置核对和生产密钥托管/审计演练。
-4. 已补[数据库保留策略、预览和只读归档导出](api/retention.md)以及[`orbit-admin retention inventory`](api/retention.md)只读盘点。策略按命名空间存入 MySQL，控制台单管理员可修改，版本、原因和前后快照进入审计；默认关闭归档，源数据不会因配置变化自动删除。固定候选目录保护有效幂等身份、未确认交付、未知效果、未终结流程和未处理 Inbox；导出包带冻结策略版本和 SHA-256；控制台支持连续批次、累计数量、摘要校验和本批重下载，真实 MySQL 回归核对同时间戳分页、保护对象、版本及权限边界。仍需在目标环境评审最终归档介质、备份恢复、删除执行器和保留周期，再执行兼容升级和容量负载。生产HA及RPO/RTO继续按实际拓扑验证，不缩减为本机多进程检查。
+4. 已补[数据库保留策略、预览和只读归档导出](api/retention.md)以及[`orbit-admin retention inventory`](api/retention.md)只读盘点。策略按命名空间存入 MySQL，控制台单管理员可修改，版本、原因和前后快照进入审计；默认关闭归档，源数据不会因配置变化自动删除。固定候选目录保护有效幂等身份、未确认交付、未知效果、未终结流程和未处理 Inbox；导出包带冻结策略版本和 SHA-256；控制台支持连续批次、累计数量、摘要校验和本批重下载，真实 MySQL 回归核对同时间戳分页、保护对象、版本及权限边界。已补[持久文件归档作业](api/retention-jobs.md)：自动有限分批、原目录续跑、原子发布、容量限制、摘要链、离线核验及真实强杀恢复；尚未接入周期调度、控制台作业列表或跨节点自动接管。仍需在目标环境评审最终归档介质、备份恢复、删除执行器和保留周期，再执行兼容升级和容量负载。生产HA及RPO/RTO继续按实际拓扑验证，不缩减为本机多进程检查。
 5. 已补[`orbit-load`](api/load.md)有界受理负载工具及24次/1000次隔离样本，见[受理报告](reports/phase-6-load.md)。新增独立[`orbit-exec-load`](api/execution-load.md)，通过真实Worker、任务结果和尝试历史核对，提供短/混合/中长任务的受理、排队、授权执行及完成耗时分布；具体环境、原始JSON和失败分母见[执行测量报告](reports/phase-6-execution-load.md)。新增[`orbit-workflow-load`](api/workflow-load.md)，用本次发布版本的双分支并行流程，逐个核对不同任务、唯一尝试、来源、精确输出与本地调用；24/100实例及24实例截止负例已重新构建回归并绑定源码/二进制哈希，见[流程测量报告](reports/phase-6-workflow-load.md)。新增[`orbit-schedule-load`](api/schedule-load.md)，已完成24/128次定时集中触发与24次计划量的截止负例，保存实际分母、唯一任务/尝试、来源与暂停收尾证据，见[定时测量报告](reports/phase-6-schedule-load.md)。Go 1.27.1 模块级门禁、MySQL 存储集成、关键 SDK/Orbit 进程故障组、24个可运行 SDK 示例真实服务串跑和 result-inbox/task-outbox 真实业务集成已复跑通过。已补[长期积压与资源曲线样本](reports/phase-6-backlog.md)：32×8 共256个触发点，在1个Worker/容量1和180秒截止下保留173个成功、83个未核验任务，并以独立数据库读取记录等待积压曲线；该单节点样本不替代目标拓扑容量。SDK受控重连风暴及[真实慢消费者背压](reports/phase-6-slow-consumer.md)已补边界回归，积压脚本已加入 CPU/RSS、MySQL 资源、连接池等待、业务快照和事务重试计数采样；已补跨节点重连、慢消费者与有界磁盘增长样本（见 [P1 定向报告](reports/phase-6-stability-p1.md)）；长期磁盘曲线与目标数据库拓扑容量继续按实际负载验收。
 6. 已补[隔离备份恢复演练](api/backup-restore.md)：源库和恢复库均为一次性 MySQL 容器，Go 1.27.1 构建的当前二进制在逻辑备份恢复后核对迁移账本、核心记录数量、固定索引和零外键；证据见[恢复报告](reports/phase-6-backup-restore.md)。该演练不替代生产备份介质、复制切换、跨版本恢复或 RPO/RTO 验收。
 7. 已补[A18 数据库短暂不可用恢复演练](api/db-recovery.md)：Go 1.27.1 构建的当前二进制在数据库停止期间返回 readiness 503，同卷恢复后返回 200，并用原权限范围继续受理任务；证据见[数据库恢复报告](reports/phase-6-db-recovery.md)。该演练不替代主从切换、复制确认、跨故障域或 RPO/RTO 验收。
@@ -236,6 +236,7 @@ A04派发已提交而消息尚未到达Worker的精确进程故障已通过[专
 - [P2 自动 Worker 运行器记录](reports/phase-2-worker-runtime.md)
 - [P2 执行历史与大载荷记录](reports/phase-2-execution-history.md)
 - [P1 稳定性与归档定向回归](reports/phase-6-stability-p1.md)
+- [持久文件归档作业回归](reports/phase-6-retention-jobs.md)

 ### 状态事件时间线子项

--- a/docs/README.md
+++ b/docs/README.md
@@ -39,6 +39,8 @@
 | [接口手册](api/README.md) | 实际接口状态、调用说明与后续接口规划 |
 | [SDK 与场景](sdk/README.md) | 可运行示例、接入方法及分阶段 SDK 交付 |
 | [Orbit Console](console.md) | 内置控制台、本地打开方式与权限边界 |
+| [保留策略](api/retention.md) | 管理端窗口配置、候选保护和只读快照 |
+| [文件归档作业](api/retention-jobs.md) | 自动有限分批、断点续跑、容量限制和离线核验 |

 ## 已确认的决策

--- a/docs/api/operations.md
+++ b/docs/api/operations.md
@@ -26,8 +26,8 @@ make release-manifest > orbit-release-manifest.json
    "workflow_schema_version": 1
  },
  "schema": {
-    "current_version": 28,
-    "migration_count": 28,
+    "current_version": 30,
+    "migration_count": 30,
    "migrations": [
      {"version": 1, "name": "000001_initial.up.sql", "checksum": "<sha256>"}
    ]
@@ -47,7 +47,7 @@ ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
 成功时输出类似：

 ```json
-{"schema_version":28,"migration_count":28,"foreign_key_count":0,"required_index_count":6,"complete":true}
+{"schema_version":30,"migration_count":30,"foreign_key_count":0,"required_index_count":6,"complete":true}
 ```

 `complete=true` 表示当前二进制的迁移账本、Orbit 表零外键，以及 000026–000028 的六个有界观测索引均满足要求。需要同时核对发布物身份时，传入保存的清单：
@@ -79,3 +79,7 @@ ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
 ```

 它与 `/metrics` 共享同一有界读取实现，但不会改变指标注册器或业务状态；遇到数据库超时会返回非零状态，调用方应保留上一次成功快照并排查数据库。
+
+## 文件归档与离线核验
+
+[`orbit-admin retention archive / verify-archive`](retention-jobs.md) 提供持久文件作业、原目录续跑及摘要链核验。读取命名空间需显式指定已保存策略版本，每个新批次记录独立作业审计，源记录不删除；离线核验无需数据库。
--- a/docs/api/retention-jobs.md
+++ b/docs/api/retention-jobs.md
@@ -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 批。该归档不是数据库备份，也不构成源数据删除授权。
--- a/docs/api/retention.md
+++ b/docs/api/retention.md
@@ -109,6 +109,10 @@ if page["next_cursor"]:

 摘要针对 `content` 的原始 UTF-8 字节，不对解析后重新格式化的 JSON 计算。SHA-256 用于发现内容损坏；摘要与正文一起被篡改时无法证明真实性，需要把审计摘要或外部签名另行保存在可信介质中。

+## 自动分批与持久归档
+
+需要在页面之外连续处理并断点续跑时，使用 [`orbit-admin retention archive`](retention-jobs.md)。目录、批量、总字节及执行时限可配置，已发布文件就是恢复检查点，支持离线核验；源业务数据仍保留。周期触发和清理执行器尚未接入。
+
 ## 只读盘点

 `orbit-admin retention inventory` 用于在制定保留窗口、归档和备份恢复方案前盘点历史数据。它只执行带截止时间的统计查询，不删除、搬迁、改写数据，也不会自动判断某条记录可以安全归档。
--- a/docs/reports/phase-6-retention-jobs.md
+++ b/docs/reports/phase-6-retention-jobs.md
@@ -0,0 +1,43 @@
+# 持久文件归档作业回归（2026-09-23）
+
+本批在 `2d8467e` 的只读归档导出之上增加本地持久作业执行器及运维 CLI。无数据库迁移、外键或源数据清理操作；控制台导出的授权方式不变。使用说明与参数见[文件归档作业](../api/retention-jobs.md)。
+
+环境：macOS arm64、Go 1.27.1、本地 POSIX 文件系统；Docker MySQL 8.4 与 Linux 容器。证据仅覆盖隔离环境中的文件恢复和数据库行为，不代表共享存储或跨节点归档高可用已经验收。
+
+## 文件与进程恢复
+
+`go test -race ./internal/retention ./cmd/orbit-admin` 覆盖：
+
+| 场景 | 核对内容 |
+| --- | --- |
+| 有限批次与续跑 | 首次仅一批，保留原作业 ID；下次仅导出第二批；完成后重复调用不重复导出 |
+| 崩溃残留 | 部分 `.write.tmp` 不算检查点，恢复会重新导出未发布批次 |
+| 真实进程强杀 | 子进程第一批落盘后发出就绪标记，父进程 Kill 并 Wait 后，新进程取得锁并只继续第二批 |
+| 文件链损坏 | 正文改动、缺批、互换、符号链接、未知文件全部阻止核验与续跑 |
+| 容量上限 | 第一批已保存，第二批超过 1 MiB 总额时停止；显式提高预算后继续，第一批原字节不变 |
+| 写入失败 | 在非 root 进程中把目录改为只读，第二批写入失败但原检查点仍可核验；恢复写权限后续跑 |
+| 取消与并发 | 批次返回后上下文取消不发布文件；相同目录第二个写者被非阻塞文件锁拒绝 |
+| 独立可信摘要 | 无 DSN 也能校验；与另行保存的末端摘要不匹配时非零退出 |
+
+每个批次先同步正文，再原子发布、同步目录并回读。文件权限为 0600，目录为 0700。SHA-256 和前序摘要用于完整性校验；没有独立可信末端摘要时，不声称能抵抗整套档案与摘要一起被重写。
+
+## Docker 首次部署闭环
+
+`make console-e2e` 从空库迁移、管理员初始化和登录开始，保留原任务/重试/计划/退出后拒绝访问验证，增加：
+
+- 使用刚保存的保留策略生成一个合法空作业，`completed=true`、`batches=1`、`roots=0`。
+- 在 `--network none` 的独立容器运行 `retention verify-archive`，不注入 DSN；结果与运行输出逐字段一致。
+
+数据库提交后的导出审计与文件持久化不是同一事务。文件失败可能导致重试产生新的导出审计；不会改写源记录，不能以审计存在推断文件已经保存。
+
+## 边界
+
+本批交付可重复执行的有限批次执行器，不新增周期调度服务或控制台作业列表。本地同目录文件锁不能证明跨节点共享文件系统可靠；不同节点独立磁盘也不能互相恢复。新一轮扫描需要独立目录，归档介质备份、定时触发、长期容量、跨节点接管及清理执行器仍需后续实现和验收。
+
+## 真实 MySQL 作业结果
+
+标准集成入口中的 `TestIntegrationRetentionDiskGrowthAndPreview` 使用 256 条样本，其中 254 条终态且完成时间相同，另 2 条为未知效果/运行租约保护对象。首次文件作业只导出 37 条，下一次从原目录接续，最终 254 条根记录、7 个批次、7 条 `archive:<job_id>` 审计；离线核验返回相同摘要和计数。停用命名空间返回 `PERMISSION_DENIED`，不能继续导出。控制台原有分页仍为 8 批、254 个唯一根记录，源表保持 256 条。
+
+有界磁盘采样观察到表/索引统计 1,835,008 → 16,564,224 字节，增量 14,729,216；预览仍为 100 条样本且有后续候选。该统计只证明本次样本增长，不用于推算生产容量。
+
+最终门禁：`make test`（四个模块 race）、`make vet`、`make build`、`make docs-check`、`make console-e2e` 和修正断言后的完整 `make integration` 均通过。全量 MySQL 存储组用时约 286 秒，真实 SDK Worker/Event 进程故障组约 130 秒，最后的双节点流程暂停恢复组约 13 秒；包含独立 Inbox/Outbox 业务示例、Schema 30 及零外键验证。首轮集成中停用命名空间的预期错误码写成了 `FORBIDDEN`，实际服务端正确返回 `PERMISSION_DENIED`；修正测试后重跑全链路通过，没有放宽权限判断。