引言

Zookeeper 作为分布式系统的核心协调服务，常用于集群管理、配置同步、命名服务等场景。其集群模式通过多节点部署保障高可用性，而 docker-compose 能极大简化集群环境的搭建与配置流程。本文将详细记录 3 节点 Zookeeper 集群的完整搭建过程，包括配置文件编写、集群启动、状态验证与数据同步测试，适合分布式技术初学者快速上手实践。

一、基础信息

本文核心目标为实现 3 节点 Zookeeper 集群部署，验证集群角色选举与数据同步功能。

二、核心要求

1. 基于 docker-compose 配置并启动 3 节点 Zookeeper 集群
2. 验证集群节点状态（运行状态、网络连通性）
3. 确认集群角色选举结果（1 个 Leader + 2 个 Follower）
4. 通过客户端操作验证跨节点数据同步功能

三、详细步骤

3.1 前置准备：创建数据目录

Zookeeper 集群需要持久化存储数据与日志，首先在本地创建专用目录，用于容器数据挂载：

1. 在本地创建 zkdata 主目录，内部分别创建 zoo1、zoo2、zoo3 子目录（对应 3 个节点）
2. 每个子目录下再创建 data 和 log 文件夹，分别存储数据与日志文件
   最终目录结构：zkdata/zoo1/data、zkdata/zoo1/log、zkdata/zoo2/data 等

3.2 编写 docker-compose.yml 配置文件

在 zkdata 目录下创建 docker-compose.yml 文件，完整配置如下（含详细注释）：

yaml

version: '3.8'

services:
  # Zookeeper 节点 1
  zoo1:
    image: zookeeper:3.8  # 官方镜像，3.8 版本稳定
    container_name: zoo1
    restart: always  # 容器退出后自动重启
    ports:
      - "2181:2181"  # 客户端连接端口
      - "2888:2888"  # 集群内通信端口
      - "3888:3888"  # 选举端口
    environment:
      ZOO_MY_ID: 1  # 节点唯一 ID
      # 集群节点配置：server.ID=主机名:2888:3888
      ZOO_SERVERS: server.1=zoo1:2888:3888;2181 server.2=zoo2:2888:3888;2181 server.3=zoo3:2888:3888;2181
    volumes:
      - ./zkdata/zoo1:/data  # 挂载数据目录
      - ./zkdata/zoo1/log:/datalog  # 挂载日志目录
    networks:
      - zk-net  # 加入自定义网络，确保节点间通信
      - netkafka

  # Zookeeper 节点 2
  zoo2:
    image: zookeeper:3.8
    container_name: zoo2
    restart: always
    ports:
      - "2182:2181"  # 宿主端口区分，避免冲突
      - "2889:2888"
      - "3889:3888"
    environment:
      ZOO_MY_ID: 2
      ZOO_SERVERS: server.1=zoo1:2888:3888;2181 server.2=zoo2:2888:3888;2181 server.3=zoo3:2888:3888;2181
    volumes:
      - ./zkdata/zoo2:/data
      - ./zkdata/zoo2/log:/datalog
    networks:
      - zk-net
      - netkafka

  # Zookeeper 节点 3
  zoo3:
    image: zookeeper:3.8
    container_name: zoo3
    restart: always
    ports:
      - "2183:2181"
      - "2890:2888"
      - "3890:3888"
    environment:
      ZOO_MY_ID: 3
      ZOO_SERVERS: server.1=zoo1:2888:3888;2181 server.2=zoo2:2888:3888;2181 server.3=zoo3:2888:3888;2181
    volumes:
      - ./zkdata/zoo3:/data
      - ./zkdata/zoo3/log:/datalog
    networks:
      - zk-net
      - netkafka

# 自定义网络，桥接模式，确保节点间通过服务名通信
networks:
  zk-net:
    driver: bridge
  netkafka:
    external: true

关键配置说明

