ClickHouse 3节点集群部署与分布式表实战

关注

原创最新推荐文章于 2026-09-08 12:46:24 发布 1k 阅读 AI 写同款· GEO 优化 ›

别再手动改配置了！用Docker Compose一键部署ClickHouse三节点集群（附ZooKeeper）本文详细介绍了如何使用Docker Compose一键部署ClickHouse三节点集群，并集成ZooKeeper协调服务。通过精心设计的docker-compose.yml文件和定制化配置，实现高效、可靠的分布式数据库集群部署，大幅简化传统手动配置流程，提升部署效率和可维护性。阅读详情

1. 集群部署前的准备：理解核心概念与架构

如果你之前只用过单机版的ClickHouse，可能会觉得集群部署听起来有点复杂。别担心，我刚开始接触的时候也这么觉得，但实际操作下来，你会发现它的设计其实非常清晰。简单来说，ClickHouse集群就是把多台服务器组合起来，让它们像一个整体一样工作，共同存储和处理海量数据。这样做的好处显而易见：数据容量可以水平扩展，查询性能可以成倍提升，而且通过副本机制还能实现高可用性，即使某台机器挂了，数据也不会丢，服务也不会停。

在我们这个3节点的实战场景里，核心是理解三个关键角色：分片（Shard）、副本（Replica）和协调者（ClickHouse Keeper）。你可以把“分片”想象成切蛋糕，一个巨大的数据集被水平切分成几块，分别存放在不同的服务器上。比如你有100亿条用户日志，可以按用户ID的哈希值分成2份，分别放在节点1和节点2。这样查询时，两个节点可以并行工作，速度自然就快了。

而“副本”就像是给每块蛋糕做的备份。在我们的配置中，每个分片目前只配置了1个副本（也就是数据本身）。如果配置了多个副本，那么同一份数据会在多个节点上存在拷贝，一个节点故障，另一个副本可以立刻顶上，保证了数据的安全性和服务的连续性。

那么，谁来管理这些分片和副本，确保数据同步、分布式查询能正确执行呢？这就是 ClickHouse Keeper 的工作。它相当于集群的“大脑”和“调度中心”，负责元数据存储、节点状态监控、分布式DDL（数据定义语言）的执行协调等。我们这次用3个节点来部署Keeper，是为了满足Raft共识算法的“多数派”要求，确保即使有一个Keeper节点宕机，集群依然能正常选举出Leader，维持协调服务不中断。这种设计在实际生产环境中能有效避免单点故障。

我建议你在动手之前，先在纸上画一下我们这次要搭建的架构图：两个节点（chnode1, chnode2）身兼双职，既作为数据存储和查询的ClickHouse Server，也作为协调集群的Keeper；第三个节点（chnode3）则专职担任Keeper，提供仲裁。这样，两个数据节点构成了一个拥有两个分片、每个分片一个副本的集群。理解了这个蓝图，后面的配置步骤就会清晰很多，你也能明白每个配置项到底在起什么作用。

2. 基础环境搭建与ClickHouse安装

万事开头难，但基础环境打好了，后面就顺了。我强烈建议你严格按照步骤来，尤其是主机名和网络配置，这里踩坑最耽误时间。我们有三台Ubuntu 22.04的服务器，IP分别是192.168.72.51、.52、.53。首先，登录每台机器，用hostnamectl命令给它们起个容易识别的名字，比如chnode1、chnode2、chnode3。这步很重要，因为后续所有配置都会依赖这些主机名，用IP虽然也行，但主机名更清晰，也不容易因IP变更而出错。

接着，编辑每台机器的/etc/hosts文件，把主机名和IP的映射关系写进去。这一步是确保集群内所有机器都能通过主机名互相找到对方。你可以用一个cat命令快速完成：

cat >> /etc/hosts <<EOF
192.168.72.51 chnode1
192.168.72.52 chnode2
192.168.72.53 chnode3
EOF

做完之后，记得在三台机器上互相ping一下主机名，比如在chnode1上ping chnode2，确保网络是通的。这些基础工作看似琐碎，但却是集群能正常通信的基石，我见过不少部署失败都是因为这里没配好。

接下来是安装ClickHouse。这里有个小细节需要注意：chnode1和chnode2需要安装完整的ClickHouse Server（包含Keeper功能），而chnode3只安装ClickHouse Keeper。这是因为我们想让chnode3作为一个纯净的协调节点，不承担数据存储的任务，这在生产环境中是推荐的做法，可以让协调服务更稳定。

