ClickHouse Keeper 是什么
Keeper 是 ClickHouse 自带的协调服务实现，在 config.xml 用 keeper_server 段开启并配置 raft 集群，用来逐步替代外部 ZooKeeper。它兼容 ZooKeeper 协议，客户端侧的 zookeeper 段只要把地址指向 Keeper 端口即可，业务表定义完全不用改。运维上可以配合 4lw 命令或 system.zookeeper 表查看会话与节点状态。
基本信息
| 配置段 | keeper_server：tcp_port、server_id、log/snapshot 路径、raft_configuration |
|---|---|
| 连接方式 | zookeeper 段指向 Keeper 端口（常见 9181）即可 |
| 运维查看 | 4lw 命令（如 mntr）或 system.zookeeper 表 |
| 协议兼容 | 兼容 ZooKeeper 协议，客户端不需要改造 |
| 所属系统 | ClickHouse 较新版本（内置协调服务） |
典型使用场景
- 替代 ZooKeeper：少维护一套外部组件，降低部署与运维成本
- 新建集群：直接用 Keeper 做协调服务，避免额外部署
- 平滑迁移：与 ZooKeeper 并存指向同一份数据，小范围验证后切换
- 状态巡检：通过 4lw 命令或 system.zookeeper 检查会话与节点
- 故障演练：练习协调节点故障后的恢复与选举流程
配置示例
配置示例
<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>
<raft_configuration>
<server>
<id>1</id>
<hostname>ch-1</hostname>
<port>9234</port>
</server>
</raft_configuration>
</keeper_server>配置项读法
| 配置项 | 含义 | 注意 |
|---|---|---|
| tcp_port | 对外服务端口 | 客户端 zookeeper 段指向它 |
| server_id | 节点标识 | 集群内必须唯一 |
| log_storage_path | 日志存储路径 | 单独磁盘并做容量监控 |
| snapshot_storage_path | 快照路径 | 与日志分开更安全 |
| raft_configuration | raft 成员列表 | 每个节点的配置要保持一致 |
迁移期 ZooKeeper 与 Keeper 可以并存并指向同一份数据（协议兼容），切换前先小范围验证，确认副本表与分布式 DDL 都正常再全量切。
server_id 与 raft 里的 server id 都必须唯一，把配置复制到多台机器时最容易漏改这一项，漏改会直接导致集群无法正常选举。
切换协调服务前要确认副本表使用的路径规则没有变化，路径不一致会让新副本从头同步，代价非常高。
生产部署按奇数个节点规划（三或五个），并按可容忍单节点故障来评估；存活节点少于多数派时协调服务不可用，副本表的创建与副本管理会全部失败。