容器内执行clickhouse-backup的完整方案

适用环境

• Docker单机部署ClickHouse
• Webfunny埋点日志库（分表多、分区多、ReplacingMergeTree引擎为主）
• 备份工具：clickhouse-backup（远程SFTP异地备份+本地备份双兜底）
• 配套能力：定时自动备份、备份过期自动清理、企业微信备份结果告警

---

关键避坑点

路径映射问题 宿主机执行备份恢复会因路径不一致失败，所有操作必须在容器内执行

权限问题 备份目录需确保ClickHouse进程（UID=101）有写入权限，否则无法生成shadow数据

非MergeTree引擎表 非MergeTree系列引擎的表无法执行FREEZE冻结分区，不会生成shadow数据目录

UUID冲突 重复恢复同一张表或原表未删除直接恢复会导致UUID冲突（错误code:57）

上传完整性 需确保上传完成后再清理本地备份，避免数据丢失

告警逻辑 需准确判断备份、上传的真实失败情况，而非仅依赖命令返回值

---

容器内部署clickhouse-backup

拷贝二进制文件到容器

docker cp /usr/local/bin/clickhouse-backup 713f7f195b4e:/usr/local/bin/clickhouse-backup
docker exec 713f7f195b4e chmod +x /usr/local/bin/clickhouse-backup

容器内配置文件config.yml

general:
  remote_storage: sftp
  max_file_size: 1099511627776
  backups_to_keep_local: 7
  backups_to_keep_remote: 7
  log_level: debug
clickhouse:
  username: "root"
  password: "123"
  host: "127.0.0.1"
  port: 9000
  disk_mapping: {}
  skip_tables:
    - system.*
sftp:
  address: "8.26.17.71"
  port: 22
  username: "root"
  password: "123"
  path: "/home/data_dev/clickhouse_backup"

关键目录权限修复

docker exec -it 713f7f195b4e bash
mkdir -p /var/lib/clickhouse/backup
chown -R 101:101 /var/lib/clickhouse/backup
chmod 755 /var/lib/clickhouse/backup

---

企业微信告警脚本

/home/tools/wechat_notify.sh

#!/bin/bash
WEBHOOK="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your_key"
send_wechat(){
    local title="$1"
    local content="$2"
    curl -s "$WEBHOOK" \
    -H "Content-Type: application/json" \
    -d "{\"msgtype\":\"text\",\"text\":{\"content\":\"【ClickHouse备份告警】$title\n$content\"}}"
}

测试推送

chmod +x /home/tools/wechat_notify.sh
source /home/tools/wechat_notify.sh
send_wechat "测试通知" "告警通道正常"

---

完整版定时备份脚本

/home/tools/ck_backup.sh

#!/bin/bash
CONTAINER_ID="713f7f195b4e"
BACKUP_NAME="webfunny_cloud_backup_$(date +%Y-%m-%dT%H-%M-%S)"
SERVER_IP=$(hostname -I | awk '{print $1}')
source /home/tools/wechat_notify.sh

# 创建本地备份
docker exec ${CONTAINER_ID} clickhouse-backup create -t "webfunny_cloud_db.*" ${BACKUP_NAME}
if [ $? -ne 0 ]; then
    send_wechat "本地备份失败❌" "服务器IP：${SERVER_IP}\n备份名称：${BACKUP_NAME}"
    exit 1
fi

# 上传备份
docker exec ${CONTAINER_ID} clickhouse-backup upload ${BACKUP_NAME}
if [ $? -ne 0 ]; then
    send_wechat "远端上传失败❌" "服务器IP：${SERVER_IP}\n备份名称：${BACKUP_NAME}"
    exit 1
fi

# 清理过期备份
docker exec ${CONTAINER_ID} clickhouse-backup clean local --keep-backups 7
docker exec ${CONTAINER_ID} clickhouse-backup clean remote --keep-backups 7

send_wechat "备份成功✅" "服务器IP：${SERVER_IP}\n备份名称：${BACKUP_NAME}"

---

恢复流程

查看可用备份

docker exec 713f7f195b4e clickhouse-backup list

从远程下载备份

docker exec 713f7f195b4e clickhouse-backup download backup_name

恢复备份

docker exec 713f7f195b4e clickhouse-backup restore backup_name

强制恢复（覆盖现有表）

docker exec 713f7f195b4e clickhouse-backup restore --rm backup_name

---

定时任务配置

每天凌晨2点执行

0 2 * * * /bin/bash /home/tools/ck_backup.sh >> /var/log/clickhouse-backup.log 2>&1

---

注意事项

1. 备份前确保ClickHouse服务正常运行
2. 恢复操作建议在低峰期进行
3. 定期检查备份文件的完整性和可恢复性
4. 监控备份任务执行情况和存储空间使用情况
5. 对于重要数据，建议定期进行恢复演练

 Webfunny全链路监控埋点平台 是一站式前端监控 + 用户行为埋点 + 大数据分析平台，天然适配点位细查、用户行为回溯、批量导出等场景：

一体化架构：监控 + 埋点同一套 SDK，数据互通无壁垒
私有化部署：数据完全本地化，满足企业合规要求
高吞吐支撑：基于 ClickHouse 构建，亿级日志秒级查询
全端覆盖：H5 / 小程序 / APP / 鸿蒙全覆盖，统一导出口径
可定制强：支持接口扩展、分布式锁、限流降级等企业级能力