在chnode1和chnode2上，执行下面的命令来添加官方仓库并安装：

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

安装过程中，终端会提示你为默认用户default设置密码。这个密码一定要记好，后面连接客户端都要用到。我习惯用一个强密码，并且记录在安全的地方。

对于chnode3，我们只安装Keeper。命令类似，但安装包换成了clickhouse-keeper：

sudo apt-get install -y clickhouse-keeper

安装完成后，别急着启动服务。因为chnode3只装了Keeper，一些默认的目录可能没创建，我们需要手动创建并设置好权限：

sudo mkdir -p /etc/clickhouse-keeper/config.d
sudo mkdir -p /var/log/clickhouse-keeper
sudo mkdir -p /var/lib/clickhouse-keeper/coordination/{log,snapshots}
sudo mkdir -p /var/lib/clickhouse-keeper/cores
sudo chown -R clickhouse:clickhouse /etc/clickhouse-keeper /var/log/clickhouse-keeper /var/lib/clickhouse-keeper

这些目录分别是存放配置、日志、协调数据日志和快照的地方，权限给对，服务才能正常读写。环境准备就绪，接下来就是最核心的配置环节了。

3. 深度解析集群节点配置

配置是集群部署的灵魂，也是新手最容易迷糊的地方。ClickHouse的配置采用XML格式，并且支持“配置片段”的方式。简单说，就是不要直接修改主配置文件/etc/clickhouse-server/config.xml，而是在config.d目录下创建我们自己的小配置文件，系统会自动把它们合并进去。这样做的好处是升级时不会被覆盖，管理起来也清晰。

我们的配置可以分为几个核心部分，我为你一一拆解。首先，是网络与日志配置。这部分chnode1和chnode2几乎一样，目的是让ClickHouse Server监听正确的端口，并配置好日志轮转。下面是一个network-and-logging.xml的例子：

<clickhouse>
    <logger>
        <level>debug</level>
        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
        <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
        <size>1000M</size>
        <count>3</count>
    </logger>
    <display_name>clickhouse</display_name>
    <listen_host>0.0.0.0</listen_host>
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    <interserver_http_port>9009</interserver_http_port>
</clickhouse>

这里listen_host设为0.0.0.0表示接受所有网络连接，在生产环境你可能需要更严格的限制。端口8123用于HTTP API（比如用curl访问），9000是原生TCP端口（clickhouse-client使用），9009是服务器之间内部通信用的。

接下来是重头戏：ClickHouse Keeper配置。这是让集群具备协调能力的关键。我们需要在三个节点上分别配置Keeper，并让它们组成一个集群。配置文件是enable-keeper.xml，三个文件内容大部分相同，唯一且至关重要的区别是<server_id>。

以chnode1为例：

<clickhouse>
    <keeper_server>
        <tcp_port>9181</tcp_port>
        <server_id>1</server_id>
        <log_storage_path>/var/lib/clickhouse/coordination/log</log_storage_path>
        <snapshot_storage_path>/var/lib/clickhouse/coordination/snapshots</snapshot_storage_path>
        <coordination_settings>
            <operation_timeout_ms>10000</operation_timeout_ms>
            <session_timeout_ms>30000</session_timeout_ms>
            <raft_logs_level>trace</raft_logs_level>
        </coordination_settings>
        <raft_configuration>
            <server>
                <id>1</id>
                <hostname>chnode1</hostname>
                <port>9234</port>
            </server>
            <server>
                <id>2</id>
                <hostname>chnode2</hostname>
                <port>9234</port>
            </server>
            <server>
                <id>3</id>
                <hostname>chnode3</hostname>
                <port>9234</port>
            </server>
        </raft_configuration>
    </keeper_server>
</clickhouse>

请注意，<server_id>必须与<raft_configuration>里对应服务器的<id>一致。chnode1配1，chnode2配2，chnode3配3。tcp_port=9181是给ClickHouse Server连接Keeper用的客户端端口，而port=9234是Keeper节点之间内部通信的Raft协议端口。raft_configuration里列出了集群所有Keeper成员，必须完全一致。

然后是宏配置（Macros）。这个配置非常巧妙，它定义了每个节点的“身份标签”。在创建复制表时，ClickHouse会自动用这些宏值来替换模板，从而知道数据应该放在哪个分片的哪个副本上。

