clickhouse分布式集群必须配置zookeeper、metrika.xml和config.xml三者协同，缺一不可；默认单节点安装无分布式能力，distributed表因缺少显式集群定义和协调服务而报“unknown cluster”错误。
ClickHouse集群不是装完clickhouse-server就能用的——缺ZooKeeper、没metrika.xml、config.xml里没include_from，建Distributed表必报Unknown cluster。
为什么yum install后Distributed表直接报错
默认RPM安装只启动本地服务，clickhouse-server进程完全不感知其他节点。分布式能力（分片路由、副本同步）必须靠外部协调+显式配置驱动。
-
Distributed('my_cluster', ...)中的my_cluster必须在metrika.xml里明确定义，否则解析失败 -
/etc/clickhouse-server/config.xml必须包含<include_from>/etc/clickhouse-server/metrika.xml</include_from>，否则metrika.xml被完全忽略 - ZooKeeper不是“可选优化项”：只要用
ReplicatedMergeTree或需要副本一致性，就必须部署并填入metrika.xml的<zookeeper></zookeeper>段
metrika.xml配错的三个高频坑
这个文件没有XML Schema校验，标签名拼错、缩进错位、<shard></shard>/<replica></replica>顺序不一致，都会静默失效——服务照常启动，但查询时才暴露问题。
- 所有节点的
metrika.xml内容必须完全一致，包括<host></host>的IP和<port></port>，不能一个写ck102一个写192.168.10.102 -
<shard></shard>内多个<replica></replica>是“同一分片的不同副本”，<shard></shard>之间才是分片关系；配反了会导致数据全写到同一个节点 -
<zookeeper></zookeeper>段里的<node></node>必须指向ZooKeeper集群真实可用地址，且端口是2181（不是ClickHouse的9000）
config.xml和ZooKeeper联动要点
config.xml本身不定义集群，它只负责加载metrika.xml并把ZooKeeper地址透传给引擎层。ZooKeeper宕机时，ReplicatedMergeTree表会拒绝写入，但Distributed表仍能查（只是查不到副本间同步后的最新数据）。
- 确认
config.xml第616行左右有<include_from></include_from>且路径正确，用ls -l /etc/clickhouse-server/metrika.xml验证文件存在 - ZooKeeper必须先于
clickhouse-server启动，且所有ClickHouse节点都能telnet zk_host 2181通 - 如果用ClickHouse Keeper替代ZooKeeper，需在
config.xml里启用<keeper_server></keeper_server>并关闭ZooKeeper相关配置
验证集群是否真生效
别只看system.clusters里有名字——那只是配置加载成功。真正要看数据路由和副本状态。
- 执行
SELECT * FROM system.clusters WHERE cluster = 'your_cluster_name'，确认shard_num和replica_num列数值符合预期 - 在每个节点建
ReplicatedMergeTree本地表后，往任一节点INSERT，立刻查其他节点对应表，看数据是否同步 - 查
system.replicas，is_leader=1的副本才接受写入，queue_size>0说明同步延迟或ZK断连
最易被忽略的是metrika.xml文件权限：必须让clickhouse用户可读，否则静默跳过加载——检查ls -l /etc/clickhouse-server/metrika.xml，确保属主是clickhouse:clickhouse。
