单机云端备份与隔离恢复手册

1. 适用范围

本手册适用于deploy/server/compose.override.yaml部署的单机公网演示环境。目标是在不暴露数据库、Redis、对象存储和身份服务端口的前提下，形成可自动执行、可校验、可追溯的加密备份，并证明PostgreSQL备份能够恢复到独立数据库。

该能力不是跨可用区生产灾备。单机磁盘故障仍可能同时损失在线数据和本机备份，因此加密归档和口令必须另行复制到不同故障域。

2. 备份范围

组件	备份方式	当前恢复验证
PostgreSQL	`pg_dump`自定义格式，不包含所有者和ACL	实际恢复到随机隔离数据库，并核对迁移、客户组织、账号、表和外键计数
Redis	认证执行`SAVE`后复制RDB	`redis-check-rdb`验证归档内RDB格式，不覆盖在线Redis
MinIO	使用容器内`mc mirror`复制全部桶和对象	逐文件SHA-256和对象文件数量一致性检查
Keycloak	暂停容器后复制`/opt/keycloak/data`，随后立即恢复	逐文件SHA-256和文件数量检查；当前开发模式H2数据不作为生产OIDC方案

备份归档使用AES-256-CBC + PBKDF2加密，迭代次数为200000。每个归档旁边保存加密文件自身的SHA-256；归档内部另有逐文件SHA256SUMS和不含凭据的manifest.properties。

3. 自动执行流程

获取独占锁
  → PostgreSQL逻辑转储和证据快照
  → Redis认证SAVE及RDB校验
  → MinIO全桶对象镜像
  → 短暂暂停Keycloak并复制一致性数据目录
  → 逐文件SHA-256
  → 压缩、加密、生成归档摘要
  → PostgreSQL随机隔离库实际恢复
  → Redis RDB及文件清单复核
  → 删除临时数据库和临时明文
  → 按保留期清理旧加密归档

任何步骤失败都会令systemd服务失败；未完成的明文暂存目录由退出陷阱删除。备份使用flock避免重叠执行，Keycloak无论成功或异常退出都会尝试解除暂停。

4. 安装与运行

cd /opt/data-terminal-cloud/current
chmod 0755 deploy/server/backup.sh deploy/server/verify-backup.sh deploy/server/install-backup.sh
deploy/server/install-backup.sh
systemctl start platform-backup.service
systemctl show platform-backup.service -p Result -p ExecMainStatus
systemctl list-timers platform-backup.timer --no-pager

默认每天02:40执行，并附加最长45分钟随机延迟，避免固定时刻资源竞争；默认保留14天。定时任务设置Persistent=true，服务器在计划时刻关机时会在恢复后补跑。

可通过环境变量覆盖：

变量	默认值	说明
`PLATFORM_ROOT`	`/opt/data-terminal-cloud/current`	当前发布目录
`BACKUP_ROOT`	`/var/backups/data-terminal-cloud`	加密归档目录，必须为安全的绝对路径
`BACKUP_PASSPHRASE_FILE`	`/etc/data-terminal-cloud/backup-passphrase`	仅root可读的独立随机口令
`BACKUP_RETENTION_DAYS`	`14`	本机备份保留天数
`VERIFY_AFTER_BACKUP`	`false`；systemd中为`true`	备份后是否立即执行隔离恢复校验

5. 手工校验与故障定位

校验最新备份：

/opt/data-terminal-cloud/current/deploy/server/verify-backup.sh

校验指定备份：

/opt/data-terminal-cloud/current/deploy/server/verify-backup.sh \
  /var/backups/data-terminal-cloud/platform-YYYYmmddTHHMMSSZ.tar.gz.enc

查看任务结果：

systemctl show platform-backup.service -p Result -p ExecMainStatus -p ActiveState
journalctl -u platform-backup.service -n 100 --no-pager
find /var/backups/data-terminal-cloud -maxdepth 1 -type f -name 'platform-*.enc' -ls

一次性服务成功结束后显示inactive (dead)是正常状态，应结合Result=success和ExecMainStatus=0判断。校验脚本不会停止在线业务、覆盖在线数据库或载入Redis快照；随机恢复数据库在成功和失败路径都会清理。

6. 安全与恢复边界

备份口令不写入仓库、归档、日志或Compose环境文件；默认权限为0600 root:root。
备份目录默认权限为0700，归档和摘要为0600。
明文转储只存在于同一受控暂存目录，归档加密后立即删除。
当前归档留在同一云服务器只提供误操作恢复能力，不提供主机或地域故障保护。
生产环境应使用托管PostgreSQL持续备份/PITR、版本化对象存储、外部OIDC、跨故障域副本、KMS托管密钥和受控恢复演练。
不能仅凭定时任务成功声称满足某个RPO/RTO；必须结合备份频率、异地复制、真实数据量和受控恢复耗时单独验收。

7. 上线前检查

把加密归档复制到不同故障域，并独立验证复制后的SHA-256。
把口令保存到云KMS、密码库或离线托管介质，不与归档放在同一位置。
配置备份失败和长时间未成功告警。
在预生产环境执行PostgreSQL、Redis、对象存储和OIDC的完整恢复演练。
记录实际备份大小、持续时间、恢复时间和业务抽查结果，再确定RPO/RTO。

5.1 KiB Raw Blame History Unescape Escape