Apache ZooKeeper Docker 容器化部署指南

概述

Apache ZooKeeper是Apache软件基金会的一个开源项目，提供分布式配置服务、同步服务和命名注册功能，适用于大型分布式系统。作为曾经的Hadoop子项目，ZooKeeper现在已成为独立的顶级项目，为分布式应用提供高可靠性的协调服务。

本指南将详细介绍如何通过Docker容器化方式部署ZOOKEEPER，包括环境准备、镜像拉取、容器部署、功能测试、生产环境建议及故障排查等内容。通过容器化部署，可以简化安装流程、确保环境一致性，并便于版本管理和升级。

环境准备

Docker环境安装

在开始部署前，需要先安装Docker环境。推荐使用以下一键安装脚本，适用于主流Linux发行版：

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本执行过程中可能需要输入sudo密码以获取必要的安装权限。安装完成后，建议将当前用户添加到docker用户组，避免每次执行docker命令都需要sudo：

bash
sudo usermod -aG docker $USER

注意：添加用户组后需要注销并重新登录才能生效

镜像准备

拉取ZOOKEEPER镜像

使用以下命令通过轩辕镜像加速地址拉取最新版本的ZOOKEEPER镜像：

bash
docker pull xxx.xuanyuan.run/library/zookeeper:latest

拉取完成后，可以使用以下命令验证镜像是否成功下载：

bash
docker images | grep zookeeper

若输出类似以下内容，则表示镜像拉取成功：

xxx.xuanyuan.run/library/zookeeper   latest    xxxxxxxx    2 weeks ago    278MB

如需查看更多可用版本标签，请访问ZOOKEEPER镜像标签列表。

容器部署

ZOOKEEPER可以部署为 standalone 模式（单节点）或 replicated 模式（集群）。根据实际需求选择合适的部署方式。

standalone 模式部署

standalone 模式适用于开发环境或简单测试场景，部署命令如下：

bash
docker run -d \
  --name zookeeper \
  --restart always \
  -p 2181:2181 \
  -p 2888:2888 \
  -p 3888:3888 \
  -p 8080:8080 \
  -v /data/zookeeper/data:/data \
  -v /data/zookeeper/datalog:/datalog \
  -e ZOO_TICK_TIME=2000 \
  -e ZOO_INIT_LIMIT=5 \
  -e ZOO_SYNC_LIMIT=2 \
  -e ZOO_MAX_CLIENT_CNXNS=60 \
  xxx.xuanyuan.run/library/zookeeper:latest

参数说明：

-d: 后台运行容器
--name zookeeper: 指定容器名称为zookeeper
--restart always: 设置容器开机自启
-p: 端口映射，依次对应客户端端口、 follower 端口、选举端口和AdminServer端口
-v: 数据卷挂载，将容器内的数据目录和日志目录映射到宿主机
-e: 设置环境变量，包括：
- ZOO_TICK_TIME: 基本时间单元（毫秒），默认2000
- ZOO_INIT_LIMIT: 允许follower连接并同步到leader的时间（以tick为单位），默认5
- ZOO_SYNC_LIMIT: 允许follower与leader同步的时间（以tick为单位），默认2
- ZOO_MAX_CLIENT_CNXNS: 限制单个客户端的并发连接数，默认60

replicated 模式部署（集群）

replicated 模式适用于生产环境，提供更高的可用性和容错能力。以下是使用Docker Compose部署3节点ZOO KEEPER集群的示例。