chnode1的Macros.xml：

<clickhouse>
    <macros>
        <shard>1</shard>
        <replica>replica_1</replica>
    </macros>
</clickhouse>

chnode2的Macros.xml：

<clickhouse>
    <macros>
        <shard>2</shard>
        <replica>replica_1</replica>
    </macros>
</clickhouse>

看到区别了吗？shard值不同（1和2），这标明它们属于不同的分片。replica值相同（都是replica_1），因为目前每个分片我们只设了一个副本。如果将来要给分片1增加一个副本放在新节点上，那个新节点的宏配置就应该是<shard>1</shard><replica>replica_2</replica>。

接下来是定义远程服务器集群，也就是告诉ClickHouse，我们的集群具体由哪些机器组成。这个配置remote-servers.xml在chnode1和chnode2上必须完全一样。

<clickhouse>
    <remote_servers replace="true">
        <cluster_2S_1R>
            <secret>mysecretphrase</secret>
            <shard>
                <internal_replication>true</internal_replication>
                <replica>
                    <host>chnode1</host>
                    <port>9000</port>
                </replica>
            </shard>
            <shard>
                <internal_replication>true</internal_replication>
                <replica>
                    <host>chnode2</host>
                    <port>9000</port>
                </replica>
            </shard>
        </cluster_2S_1R>
    </remote_servers>
</clickhouse>

这里我们定义了一个名为cluster_2S_1R的集群（意思是2分片1副本）。<secret>是集群节点间通信的可选密码，增强安全性。每个<shard>标签代表一个分片，里面包含了该分片的副本列表。internal_replication=true是个好习惯，它意味着数据写入时，由该分片内的副本自己负责同步，而不是由分布式表引擎来管，这样更高效可靠。

最后，我们需要告诉ClickHouse Server去哪里找Keeper服务。这就是use-keeper.xml文件的作用，它在chnode1和chnode2上也是一样的：

<clickhouse>
    <zookeeper>
        <node index="1">
            <host>chnode1</host>
            <port>9181</port>
        </node>
        <node index="2">
            <host>chnode2</host>
            <port>9181</port>
        </node>
        <node index="3">
            <host>chnode3</host>
            <port>9181</port>
        </node>
    </zookeeper>
</clickhouse>

注意，这里用的是<zookeeper>标签，因为ClickHouse Keeper完美兼容ZooKeeper协议，ClickHouse Server把它当ZooKeeper来连接。端口就是Keeper配置中定义的9181。

对于chnode3，由于它只运行Keeper，配置就简单多了，只需要一个enable-keeper.xml（内容与chnode1的类似，但server_id设为3），并且这个文件要放在/etc/clickhouse-keeper/config.d/目录下。同时，这个文件里需要额外加上<listen_host>0.0.0.0</listen_host>，让Keeper服务监听网络。

4. 启动服务与集群健康检查

配置全部写好后，千万别急着启动。先做一次全面的“配置预检”，这是我踩过坑后养成的习惯。用tree命令看看每个节点的配置目录结构是否完整、文件是否放对了地方。

在chnode1和chnode2上：

sudo apt install -y tree
tree /etc/clickhouse-server/

你应该看到config.d目录下有我们创建的五个XML文件。在chnode3上：

tree /etc/clickhouse-keeper/

应该看到config.d目录下有enable-keeper.xml。

确认无误后，开始启动服务，顺序有讲究：先启动Keeper集群，再启动ClickHouse Server。因为Server启动时需要连接Keeper。

首先，在chnode3上启动Keeper：

sudo systemctl enable --now clickhouse-keeper.service

然后，在chnode1和chnode2上启动Server（它内部集成的Keeper也会被启动）：

sudo systemctl enable --now clickhouse-server.service

启动后，立即用systemctl status检查服务状态，确保是active (running)。重点看日志有没有报错，特别是“Connection refused”或“Cannot resolve host”这类网络和连接错误。

服务都跑起来后，我们来验证Keeper集群是否健康。用一个简单命令检查每个Keeper节点的角色：

echo mntr | nc localhost 9181

你会看到一堆输出，其中zk_server_state这一行是关键。在三个节点上分别执行，正常情况下，其中一个节点会显示leader，另外两个显示follower。这说明Raft选举成功，Keeper集群工作正常。如果三个都是follower或者出现standalone，那说明集群没组建成功，需要回去检查Keeper配置中的raft_configuration和网络连通性。

