# 备份与按时间点恢复

主控业务库与 ClickHouse 关键表的定时备份、加密与异地副本，以及恢复到指定时间点。

主控的定时任务 `master.backup` 备份两类数据:MariaDB 业务库(默认每小时一次,文件名 `gocdn-db-<UTC 时间>.sql.gz`)和 ClickHouse 关键表(每天一次,`billing_hourly` 与 `usage_site_5m`,文件名 `gocdn-ch-*.jsonl.gz`)。配置了加密公钥后,文件以 `.age` 结尾。


## 在面板里设置
进入「系统管理 › 系统设置 › 数据清理」页签的「数据库备份」卡片:

| 设置 | 说明 |
|---|---|
| 定时备份 | 总开关 |
| 备份间隔 | 预设 10 分钟到 1 天,也可自定义(如 `90m`);范围 10 分钟–7 天,失败后 10 分钟重试 |
| 近期全留份数 | 最近这么多份全部保留,默认 24(间隔 1 小时即逐小时) |
| 保留天数 | 更早的每天只留一份,默认 7 天 |
| 磁盘剩余下限 | 备份目录所在磁盘剩余空间低于它时先删旧备份,默认 15%;0 为不检查 |
| 备份总量上限 | 备份目录总量上限,0 为不限 |
| 备份目录 | 默认 `/var/lib/gocdn/backup/db` |
| 高级:异地副本目录、加密公钥 | 见下文 |

备份运行情况和异常在「系统管理 › 日志审计 › 备份」查看。

### 磁盘保护
磁盘剩余低于下限或总量超限时,先删最旧的备份,但每一类始终保留最新的一份;删完仍不够就跳过本次备份并告警,10 分钟后重试,避免把磁盘写满拖垮主控。

## 加密
在「加密公钥」填入 age 公钥(`age1` 开头),备份文件会加密成 `.age`。新装的主控会自动生成私钥 `/etc/gocdn/backup-age.key`,请把它拷到别的机器保管。旧安装可以在主控上以 root 执行:

```
gocdn-master backup-keygen -out /etc/gocdn/backup-age.key
```

私钥丢失后无法解密备份。未加密的备份,尤其是推送到异地目录的,「备份」页签顶部会出现「备份未加密」提示。

## 异地副本与时间点恢复
填写「异地副本目录」(一般是挂载的 NAS 或另一块盘)后,每次备份会把文件复制过去,同时每分钟把数据库增量日志(binlog)推送过去,恢复点目标约 1 分钟。

- 远端磁盘需要运维自己挂载,且挂载点在挂载前不能被 gocdn 用户写入。
- MariaDB 需要开启 binlog(`log_bin`),业务库账号需要 `BINLOG MONITOR` 与 `REPLICATION SLAVE` 权限。不满足时只推送整库备份,「备份」页签会出现「binlog 增量备份未生效」提示。

## 恢复业务库
恢复前先停主控服务,然后在主控上执行。

恢复到备份那一刻:

```
gocdn-master db-restore < gocdn-db-<时间>.sql.gz
```

恢复到指定时间点(需要异地副本里的 binlog):

```
gocdn-master db-restore -until <RFC3339 时间> -binlog-dir <异地目录>/binlog < gocdn-db-<时间>.sql.gz
```

可选参数:`-age-identity`(加密备份的私钥)、`-overwrite`(覆盖已有数据)、`-client-defaults`。末行出现 `DB_RESTORE_DONE` 表示成功。

## 恢复 ClickHouse 关键表
```
gocdn-master ch-restore < gocdn-ch-<时间>.jsonl.gz
```
末行出现 `CH_RESTORE_DONE` 表示成功。

## 签名钥与凭据加密钥
- 签名钥另有加密备份 `/var/lib/gocdn/backup/keys.tar.age`,口令文件是 `/etc/gocdn/keys-backup.pass`。恢复用 `gocdn-keys restore -passphrase-stdin -in keys.tar.age < 口令文件`。
- 凭据加密钥 `/etc/gocdn/dns-cred.key` 不在任何备份里,必须单独拷到别的机器保管。

:::warn
备份目录、私钥和钥文件都放在主控本机时,主控磁盘损坏就等于全部丢失。务必配置异地副本,并把 `backup-age.key`、`keys-backup.pass`、`dns-cred.key` 存到离机位置。
:::

把主控迁到新机器的完整步骤见[卸载与迁移](https://www.gocdn888.com/zh/guide/migrate)。