首先，创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  zoo1:
    image: xxx.xuanyuan.run/library/zookeeper:latest
    restart: always
    hostname: zoo1
    container_name: zoo1
    ports:
      - "2181:2181"
    environment:
      ZOO_MY_ID: 1
      ZOO_SERVERS: server.1=zoo1:2888:3888;2181 server.2=zoo2:2888:3888;2181 server.3=zoo3:2888:3888;2181
      ZOO_TICK_TIME: 2000
      ZOO_INIT_LIMIT: 10
      ZOO_SYNC_LIMIT: 5
    volumes:
      - ./zoo1/data:/data
      - ./zoo1/datalog:/datalog
    networks:
      - zookeeper-network

  zoo2:
    image: xxx.xuanyuan.run/library/zookeeper:latest
    restart: always
    hostname: zoo2
    container_name: zoo2
    ports:
      - "2182:2181"
    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
      ZOO_TICK_TIME: 2000
      ZOO_INIT_LIMIT: 10
      ZOO_SYNC_LIMIT: 5
    volumes:
      - ./zoo2/data:/data
      - ./zoo2/datalog:/datalog
    networks:
      - zookeeper-network

  zoo3:
    image: xxx.xuanyuan.run/library/zookeeper:latest
    restart: always
    hostname: zoo3
    container_name: zoo3
    ports:
      - "2183:2181"
    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
      ZOO_TICK_TIME: 2000
      ZOO_INIT_LIMIT: 10
      ZOO_SYNC_LIMIT: 5
    volumes:
      - ./zoo3/data:/data
      - ./zoo3/datalog:/datalog
    networks:
      - zookeeper-network

networks:
  zookeeper-network:
    driver: bridge

关键配置说明：

ZOO_MY_ID: 节点ID，必须唯一，取值范围1-255
ZOO_SERVERS: 集群节点列表，格式为server.id=host:port:port;clientPort
每个节点映射不同的宿主机端口（2181, 2182, 2183）
使用专用网络zookeeper-network确保节点间通信

启动集群：

bash
docker-compose up -d

注意：在单一机器上部署ZOO KEEPER集群仅用于测试，不提供真正的冗余。生产环境中，每个节点应部署在独立的物理机上。

自定义配置文件部署

如果需要更复杂的配置，可以通过挂载自定义配置文件的方式部署：

首先创建自定义配置文件zoo.cfg：

properties
tickTime=2000
initLimit=5
syncLimit=2
dataDir=/data
dataLogDir=/datalog
clientPort=2181
maxClientCnxns=60
autopurge.purgeInterval=1
autopurge.snapRetainCount=3
4lw.commands.whitelist=stat,ruok,srvr,cons,envi,conf,isro

使用自定义配置文件启动容器：

bash
docker run -d \
  --name zookeeper \
  --restart always \
  -p 2181:2181 \
  -v /data/zookeeper/data:/data \
  -v /data/zookeeper/datalog:/datalog \
  -v $(pwd)/zoo.cfg:/conf/zoo.cfg \
  xxx.xuanyuan.run/library/zookeeper:latest

功能测试

容器启动后，可以通过以下方式验证ZOOKEEPER服务是否正常运行。

检查容器状态

bash
docker ps | grep zookeeper

如果容器正常运行，将显示类似以下内容：

CONTAINER ID   IMAGE                                        COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
xxxxxxxxxxxx   xxx.xuanyuan.run/library/zookeeper:latest   "/docker-entrypoint.…"   5 minutes ago   Up 5 minutes   0.0.0.0:2181->2181/tcp, 0.0.0.0:2888->2888/tcp, 0.0.0.0:3888->3888/tcp, 0.0.0.0:8080->8080/tcp   zookeeper

查看容器日志

bash
docker logs -f zookeeper

正常启动后，日志中会显示类似以下内容：

...
2023-11-15 08:30:00,000 [myid:] - INFO  [main:ZooKeeperServer@836] - Started admin server on address 0.0.0.0, port 8080 and command URL /commands
2023-11-15 08:30:00,001 [myid:] - INFO  [main:ZooKeeperServerMain@120] - Started ZooKeeper Server
...

按Ctrl+C可退出日志查看。

通过AdminServer端口测试

ZOOKEEPER提供了HTTP接口的AdminServer，可以通过8080端口访问：

bash
curl http://localhost:8080/commands/stat

正常情况下会返回服务器状态信息：