接下来，用clickhouse-client连接任意一个数据节点（比如chnode1），输入安装时设置的密码：

clickhouse-client --host chnode1 --password

连接成功后，执行一个关键查询来验证集群拓扑是否被正确识别：

SELECT host_name, host_address, replica_num FROM system.clusters WHERE cluster='cluster_2S_1R';

如果配置正确，你会看到两行结果，分别对应chnode1和chnode2，它们的replica_num都是1。这个查询是从系统表里查看我们定义的集群，它能直观地告诉你ClickHouse自己“眼里”的集群是什么样子。到这一步，基础集群就已经搭建成功了。

5. 分布式表实战：从创建到查询

集群搭好了，就像盖好了房子，接下来我们要在里面“布置家具”——创建表并放入数据。ClickHouse在这里有个精妙的设计：本地表（Local Table） 和 分布式表（Distributed Table）。理解它们的关系至关重要。

本地表是真正物理存储数据的表，它存在于每个节点的本地磁盘上。而分布式表是一个“逻辑视图”或“代理”，它本身不存储数据，只是定义了数据如何分布以及如何从各个本地表聚合查询。当你向分布式表插入数据时，它会根据规则将数据分发到对应的本地表；当你从分布式表查询时，它会向所有相关本地表发起查询并汇总结果。

首先，我们创建一个测试数据库，并且要用ON CLUSTER子句。这个子句是分布式DDL的魔法，它会让这个命令在整个集群的所有节点上执行。

CREATE DATABASE test_db ON CLUSTER cluster_2S_1R;

执行后，你会看到类似下面的输出，显示命令在chnode1和chnode2上都执行成功了：

┌─host────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ chnode2 │ 9000 │ 0       │       │ 1                   │ 0                │
│ chnode1 │ 9000 │ 0       │       │ 0                   │ 0                │
└─────────┴──────┴─────────┴───────┴─────────────────────┴──────────────────┘

接着，在集群上创建一个本地表。我们使用最常用的MergeTree引擎家族。注意，这里我们没有使用ReplicatedMergeTree，因为我们的集群目前是每个分片一个副本，没有跨副本复制的需求。如果要做多副本高可用，就需要用ReplicatedMergeTree并配合宏。

CREATE TABLE test_db.local_metrics ON CLUSTER cluster_2S_1R
(
    `event_time` DateTime,
    `metric_name` String,
    `value` Float64,
    `tags` Map(String, String)
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(event_time)
ORDER BY (metric_name, event_time);

这个表结构模拟了一个常见的监控指标表：时间、指标名、值、标签。按月份分区，按指标名和时间排序，适合时序类查询。

现在，有趣的部分来了。我们分别在两个节点上，直接向本地表插入数据。在chnode1的客户端执行：

INSERT INTO test_db.local_metrics VALUES ('2024-10-27 10:00:00', 'cpu_usage', 65.5, {'host':'web01', 'region':'east'});

然后，在chnode2的客户端执行：

INSERT INTO test_db.local_metrics VALUES ('2024-10-27 10:00:00', 'memory_usage', 80.2, {'host':'db01', 'region':'west'});

插入完成后，你分别在chnode1和chnode2上查询local_metrics表，会发现每个节点只能看到自己插入的那条数据。这正是分片的效果，数据被隔离存储在了不同的节点上。

那么，怎么才能一次性查询到所有数据呢？这就需要创建分布式表。分布式表使用Distributed引擎，它需要四个参数：集群名、数据库名、本地表名、以及分片键。

CREATE TABLE test_db.distributed_metrics ON CLUSTER cluster_2S_1R
AS test_db.local_metrics
ENGINE = Distributed('cluster_2S_1R', 'test_db', 'local_metrics', rand());

第一个参数cluster_2S_1R：指定数据分布在哪个集群。
第二、三个参数test_db, local_metrics：指定底层的本地数据库和表名。
第四个参数rand()：这是分片键（Sharding Key）。它决定了新数据插入时，如何选择分片。rand()表示随机分配，这适用于数据均匀分布的场景。对于像用户ID这样的字段，用intHash64(user_id)这类哈希函数会更合适，能保证相同用户的数据落在同一个分片，有利于查询。

现在，在任何节点上查询分布式表：

SELECT * FROM test_db.distributed_metrics ORDER BY event_time;

你会惊喜地看到两条数据都出现了！分布式表引擎在背后自动向chnode1和chnode2上的local_metrics表发起了查询，并将结果合并后返回给你。更强大的是，你直接向分布式表插入数据，它也会自动按分片键规则进行分发：

INSERT INTO test_db.distributed_metrics VALUES ('2024-10-27 11:00:00', 'disk_io', 120.0, {'host':'cache01', 'region':'central'});

这条数据会根据rand()函数的值，被自动写入chnode1或chnode2其中的一个本地表。你可以通过查询分布式表来验证，也可以分别查询两个节点的本地表，看看数据被分配到了哪里。这种透明化的数据分布和聚合，正是ClickHouse分布式能力的魅力所在。

6. 生产环境考量与故障排查锦囊

把集群跑起来并完成基本操作，只是第一步。要真正用到生产环境，还有一些重要的考量点和常见的“坑”需要提前了解。根据我的经验，下面这些方面值得你特别关注。

首先，关于Keeper的部署。我们的示例为了简化，让chnode1和chnode2同时运行Server和Keeper。但在真实的生产环境中，强烈建议将ClickHouse Keeper部署在独立的专用节点上。原因很简单：Keeper是集群的协调中枢，它的稳定性和性能至关重要。如果Keeper和繁忙的数据节点混布，一旦数据节点资源（CPU、内存、IO）吃紧，可能会影响Keeper的心跳和选举，严重时甚至导致整个集群协调服务瘫痪，那将是灾难性的。独立部署可以让Keeper集群更稳定，也便于单独监控和扩展。

其次，分片键的选择是一门艺术。我们示例中用了rand()，这是最简单的，但不一定是最优的。一个好的分片键应该满足：1) 数据分布均匀，避免某个分片过热成为瓶颈；2) 常用查询能利用分片本地化，比如经常按用户ID查询，那就用用户ID做分片键，这样查询可以精准路由到特定分片，而不是扫描所有节点。常用的选择有：对某个ID字段做哈希；或者按时间范围分片（但要注意数据冷热不均）。你需要根据业务查询模式仔细设计。

