备份、恢复与迁移¶
本文面向自托管管理员。备份的目标不是“保存一个数据库文件”，而是能够在另一台机器上恢复出可登录、可查询、可继续运行的 QuantDinger。
必须保存的内容¶
| 内容 | 是否必须 | 说明 |
|---|---|---|
| PostgreSQL 数据库 | 是 | 用户、策略、回测、订单、系统配置等持久数据 |
.env |
是 | 端口、部署模式和外部服务配置 |
CREDENTIAL_ENCRYPTION_KEY |
是 | 解密已保存券商、交易所和第三方凭证；丢失后无法恢复 |
| 反向代理与证书配置 | 生产环境必须 | 域名、HTTPS 和代理规则 |
| 自定义策略、脚本和挂载目录 | 按需 | 不在数据库或镜像内的本地资产 |
镜像版本或 IMAGE_TAG |
建议 | 用于重现备份时的运行版本 |
不要把 .env、密钥或数据库备份提交到 Git。备份应加密，并与生产服务器分开保存。
创建一致性备份¶
- 记录当前版本：
bash
docker compose ps
docker compose images
- 创建目录并导出 PostgreSQL 自定义格式备份：
bash
mkdir -p backups
docker exec quantdinger-db pg_dump -U quantdinger -Fc -d quantdinger -f /tmp/quantdinger.dump
docker cp quantdinger-db:/tmp/quantdinger.dump ./backups/quantdinger.dump
- 将
.env、代理配置和自定义挂载目录复制到加密备份介质。 - 记录备份时间、QuantDinger 版本、数据库容器版本和校验和。
- 在隔离环境执行一次恢复演练。没有通过恢复演练的文件不能算有效备份。
持续写入较多的生产实例，建议先暂停策略和任务入口，待数据库导出完成后再恢复运行。
恢复到新环境¶
- 安装与原环境兼容的 Docker 和 QuantDinger 版本。
- 恢复
.env，尤其保持原CREDENTIAL_ENCRYPTION_KEY不变。 - 启动 PostgreSQL，停止可能写入数据库的应用服务。
- 复制并恢复备份：
bash
docker cp ./backups/quantdinger.dump quantdinger-db:/tmp/restore.dump
docker exec quantdinger-db pg_restore -U quantdinger -d quantdinger --clean --if-exists /tmp/restore.dump
- 运行当前版本的数据库迁移并启动完整服务：
bash
docker compose up -d migration
docker compose up -d
- 按顺序验证健康检查、管理员登录、策略与回测历史、券商账户、通知和任务队列。
建议先恢复到临时环境验证，再切换生产域名。恢复过程中不要执行 docker compose down -v，它会删除数据卷。
迁移到另一台主机¶
迁移应采用“旧机备份 → 新机恢复 → 验收 → 切流”的方式：
- 降低 DNS TTL，并记录旧环境版本。
- 在旧机暂停新策略、计划任务和写入入口。
- 创建最终数据库备份并复制配置和自定义资产。
- 在新机恢复，用临时域名完成验收。
- 切换 DNS 或负载均衡器，观察健康、日志和订单状态。
- 保留旧机为只读回退点，确认稳定后再下线。
跨版本迁移时，先用旧版本恢复成功，再按升级与回滚逐版升级。不要把数据库直接恢复到一个未经验证的更旧应用版本。
定期检查清单¶
- 每日或按业务恢复点目标备份数据库。
- 每次升级前做一次不可覆盖的完整备份。
- 至少每季度完成一次隔离恢复演练。
- 定期验证备份校验和、加密密钥和保留周期。
- 备份凭证只授予必要人员，下载和恢复操作应留审计记录。