一、ZooKeeper单机集群部署背景与需求

ZooKeeper作为分布式系统的协调服务框架，广泛应用于配置管理、命名服务、分布式锁等场景。在开发测试或小型项目中，单机部署的ZooKeeper集群（伪集群模式）既能满足基本功能需求，又能降低资源消耗和运维复杂度。Docker技术的普及使得环境搭建更加标准化和可复用，尤其适合快速部署和验证。本文将详细介绍如何使用Docker在单机环境下部署ZooKeeper集群，覆盖环境准备、镜像选择、配置文件编写及容器启动等全流程。

二、环境准备与Docker基础

1. Docker安装与验证

在Linux（推荐CentOS/Ubuntu）或macOS/Windows（需Docker Desktop）上安装Docker后，执行以下命令验证安装：

docker --version
docker run hello-world

若看到“Hello from Docker!”输出，则说明Docker环境正常。

2. 网络与存储规划

ZooKeeper集群需要节点间通信，建议创建专用Docker网络：

docker network create zk-net

数据持久化需挂载宿主机目录到容器，避免容器重启导致数据丢失。

三、ZooKeeper镜像选择与拉取

1. 官方镜像与第三方镜像对比

官方镜像：zookeeper:latest（基于OpenJDK）
第三方镜像：如bitnami/zookeeper（预配置优化）
推荐使用官方镜像，因其更新及时且文档完善。拉取命令：
```
docker pull zookeeper:latest
```

2. 镜像版本说明

3.7.0：稳定版，适合生产环境
latest：最新版，可能包含未充分测试的功能
生产环境建议指定版本号（如zookeeper:3.7.0）。

四、ZooKeeper单机集群配置

1. 伪集群原理

通过配置多个ZooKeeper实例（不同端口）在同一台机器上模拟集群，每个实例有独立的dataDir和clientPort。

2. 配置文件编写

创建zoo.cfg模板文件，内容如下：

tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data
clientPort=2181
server.1=localhost:2888:3888

tickTime：基本时间单位（毫秒）
initLimit：集群初始化时允许的连接超时次数
syncLimit：Leader与Follower同步的超时次数
dataDir：数据存储目录
clientPort：客户端连接端口
server.X：节点列表（格式：主机名:心跳端口:选举端口）

3. 多实例配置

创建三个配置文件（zoo1.cfg、zoo2.cfg、zoo3.cfg），分别修改以下参数：

dataDir：/data1、/data2、/data3
clientPort：2181、2182、2183
server.X中的X需与myid文件内容一致（见下文）

五、Docker容器启动与集群初始化

1. 创建数据目录与myid文件

在宿主机创建目录并写入节点ID：

mkdir -p /zk/data{1,2,3}
echo "1" > /zk/data1/myid
echo "2" > /zk/data2/myid
echo "3" > /zk/data3/myid

myid文件内容需与zoo.cfg中的server.X对应。

2. 启动容器

使用docker run命令启动三个容器，示例（以第一个节点为例）：

docker run -d \
  --name zk1 \
  --network zk-net \
  -p 2181:2181 \
  -v /zk/data1:/data \
  -v /path/to/zoo1.cfg:/conf/zoo.cfg \
  zookeeper:latest

-d：后台运行
--name：容器名称
--network：加入专用网络
-p：端口映射
-v：挂载数据目录和配置文件
重复上述命令，修改--name、-p和-v参数以启动zk2和zk3。

3. 验证集群状态

进入任意容器执行：

docker exec -it zk1 bash
echo stat | nc localhost 2181

输出应包含Mode: follower或Mode: leader，且三个节点均显示Followers或Leading状态。

六、常见问题与解决方案

1. 端口冲突

错误现象：容器启动失败，日志显示Address already in use。
解决方案：检查宿主机端口占用（netstat -tulnp | grep 2181），或修改clientPort并重新映射。

2. 数据目录权限

错误现象：容器启动后立即退出，日志显示Permission denied。
解决方案：确保宿主机数据目录对Docker进程有读写权限（chmod -R 777 /zk/data*）。

3. 集群无法选举Leader

错误现象：echo stat输出显示所有节点为Follower或Observing。
解决方案：检查zoo.cfg中的server.X配置是否正确，尤其是主机名和端口；确保myid文件内容与配置匹配。

七、优化建议与扩展

1. 资源限制

通过--memory和--cpus参数限制容器资源，避免单个节点占用过多资源：

docker run -d --memory="512m" --cpus="1.0" ...

2. 日志收集

使用docker logs -f zk1实时查看日志，或挂载日志目录到宿主机：

-v /zk/logs:/var/log/zookeeper

3. 扩展为真实集群

若需部署到多台机器，需修改server.X中的主机名为实际IP或域名，并确保网络互通。

八、总结与展望

通过Docker部署ZooKeeper单机集群，开发者可以快速验证分布式协调功能，降低环境搭建成本。本文覆盖了从环境准备到集群验证的全流程，并提供了常见问题的解决方案。未来可进一步探索Kubernetes下的ZooKeeper Operator部署，或集成Prometheus监控集群状态。

使用Docker快速部署ZooKeeper单机集群指南