ClickHouse 分片集群备份一致性分析文档

1. 问题背景

在 ClickHouse 分片集群环境中，如何保证所有分片备份时的数据一致性是一个关键问题。本文档分析了官方提供的备份方案及其局限性，并提供了环境中的实际配置情况。

2. 环境信息

2.1 集群配置

项目	值
集群名称	ck-5330623f
分片数量	2 (shardsCount: 2)
副本数量	2 (replicasCount: 2)
存储类型	csi-localpv (hostPath)
存储路径	/opt/qfusion/localpv/
ClickHouse 版本	24.8.7.41

2.2 Pod 列表

ck-5330623f-replica0-0-0    # 分片0，副本0
ck-5330623f-replica0-1-0    # 分片0，副本1
ck-5330623f-replica1-0-0    # 分片1，副本0
ck-5330623f-replica1-1-0    # 分片1，副本1 (Pending)
ck-5330623f-zk-0/1/2-0      # ZooKeeper 节点

2.3 备份配置

# chi-ck-5330623f-backup-config
general:
  remote_storage: none
  backups_to_keep_local: 0
  backups_to_keep_remote: 0

clickhouse:
  username: rdsadmin
  host: localhost
  port: 9000
  sync_replicated_tables: true

# 关键配置
restore_schema_on_cluster: ""  # 未启用集群级别恢复

3. 官方备份方案分析

3.1 Altinity clickhouse-backup 工具

官方文档链接:

• Examples.md - Sharded cluster backup

推荐备份方式:

# 备份 - 只在每个分片的第一个副本上运行
shard_number=$(clickhouse-client -q "SELECT getMacro('shard')")
clickhouse-backup create_remote shard${shard_number}-backup

推荐恢复方式:

# 步骤1: 在所有副本上恢复 schema
shard_number=$(clickhouse-client -q "SELECT getMacro('shard')")
clickhouse-backup restore_remote --rm --schema shard${shard_number}-backup

# 步骤2: 只在每个分片的第一个副本上恢复数据
clickhouse-backup restore_remote --rm shard${shard_number}-backup

3.2 工作原理 - FREEZE 机制

clickhouse-backup 工具使用 ClickHouse 的 ALTER TABLE ... FREEZE 命令：

ALTER TABLE ... FREEZE PARTITION ...

实现方式:

• 使用 hardlinks 将数据复制到 /var/lib/clickhouse/shadow/ 目录
• 几乎不消耗额外磁盘空间（因为是硬链接）
• 不阻塞表的正常操作
• 本质上是文件级别的"快照"，不是存储卷快照

3.3 ClickHouse 内置 BACKUP/RESTORE 命令

官方文档链接:

• Backup and Restore in ClickHouse

-- 语法
BACKUP|RESTORE [ASYNC]
TABLE|DATABASE|ALL
[ON CLUSTER 'cluster_name']
TO|FROM Disk|S3|File(...)
[SETTINGS ...]

4. 分片备份一致性问题

4.1 核心问题

问题陈述: 官方没有提供原子性跨分片备份的方案，无法保证每个分片同时备份以保持数据一致性。

GitHub Issue 链接:

• Issue #326 - Best practice to backup and restore sharding clickhouse

用户提出的核心问题：

“I am concern about the synchronization and atomicity of the operation. For example, does it matter that the backup time of different shard are slightly different?”

该问题至今没有官方明确解答。

4.2 为什么无法保证跨分片一致性？

原因	说明
分片独立备份	必须分别对每个分片执行备份，无法做到原子性
时间差存在	各分片备份完成时间不同，存在时间窗口
无分布式事务	ClickHouse 分片间没有跨分片事务保证
Distributed 表是视图	Distributed 表不存储实际数据，只是查询路由

4.3 恢复时的额外问题

GitHub Issue 链接:

• Issue #299 - How to backup and restore correctly the cluster with distributed tables and shards

