数据备份&恢复详细说明

1 前置说明

（1）本文适用于当前主机运行异常，定时备份文件在本地、配置无变化的场景，也就是"原地恢复"。

（2）如果是用于测试演练、原服务器故障、服务器迁移等"异机恢复"的场景，请先在异机上安装同版本的ONES服务（复制config/private.yaml配置文件），正常部署minio、开启备份，然后将旧机器minio整个备份文件夹拷贝到新服务器minio指定目录下，然后参考本文和数据恢复&Docker迁移补充说明操作。如有疑问，请联系ONES工程师。

（3）由于审计日志备份机制变化， 6.1.93版本及以下请参考“2.1 审计日志之Kafka备份”； 6.1.94版本及以上，请参考“2.2 审计日志之ClickHouse备份”。

（4）可在宿主机上用root用户执行kubectl命令；必须先执行ones-ai-k8s.sh命令进入容器，才能执行make 操作，才能查看config/private.yaml、default/config.yaml等配置文件。

2 审计日志备份

2.1 审计日志之Kafka备份（6.1.93版本及以下）

2.1.1 备份kafka

# 宿主机上root用户执行，检查kafka-backup的pod启动
kubectl -n ones get po | grep kafka-backup

# 手动触发备份
ones-ai-k8s.sh
make kafka-base-backup NAMESPACE=ones
# 到minio管理后台确认存储桶kafka-xbackup中的备份文件
# 自动定时备份，参考如下默认配置参数，每天7点/19点自动执行增量备份

2.1.2 默认配置

kafkaBackupImage: "img.ones.pro/release/kafka-backup:release-v0.0.9"
kafkaBackupReplicas: 1
kafkaBackupIgnoredTopic: "^__consumer_offsets" # kafka需要忽略备份的topic的正则表达式, 多个正则表达式用'|'逗号分开, 例如 "^test$|^__" 忽略 前缀__和名为test的topic
kafkaBackupIncRule: "0 0 7,19 * * *" # kafka 增量备份 定时规则 早上7点和晚上7点
kafkaBackupResotreCompress: "ones-binlog:zstd" # 指定topic的消息压缩类型, 默认使用Lz4，可选项None,Snappy,Lz4,Zstd,Gzip。 多个topic逗号','隔开
kafkaBackupProduceBatchSize: "1MB" # 还原数据时，批生产阈值(注意不能大于kafka批处理阈值)
kafkaBackupCPULimit: "2000m"
kafkaBackupMemoryLimit: "1024Mi"

2.1.3 kafka数据恢复

# 1. 清理旧数据

# 1.1. 宿主机上root用户执行，停业务，清理kafka数据
kubectl scale deploy -n ones audit-log-sync-deployment binlog-event-sync-deployment ones-canal-deployment ones-bi-sync-canal-deployment --replicas=0
# 确认服务已停止
kubectl get pod -n ones|grep -E 'bin|audit|canal'

# 1.2. 停中间件
kubectl scale sts -n ones zookeeper-ha kafka-ha --replicas=0
# 确认服务已停止
kubectl get pod -n ones|grep -E 'zookeeper|kafka-ha'

# 1.3 清理localstorage（仅限于单机版）
onesNameSpace=ones
dat=$(date +'%Y%m%d-%H%M%S')
# localstorageStorageBasePath=/data/ones/ones-local-storage
# 确认宿主机存储的路径
path=$(ones-ai-k8s.sh make get_value KEY=localstorageStorageBasePath | grep -e "^/")
localstorageStorageBasePath=$(echo -n "$path" | tr -d '\n\r')
echo "localstorageStorageBasePath is : $localstorageStorageBasePath"

