github/xuanyuan_docker_proxy
1
0
Fork 0
mirror of https://github.com/SeanChang/xuanyuan_docker_proxy.git synced 2026-10-06 14:33:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
xuanyuan_docker_proxy/blog/apache-zookeeper-docker.md
T
Sean 483a2b88fd 部署文档定期更新 
部署文档定期更新
2026-08-22 20:36:37 +08:00

16 KiB
Raw Permalink Blame History

Apache ZooKeeper Docker 容器化部署指南

Apache ZooKeeper Docker 容器化部署指南

分类: Docker部署教程 | 标签: apache-zookeeper,docker,部署教程 | 发布时间: 2025-12-13 06:08:26

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

概述

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

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

环境准备

Docker环境安装

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

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

备用地址：

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

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

sudo usermod -aG docker $USER

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

镜像准备

拉取ZOOKEEPER镜像

使用以下命令通过轩辕镜像访问支持地址拉取最新版本的ZOOKEEPER镜像：

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

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

docker images | grep zookeeper

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

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

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

容器部署

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

standalone 模式部署

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

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文件：

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确保节点间通信

启动集群：

docker-compose up -d

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

自定义配置文件部署

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

  1. 首先创建自定义配置文件zoo.cfg：
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
  1. 使用自定义配置文件启动容器：
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服务是否正常运行。

检查容器状态

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

查看容器日志

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端口访问：

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

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

{
  "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服务：

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

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

# 创建节点
create /test "testdata"

# 查看节点
get /test

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

# 列出节点
ls /test

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

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

# 退出客户端
quit

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

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

# 查看节点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参数)将数据目录和日志目录挂载到宿主机
  • 定期备份数据目录，可使用以下命令创建备份： 
    # 创建数据备份
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参数 
    -e JVMFLAGS="-Xmx2048m -Xms2048m -XX:+UseG1GC"
  • 事务日志与数据目录分离：将dataLogDir和dataDir分别挂载到不同的存储设备
  • 启用自动清理：设置ZOO_AUTOPURGE_PURGEINTERVAL和ZOO_AUTOPURGE_SNAPRETAINCOUNT自动清理旧的快照和事务日志 
    -e ZOO_AUTOPURGE_PURGEINTERVAL=24 -e ZOO_AUTOPURGE_SNAPRETAINCOUNT=7
  • 根据实际需求调整tickTime、initLimit和syncLimit参数

监控配置

  • 启用Prometheus指标导出： 
    -e ZOO_CFG_EXTRA="metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider metricsProvider.httpPort=7070"
  • 配置Grafana面板监控关键指标
  • 设置日志轮转，避免日志文件过大： 
    -v $(pwd)/logback.xml:/conf/logback.xml
  • 集成监控告警系统，监控节点状态、连接数、延迟等关键指标

高可用配置

  • 生产环境中，ZOO KEEPER集群应至少包含3个节点
  • 使用Docker Swarm或Kubernetes进行容器编排，实现自动故障转移
  • 配置健康检查，及时发现并恢复故障节点： 
    --health-cmd "curl -f http://localhost:8080/commands/stat || exit 1" \
--health-interval 30s \
--health-timeout 10s \
--health-retries 3
  • 确保各节点部署在不同的物理机或可用区，避免单点故障

故障排查

容器启动失败

  1. 检查容器日志：

    docker logs zookeeper

  2. 常见启动失败原因：

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

连接问题

  1. 检查容器是否正常运行：

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

  2. 检查端口映射是否正确：

    docker port zookeeper

  3. 检查防火墙规则：

    # 查看防火墙状态
systemctl status firewalld

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

  4. 检查网络连接：

    telnet localhost 2181

集群节点同步问题

  1. 检查集群配置：

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

  2. 确认各节点myid是否唯一：

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

  3. 检查节点间网络连通性：

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

  4. 查看详细日志定位问题：

    docker logs --tail 100 zoo1

性能问题

  1. 检查系统资源使用情况：

    docker stats zookeeper

  2. 分析ZOO KEEPER性能指标：

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

  3. 常见性能问题解决：

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

日志分析

查看最近日志：

docker logs --tail 100 zookeeper

实时查看日志：

docker logs -f zookeeper

查看特定时间段的日志：

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镜像文档（轩辕）和官方文档。

Reference in New Issue View Git Blame Copy Permalink