# Apache ZooKeeper Docker 容器化部署指南

![Apache ZooKeeper Docker 容器化部署指南](https://assets.xuanyuan.me/docker/blog/docker-apache-zookeeper.png)

*分类: 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
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
```


备用地址：

```bash
bash <(wget -qO- https://get.xuanyuan.me/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镜像标签列表](https://xuanyuan.cloud/r/library/zookeeper/tags)。

## 容器部署

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集群仅用于测试，不提供真正的冗余。生产环境中，每个节点应部署在独立的物理机上。

### 自定义配置文件部署

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

1. 首先创建自定义配置文件`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
```

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

```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
  ```
- 确保各节点部署在不同的物理机或可用区，避免单点故障

## 故障排查

### 容器启动失败

1. 检查容器日志：
   ```bash
   docker logs zookeeper
   ```

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

### 连接问题

1. 检查容器是否正常运行：
   ```bash
   docker inspect -f '{{.State.Status}}' zookeeper
   ```

2. 检查端口映射是否正确：
   ```bash
   docker port zookeeper
   ```

3. 检查防火墙规则：
   ```bash
   # 查看防火墙状态
   systemctl status firewalld
   
   # 检查端口是否开放
   firewall-cmd --list-ports | grep 2181
   ```

4. 检查网络连接：
   ```bash
   telnet localhost 2181
   ```

### 集群节点同步问题

1. 检查集群配置：
   ```bash
   docker exec -it zoo1 cat /conf/zoo.cfg
   ```

2. 确认各节点`myid`是否唯一：
   ```bash
   docker exec -it zoo1 cat /data/myid
   docker exec -it zoo2 cat /data/myid
   docker exec -it zoo3 cat /data/myid
   ```

3. 检查节点间网络连通性：
   ```bash
   docker exec -it zoo1 ping zoo2
   docker exec -it zoo1 ping zoo3
   ```

4. 查看详细日志定位问题：
   ```bash
   docker logs --tail 100 zoo1
   ```

### 性能问题

1. 检查系统资源使用情况：
   ```bash
   docker stats zookeeper
   ```

2. 分析ZOO KEEPER性能指标：
   ```bash
   curl http://localhost:8080/commands/stat
   ```

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

### 日志分析

查看最近日志：
```bash
docker logs --tail 100 zookeeper
```

实时查看日志：
```bash
docker logs -f zookeeper
```

查看特定时间段的日志：
```bash
docker logs zookeeper | grep "2023-11-15 08:30"
```

## 参考资源

- [ZOO KEEPER镜像文档（轩辕）](https://xuanyuan.cloud/r/library/zookeeper)
- [ZOO KEEPER镜像标签列表](https://xuanyuan.cloud/r/library/zookeeper/tags)
- [Apache ZOO KEEPER官方网站](https://zookeeper.apache.org/)
- [Apache ZOO KEEPER官方文档](https://zookeeper.apache.org/doc/current/)
- [Docker官方文档](https://docs.docker.com/)
- [Docker Compose文档](https://docs.docker.com/compose/)

## 总结

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

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

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

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