ls -l ${localstorageStorageBasePath}/kafka/${onesNameSpace}/*/ 
# ❗️注意请谨慎删除数据，这里使用mv代替删除
mkdir -p /tmp/data-kafka-ha_$dat  /tmp/data-zookeeper-ha_$dat/
mv ${localstorageStorageBasePath}/kafka/${onesNameSpace}/data-kafka-ha-0/*  /tmp/data-kafka-ha_$dat/
mv ${localstorageStorageBasePath}/kafka/${onesNameSpace}/data-zookeeper-ha-0/*  /tmp/data-zookeeper-ha_$dat/
# 确认删除
ls -l ${localstorageStorageBasePath}/kafka/${onesNameSpace}/*/ 

# 2. 启动服务
ones-ai-k8s.sh
make setup-ones
# 2.1 启动空数据的中间件
kubectl scale sts -n ones zookeeper-ha kafka-ha --replicas=1  # 副本数根据集群规模调整
# 确认中间件启动
kubectl get pod -n ones|grep -E 'zookeeper-ha|kafka-ha'
# 2.2 起业务
kubectl scale deploy -n ones binlog-event-sync-deployment audit-log-sync-deployment ones-canal-deployment ones-bi-sync-canal-deployment --replicas=1
# 确认业务已启动
kubectl get pod -n ones|grep -E 'bin|audit|canal'

# 3. 恢复数据
make kafka-restore NAMESPACE=ones DATA_PATH=20230807-111039.264

2.2 审计日志之ClickHouse备份（6.1.94版本及以上）

2.2.1 备份ClickHouse

ones-ai-k8s.sh
make backup-clickhouse-now

# 如果执行报错The specified bucket does not exist. 则进入clickhouse-backup-deployment-***容器内，先执行如下命令
# rclone  mkdir s3:clickhouse-backup --config=/etc/clickhouse-backup/rclone.conf 
# 如果报错上述命令报错 didn't find section in config file，则执行下述命令
# rclone  mkdir s3-dest:clickhouse-backup --config=/etc/clickhouse-backup/rclone.conf 

如果在日志内容中看到BACKUP_CREATED，则说明备份成功。

2.2.2 默认配置

(1) 备份的时间

每周六23点做一次全量备份，每天分别在13点和20点各做一次增量备份。如果要修改备份时间，可以修改 clickhouseBackupCronSpec、clickhouseFullBackupDay和clickhouseFullBackupTime 的值。

clickhouseBackupCronSpec: "0 0 13,20,23 * * *"
clickhouseFullBackupDay: "6" # 全量备份的日期，0-6，0为周日, 6为周六
clickhouseFullBackupTime: "23" # 全量备份的时间, 0-23

(2) 备份的内容

默认只备份 audit_log 库的 audit_log 表，如果要备份其他库或表，可以修改 clickhouseBackupTables 的值。

clickhouseBackupTables: "audit_log.audit_log" # 需要备份的表，多个表用逗号隔开, 如 "audit_log.audit_log,default.task"

2.2.3 clickhouse数据恢复

(1) 自动恢复

ones-ai-k8s.sh
make clickhouse-restore

默认用最近一次的备份进行恢复，需要恢复的表由 clickhouseBackupTables 配置决定。

指定备份文件

如果自动恢复失败，可以手动指定备份文件进行恢复。

ones-ai-k8s.sh
make clickhouse-restore BACKUP=http://<S3 endpoint>/clickhouse-backup/2025/01/02/incr_2025010206_base_audit_log_audit_log_20250102.zip

(2) 手动恢复

如果 ClickHouse 发生了重启或者想从另外的对象存储进行恢复，可以去对应的存储拿到备份包的地址进行恢复。此方法也适用于服务器环境的迁移，比如 Docker 迁移到 K3s 等。

# 先进入clickhouse-backup-deployment-***容器内 
rclone lsl s3:clickhouse-backup --config=/etc/clickhouse-backup/rclone.conf | sort -k2,2r
 928 2025-01-16 14:00:00.188000000 2025/01/16/incr_2025011614_base_audit_log_audit_log_2025011613.zip
5929 2025-01-16 13:00:00.208000000 2025/01/16/base_audit_log_audit_log_2025011613.zip

