ClickHouse分布式集群需metrika.xml、ZooKeeper和config.xml三者协同配置，缺一不可；默认单节点安装无分布式能力，未显式定义集群和协调服务时，Distributed表会报“Unknown cluster”错误。
ClickHouse 分布式集群不是“装一个软件”就能跑起来的，必须明确：单节点
默认不带分布式能力；要跨机器查询、写入、自动分片和副本同步，必须手动配置
、ZooKeeper、
三者协同，缺一不可。
为什么直接 yum/apt install 后不能直接用分布式表？
因为默认安装只启用本地服务，
进程完全不知道其他节点存在。分布式能力（如
表引擎）依赖外部协调服务（ZooKeeper）和显式集群定义。没有
，即使你建了
表，也会报错
。
中必须包含
才能加载集群配置
ZooKeeper 不是可选组件——只要用了
引擎或需要副本一致性，就必须部署并填入
的
段
所有节点的
必须内容一致（包括
和
的顺序与 IP），否则数据路由会错乱
metrika.xml 里最常配错的三个地方
是 ClickHouse 分布式的心脏，但它的结构松散、无 schema 校验，错一个标签或缩进就静默失效。
Docker Desktop（linux）
当前 Docker 最新稳定版本之一，主要针对稳定性和兼容性进行了修复优化，适合生产环境与日常开发使用。该版本继续强化 AI 开发支持、容器日志管理以及 Docker Engine 的安全能力，对 Windows/macOS/Linux 平台兼容性进行了进一步优化。
下载
下的
必须包裹
，不能反过来；多个
并列才表示分片，同一
内多个
才表示副本
的
值必须是其他节点能 DNS 解析或直连的地址（别写
或
），且
是 clickhouse-server 的 TCP 端口（默认
），不是 HTTP 端口（
）
的
列表必须包含全部 ZooKeeper 节点（如三节点 zk 集群就得写三条），且每个
必须可被所有 CH 节点访问，端口是 zk 的 clientPort（通常
）
启动后查不到集群状态？先看这三件事
运行
返回空或只有本地节点，说明集群配置没生效。
检查
日志：
，重点搜
、
、
确认
文件权限：必须是
用户可读（
）
重启服务不是 reload：
，不是
—— config 加载只在进程启动时做一次
真正麻烦的不是配置项本身，而是所有节点的网络互通性、时间同步（ZooKeeper 对时钟漂移敏感）、以及
中看似无关紧要的空格和换行——它们会让整个集群“看起来正常”，却在写入时丢数据或查不到结果。
clickhouse-servermetrika.xmlconfig.xmlclickhouse-serverDistributedmetrika.xmlDistributed('cluster_name', ...)Unknown cluster 'cluster_name'/etc/clickhouse-server/config.xml/etc/clickhouse-server/metrika.xml ReplicatedMergeTreemetrika.xmlmetrika.xmlmetrika.xmllocalhost127.0.0.1900081232181clickhouse-client -q "SELECT * FROM system.clusters"clickhouse-serversudo tail -n 50 /var/log/clickhouse-server/clickhouse-server.err.logFailed to load configUnknown clusterCan't resolve hostmetrika.xmlclickhouse:clickhousesudo chown clickhouse:clickhouse /etc/clickhouse-server/metrika.xmlsudo systemctl restart clickhouse-serversystemctl reloadmetrika.xml