json
{
  "serverStats": {
    "packetsReceived": 1,
    "packetsSent": 0,
    "maxLatency": 0,
    "minLatency": 0,
    "avgLatency": 0,
    "numAliveConnections": 0,
    "outstandingRequests": 0,
    "serverVersion": "3.9.4-1f48317108a068600f40e8f075f1f3f19a3d8f5f, built on 2023-10-10 08:26 UTC",
    "zkVersion": "3.9.4",
    "dataDir": "/data/version-2",
    "dataLogDir": "/datalog/version-2",
    "lastZxid": 0,
    "lastTick": 0,
    "maxClientCnxnsPerHost": 60,
    "clientPort": 2181,
    "secureClientPort": -1,
    "serverId": 0,
    "mode": "standalone",
    "electionType": 0,
    "leader": 0,
    "peerType": 0,
    "syncLimit": 2,
    "initLimit": 5,
    "tickTime": 2000,
    "maxSessionTimeout": 40000,
    "minSessionTimeout": 2000,
    "numZNodes": 5,
    "numDataNodes": 0,
    "numConnections": 0,
    "readOnly": false,
    "avgRequestLatency": 0,
    "ephemeralsCount": 0,
    "watchesCount": 0,
    "approximateDataSize": 27,
    "openFileDescriptorCount": 38,
    "maxFileDescriptorCount": 1048576
  }
}

使用ZOO KEEPER命令行客户端测试

通过容器内的zkCli.sh工具连接ZOO KEEPER服务：

bash
docker exec -it zookeeper zkCli.sh -server localhost:2181

连接成功后，可以执行ZOO KEEPER命令进行测试：

bash
# 创建节点
create /test "testdata"

# 查看节点
get /test

# 创建子节点
create /test/child "childdata"

# 列出节点
ls /test

# 修改节点数据
set /test "newtestdata"

# 删除节点
delete /test/child
delete /test

# 退出客户端
quit

集群状态检查（适用于replicated模式）

对于集群部署，可以检查各节点状态：

bash
# 查看节点1状态
docker exec -it zoo1 zkServer.sh status

# 查看节点2状态
docker exec -it zoo2 zkServer.sh status

# 查看节点3状态
docker exec -it zoo3 zkServer.sh status

正常情况下，集群中会有一个leader节点和两个follower节点。

生产环境建议

硬件资源配置

CPU：通常情况下，2-4核CPU足以满足大多数场景需求
内存：根据集群规模和工作负载调整，建议至少4GB
存储：使用高性能SSD存储，特别是事务日志目录(dataLogDir)应放在最快的存储设备上
网络：确保集群节点间网络稳定，低延迟

数据持久化与备份

始终使用数据卷(-v参数)将数据目录和日志目录挂载到宿主机

定期备份数据目录，可使用以下命令创建备份：

bash
# 创建数据备份
docker exec zookeeper tar -czf /tmp/zookeeper-backup-$(date +%Y%m%d).tar.gz /data /datalog

# 复制到宿主机
docker cp zookeeper:/tmp/zookeeper-backup-$(date +%Y%m%d).tar.gz /backup/

制定定期备份策略，根据数据重要性和变化频率调整备份频率

安全配置

限制客户端连接：通过maxClientCnxns限制单个客户端的并发连接数
配置适当的防火墙规则，只允许受信任的IP访问ZOO KEEPER端口
对于生产环境，考虑启用ZOO KEEPER的SASL认证机制
避免将ZOO KEEPER直接暴露在公网上

性能优化

调整JVM参数：通过JVMFLAGS环境变量设置合适的JVM参数

bash
-e JVMFLAGS="-Xmx2048m -Xms2048m -XX:+UseG1GC"

事务日志与数据目录分离：将dataLogDir和dataDir分别挂载到不同的存储设备

启用自动清理：设置ZOO_AUTOPURGE_PURGEINTERVAL和ZOO_AUTOPURGE_SNAPRETAINCOUNT自动清理旧的快照和事务日志

bash
-e ZOO_AUTOPURGE_PURGEINTERVAL=24 -e ZOO_AUTOPURGE_SNAPRETAINCOUNT=7

根据实际需求调整tickTime、initLimit和syncLimit参数

