引言：理解ClickHouse集群的核心价值
ClickHouse作为一款高性能的列式OLAP数据库，在处理海量数据分析场景中表现出色。然而，单节点的ClickHouse无法满足生产环境对高可用性、横向扩展和数据容灾的需求。通过配置分片（Sharding）和副本（Replication）集群，我们可以构建一个既能水平扩展写入/查询能力，又具备自动故障转移能力的分布式系统。
本文将从零开始，详细讲解如何搭建一个高可用的ClickHouse集群，并分享在实际操作中常见的问题及其解决方案。
第一部分：ClickHouse集群架构基础概念
在动手配置之前，必须先理解ClickHouse集群的两个核心概念：
分片（Sharding）
和
副本（Replication）
。
1.1 分片（Sharding）
分片是指将数据水平切分到不同的节点上。
目的
：解决单节点存储瓶颈和写入/查询性能瓶颈。
原理
：数据根据分片键（通常是主键或随机数）通过哈希取模等方式分配到不同的分片中。每个分片存储数据的一部分。
1.2 副本（Replication）
副本是指在同一个分片内，将数据复制到多个节点上。
目的
：解决单点故障问题，提供高可用性（HA）。
原理
：利用ZooKeeper（或ClickHouse内置的ClickHouse Keeper）进行协调，保证副本间的数据一致性。当一个节点宕机时，查询可以自动路由到存活的副本节点。
1.3 典型架构拓扑
一个标准的高可用集群通常长这样：
2个分片（Shard）
：用于数据横向扩展。
每个分片2个副本（Replica）
：用于高可用。
3台ZooKeeper节点
：用于元数据协调（建议奇数台）。
第二部分：环境准备与ZooKeeper配置
ClickHouse的副本复制依赖于ZooKeeper（或ClickHouse Keeper）。虽然ClickHouse 22.8+版本推出了内置的ClickHouse Keeper（无需外部依赖），但为了通用性和生产环境的稳定性，我们先讲解标准的ZooKeeper配置。
2.1 机器规划
假设有4台服务器（IP仅为示例）：
192.168.1.101
：Node1 (Shard1-Replica1)
192.168.1.102
：Node2 (Shard1-Replica2)
192.168.1.103
：Node3 (Shard2-Replica1)
192.168.1.104
：Node4 (Shard2-Replica2)
注：生产环境建议ZooKeeper独立部署，不要与ClickHouse混部，这里为了演示方便，假设我们在Node1, Node2, Node3上部署ZK。
2.2 ZooKeeper 安装与配置
在三台机器上下载并解压ZooKeeper，配置
conf/zoo.cfg
：
# zoo.cfg
tickTime=2000
initLimit=10
syncLimit=5
dataDir=/var/lib/zookeeper
clientPort=2181
server.1=192.168.1.101:2888:3888
server.2=192.168.1.102:2888:3888
server.3=192.168.1.103:2888:3888
在每台机器的
dataDir
目录下创建
myid
文件：
Node1:
echo “1” > /var/lib/zookeeper/myid
Node2:
echo “2” > /var/lib/zookeeper/myid
Node3:
echo “3” > /var/lib/zookeeper/myid
启动ZooKeeper服务。至此，协调服务准备完毕。
第三部分：ClickHouse 集群配置详解
这是最核心的部分。我们需要配置
/etc/clickhouse-server/config.xml
和
/etc/clickhouse-server/users.xml
，以及最重要的集群定义文件
/etc/clickhouse-server/config.d/metrika.xml
（推荐分离配置）。
3.1 配置文件结构建议
为了避免主配置文件
config.xml
过于混乱，ClickHouse 支持将配置放入
config.d/
目录中。
3.2 定义集群拓扑 (
metrika.xml
)
在
/etc/clickhouse-server/config.d/
下创建
metrika.xml
（文件名可自定义）。
这个文件定义了集群的逻辑结构。
配置要点解析：
internal_replication
: 设为
true
意味着当你向该集群写入数据时，ClickHouse 分发器只会将数据写入该分片的一个副本，然后由副本之间的复制机制同步到另一个副本。这是标准做法，避免了数据重复写入导致膨胀。
macros
: 这是最容易出错的地方。ZooKeeper 通过
/clickhouse/tables/{shard}/{table_name}/replicas/{replica_path}
来管理元数据。
macros
中的
shard
和
replica
变量会被替换到路径中。
每台服务器的
replica
值必须唯一
。
3.3 修改主配置文件
config.xml
确保
config.xml
能够加载我们刚才的配置，并设置监听地址。
3.4 配置用户权限 (
users.xml
)
如果需要通过网络访问，确保用户配置正确。
第四部分：启动集群与验证
4.1 启动服务
在所有节点上启动 ClickHouse Server：
sudo systemctl start clickhouse-server
sudo systemctl status clickhouse-server
4.2 验证集群状态
在任意节点执行以下 SQL，查看集群拓扑是否正确识别：
SELECT * FROM system.clusters;
预期输出：
你应该能看到名为
my_cluster
的集群，包含2个分片，每个分片2个副本。如果这里没有数据，检查
metrika.xml
语法和
include_from
路径。
4.3 创建分布式表与本地表
ClickHouse 的分布式查询依赖于两张表：
本地表 (Local Table)
：实际存储数据的表，每个节点都有。
分布式表 (Distributed Table)
：逻辑表，不存储数据，只负责将查询路由到本地表。
步骤：
在所有节点上执行（创建本地表）
：
本地表引擎必须相同（例如
ReplicatedMergeTree
），表名建议相同。
CREATE TABLE default.local_table_local ON CLUSTER my_cluster
(
`id` UInt32,
`name` String,
`timestamp` DateTime
)
ENGINE = ReplicatedMergeTree(‘/clickhouse/tables/{shard}/local_table_local’, ‘{replica}’)
PARTITION BY toYYYYMM(timestamp)
ORDER BY id;
注意：这里显式指定了ZK路径，也可以省略，ClickHouse会自动使用
macros
填充。
在任意节点执行（创建分布式表）
：
分布式表只需要创建一次，通常放在
default
库。
CREATE TABLE default.distributed_table_local ON CLUSTER my_cluster
(
`id` UInt32,
`name` String,
`timestamp` DateTime
)
ENGINE = Distributed(my_cluster, default, local_table_local, id);
参数解释：
Distributed(集群名, 库名, 本地表名, 分片键)
。
4.4 数据写入与查询测试
写入
：向分布式表插入数据。
INSERT INTO default.distributed_table_local VALUES (1, ‘test1’, now());
数据会根据
id
进行哈希分发到不同的分片，并在分片内复制到副本。
查询
：
查询分布式表
（全集群聚合）：
SELECT count() FROM default.distributed_table_local;
查询本地表
（单节点聚合）：
SELECT count() FROM default.local_table_local; — 在特定节点执行
第五部分：高可用性测试与故障转移
高可用不是配置出来的，是验证出来的。
5.1 模拟节点宕机
假设
192.168.1.101
(Shard1-Replica1) 宕机。
sudo systemctl stop clickhouse-server
5.2 验证查询可用性
在客户端连接
192.168.1.102
(Shard1-Replica2) 或其他存活节点，查询分布式表：
SELECT * FROM default.distributed_table_local WHERE id = 1;
结果
：查询应正常返回数据，因为
ReplicatedMergeTree
会自动切换到存活的副本。
5.3 验证写入可用性
向分布式表插入数据：
INSERT INTO default.distributed_table_local VALUES (2, ‘test2’, now());
结果
：写入成功。虽然
192.168.1.101
宕机，但分布式表引擎会自动选择存活的副本进行写入（前提是
internal_replication
配置正确）。
第六部分：常见问题避坑指南 (Troubleshooting)
在配置和维护ClickHouse集群时，以下问题是最高频出现的：
6.1 ZooKeeper 连接失败
现象
：
system.clusters
为空，或者写入报错
Connection loss
。
原因
：
config.d/metrika.xml
中的
配置错误，或者防火墙拦截了 2181 端口。
解决
：
检查
config.xml
是否正确引入了
metrika.xml
。
在ClickHouse服务器上执行
telnet
。
查看日志
/var/log/clickhouse-server/clickhouse-server.log
。
6.2 宏 (Macro) 配置错误
现象
：写入报错
No node
或
Table already exists
（在ZK层面），或者副本状态显示
future
。
原因
：
macros
中的
replica
值在同一个分片内重复了，或者
shard
值写错。
解决
：
检查每台机器的
macros
配置。
查看
system.replicas
表：
SELECT * FROM system.replicas WHERE table = ‘local_table_local’
。如果
is_active
为 0，通常与 ZK 通信或宏配置有关。
6.3 分布式表查询慢
现象
：查询分布式表比查询单表慢很多。
原因
：查询被发送到了所有分片，且在远程节点进行了大量的数据传输（
SELECT *
且数据量大）。
解决
：
下推计算
：尽量使用
WHERE
条件过滤数据，ClickHouse 会自动将过滤条件下推到分片。
使用 GLOBAL IN
：如果需要关联字典或大表，使用
GLOBAL IN
避免数据分发风暴。
直接查询本地表
：如果业务允许，直接连接特定分片查询。
6.4 副本不同步 (Replication Lag)
现象
：两个副本的数据不一致。
原因
：ZK 压力大、网络抖动、或者手动执行了
DETACH TABLE
后未恢复。
解决
：
检查
system.replicas
表中的
log_max_index
和
log_pointer
。
尝试
SYSTEM RESTORE REPLICA table_name
（如果副本状态损坏）。
查看 ZK 日志，看是否有积压。
6.5 磁盘空间不足导致只读
现象
：ClickHouse 变为只读模式，无法写入。
原因
：磁盘剩余空间低于配置的阈值（默认 1GB 或 10%）。
解决
：
清理旧数据：
DROP TABLE
或
ALTER TABLE … DELETE
（注意这会产生新分区，需要合并）。
修改配置
storage_configuration
中的
move_factor
，但这只是延缓问题，扩容才是正解。
第七部分：总结
搭建ClickHouse高可用集群是一个系统工程，涉及ZooKeeper、网络、配置文件等多个环节。核心在于理解
Sharding
（扩展性）和
Replication
（高可用）的配合。
最佳实践建议：
配置分离
：将集群配置放在
config.d/
目录，便于版本管理和Ansible自动化部署。
监控ZooKeeper
：ZooKeeper是集群的心脏，必须重点监控其延迟和连接数。
定期巡检
：查询
system.replicas
和
system.clusters
，确保所有副本
is_active=1
。
使用 ClickHouse Keeper
：如果版本允许，建议使用内置的 ClickHouse Keeper 替代外部 ZK，减少运维复杂度。
通过以上步骤和避坑指南，你应该能够成功搭建一个稳定、高效的ClickHouse分布式集群。