# 选择最新的文件作为恢复文件,进入到 ClickHouse 执行如下 SQL
RESTORE TABLE audit_log.audit_log FROM S3('http://endpoint/clickhouse-backup/2024/12/31/incr_2024123108_base_audit_log_audit_log_20241231.zip', '<AccessKey>', '<Secret>');

3 业务数据MySQL备份

3.1 备份操作

对于v3.14.49 以下版本，请参考FAQ处理；对于v3.14.49 及以上版本，可用如下命令：

ones-ai-k8s.sh

# 手动全量备份
make mysql-base-backup NAMESPACE=ones

# 手动增量备份
make mysql-inc-backup NAMESPACE=ones

# 查看日志
make logs-mysql-xbackup NAMESPACE=ones

# 查看最后100条日志
make logs-mysql-xbackup NAMESPACE=ones TAIL=100

# 检查是否有备份进度
make checkprocess-mysql-xbackup-policy NAMESPACE=ones

# mysql过期备份删除
# 默认删除30天之前的备份
make delete-mysql-backup NAMESPACE=ones

# 删除7天之前的备份
make delete-mysql-backup NAMESPACE=ones BEFORE=7d

3.2 默认配置

MySQL备份相关配置，保持默认即可，可按需调整：

# 内置 mysql 备份相关配置
mysqlXbackupEnable: false # 是否启用mysql xbackup备份 true or false
mysqlXbackupToken: "" # 配置msyql-xbackup-service服务端备份接口的token，用于接口鉴权。 make init-config初始化该项
mysqlXbackupServiceNodePort0: "" # 通过nodePort访问mysql第一个实例的xbackup server（仅用于测试，生产环境中，非特殊情况下不建议进行配置 ）, example: 30180 # The default node port range for Kubernetes is 30000 - 32767
mysqlXbackupServiceNodePort1: "" # 通过nodePort访问mysql第二个实例的xbackup server（仅用于测试，生产环境中，非特殊情况下不建议进行配置 ）, example: 30181 # The default node port range for Kubernetes is 30000 - 32767
mysqlXbackupServiceNodePort2: "" # 通过nodePort访问mysql第三个实例的xbackup server（仅用于测试，生产环境中，非特殊情况下不建议进行配置 ）, example: 30182 # The default node port range for Kubernetes is 30000 - 32767
# 默认的内置 mysql 备份由集群外组件机的备份客户端进行备份，如果需要使用集群内部的备份客户端进行备份，则需要配置以下参数
mysqlXbackupInternalEnable: false # 是否启用mysql xbackup集群内备份 true or false，组件机备份与集群内备份只能二选一
mysqlXbackupPolicyImage: "img.ones.pro/release/mysql-xbackup-policy:v3.14.1"
mysqlXbackupNginxBasicAuthPassword: ""  # 对应密钥xbackupNginxBasicAuthPasswordSecret，对应组件机的xbackup_nginx_basic_auth_password
mysqlXbackupServerInstance: "0" # 要连接的mysql集群具体实例, 对应mysql_xbackup_server_instance
mysqlXbackupAlertEnable: "false"  # true or false ，若开启，则使用对应mysql_alert_baseurl地址，否则为空
mysqlXbackupAlertmanagerBasicAuthPassword: ""  # alertmanagerBasicAuthPasswordSecret的密码，对应组件机的alertmanager_basic_auth_password
mysqlXbackupBucket: "mysql-xbackup"  # 备份存放存储桶。 对应 mysql_oss_bucket
mysqlXbackupManual: "false"  # 对应 mysql_manual
mysqlXbackupCron: "true"  # 对应 mysql_cron
mysqlXbackupCronAll: "0 20 3 * * SAT"  # 全量备份crontab。 对应 mysql_cron_all
mysqlXbackupCronInc: "0 30 * * * *"  # 增量备份crontab。对应 mysql_cron_inc
mysqlXbackupCronRuleRecover: "true"  # 对应 mysql_cron_rule_recover
mysqlXbackupLogFile: "/dev/stdout"  # 对应 mysql_log_file
mysqlXbackupLogDetail: "false"  # 对应 mysql_log_detail
mysqlXbackupAllSuccessSendAlert: "true"  # 对应 all_success_send_alert
mysqlXbackupIncSuccessSendAlert: "false"  # 对应 inc_success_send_alert
mysqlXbackupAllFailedSendAlert: "true"  # 对应 all_failed_send_alert
mysqlXbackupIncFailedSendAlert: "true"  # 对应 inc_failed_send_alert
mysqlXbackupDataVolumeSize: 1Gi
mysqlXbackupCPULimit: "2000m"
mysqlXbackupMemoryLimit: "1024Mi"

