配置一个 多分片、多副本的 ClickHouse 分布式集群 demo

配置一个 多分片、多副本的 ClickHouse 分布式集群 是构建高可用、可扩展 OLAP 系统的核心技能。本篇将带你从零开始，一步步配置一个生产级的 ClickHouse 集群，包含 2 个分片（Shard），每个分片有 2 个副本（Replica），共 4 个节点。

---

🏗️ 一、目标架构

我们构建如下集群：

Cluster: prod_cluster
│
├── Shard 1
│   ├── Replica 1 → node1 (192.168.1.11)
│   └── Replica 2 → node2 (192.168.1.12)
│
├── Shard 2
│   ├── Replica 1 → node3 (192.168.1.13)
│   └── Replica 2 → node4 (192.168.1.14)

• 使用 ReplicatedMergeTree 实现副本复制
• 使用 Distributed 表实现跨分片查询
• 使用 ClickHouse Keeper（推荐）或 ZooKeeper 协调复制

✅ 本文使用 ClickHouse Keeper（v21+ 内置），更简单易维护。

---

🧰 二、环境准备

项目	要求
节点数量	4 台服务器（node1 ~ node4）
操作系统	Ubuntu 20.04 / CentOS 7+
ClickHouse 版本	≥ 21.8（支持 ClickHouse Keeper）
网络	所有节点互通，开放必要端口
用户权限	具备 sudo 权限

---

🔌 三、网络与端口说明

端口	用途
9000	TCP 客户端连接（clickhouse-client）
8123	HTTP 接口
9444	ClickHouse Keeper Raft 通信
9181	ClickHouse Keeper 客户端端口

---

🛠️ 四、步骤 1：安装 ClickHouse（所有节点）

以 Ubuntu 为例：

# 添加仓库
sudo apt-get install -y apt-transport-https ca-certificates dirmngr
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754
echo "deb https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update

# 安装服务
sudo apt-get install -y clickhouse-server clickhouse-client

✅ 所有 4 个节点都执行此操作。

---

🧩 五、步骤 2：配置 ClickHouse Keeper（推荐替代 ZooKeeper）

我们使用 3 节点 ClickHouse Keeper（可在 node1、node2、node3 上运行）。

编辑 config.xml（所有节点）

<!-- /etc/clickhouse-server/config.xml -->

<!-- ClickHouse Keeper 配置 -->
<clickhouse_keeper_server>
    <tcp_port>9181</tcp_port>
    <server_id>1</server_id>  <!-- 每节点不同：node1=1, node2=2, node3=3 -->
    
    <coordination_settings>
        <operation_timeout_ms>10000</operation_timeout_ms>
        <session_timeout_ms>30000</session_timeout_ms>
        <raft_logs_level>warning</raft_logs_level>
    </coordination_settings>

    <raft_configuration>
        <server>
            <id>1</id>
            <hostname>node1</hostname>
            <port>9444</port>
        </server>
        <server>
            <id>2</id>
            <hostname>node2</hostname>
            <port>9444</port>
        </server>
        <server>
            <id>3</id>
            <hostname>node3</hostname>
            <port>9444</port>
        </server>
    </raft_configuration>
</clickhouse_keeper_server>

✅ 注意：

• server_id 每台 Keeper 节点必须唯一
• raft_configuration 列出所有 Keeper 节点

---

🌐 六、步骤 3：配置集群定义（所有节点）

在 config.xml 中添加集群配置：

<remote_servers>
    <prod_cluster>
        <!-- 分片 1 -->
        <shard>
            <internal_replication>true</internal_replication>
            <replica>
                <host>node1</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node2</host>
                <port>9000</port>
            </replica>
        </shard>

        <!-- 分片 2 -->
        <shard>
            <internal_replication>true</internal_replication>
            <replica>
                <host>node3</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node4</host>
                <port>9000</port>
            </replica>
        </shard>
    </prod_cluster>
</remote_servers>

✅ internal_replication=true：写入时自动选择一个副本写入，避免重复写。

---

🔁 七、步骤 4：启动服务

在所有节点重启 ClickHouse