报告的问题：

• 从分片1恢复数据后，数据被意外复制到分片2
• 最终导致两个分片包含相同数据（完全不符合预期）

5. 存储快照方案分析

5.1 官方文档说明

链接:

• Alternative backup methods

官方关于文件系统快照的描述：

“Some local filesystems provide snapshot functionality (for example, ZFS), but they might not be the best choice for serving live queries. A possible solution is to create additional replicas with this kind of filesystem and exclude them from the Distributed tables that are used for SELECT queries.”

5.2 存储快照的局限性

即使使用存储快照（ZFS/LVM/云盘快照），仍然无法解决跨分片一致性问题：

问题	说明
分片独立快照	必须分别对每个分片的存储做快照
时间差	各分片快照时间不同，数据仍存在时间窗口的不一致
无原子性	存储层无法感知应用层的分片逻辑

5.3 当前环境的存储限制

存储类型: csi-localpv
底层类型: hostPath (普通本地目录)
文件系统: 不支持快照 (ext4/xfs，非 ZFS/LVM)

结论: 当前环境无法使用存储快照方案。

6. 方案对比

备份方式	跨分片一致性	优点	缺点
clickhouse-backup (FREEZE)	❌ 无保证	硬链接节省空间、不阻塞操作	逐分片备份、有时间差
存储快照 (ZFS/LVM)	❌ 无保证	快速、存储层原生支持	需要特定文件系统、仍有时间差
BACKUP ON CLUSTER	❌ 无保证	原生 SQL 命令、易用	官方未保证跨分片原子性
暂停写入 + 备份	✅ 有保证	可确保一致性	影响业务可用性

7. 官方推荐的快照备份方案（如果使用）

如果环境支持 ZFS 等快照文件系统，官方推荐的架构：

┌─────────────────────────────────────────────────────────────┐
│                    应用查询                                  │
│                       │                                      │
│                       ▼                                      │
│              Distributed Table                             │
│                  /          \                                │
│                 /            \                               │
│         Shard 1本地表      Shard 2本地表                      │
│         (正常副本)        (正常副本)                          │
│                 \            /                               │
│                  \          /                                │
│         专用备份副本 ← 排除在 Distributed 查询之外           │
│         (使用 ZFS/LVM)                                      │
│         │                                                    │
│         └──► 做存储快照备份                                  │
└─────────────────────────────────────────────────────────────┘

实施步骤：

1. 为每个分片创建专用的备份副本
2. 使用 ZFS/LVM 等支持快照的文件系统
3. 将这些副本从 Distributed 表中排除（不影响正常查询）
4. 对专用副本进行快照

8. 结论

1. 官方没有提供原子性跨分片备份方案 - Altinity clickhouse-backup 工具需要逐个分片进行备份

2. 无法保证所有分片同时备份 - 从官方示例可以看到，需要为每个分片单独执行备份

3. 数据一致性无法保证 - 分片间没有分布式事务保证，即使能同时触发备份，各分片执行时间也会有差异

4. 存储快照无法解决根本问题 - 存储快照只是改变了备份的实现方式，但本质上仍需要逐个分片操作

5. 可能的解决方案（需自行实现）:

   • 应用层暂停写入 → 备份所有分片 → 恢复写入
   • 使用专用备份副本 + 文件系统快照
   • 只备份本地表，恢复时重新创建分布式表
   • 使用 ReplicatedMergeTree 引擎 + 利用 ZooKeeper 的一致性保证

9. 参考链接

类型	链接
官方文档	ClickHouse Backup and Restore
官方文档	Alternative backup methods
GitHub Issue	#326 - Shard backup atomicity concerns
GitHub Issue	#299 - Shard restore problems
官方示例	Examples.md - Sharded cluster backup
技术博客	Introduction to ClickHouse Backups - Altinity

---

文档生成时间: 2026-01-08
环境: 210集群 (ck-5330623f)