3.3 MySQL数据恢复

3.3.1 关闭备份客户端

编辑 config/private.yaml ，注释掉如下配置：

ones-ai-k8s.sh
vi config/private.yaml
# mysqlXbackupInternalEnable: true

# 下发配置
ones-ai-k8s.sh
make setup-ones
kubectl -n ones get po | grep mysql-xbackup
# 检查备份策略服务是否关闭

3.3.2 停用mysql，清理数据

# 在宿主机上用root用户执行
kubectl -n ones patch mysqlcluster mysql-cluster -p '{"spec":{"replicas":0}}' --type=merge
kubectl -n ones patch statefulset mysql-operator -p '{"spec":{"replicas":0}}' --type=merge

# 删除原有数据（仅限单机版）
# localstorageStorageBasePath=/data/ones/ones-local-storage/
# 确认宿主机存储的路径
path=$(ones-ai-k8s.sh make get_value KEY=localstorageStorageBasePath | grep -e "^/")
localstorageStorageBasePath=$(echo -n "$path" | tr -d '\n\r')
echo "localstorageStorageBasePath is : $localstorageStorageBasePath"

onesNameSpace=ones
dat=$(date +'%Y%m%d-%H%M%S')
# 删除现有数据
# ❗️注意请谨慎删除数据，这里使用mv代替删除
mkdir -p /tmp/data-mysql-cluster-mysql_$dat  /tmp/data-mysql-operator_$dat/
mv ${localstorageStorageBasePath}/mysql/${onesNameSpace}/data-mysql-cluster-mysql-0/*  /tmp/data-mysql-cluster-mysql_$dat/
mv ${localstorageStorageBasePath}/mysql/${onesNameSpace}/data-mysql-operator-0/*  /tmp/data-mysql-operator_$dat/
ll ${localstorageStorageBasePath}/mysql/${onesNameSpace}/data-mysql-cluster-mysql-*/ ${localstorageStorageBasePath}/mysql/${onesNameSpace}/data-mysql-operator-*/

3.3.2 启用恢复配置

(1) 修改配置文件

ones-ai-k8s.sh
vim config/private.yaml

mysqlXbackupRestoreEnable: "true"
# 这里填写要恢复的时间点对应的mysql备份文件
mysqlXbackupRestoreInitBucketUrl: "s3://mysql-xbackup/base-20230804-173510.gz"
# 这里的AccessKeyId，AccessKey，Endpoint的原文分别是使用上文部署minio的账户名，密码，访问地址
# 这里要填写 AWS_ACCESS_KEY_ID base64后的结果， 比如 `echo -n "AWS_ACCESS_KEY_ID" | base64`
mysqlXbackupAwsAccessKeyId: "bWluaW91c2Vy"
# 这里要填写 AWS_SECRET_ACCESS_KEY base64后的结果， 比如 `echo -n "AWS_SECRET_ACCESS_KEY" | base64`
mysqlXbackupAwsSecretAccessKey: "UUpuZHNlODk="   
# 这里要填写 S3_ENDPOINT base64后的结果， 比如 `echo -n "S3_ENDPOINT" | base64` 其中S3_ENDPOINT格式为http://{{ minioClusterIP }}:{{ minioServicePortExport }}
mysqlXbackupS3Endpoint: "aHR0cDovL21pbmlvLTAubWluaW8tc2VydmljZS5vbmVzLWJhY2t1cDo5MDAw"           

