ZooKeeper 迁移到 ClickHouse Keeper：3 节点 quorum、converter 转换与 25.10 的默认变更

ClickHouse Keeper（clickhouse-keeper）用来替代 ZooKeeper，提供数据复制与分布式 DDL 执行的协调服务，客户端协议保持兼容。官方说明见 Keeper 指南 与 替代 ZooKeeper。

为什么替：ZAB vs RAFT

ZooKeeper 用 Java 实现，共识算法 ZAB 不为读提供线性一致性，每个节点本地服务读。Keeper 用 C++ 编写，采用 RAFT（NuRaft）实现，读写都能提供线性一致性；默认保证与 ZooKeeper 相同——写线性一致、读非线性一致。客户端/服务器协议兼容，任何标准 ZooKeeper 客户端都能与之交互。

关键差异：

• 服务器间协议不兼容，无法构建混合 ZooKeeper/Keeper 集群。
• 快照与日志格式与 ZooKeeper 不兼容，需要 clickhouse-keeper-converter 转换。
• C++ 单二进制，无外部依赖。
• 快照/日志压缩更省磁盘。
• 没有默认包大小与节点数据大小限制（ZooKeeper 是 1 MB）。
• 没有 ZXID 溢出问题（ZooKeeper 每 20 亿事务会强制重启）。
• 分区后恢复更快；可选 quorum_reads 提供线性一致读；同数据量下内存占用更少。

Keeper 既可嵌入 ClickHouse server（配置 ``），也可独立运行。

写入为主、内存效率重要、非 Java 生态、要管理 ClickHouse 集群，适合用它；读为主、需要读扩展、依赖 Java 组件，则不适合。

配置与运行

主要标签 ``：tcp_port（默认 2181）、tcp_port_secure、server_id（唯一）、log_storage_path、snapshot_storage_path、enable_reconfiguration、max_memory_usage_soft_limit、http_control、digest_enabled、create_snapshot_on_exit、hostname_checks_enabled、four_letter_word_white_list、enable_ipv6。

coordination_settings 默认值：

• operation_timeout_ms 10000
• min_session_timeout_ms 10000
• session_timeout_ms 100000
• heart_beat_interval_ms 500
• election_timeout_lower_bound_ms 1000
• election_timeout_upper_bound_ms 2000
• rotate_log_storage_interval 100000
• reserved_log_items 100000
• snapshot_distance 100000
• snapshots_to_keep 3
• stale_log_gap 10000
• fresh_log_gap 200
• max_requests_batch_size 100
• force_sync true
• quorum_reads false
• auto_forwarding true
• shutdown_timeout 5000
• startup_timeout 30000
• async_replication false（默认禁用以免破坏向后兼容；若所有实例都是 v23.9+，建议启用）

raft_configuration 只有一个参数 secure，用于加密 quorum 通信。每个 `` 有 id、hostname、port、can_become_leader（false 表示 learner）。

server_id 与 hostname 的映射必须保持一致，不要复用或打乱；主机可能变化时用主机名而不是 IP，改主机名等价于移除再添加服务器。

Keeper 集成在 ClickHouse server 包中，把 `` 加到 config.d 正常启动即可。独立运行：

clickhouse-keeper --config /etc/your_path_to_config/config.xml

没有符号链接时：

clickhouse keeper --config ...

三节点 quorum 配置

ensemble 大小必须是奇数，quorum 需要多数（50%+1）。2 节点一次单点故障就失去 quorum，推荐 3 节点。

每个节点放 /etc/clickhouse-server/config.d/keeper.xml（hostname3 用 /etc/clickhouse-keeper/keeper_config.xml）：

2181
1
/var/lib/clickhouse/coordination/log
/var/lib/clickhouse/coordination/snapshots

10000
30000
trace
10000

1
hostname1
9444

2
hostname2
9444

3
hostname3
9444

/clickhouse/testcluster/task_queue/ddl

server_id 每个节点不同（1/2/3）。官方文档示例的 raft 端口用 9234，上面这个例子用 9444。独立启动：

clickhouse-keeper --config /etc/clickhouse-keeper/keeper_config.xml

从 ZooKeeper 迁移

无法无缝迁移：必须停 ZooKeeper 集群、转换数据、再启动 Keeper。converter 要求 ZooKeeper 3.4+。

迁移前：安排维护窗口；停止所有会修改协调元数据的后台任务（SYSTEM STOP MERGES;）；记录基线指标。

1. 停止向所有 ClickHouse 节点摄取数据。
2. 停止所有 ClickHouse 节点后台任务。
3. 停止所有 ZooKeeper 节点。
4. （可选但建议）找到 leader，重启它之后再停，强制写一致快照到磁盘。
5. 在 leader 节点运行转换器：

clickhouse-keeper-converter \
--zookeeper-logs-dir /var/lib/zookeeper/version-2 \
--zookeeper-snapshots-dir /var/lib/zookeeper/version-2 \
--output-dir /path/to/clickhouse/keeper/snapshots

完整 ClickHouse 可执行文件时用 clickhouse keeper-converter，否则下载二进制。

1. 把快照复制到所有 Keeper 节点。任何节点启动前必须已经有快照，否则没有快照的节点可能以空状态把自己选成 leader。
2. 更新 ClickHouse 配置指向新的 Keeper 集群。
3. 在所有节点启动 Keeper，然后重启 ClickHouse。
4. 与迁移前基线对比指标，验证一致性。
5. 恢复后台任务与数据摄取。

整合多个 ZooKeeper 集群：官方 converter 只支持一对一，合并需要改转换器源码（反序列化快照、重算 numChildren 避免节点 ID 冲突、写入目标目录）。

ACL：支持 world/auth/digest。完全加密或完全未加密可以直接转换；部分加密需要先给超级管理员授权，再用 setAcl -R 清除受影响 path 的 ACL。

部分元数据只存在 ZooKeeper 里，不迁移就会丢，例如 Distributed DDL 队列、RBAC 数据。

迁移后调优

compress_snapshots_with_zstd_format 默认为 true。

硬限制

• 混合 ZooKeeper/Keeper quorum 不支持，两者共识协议不同。
• 快照/日志格式与 ZooKeeper 不兼容。
• 不建议超过 3 个 Keeper 节点（不含 observer）：节点越多 leader 重选越慢、提交更慢，拖慢插入与 DDL，性能未必更好甚至更差，还更耗资源。
• Keeper 版本无需与 ClickHouse server 版本一致。

async_replication 升级注意

async_replication 是 Keeper 内部的 RAFT 复制优化，25.10 起默认开启，不改变 Replicated 表的语义。

从 的/ready` 端点，供 Kubernetes 探针使用。

• 支持用磁盘存快照、日志、状态文件，可用 s3_plain/s3/local。
• system 表：system.zookeeper、system.zookeeper_connection、system.zookeeper_connection_log、system.zookeeper_log；26.1+ 有 system.zookeeper_info 和 Keeper HTTP API/dashboard。

项目信息 / 参考

• 官方 Keeper 指南：
• 替代 ZooKeeper 说明：
• Altinity KB：
• NuRaft：
• Altinity operator CHK 示例：