convex-backup

备份——并证明恢复有效

每个备份方案都有两部分，但大多数人只做第一部分：创建备份，以及证明能够恢复备份。此能力兼顾两者——设置定期快照导出，然后执行一次 RESTORE DRILL，将数据实际恢复到一次性预览环境中，并断言数据完好无损。该演练复用 migrate-rehearse 的确切基本操作（快照导出 → 预览部署 → 快照导入），但目标是恢复，而不是向前变更，因此测试的是安全网，而不是想当然地认为它有效。

工作流

1. GUARD：deploy-guard——对要备份的部署进行分类并发布通知（读取/导出是安全的；演练的恢复目标是一次性预览环境，绝不会是生产环境）。
2. 创建快照：npx convex export --path backup-<date>.zip（如果应用存储文件，请添加 --include-file-storage）。这是备份文件；请将其视为敏感的真实数据。
3. 安排定期备份（持续执行的部分）：根据数据变化速度和可容忍的数据丢失量（RPO）建议合适的频率——例如，通过 CI/cron 每天运行一次 npx convex export，并将备份存储到用户控制的持久化存储中，同时设置保留期限。Convex 平台本身也提供备份；此方案会额外创建一份用户所有、可移植的副本。
4. RESTORE DRILL（几乎没人做的部分——这才是重点）： (a) 前提条件：将 Preview Deploy Key 设置为 CONVEX_DEPLOY_KEY（与 migrate-rehearse 的要求相同；这是付费层级功能）。如果无法使用，请改为对一个全新的个人开发部署进行演练，并明确说明。 (b) 从当前代码创建一次性预览环境：npx convex deploy --preview-create restore-drill-<date>。 (c) 将快照恢复到该环境：npx convex import backup-<date>.zip --deployment restore-drill-<date> --replace（导入时通过 --deployment 指定部署名称；导入命令没有 --preview-name 参数）。 (d) 断言恢复成功：读取恢复后的数据（使用 MCP tables 检查行数，并使用 data/runOneoffQuery 抽样检查），确认关键表已恢复，行数符合预期，并检查部分真实记录——如果恢复「成功」但最终有 0 行，这就是一次失败的演练。尽可能与源部署的行数进行比较。
5. 清楚报告演练结果：备份了什么；是否确实执行并验证了恢复（或者演练失败的原因——在真正的灾难发生前发现失败的演练，是最有价值的结果）；建议的备份频率与保留期限；以及恢复操作手册（恢复到生产环境的确切命令：npx convex import backup.zip --replace --prod，执行前须经过 deploy-guard 检查，并说明快照创建后发生的数据写入丢失这一注意事项）。
6. 清理：完成后删除本地快照副本（其中包含真实数据）；演练预览环境会自动过期。绝不要提交备份文件。

规则

• 从未恢复过的备份只是希望，不是真正的备份——始终执行（或提出执行）RESTORE DRILL，不要只导出备份。
• 演练必须将备份恢复到一次性预览环境（或开发环境），绝不能是生产环境；恢复目标部署必须与备份源部署不同。
• 断言恢复成功，不要想当然：如果恢复后有 0 行，就是一次失败的演练——请检查关键表的行数，以及与源数据对比的真实记录样本。
• 失败的演练是最有价值的结果——务必明确指出；这正是要在真正的灾难发生前进行演练的原因。
• 根据 RPO（可容忍的数据丢失量）安排备份频率；除 Convex 平台备份外，还要保留一份用户所有、可移植的副本，并设置保留期限。
• 快照包含敏感的真实数据：完成后删除本地副本，绝不提交；恢复到生产环境的操作手册必须经过 deploy-guard 检查，并说明快照创建后发生的数据写入丢失这一注意事项。
• 复用 migrate-rehearse 的快照和预览环境机制，但目标是恢复，而不是向前变更——向前的架构变更属于 migrate-rehearse。