（2）下发配置并开启恢复

make setup-ones
make setup-ones-built-in-mysql

# 等待mysql-operator和mysql-cluster启动,此时会加载数据进行恢复，耗时较长
# 检查数据库是否正常,mysql-cluster-mysql-0的pod状态为6/6或者7/7表示恢复正常
kubectl get pod -A|grep -i mysql

3.3.2 配置还原

恢复过一次之后，上述恢复配置必须全部注释，然后手动再做一次全量备份，以保证后续的增量备份成功。

4 文件备份

4.1 备份文件

备份文件数据，包括业务附件、wiki页面、海报/图片等。

ones-ai-k8s.sh
make mc-backup-tools NAMESPACE=ones 

4.2 文件数据恢复

从minio将备份数据同步到本地

ones-ai-k8s.sh
make mc-restore NAMESPACE=ones 

5 补充说明

按照上述操作完成数据恢复后，参考数据恢复&Docker迁移补充说明检查。

6 FAQ

6.1 Mysql备份异常处理

如果出现如下错误：

bash-5.0# make logs-mysql-xbackup NAMESPACE=ones
error: error executing jsonpath "{.items[0].metadata.name}": Error executing template: array index out of bounds: index 0, length 0. Printing more information for debugging the template:
...

请检查 MySQL 备份组件已启动，其状态为 Running:

# 检查pod启动
kubectl -n ones get po | grep mysql-xback

6.2 Mysql旧版本兼容

若ONES版本低于 ones: v3.14.49，如上命令出现错误：

bash-5.0# make logs-mysql-xbackup NAMESPACE=ones
/bin/sh: ansible: not found

bash-5.0# make mysql-inc-backup NAMESPACE=ones
/bin/sh: ansible-playbook: not found

可考虑使用如下临时命令：

bkpod=$(kubectl -n ones get po -l app=mysql-xbackup -o jsonpath='{.items[0].metadata.name}')  # 这里取pod名，直接复制即可
# 查看日志，由于日志输出到/dev/stdout，手动执行的日志仅会输出到执行的终端上
kubectl -n ones logs -f ${bkpod}

# 注意：目前手动执行备份会导致自动定期备份任务失效，此问题有待后续修复，临时处理方案见 https://opsdoc.ones.cn/docs/faq/k3s/mysql-backup-cron-failed
# 手动全量备份 命令前台运行，终端输出日志，有需要可以改为后台执行
kubectl -n ones exec -it ${bkpod} -- mysql-xbackup-policy -m --detail  --instance=0

# 手动增量备份
kubectl -n ones exec -it ${bkpod} -- mysql-xbackup-policy -m -i --detail  --instance=0

# 检查是否有备份在执行
kubectl -n ones exec -it ${bkpod} -- mysql-xbackup-policy checkProcess

# mysql过期备份删除
BEFORE=30d
kubectl -n ones exec -it ${bkpod} -- mysql-xbackup-policy clean --min-age=${BEFORE} --detail

1 前置说明​

2 审计日志备份​

2.1 审计日志之Kafka备份（6.1.93版本及以下）​

2.1.1 备份kafka​

2.1.2 默认配置​

2.1.3 kafka数据恢复​

2.2 审计日志之ClickHouse备份（6.1.94版本及以上）​

2.2.1 备份ClickHouse​

2.2.2 默认配置​

(1) 备份的时间​

(2) 备份的内容​

2.2.3 clickhouse数据恢复​

(1) 自动恢复​

指定备份文件​

(2) 手动恢复​

3 业务数据MySQL备份​

3.1 备份操作​

3.2 默认配置​

3.3 MySQL数据恢复​

3.3.1 关闭备份客户端​

3.3.2 停用mysql，清理数据​

3.3.2 启用恢复配置​

3.3.2 配置还原​

4 文件备份​

4.1 备份文件​

4.2 文件数据恢复​

5 补充说明​

6 FAQ​

6.1 Mysql备份异常处理​

6.2 Mysql旧版本兼容​