• ZOO_MY_ID：每个节点的唯一标识（1-255），必须与 ZOO_SERVERS 中的 server.ID 对应
• ZOO_SERVERS：集群节点列表，格式为 server.ID=主机名:通信端口:选举端口;客户端端口
• 端口映射：3 个节点的宿主端口需区分（2181/2182/2183），避免端口冲突
• 数据挂载：通过 volumes 挂载本地目录，实现数据持久化

3.3 启动 Zookeeper 集群

1. 打开 CMD 终端，进入 zkdata 目录（docker-compose.yml 所在目录）
2. 执行启动命令，后台运行集群：

   bash

   docker-compose up -d
   

3. 等待镜像拉取与容器启动，成功后终端输出如下：
   

3.4 验证集群状态

3.4.1 查看容器运行状态

执行以下命令，确认 3 个节点均处于 Up 状态：

bash

docker-compose ps

输出结果如下，可见所有容器正常运行，三个容器状态均为 Up，端口映射生效：

3.4.2 验证集群角色选举

Zookeeper 集群启动后会自动选举 Leader 节点（负责写操作与数据同步），其余为 Follower 节点（负责读操作）。执行以下命令查询每个节点的角色：

bash

# 查看 zoo1 角色
docker exec -it zoo1 zkServer.sh status
# 查看 zoo2 角色
docker exec -it zoo2 zkServer.sh status
# 查看 zoo3 角色
docker exec -it zoo3 zkServer.sh status

执行结果如下：

• zoo1、zoo2 为 Mode: follower（从节点）
• zoo3 为 Mode: leader（主节点）
• 说明：角色选举结果随机，只要集群有 1 个 Leader、2 个 Follower 即正常

3.5 客户端操作与数据同步验证

3.5.1 连接集群客户端

通过 zoo1 节点的客户端创建数据节点，验证数据是否能同步到所有节点：

1. 进入 zoo1 容器的 Zookeeper 客户端：

   bash

   docker exec -it zoo1 zkCli.sh -server zoo1:2181
   

2. 客户端连接成功后，创建一个测试节点 /test，数据为 zookeeper-cluster-test：

   bash

   create /test "zookeeper-cluster-test"
   

3. 查询该节点数据，确认创建成功：

   bash

   get /test

输出 zookeeper-cluster-test

3.5.2 跨节点验证数据同步

分别连接 zoo2 和 zoo3 节点的客户端，查询 /test 节点数据，验证同步效果：

1. 连接 zoo2 客户端并查询：

   bash

   docker exec -it zoo2 zkCli.sh -server zoo2:2181
   get /test
   

2. 连接 zoo3 客户端并查询：

   bash

   docker exec -it zoo3 zkCli.sh -server zoo3:2181
   get /test
   

两个节点均能成功返回 zookeeper-cluster-test，证明集群数据同步功能正常。

四、常见问题与避坑总结

4.1 常见问题解决方案

• 端口冲突：启动失败提示端口被占用，需修改 docker-compose.yml 中的宿主端口（如 2181 改为 2184），确保 3 个节点的端口互不重复。
• 挂载目录权限：Windows 系统下若提示权限不足，可右键本地 zkdata 目录，设置 “完全控制” 权限给当前用户。
• 集群无法选举 Leader：检查 ZOO_MY_ID 是否唯一，ZOO_SERVERS 配置中的主机名与容器名是否一致，网络是否正常连通。
• 外部网络报错：若无需关联 Kafka 网络，可删除 networks 中的 netkafka 配置（包括服务内和全局网络定义）。

Zookeeper 集群的高可用性依赖于节点数量（建议奇数节点，如 3、5 个）和数据同步机制，本次 3 节点集群既能满足基础测试需求，也可作为生产环境的最小部署单元。

结尾

本文详细梳理了 3 节点 Zookeeper 集群的 docker-compose 搭建流程，从配置编写到功能验证一步到位。