# 管理后台使用说明：数据备份功能

URL: https://docs.ones.cn/deploy/configure/ones-admin/ones-admin-backup-usage

本文面向实施维护人员，说明如何打开 ONES 数据备份，并在管理后台查看、手动触发和确认备份结果。

管理后台打开方式请参考： [打开管理后台](https://docs.ones.cn/deploy/configure/ones-admin/open-ones-admin/) 。

备份底层配置可参考运维手册： [备份 ONES](https://docs.ones.cn/deploy/configure/data/backup-restore/backup-Instructions/) 。

## 1. 功能说明

管理后台的 `数据备份` 页面用于：

- 查看 MySQL、ClickHouse、附件的备份状态。
- 查看上次成功备份时间。
- 查看自动备份计划。
- 手动触发一次备份。
- 查看备份历史和失败原因。
注意：

- 管理后台只负责展示和触发备份，备份功能仍需要先在部署配置中开启。
- 数据恢复不在本页面操作，恢复请按恢复文档或恢复命令执行。
- 备份涉及数据安全，生产环境操作前应先确认对象存储、磁盘空间和保留策略。

## 2. 打开备份功能

### 2.1 进入操作容器

生产环境在部署机执行：

```sh
./ones-ai-k8s.sh
```

进入容器后切到部署目录：

```sh
cd /data/ones/ones-ai-k8s
```

### 2.2 修改配置

先备份配置：

```sh
cp config/private.yaml config/private.yaml.bak-$(date +%Y%m%d-%H%M%S)
```

编辑配置：

```sh
vi config/private.yaml
```

先配置备份对象存储。6.33 及以上版本常用配置如下：

```yaml
backupS3Endpoint: http://minio.ones-backup:9000
backupS3AccessKeyID: <对象存储AccessKey>
backupS3SecretAccessKey: <对象存储SecretKey>
backupS3ForcePathStyle: true
backupS3PublicBucket: ones-public-files-backup
backupS3PrivateBucket: ones-private-files-backup
backupS3MySQLXbackupBucket: mysql-xbackup
backupS3ClickhouseBucket: clickhouse-backup
```

再按需开启备份对象。

开启附件备份：

```yaml
backupEnabledForObjectStorage: "true"
```

开启 MySQL 备份：

```yaml
mysqlXbackupEnable: "true"
mysqlStatusServerEnable: true
mysqlXbackupToken: "<随机字符串>"
mysqlXbackupInternalEnable: true
xbackupNginxEnable: true
xbackupNginxBasicAuthUser: "<备份代理用户名>"
xbackupNginxBasicAuthPasswordSecret: "<htpasswd生成的密码密文>"
mysqlXbackupNginxBasicAuthPassword: "<备份代理明文密码>"
```

如果现场使用外置 MySQL，不需要开启内置 MySQL 备份，请按现场数据库备份方案处理。

开启 ClickHouse 备份：

```yaml
clickhouseBackupEnable: "true"
clickhouseBackupCleanEnable: "true"
clickhouseBackupCleanDaysMinAge: "60"
```

配置要点：

- `backupS3Endpoint` 、 `backupS3AccessKeyID` 、 `backupS3SecretAccessKey` 必须能访问对象存储。
- MySQL、ClickHouse、附件可以按需单独开启。
- 如果页面显示 `配置不完整` ，通常是对象存储地址、密钥或 bucket 配置缺失。

### 2.3 应用配置

执行：

```sh
make setup-ones
make setup-ones-built-in-mysql
```

等待命令完成后，检查组件状态：

```sh
kubectl -n ones get deploy | grep -E 'backup|xbackup'
kubectl -n ones get pods | grep -E 'backup|xbackup'
```

重点确认：

- `mc-backup-tools` 正常运行，用于附件备份。
- `mysql-xbackup` 正常运行，用于 MySQL 备份。
- `clickhouse-backup` 正常运行，用于 ClickHouse 备份。
如果某类备份没有开启，对应组件可能是 `0/0` ，这是正常的。

## 3. 进入数据备份页面

浏览器打开：

```text
http://<管理后台访问地址>/ones-admin/
```

登录后，左侧菜单点击 `数据备份` 。

如果需要用英文界面查看或截图，可以使用：

```text
http://<管理后台访问地址>/ones-admin/?locale=en-US#/backup
```

页面示例：

![Data backup overview](https://docs.ones.cn/assets/images/backup-overview-en-c5fddd093ee0a396e4f60a73f5c0e789.png)

重点看：

- `Current backup status` ：当前备份对象是否启用。
- `Last successful backup` ：最近一次成功备份时间。
- `Backup plan` ：自动备份计划入口。
- `Backup history` ：备份历史记录。
状态说明：

- `Enabled` ：该备份对象已开启，可以自动备份，通常也可以手动触发。
- `Not enabled` ：该备份对象没有开启。
- `Configuration invalid` ：已开启，但配置不完整，需要补齐缺失配置。

## 4. 查看备份计划

点击 `Backup plan` ，可以查看自动备份策略。

![Backup plan](https://docs.ones.cn/assets/images/backup-plan-modal-en-30a85d7b5e3fd6fc6585fec8557d4228.png)

常见信息：

- MySQL：通常包含全量备份和增量备份计划。
- ClickHouse：通常按计划执行备份，并按保留天数清理。
- Attachments：通常每日执行增量备份。
- Retention period：备份保留策略。
备份计划来自 `config/private.yaml` 中的 cron 和保留策略配置。如果需要调整计划，应修改配置后重新执行生效命令。

## 5. 手动触发备份

点击右上角 `Manual backup` 。

![Manual backup](https://docs.ones.cn/assets/images/backup-manual-modal-en-8891ef65e9c8a63cd9a2bc07a782b6d9.png)

正常流程：

1. 选择一个或多个备份对象。
2. 为支持的对象选择备份方式，例如全量或增量。
3. 点击 `Start backup` 。
4. 回到历史列表查看任务状态。
注意：

- 如果弹窗提示 `No backup targets can be triggered manually` ，说明当前没有可手动触发的备份对象。
- 如果提示某个对象 `Backup target is not enabled` ，需要先回到部署配置中开启该对象。
- 不要在短时间内重复触发同一个备份对象。
- 首次开启备份后，建议先手动触发一次，确认备份链路可用。

### 5.1 手工备份执行示例

以下截图为当前环境实际执行 `Attachments` 手工备份的过程示例。

触发前，先确认目标对象处于 `Enabled` 。如果目标显示 `Not enabled` ，需要先按第 2 节补齐配置并执行生效命令。

![Manual backup target enabled](https://docs.ones.cn/assets/images/backup-manual-overview-enabled-en-08f3718ee1665dc11406a3c7735c50e6.png)

点击 `Manual backup` 后，选择本次要备份的对象。示例中只选择 `Attachments` 。

![Select attachments backup](https://docs.ones.cn/assets/images/backup-manual-attachment-selected-en-4b35bc783d991dc3820fc270a7f18a81.png)

点击 `Start backup` 后，回到 `Backup history` 查看任务状态。任务刚开始时状态为 `In progress` 。

![Manual backup running](https://docs.ones.cn/assets/images/backup-manual-running-en-52444ce45a298f7a84445642b6fd1640.png)

等待任务完成后，刷新或查看历史列表，状态变为 `Success` 。示例中最新一条 `Attachments` 手工备份耗时 `33 seconds` 。

![Manual backup success](https://docs.ones.cn/assets/images/backup-manual-success-en-72dff72bbc39570764935729c5888f12.png)

执行完成后，重点确认：

- `Trigger type` 为 `Manual` 。
- `Initiator` 为 `Admin Console` 。
- `Status` 为 `Success` 。
- `Duration` 有正常耗时。
- `Backup path` 有备份写入位置。

## 6. 查看备份历史

在 `Backup history` 中查看备份记录。

常用筛选：

- `Backup target` ：按 MySQL、ClickHouse、Attachments 筛选。
- `Status` ：按运行中、成功、失败筛选。
- 日期范围：查看指定时间段内的备份记录。
每条记录重点看：

- `Time` ：备份开始时间。
- `Backup target` ：备份对象。
- `Strategy` ：全量或增量。
- `Trigger type` ：自动或手动。
- `Status` ：成功、失败或运行中。
- `Backup path` ：备份写入位置。
- `Failure reason` ：失败原因。
如果失败记录提供日志下载入口，可以下载日志后再排查。

## 7. 检查备份文件

如果使用集群内置 MinIO，可以先确认备份数据目录：

```sh
PVC=data-minio-0
PV=$(kubectl -n ones-backup get pvc "$PVC" -o jsonpath='{.spec.volumeName}')
kubectl get pv "$PV" -o jsonpath='{.spec.local.path}{"\n"}'
```

进入输出目录后，按备份对象检查文件：

```sh
# 附件备份
du -sh ones-private-files-backup/
du -sh ones-public-files-backup/

# MySQL 备份
ls -altr mysql-xbackup/

# ClickHouse 备份
ls -altr clickhouse-backup/*/*/*
```

如果使用外置 S3 或外置 MinIO，也可以直接到对象存储控制台查看对应 bucket。

## 8. 常见问题

### 页面显示 Not enabled

说明对应备份对象没有开启。请检查：

- 附件： `backupEnabledForObjectStorage`
- MySQL： `mysqlXbackupEnable`
- ClickHouse： `clickhouseBackupEnable`
修改后执行：

```sh
make setup-ones
make setup-ones-built-in-mysql
```

### 页面显示 Configuration invalid

说明配置缺失。常见缺失项：

- `backupS3Endpoint`
- `backupS3AccessKeyID`
- `backupS3SecretAccessKey`
- 对应 bucket 配置
- MySQL 的 `mysqlXbackupToken`
- ClickHouse 的 `clickhouseBackupTables`
补齐后重新应用配置。

### 手动备份按钮可点，但任务失败

先看历史列表中的失败原因。如果有日志下载入口，先下载日志。

常见原因：

- 对象存储不可访问。
- AccessKey 或 SecretKey 错误。
- bucket 不存在。
- MySQL 或 ClickHouse 备份组件未正常运行。
- 集群资源不足或网络异常。

### 备份历史为空

可能原因：

- 备份刚开启，还没有产生任务。
- 筛选条件过窄。
- 自动备份时间还没有到。
可以清空筛选后再看，或手动触发一次备份进行验证。

### 管理后台能否执行恢复

不能。当前页面用于备份状态、备份计划、手动备份和历史查看。恢复操作请按恢复文档或现场恢复方案执行。