ClickHouse Keeper Docker镜像文档

1. 镜像概述

ClickHouse Keeper是ClickHouse官方提供的分布式协调服务镜像，基于Apache ZooKeeper协议实现，专为ClickHouse集群设计。该镜像封装了ClickHouse Keeper服务，用于管理ClickHouse集群的核心元数据（如表结构、分区信息、集群拓扑等），确保分布式环境下的高可用性、数据一致性和服务可靠性，是构建ClickHouse分布式集群的关键组件。

2. 核心功能与特性

• ZooKeeper协议兼容：完全兼容ZooKeeper客户端协议，可无缝替换ZooKeeper作为ClickHouse集群的协调服务，无需修改现有客户端代码。
• 高可用性架构：支持多节点部署，通过领导者选举（Leader Election）机制实现故障自动转移，确保服务持续可用，避免单点故障。
• 数据一致性保障：基于ZAB（ZooKeeper Atomic Broadcast）协议实现分布式数据同步，保证集群元数据的强一致性。
• 轻量级设计：针对ClickHouse集群场景优化，资源占用低，性能高效，支持高并发元数据操作。
• 元数据管理：负责存储和同步ClickHouse集群的关键元数据，包括副本配置、分片映射、分布式DDL任务状态等。
• 集群状态监控：实时监控集群节点状态，自动同步配置变更，确保集群节点配置一致性。

3. 使用场景与适用范围

• ClickHouse分布式集群部署：作为必备协调组件，管理集群元数据及分布式任务调度。
• ZooKeeper替代方案：在ClickHouse生态中替代ZooKeeper，减少第三方依赖，简化集群部署架构。
• 高可用生产环境：适用于对服务可靠性要求高的生产环境，确保集群故障时元数据不丢失、服务不中断。
• 多节点协调场景：支持多节点ClickHouse集群的配置同步、主从切换及分布式锁管理。

4. 使用方法与配置说明

4.1 拉取镜像

docker pull clickhouse/clickhouse-keeper

4.2 单节点快速启动

适用于测试或开发环境，通过以下命令启动单节点ClickHouse Keeper：

docker run -d \
  --name clickhouse-keeper \
  -p 2181:2181 \  # 客户端连接端口（ZooKeeper兼容端口）
  -v $(pwd)/keeper-data:/var/lib/clickhouse-keeper \  # 数据持久化目录
  clickhouse/clickhouse-keeper

4.3 集群部署（docker-compose示例）

生产环境推荐3节点集群部署（奇数节点避免脑裂），以下为docker-compose配置示例：

version: '3.8'
services:
  keeper1:
    image: clickhouse/clickhouse-keeper
    container_name: keeper1
    restart: always
    ports:
      - "2181:2181"  # 客户端端口
      - "2888:2888"  # 节点间通信端口
      - "3888:3888"  # 选举端口
    volumes:
      - ./keeper1/data:/var/lib/clickhouse-keeper  # 数据目录
      - ./keeper1/config:/etc/clickhouse-keeper    # 配置目录
    environment:
      - KEEPER_ID=1
      - KEEPER_SERVERS=keeper1:2888:3888;keeper2:2888:3888;keeper3:2888:3888
    networks:
      - clickhouse-net

  keeper2:
    image: clickhouse/clickhouse-keeper
    container_name: keeper2
    restart: always
    ports:
      - "2182:2181"
      - "2889:2888"
      - "3889:3888"
    volumes:
      - ./keeper2/data:/var/lib/clickhouse-keeper
      - ./keeper2/config:/etc/clickhouse-keeper
    environment:
      - KEEPER_ID=2
      - KEEPER_SERVERS=keeper1:2888:3888;keeper2:2888:3888;keeper3:2888:3888
    networks:
      - clickhouse-net

  keeper3:
    image: clickhouse/clickhouse-keeper
    container_name: keeper3
    restart: always
    ports:
      - "2183:2181"
      - "2890:2888"
      - "3890:3888"
    volumes:
      - ./keeper3/data:/var/lib/clickhouse-keeper
      - ./keeper3/config:/etc/clickhouse-keeper
    environment:
      - KEEPER_ID=3
      - KEEPER_SERVERS=keeper1:2888:3888;keeper2:2888:3888;keeper3:2888:3888
    networks:
      - clickhouse-net

networks:
  clickhouse-net:
    driver: bridge

启动集群：

docker-compose up -d

4.4 配置说明

4.4.1 环境变量

4.4.2 配置文件（config.xml）

核心配置文件路径为/etc/clickhouse-keeper/config.xml，关键配置示例：

<clickhouse-keeper>
  <server_id>1</server_id>  <!-- 节点ID，与KEEPER_ID一致 -->
  <data_path>/var/lib/clickhouse-keeper</data_path>  <!-- 数据目录 -->
  <log_storage_path>/var/lib/clickhouse-keeper/log</log_storage_path>  <!-- 日志存储目录 -->
  <snapshot_storage_path>/var/lib/clickhouse-keeper/snapshots</snapshot_storage_path>  <!-- 快照目录 -->
  <coordination_settings>
    <operation_timeout_ms>10000</operation_timeout_ms>  <!-- 操作超时时间 -->
    <session_timeout_ms>30000</session_timeout_ms>      <!-- 会话超时时间 -->
  </coordination_settings>
  <servers>  <!-- 集群节点配置，与KEEPER_SERVERS对应 -->
    <server>
      <id>1</id>
      <hostname>keeper1</hostname>
      <port>2888</port>
      <election_port>3888</election_port>
    </server>
    <server>
      <id>2</id>
      <hostname>keeper2</hostname>
      <port>2888</port>
      <election_port>3888</election_port>
    </server>
    <server>
      <id>3</id>
      <hostname>keeper3</hostname>
      <port>2888</port>
      <election_port>3888</election_port>
    </server>
  </servers>
</clickhouse-keeper>

5. 部署验证

使用ZooKeeper客户端验证服务可用性：

# 安装ZooKeeper客户端（或使用容器）
docker run --rm -it zookeeper zkCli.sh -server localhost:2181

# 连接成功后执行以下命令验证
ls /  # 查看根节点，默认返回空列表（初始状态）
create /test "hello"  # 创建测试节点
get /test  # 获取节点数据，应返回"hello"

6. 注意事项

• 集群节点数量：生产环境建议部署3/5个节点（奇数），确保高可用性及避免脑裂。
• 数据持久化：需通过卷挂载DATA_DIR目录，避免容器重启导致数据丢失。
• 资源配置：根据集群规模调整CPU/内存资源，推荐最低配置：2核CPU、4GB内存。
• 网络互通：确保集群节点间SERVER_PORT（2888）和ELECTION_PORT（3888）端口互通。
• 监控配置：建议集成Prometheus+Grafana监控节点状态、磁盘使用率及连接数。