一、前置准备

确保本地已安装 Docker 环境（Docker Desktop 或 Docker Engine），验证 Docker 可用性：

# 查看 Docker 版本，验证环境正常运行
docker --version

二、第一步：选择并拉取 Zookeeper 镜像

1. 镜像来源（推荐官方稳定镜像）

Zookeeper 有 Docker Hub 官方维护镜像（zookeeper），版本齐全、更新及时、兼容性好，是首选方案，无需额外寻找第三方镜像。

2. 拉取 Zookeeper 镜像（核心命令）

# 拉取最新稳定版 Zookeeper 镜像（推荐，自动获取最新 LTS 版本）
docker pull zookeeper:latest

# 可选：指定具体稳定版本（如 3.8.4，避免版本变动带来的兼容问题）
docker pull zookeeper:3.8.4

• 说明：Zookeeper 3.5+ 版本新增了 Admin Server 功能，后续 Web UI 访问依赖该功能，推荐拉取 3.5+ 版本。

3. 验证镜像拉取成功

# 查看本地已拉取的 Zookeeper 镜像
docker images | grep zookeeper

执行后若能看到镜像名称（zookeeper）、对应标签（latest 或 3.8.4）和镜像体积，说明镜像拉取成功。

三、第二步：启动 Zookeeper 单机版容器（核心命令）

执行以下命令一键启动 Zookeeper 单机容器，映射必要端口和数据卷（保证数据持久化和外部可访问）：

# 启动 Zookeeper 单机版容器（核心命令）
docker run -d \
  --name zk-single \
  --restart always \
  -p 2181:2181 \
  -p 8080:8080 \
  -v /usr/local/zk/data:/data \
  -v /usr/local/zk/datalog:/datalog \
  -e ZOO_MY_ID=1 \
  zookeeper:latest

命令参数详细说明（理解每个参数的作用）

三、第三步：验证 Zookeeper 单机版启动成功

1. 查看容器运行状态

# 查看 Zookeeper 容器是否正常运行（状态为 Up 即成功）
docker ps | grep zk-single

• 若状态显示 Up X minutes（已运行 X 分钟），说明容器启动成功；
• 若状态异常（如 Exited），可执行 docker logs zk-single 查看容器日志，定位具体错误（常见错误为目录权限不足、端口被占用）。

2. 访问 Zookeeper Web UI（浏览器验证，3.5+ 版本支持）

打开本地浏览器，输入以下地址，能看到 Zookeeper 节点状态、配置信息即成功：

• 核心查看项：Mode 显示为 standalone（单机模式），说明部署模式正确；Server State 显示为 running，说明服务正常运行。

3. 进入 Zookeeper 客户端（终端验证操作）

方式 1：进入容器内部使用 zkCli.sh（推荐）

# 1. 进入 Zookeeper 容器内部
docker exec -it zk-single bash

# 2. 启动 Zookeeper 交互式客户端（核心命令）
zkCli.sh

方式 2：直接在本地终端执行客户端命令（无需进入容器）

# 直接通过 Docker 命令启动 Zookeeper 客户端，无需进入容器
docker exec -it zk-single zkCli.sh

客户端常用命令验证（进入客户端后执行）

# 1. 查看 Zookeeper 根节点下的所有子节点（初始为空）
ls /

# 2. 创建一个测试节点（临时节点，退出客户端后自动删除）
create /test "hello-zookeeper"

# 3. 查看创建的节点数据
get /test

# 4. 修改节点数据
set /test "hello-docker-zk"

# 5. 删除测试节点
delete /test

• 执行以上命令均无报错，且能正常查询、修改数据，说明 Zookeeper 单机版功能正常。

四、常用辅助命令（后续操作必备）

1. 停止 Zookeeper 容器

2. 重启 Zookeeper 容器

3. 删除 Zookeeper 容器（谨慎操作，删除前先停止）

# 1. 先停止容器
docker stop zk-single

# 2. 再删除容器
docker rm zk-single

4. 查看 Zookeeper 容器日志（排查错误）

# 实时查看日志（按 Ctrl+C 退出实时监控）
docker logs -f zk-single

# 查看最近 200 行日志（适合快速定位近期错误）
docker logs --tail 200 zk-single

五、常见问题排查

1. 端口 2181 被占用：

• 错误日志提示 Address already in use，说明 2181 端口被其他进程占用；
• 解决方案：修改端口映射，如 -p 2182:2181，后续客户端连接使用 2182 端口。

2. 数据目录权限不足：

• 错误日志提示 Permission denied，说明本地挂载目录无读写权限；
• 解决方案：给本地目录赋予读写权限，chmod -R 777 /usr/local/zk。

3. Web UI 无法访问（8080 端口）：

• 确认 Zookeeper 版本为 3.5+（3.4 及以下版本无 Admin Server，不支持 Web UI）；
• 确认端口映射正确，无其他进程占用 8080 端口。

六、总结

1. 镜像来源：首选 Docker Hub 官方镜像 zookeeper，通过 docker pull zookeeper:latest（或指定版本）拉取；
2. 核心启动命令：docker run 配合端口映射、数据卷挂载、环境变量配置，实现 Zookeeper 单机版一键启动；
3. 验证方式：通过 docker ps 查看容器状态、浏览器访问 Web UI、zkCli.sh 客户端操作，三重验证确保服务正常；
4. 关键注意：数据卷挂载保证数据持久化，--restart always 提升服务稳定性，2181 端口是客户端连接的核心端口。 

按照以上步骤，即可快速通过 Docker 搭建 Zookeeper 单机版环境，无需复杂配置，适合开发测试和快速上手 Zookeeper 基本操作。