44 lines
4.2 KiB
Markdown
44 lines
4.2 KiB
Markdown
# 持久文件归档作业回归（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`；修正测试后重跑全链路通过，没有放宽权限判断。
|