test: add isolated backup restore rehearsal

docs/api/README.md

@@ -23,6 +23,7 @@
 | `orbit-admin verify` 发布前结构核验 | 已实现只读迁移、零外键和 000026–000028 固定索引检查 | [运维核验](operations.md) |
 | `orbit-admin retention inventory` 保留清单 | 已实现带 UTC 截止时间的只读盘点；不执行归档、删除或权限变更 | [保留清单](retention.md) |
 | `sdk/go/cmd/orbit-load` 有界受理负载工具 | 已实现固定并发、无自动重试、延迟百分位和错误分类；只用于隔离环境 | [负载工具](load.md) |
+| `scripts/test-backup-restore.sh` 隔离备份恢复演练 | 已实现一次性 MySQL 逻辑备份、独立恢复、核心计数及零外键核验 | [备份恢复演练](backup-restore.md) |
 | `/v1/worker/connect` | P2 已实现并通过阶段验收 | [Worker 契约](worker.md)、[Schema](worker-schema.md) |
 | 任务相对延迟 `delay_ms` | 已实现数据库计时、原键恢复与实际执行例子 | [任务接口](tasks.md)、[延迟示例](../examples/delayed-task.md) |
 | 任务冻结策略与 Worker `retryable` | P3 安全重试已实现 | [安全重试](retries.md) |

docs/api/backup-restore.md

@@ -0,0 +1,20 @@
+# 隔离备份恢复演练
+
+`scripts/test-backup-restore.sh` 用两个一次性 MySQL 容器演练逻辑备份恢复：源库按当前迁移建库并写入通用应用、命名空间、凭据和队列，使用 MySQL `mysqldump` 导出，再恢复到独立目标库。脚本随后运行 `orbit-admin verify`，并比较关键核心表数量和目标库外键数量。
+
+```sh
+DOCKER=/usr/local/bin/docker \
+ORBIT_TEST_MYSQL_IMAGE=mysql:8.4 \
+sh scripts/test-backup-restore.sh
+```
+
+运行前需要已经构建当前版本的 `bin/orbit-migrate` 和 `bin/orbit-admin`；也可以通过 `ORBIT_MIGRATE_BIN`、`ORBIT_ADMIN_BIN` 指定绝对路径。脚本只连接自己创建的容器，使用随机 root 密码和随机映射端口；退出时删除容器和临时凭据文件。它不读取、覆盖或清理任何已有数据库。
+
+演练检查以下结果：
+
+- 迁移账本完整且 `dirty=false`，当前版本与二进制校验和一致。
+- 应用、命名空间、凭据、队列和迁移账本的核心记录数量在源库与恢复库相同。
+- 恢复库 Orbit 表的外键数量为零，固定观测索引完整。
+- `orbit-admin verify` 只读返回 `complete=true`；它不会修改恢复库或自动修复结构。
+
+该演练验证逻辑备份文件能在同版本 MySQL 和同一迁移账本下恢复。它不能证明备份介质持久性、跨版本升级、跨故障域复制、生产密钥托管、外部业务副作用核对、RPO/RTO 或在线大库备份窗口；这些必须在目标部署环境单独验收。