监控配置

启用Prometheus指标导出：

bash
-e ZOO_CFG_EXTRA="metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider metricsProvider.httpPort=7070"

配置Grafana面板监控关键指标

设置日志轮转，避免日志文件过大：

bash
-v $(pwd)/logback.xml:/conf/logback.xml

集成监控告警系统，监控节点状态、连接数、延迟等关键指标

高可用配置

生产环境中，ZOO KEEPER集群应至少包含3个节点
使用Docker Swarm或Kubernetes进行容器编排，实现自动故障转移

配置健康检查，及时发现并恢复故障节点：

bash
--health-cmd "curl -f http://localhost:8080/commands/stat || exit 1" \
--health-interval 30s \
--health-timeout 10s \
--health-retries 3

确保各节点部署在不同的物理机或可用区，避免单点故障

故障排查

容器启动失败

检查容器日志：

bash
docker logs zookeeper

常见启动失败原因：
- 端口冲突：确保宿主机端口未被其他服务占用
- 权限问题：检查宿主机挂载目录权限，可尝试：
```
bash
chmod -R 777 /data/zookeeper
```
- 配置文件错误：检查自定义配置文件格式和内容
- 数据目录损坏：尝试备份并清空数据目录后重启

连接问题

检查容器是否正常运行：

bash
docker inspect -f '{{.State.Status}}' zookeeper

检查端口映射是否正确：

bash
docker port zookeeper

检查防火墙规则：

bash
# 查看防火墙状态
systemctl status firewalld

# 检查端口是否开放
firewall-cmd --list-ports | grep 2181

检查网络连接：

bash
telnet localhost 2181

集群节点同步问题

检查集群配置：

bash
docker exec -it zoo1 cat /conf/zoo.cfg

确认各节点myid是否唯一：

bash
docker exec -it zoo1 cat /data/myid
docker exec -it zoo2 cat /data/myid
docker exec -it zoo3 cat /data/myid

检查节点间网络连通性：

bash
docker exec -it zoo1 ping zoo2
docker exec -it zoo1 ping zoo3

查看详细日志定位问题：

bash
docker logs --tail 100 zoo1

性能问题

检查系统资源使用情况：

bash
docker stats zookeeper

分析ZOO KEEPER性能指标：

bash
curl http://localhost:8080/commands/stat

常见性能问题解决：
- 内存不足：增加JVM堆大小
- 磁盘IO瓶颈：迁移到更快的存储设备
- 连接数过多：检查是否有客户端未正确关闭连接
- 不合理的ZNode结构：优化数据模型，避免创建过深的节点层次

日志分析

查看最近日志：

bash
docker logs --tail 100 zookeeper

实时查看日志：

bash
docker logs -f zookeeper

查看特定时间段的日志：

bash
docker logs zookeeper | grep "2023-11-15 08:30"

参考资源

总结

本文详细介绍了ZOOKEEPER的Docker容器化部署方案，包括 standalone 模式和 replicated 模式的部署方法，以及功能测试、生产环境建议和故障排查等内容。通过Docker部署ZOOKEEPER可以简化安装流程，提高环境一致性，并便于版本管理和升级。

关键要点：

使用一键脚本快速安装Docker环境
通过轩辕镜像加速提升镜像下载速度
根据需求选择 standalone 模式或 replicated 模式部署
始终使用数据卷挂载确保数据持久化
生产环境中建议部署3节点以上集群以保证高可用
定期备份数据并监控系统状态

后续建议：

深入学习ZOOKEEPER高级特性，如分布式锁、配置管理等
根据业务需求调整JVM参数和ZOO KEEPER配置
建立完善的监控和告警机制，及时发现并解决问题
制定合理的扩容策略，应对业务增长
学习ZOO KEEPER数据模型设计最佳实践，优化应用性能

通过合理配置和运维，ZOOKEEPER可以为分布式系统提供可靠的协调服务，支撑业务稳定运行。如需了解更多详情，请参考ZOO KEEPER镜像文档（轩辕）和官方文档。