sudo service clickhouse-server restart

ClickHouse 会自动启动 Keeper（如果配置了 clickhouse_keeper_server）

检查 Keeper 是否运行

echo "status" | nc node1 9181

输出应包含 leader 或 follower。

---

📦 八、步骤 5：创建复制表（在任意节点执行）

-- 创建本地复制表（每个分片上的副本都会创建）
CREATE TABLE user_log_local ON CLUSTER 'prod_cluster'
(
    user_id UInt32,
    event_date Date,
    action String,
    duration UInt32,
    city String
) ENGINE = ReplicatedMergeTree(
    '/clickhouse/tables/{shard}/user_log_local',  -- ZooKeeper/Keeper 路径
    '{replica}'                                  -- 副本标识（自动替换）
)
PARTITION BY toYYYYMM(event_date)
ORDER BY (event_date, user_id);

✅ ON CLUSTER 'prod_cluster' 会自动在所有节点执行建表语句。

---

🚀 九、步骤 6：创建分布式表（用于查询）

-- 创建分布式表，用于跨分片查询
CREATE TABLE user_log_all ON CLUSTER 'prod_cluster'
(
    user_id UInt32,
    event_date Date,
    action String,
    duration UInt32,
    city String
)
ENGINE = Distributed(
    'prod_cluster',           -- 集群名
    'default',                -- 数据库
    'user_log_local',         -- 本地表名
    city                     -- 分片键（按 city 哈希分片）
);

✅ 分片键建议：

• rand()：随机分片
• intHash32(user_id)：按用户分片
• city：按城市分片（需字符串哈希）

---

🧪 十、步骤 7：测试写入与查询

写入数据（可写任意节点）

clickhouse-client --host node1 --query="
INSERT INTO user_log_all VALUES
(1001, '2024-04-01', 'login', 30, 'Beijing'),
(1002, '2024-04-01', 'click', 15, 'Shanghai'),
(1003, '2024-04-02', 'view', 45, 'Beijing');
"

查询数据（自动聚合所有分片）

SELECT 
    event_date,
    city,
    COUNT(*) AS cnt,
    AVG(duration) AS avg_duration
FROM user_log_all
GROUP BY event_date, city
ORDER BY event_date, city;

---

📊 十一、验证复制与集群状态

1. 查看集群配置

SELECT * FROM system.clusters WHERE cluster = 'prod_cluster';

2. 查看副本状态（检查复制是否正常）

SELECT 
    table,
    is_leader,
    is_readonly,
    queue_size,
    absolute_delay,
    total_replicas,
    active_replicas
FROM system.replicas 
WHERE table = 'user_log_local';

✅ 健康状态：

• queue_size = 0
• absolute_delay ≈ 0
• active_replicas = total_replicas

---

⚠️ 十二、常见问题与排查

问题	排查方法
表未在所有节点创建	检查 ON CLUSTER 是否报错，手动在各节点执行
复制延迟高	检查 queue_size, absolute_delay，查看 Keeper 状态
写入失败	检查 Keeper 是否可用，网络是否通
Distributed 表无法查询	检查 user_log_local 是否存在，分片配置是否正确
Keeper 启动失败	检查 server_id 唯一性，端口是否被占用

---

✅ 十三、最佳实践建议

项目	推荐做法
Keeper 节点数	3 或 5（奇数，避免脑裂）
副本数	2（平衡成本与可用性）
分片键	使用 intHash32(user_id) 或 city
写入	写 Distributed 表（user_log_all）
查询	优先查 Distributed 表
备份	使用 clickhouse-backup 工具备份一个副本即可
监控	集成 Prometheus + Grafana 监控 system.replicas

---

🎯 十四、总结：多分片多副本集群的核心价值

能力	实现方式
水平扩展	多分片支持 PB 级数据
高可用	每个分片有 2 副本，防止单点故障
自动复制	ReplicatedMergeTree + Keeper
透明查询	Distributed 表引擎
负载均衡	写入和查询可分发到多个节点

🎯 这个集群架构是 ClickHouse 生产环境的“标准模板”，适用于日志分析、用户行为、实时报表等场景。