一、环境准备与背景说明

ZooKeeper作为分布式系统的协调服务，广泛应用于配置管理、分布式锁、服务发现等场景。在开发测试或轻量级生产环境中，单机部署ZooKeeper可以快速验证功能，同时避免复杂的集群配置。Docker的轻量化特性使其成为单机部署的理想选择，能够隔离依赖、简化环境管理。

1.1 系统要求与依赖检查

操作系统：推荐Linux（如Ubuntu 20.04+）或macOS（Docker Desktop支持）
Docker版本：建议使用最新稳定版（如Docker Engine 24.x）
资源需求：至少2GB内存、2核CPU（测试环境可适当降低）
网络配置：确保主机可访问Docker守护进程（默认2375/2376端口）

1.2 部署模式选择

单机部署ZooKeeper有两种常见模式：

伪集群模式：在单个Docker容器内运行多个ZooKeeper实例（通过不同端口模拟集群）
单实例模式：直接运行单个ZooKeeper节点（适用于非高可用场景）

本文重点讲解单实例模式，因其配置简单且能满足大多数开发测试需求。若需伪集群模式，可通过docker-compose配置多个服务实例。

二、Docker部署ZooKeeper的详细步骤

2.1 拉取官方镜像

ZooKeeper官方提供了Docker镜像（zookeeper:latest），推荐使用稳定版本（如zookeeper:3.8.1）：

docker pull zookeeper:3.8.1

验证镜像：

docker images | grep zookeeper

2.2 启动单实例容器

使用以下命令启动ZooKeeper容器：

docker run -d \
  --name zookeeper \
  -p 2181:2181 \
  -e ZOO_MY_ID=1 \
  -e ZOO_SERVERS="server.1=0.0.0.0:2888:3888" \
  -v /path/to/data:/data \
  -v /path/to/datalog:/datalog \
  zookeeper:3.8.1

参数说明：

-p 2181:2181：将容器2181端口映射到主机
-e ZOO_MY_ID=1：设置节点ID（单机模式可忽略，但伪集群需唯一）
-e ZOO_SERVERS：配置服务器列表（单机模式可简化为单节点）
-v：挂载数据卷（持久化数据）

简化版命令（推荐开发环境）：

docker run -d --name zookeeper -p 2181:2181 zookeeper:3.8.1

2.3 配置优化建议

2.3.1 自定义配置文件

若需修改zoo.cfg，可创建自定义配置文件并挂载到容器：

# 创建配置文件
cat > /path/to/custom_zoo.cfg <<EOF
tickTime=2000
dataDir=/data
clientPort=2181
maxClientCnxns=60
EOF
# 启动容器时挂载配置
docker run -d \
  --name zookeeper \
  -p 2181:2181 \
  -v /path/to/custom_zoo.cfg:/conf/zoo.cfg \
  zookeeper:3.8.1

2.3.2 资源限制

通过--memory和--cpus限制容器资源：

docker run -d \
  --name zookeeper \
  --memory="1g" \
  --cpus="1.5" \
  -p 2181:2181 \
  zookeeper:3.8.1

三、验证部署与基础操作

3.1 检查容器状态

docker ps | grep zookeeper
docker logs zookeeper  # 查看启动日志

3.2 连接ZooKeeper客户端

使用zkCli.sh连接本地ZooKeeper：

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

常用命令：

ls /：查看根节点
create /test_node "data"：创建节点
get /test_node：获取节点数据
delete /test_node：删除节点

3.3 伪集群模式配置（进阶）

若需模拟集群环境，可使用docker-compose：

version: '3'
services:
  zk1:
    image: zookeeper:3.8.1
    ports:
      - "2181:2181"
    environment:
      ZOO_MY_ID: 1
      ZOO_SERVERS: "server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181"
  zk2:
    image: zookeeper:3.8.1
    ports:
      - "2182:2181"
    environment:
      ZOO_MY_ID: 2
      ZOO_SERVERS: "server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181"
  zk3:
    image: zookeeper:3.8.1
    ports:
      - "2183:2181"
    environment:
      ZOO_MY_ID: 3
      ZOO_SERVERS: "server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181"

启动命令：

docker-compose up -d

四、常见问题与解决方案

4.1 端口冲突

问题：主机2181端口被占用。
解决：修改映射端口或停止占用进程：

# 查找占用端口的进程
sudo lsof -i :2181
# 停止进程（根据实际PID）
kill -9 <PID>

4.2 数据持久化失败

问题：容器重启后数据丢失。
解决：确保正确挂载数据卷：

# 创建数据目录
mkdir -p /var/zookeeper/{data,datalog}
# 启动时挂载
docker run -d \
  --name zookeeper \
  -p 2181:2181 \
  -v /var/zookeeper/data:/data \
  -v /var/zookeeper/datalog:/datalog \
  zookeeper:3.8.1

4.3 性能调优

JVM参数：通过JAVA_OPTS环境变量调整堆内存：

docker run -d \
  --name zookeeper \
  -p 2181:2181 \
  -e JAVA_OPTS="-Xms512m -Xmx1024m" \
  zookeeper:3.8.1

日志级别：修改log4j.properties（需挂载自定义配置）

五、总结与最佳实践

开发环境：优先使用单实例模式，简化配置。
生产环境：建议使用Kubernetes或Docker Swarm部署集群。
监控：集成Prometheus+Grafana监控ZooKeeper指标（如zk_server_state）。
备份：定期备份/data目录下的version-2文件夹。

通过Docker部署ZooKeeper，开发者可以快速构建可复用的测试环境，同时避免直接操作主机系统的复杂性。对于更复杂的场景，可结合docker-compose或编排工具实现自动化管理。

Docker单机部署ZooKeeper全攻略