ClickHouse分布式集群需metrika.xml、ZooKeeper和config.xml三者协同配置，缺一不可；默认单节点安装无分布式能力，未显式定义集群和协调服务时，Distributed表会报“Unknown cluster”错误。
ClickHouse 分布式集群不是“装一个软件”就能跑起来的，必须明确：单节点 clickhouse-server 默认不带分布式能力；要跨机器查询、写入、自动分片和副本同步，必须手动配置 metrika.xml、ZooKeeper、config.xml 三者协同，缺一不可。
为什么直接 yum/apt install 后不能直接用分布式表？
因为默认安装只启用本地服务，clickhouse-server 进程完全不知道其他节点存在。分布式能力（如 Distributed 表引擎）依赖外部协调服务（ZooKeeper）和显式集群定义。没有 metrika.xml，即使你建了 Distributed('cluster_name', ...) 表，也会报错 Unknown cluster 'cluster_name'。
-
/etc/clickhouse-server/config.xml中必须包含<include_from>/etc/clickhouse-server/metrika.xml</include_from>才能加载集群配置 - ZooKeeper 不是可选组件——只要用了
ReplicatedMergeTree引擎或需要副本一致性，就必须部署并填入metrika.xml的<zookeeper>段 - 所有节点的
metrika.xml必须内容一致（包括<shard>和<replica>的顺序与 IP），否则数据路由会错乱
metrika.xml 里最常配错的三个地方
metrika.xml 是 ClickHouse 分布式的心脏，但它的结构松散、无 schema 校验，错一个标签或缩进就静默失效。
-
<remote_servers>下的<shard>必须包裹<replica>，不能反过来；多个<shard>并列才表示分片，同一<shard>内多个<replica>才表示副本 -
<replica>的<host>值必须是其他节点能 DNS 解析或直连的地址（别写localhost或127.0.0.1），且<port>是 clickhouse-server 的 TCP 端口（默认9000），不是 HTTP 端口（8123） -
<zookeeper>的<node>列表必须包含全部 ZooKeeper 节点（如三节点 zk 集群就得写三条），且每个<host>必须可被所有 CH 节点访问，端口是 zk 的 clientPort（通常2181）
启动后查不到集群状态？先看这三件事
运行 clickhouse-client -q "SELECT * FROM system.clusters" 返回空或只有本地节点，说明集群配置没生效。
- 检查
clickhouse-server日志：sudo tail -n 50 /var/log/clickhouse-server/clickhouse-server.err.log，重点搜Failed to load config、Unknown cluster、Can't resolve host - 确认
metrika.xml文件权限：必须是clickhouse:clickhouse用户可读（sudo chown clickhouse:clickhouse /etc/clickhouse-server/metrika.xml） - 重启服务不是 reload：
sudo systemctl restart clickhouse-server，不是systemctl reload—— config 加载只在进程启动时做一次
真正麻烦的不是配置项本身，而是所有节点的网络互通性、时间同步（ZooKeeper 对时钟漂移敏感）、以及 metrika.xml 中看似无关紧要的空格和换行——它们会让整个集群“看起来正常”，却在写入时丢数据或查不到结果。
