备份与恢复

备份包含什么

官方 backup.sh 会：

1. 使用一致性事务导出 MySQL，并压缩为 juzhenpan-db-时间.sql.gz；
2. 验证 gzip 完整性；
3. 为数据库备份生成 SHA-256 校验文件；
4. 归档存在的 .env 和 config.yml；
5. 尽量归档容器内 /app/data 与 /app/static。

如果文件归档失败，脚本会保留已经成功的数据库备份并给出提示。此时不能把整套备份写成“全部成功”。

许可证相关运行目录

商业实例的固定实例 ID 和配置加密密钥属于恢复所需资料。确认你的备份策略包含完整 runtime/ 及原凭据密钥；不要将这份目录复制成第二个同时运行的实例。

执行备份

在安装目录运行：

./backup.sh

也可以指定备份目录：

./backup.sh /mnt/secure-backups/juzhenpan

完成后至少检查：

gzip -t backups/juzhenpan-db-时间.sql.gz
cd backups
shasum -a 256 -c juzhenpan-db-时间.sql.gz.sha256

.env、数据库和运行目录都可能含敏感信息，备份目录应只允许受控账号读取。

建议周期

• 每天至少一次自动备份；
• 升级、迁移和高风险批量操作前额外备份；
• 本机至少保留 7 天；
• 再复制到另一台受控服务器或私有对象存储；
• 定期在隔离环境做恢复演练。

只在同一块磁盘保存备份无法应对整盘损坏。

恢复数据库

恢复会覆盖当前数据库，先确认文件、时间点和目标实例：

JUZHENPAN_RESTORE_CONFIRM=RESTORE \
  ./restore.sh backups/juzhenpan-db-20260913-120000.sql.gz

脚本会校验 gzip 和同目录 SHA-256 文件，停止应用写入，导入数据库，再重新启动应用。

恢复后执行：

docker compose ps
docker compose logs --tail=200 app

并检查迁移版本、管理员登录、授权状态、资源数量、搜索索引、上传文件和任务记录。

恢复不是只导入 SQL

完整灾难恢复还可能需要：

• .env 和 config.yml；
• runtime/ 中的程序、版本、实例 ID 和加密凭据；
• 上传和应用数据归档；
• 与数据库时间点相符的搜索索引，或从数据库安全重建；
• 原域名、反向代理和外部连接配置。

不要把恢复演练直接指向生产数据库，也不要启动两个带相同实例身份的副本。

禁止操作

不要执行 docker compose down -v 作为普通重启或排障手段。-v 会删除 Compose 管理的数据卷，可能永久删除数据库、索引和上传数据。