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

## 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. 自动执行流程

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

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

## 4. 安装与运行

```bash
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. 手工校验与故障定位

校验最新备份：

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

校验指定备份：

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

查看任务结果：

```bash
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. 上线前检查

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