第 19 章：Keeper 与元数据

这是《ClickHouse 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 Keeper 或 ZooKeeper 是 ClickHouse 集群的协调层，用于副本日志、块去重信息、leader 选举、分布式 DDL 队列和任务锁。

19.1 协调内容

/clickhouse
  /tables
    /{shard}
      /table
        /replicas
          /replica-1
          /replica-2
        /leader
        /blocks
        /log
  /task_queue
  /ddl

不同版本的路径布局和实现细节可能调整，核心是保存集群协调状态，而不是业务数据。

19.2 Keeper 部署

生产建议至少三节点：

keeper-01  follower / leader
keeper-02  follower / leader
keeper-03  follower / leader

要求：

1. 低延迟网络；
2. SSD 和独立资源；
3. 时钟同步；
4. 独立监控；
5. 定期备份配置；
6. 不与其他大 IO 服务混部。

19.3 配置示例

<clickhouse>
    <keeper_server>
        <tcp_port>9181</tcp_port>
        <server_id>1</server_id>
        <raft_configuration>
            <server>
                <id>1</id>
                <hostname>keeper-01</hostname>
                <port>9234</port>
            </server>
            <server>
                <id>2</id>
                <hostname>keeper-02</hostname>
                <port>9234</port>
            </server>
            <server>
                <id>3</id>
                <hostname>keeper-03</hostname>
                <port>9234</port>
            </server>
        </raft_configuration>
    </keeper_server>
</clickhouse>

ClickHouse 节点连接协调服务：

<zookeeper>
    <node>
        <host>keeper-01</host>
        <port>9181</port>
    </node>
    <node>
        <host>keeper-02</host>
        <port>9181</port>
    </node>
</zookeeper>

19.4 元数据与数据文件

ClickHouse 元数据包含：

database metadata
table create statement
column definitions
part information
replication log
access control

本地数据目录保存实际列文件和索引。恢复集群时必须同时考虑：

1. 元数据；
2. 数据 part；
3. Keeper 路径；
4. 用户权限；
5. 集群配置；
6. 分布式表定义。

19.5 分布式 DDL

ON CLUSTER 语句写入 DDL 队列，各节点异步执行。

查看队列：

SELECT
    entry,
    host,
    status,
    query,
    exception
FROM system.distributed_ddl_queue
ORDER BY entry DESC
LIMIT 20;

常见失败：

1. 节点不可达；
2. 宏缺失；
3. 权限不足；
4. 表已存在；
5. 版本不兼容；
6. 磁盘满；
7. Keeper 超时。

19.6 副本与 Keeper

查看副本状态：

SELECT
    database,
    table,
    replica_name,
    is_readonly,
    queue_size,
    absolute_delay
FROM system.replicas;

如果 Keeper 不可用：

1. 已有数据仍可能可读；
2. 写入和复制协调会受影响；
3. 副本可能进入只读；
4. DDL 可能失败；
5. 集群不要在此时做拓扑变更。

19.7 四字命令

常用命令：

示例：

echo mntr | nc keeper-01 9181

命令支持与安全限制依版本和安全模式而异，生产环境应只允许可信网络访问。

19.8 监控要点

ClickHouse 侧关注：

SELECT countIf(is_readonly) AS readonly_replicas,
       sum(queue_size) AS queue_size
FROM system.replicas;

19.9 故障处理

少数节点故障

多数派仍可用，替换故障节点后加入集群。

多数派不可用

协调服务不可用，此时不要盲目重启或清空数据。保护现场，恢复多数派或使用备份。

脑裂与隔离

确保 Quorum 配置正确，节点网络分区时少数派不能提供服务。跨机房部署要评估延迟和故障域。

19.10 备份与迁移

必须备份：

1. Keeper 配置；
2. ClickHouse config；
3. users 配置；
4. 元数据 SQL；
5. 数据快照；
6. 集群拓扑记录。

迁移 Keeper 时应：

1. 逐台替换；
2. 确认多数派健康；
3. 观察 ClickHouse 副本状态；
4. 更新连接配置；
5. 保留回滚窗口。

本章小结

Keeper 是副本和集群协调的核心，故障影响写入、复制和 DDL。生产上要独立部署、监控 Quorum 和延迟，并把 Keeper 状态、ClickHouse 元数据与数据 part 作为一个整体来制定备份恢复方案。

思考题

1. Keeper 保存业务数据吗？
2. 为什么建议奇数节点？
3. Keeper 不可用时副本会有什么表现？
4. 分布式 DDL 为什么可能部分成功？
5. 集群恢复为什么要同时考虑元数据和数据？