关于副本与高可用。我们当前是2分片1副本，任何一个数据节点宕机，都会导致部分数据不可用。要实现高可用，就需要配置多副本。例如，2分片2副本，就需要至少4个数据节点。这时，表引擎要换成ReplicatedMergeTree，它会在Keeper的协调下，自动在副本间同步数据。配置了多副本后，不仅容灾能力增强，读查询也可以负载均衡到多个副本上，提升查询吞吐。

安全配置不容忽视。我们的示例用了简单的密码，并且网络监听在0.0.0.0。在生产环境，你应该：1) 使用更复杂的密码，并考虑使用SHA256加密存储；2) 通过<networks>限制可访问的IP段；3) 为不同业务创建不同的用户并分配最小必要权限，而不是都用default用户；4) 考虑配置SSL/TLS加密客户端与服务器之间、以及服务器之间的通信。

监控是运维的眼睛。ClickHouse提供了丰富的系统表（如system.metrics, system.events, system.query_log），你可以从中获取查询性能、资源使用、慢查询等关键信息。建议将这些指标接入到Prometheus + Grafana这样的监控体系中，设置好告警规则（如节点下线、查询超时、磁盘快满了等）。

即使准备再充分，实际运行中也可能遇到问题。这里分享几个我遇到的典型故障和排查思路：

节点无法加入集群：首先检查防火墙，确保9000, 9009, 9181, 9234这几个端口在集群节点间是互通的。然后检查/etc/hosts或DNS，确保主机名能正确解析到IP。最后，仔细核对每个节点macros.xml中的shard和replica值是否在集群内唯一。
分布式查询特别慢：可能是“数据倾斜”了。用SELECT shard_num, count() FROM distributed_table GROUP BY shard_num看看每个分片的数据量是否均衡。如果不均衡，说明分片键没选好。也可能是某个节点负载过高，检查该节点的CPU、内存、磁盘IO情况。
写入分布式表报错：检查Keeper集群状态是否健康（用mntr命令）。如果Keeper失联，复制表和分布式DDL操作都会失败。同时，检查接收数据的本地表磁盘空间是否充足。
内存不足（OOM）：ClickHouse某些操作（如大表JOIN、聚合）非常吃内存。除了给服务器配足内存外，可以在users.xml中为不同用户或查询设置max_memory_usage参数，防止单个查询拖垮整个节点。