ZooKeeper 单机部署指南

ZooKeeper 单机部署指南

本文是部署之后，用AI总结的部署方法，不保证一定能按照这个步骤部署成功，仅供参考；还有一点，这个文章里面说的zk_standalone_pkg.zip包是别人之前下载好的，这边是拿过来用的，也没放到这个平台，所以这个文章更多的是作为个人笔记使用，不保证一定能按照步骤部署好，因为有很多因素的影响。请读者降低预期。
本文档介绍如何使用 zk_standalone_pkg 部署包在单台云主机上快速部署 ZooKeeper 单节点服务。

一、前置准备

1.1 环境要求

• Linux 云主机（推荐 Ubuntu）
• 已准备好 zk_standalone_pkg.zip 部署包
• 开放端口：2181（ZooKeeper 客户端连接端口）

1.2 部署包说明

部署包 zk_standalone_pkg.zip 包含以下内容：

• zookeeper/ 目录
  • docker-compose.yaml - Docker Compose 配置文件
  • conf/ - ZooKeeper 配置文件目录
    • zoo.cfg - ZooKeeper 主配置文件
  • zookeeper_3.8.tar - ZooKeeper 3.8 Docker 镜像文件

二、部署步骤

2.1 上传并解压部署包

# 上传部署包到云主机（使用 scp 或其他方式）
# scp zk_standalone_pkg.zip user@your-server:/opt/

# 解压部署包
unzip -q zk_standalone_pkg.zip

# 进入解压后的目录
cd zookeeper/

2.2 处理 preload 相关报错（如遇到）

如果在后续步骤中遇到 preload 相关报错，执行以下操作：

# 备份原 preload 文件
sudo cp /etc/ld.so.preload /etc/ld.so.preload.bak

# 清空 preload 文件
sudo sh -c '> /etc/ld.so.preload'

2.3 安装 Docker

Ubuntu 系统

# 使用 snap 安装 Docker（推荐方式）
snap install docker

CentOS 系统

# 安装必要工具
sudo yum install -y yum-utils

# 添加 Docker 仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

2.4 加载 ZooKeeper 镜像

# 确保在 zookeeper 目录下，且 zookeeper_3.8.tar 文件存在
docker load -i zookeeper_3.8.tar

# 验证镜像是否加载成功
docker images | grep zookeeper

应该看到类似输出：

zookeeper    3.8    xxxxx    X minutes ago    XXX MB

2.5 安装 Docker Compose

Ubuntu 系统

apt install docker-compose

CentOS 系统

# 下载 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 赋予执行权限
sudo chmod +x /usr/local/bin/docker-compose

验证安装：

docker-compose --version

2.6 创建数据目录

# 创建数据目录（docker-compose.yaml 中使用的绝对路径）
sudo mkdir -p /data/zookeeper/data

# 创建日志目录（docker-compose.yaml 中使用的相对路径）
mkdir -p datalog

# 设置权限（ZooKeeper 容器内用户ID为1000）
sudo chown -R 1000:1000 /data/zookeeper/data
sudo chown -R 1000:1000 datalog

为什么需要手动创建目录和设置权限？

Docker 在挂载 volume 时，如果目标目录不存在，会自动创建这些目录 ，但创建的目录权限通常是 root:root（或当前执行 docker 命令的用户）。

为什么有时候不创建也能成功？

1. 如果使用 sudo 运行 docker-compose：自动创建的目录可能是 root 权限，但某些 Docker 配置或版本可能允许容器内用户写入
2. ZooKeeper 镜像的启动脚本：可能包含权限处理逻辑，会自动修复权限问题
3. 目录已存在且权限合适：如果目录之前已经创建过且权限正确

为什么建议手动创建？

1. 避免权限问题：确保 ZooKeeper 进程（用户ID 1000）有写入权限，避免后续运行时出现权限错误
2. 数据持久化安全：明确控制数据目录的所有者和权限，确保数据安全
3. 生产环境最佳实践：在生产环境中，明确设置权限是标准做法

如果跳过这一步，遇到权限问题时怎么办？

如果启动后 ZooKeeper 无法写入数据或日志，可以执行：

sudo chown -R 1000:1000 /data/zookeeper/data

sudo chown -R 1000:1000 /path/to/zookeeper/datalog

docker-compose restart

```

2.7 启动 ZooKeeper 服务

# 确保在 zookeeper 目录下
cd /data/zookeeper/  # 注意：根据参考文件，应该在这个目录下执行
# 或者如果 docker-compose.yaml 在 zookeeper 目录下，则：
# cd /path/to/zookeeper/

# 启动服务（后台运行）
docker-compose up -d

2.8 验证部署

检查容器状态

# 查看容器是否运行
docker ps

应该看到类似输出：

CONTAINER ID   IMAGE            STATUS         PORTS                    NAMES
xxxxx          zookeeper:3.8    Up X minutes   0.0.0.0:2181->2181/tcp  zookeeper-standalone

检查端口监听

# 检查 2181 端口是否监听
ss -antulp | grep 2181

应该看到类似输出：

tcp   LISTEN  0  50  *:2181  *:*  users:(("java",pid=xxxxx,fd=xx))

查看启动日志

# 查看容器启动日志
docker-compose logs

# 实时查看日志
docker-compose logs -f

看到以下输出表示启动成功：

zookeeper-standalone  | ZooKeeper JMX enabled by default
zookeeper-standalone  | Using config: /conf/zoo.cfg
zookeeper-standalone  | Client port found: 2181. Client address: localhost. Client SSL: false.
zookeeper-standalone  | Mode: standalone

按 Ctrl+C 退出日志查看。

三、功能验证

3.1 使用四字命令验证

# 检查服务是否正常（返回 imok 表示正常）
echo ruok | nc localhost 2181

# 查看服务状态
echo stat | nc localhost 2181

# 查看配置信息
echo conf | nc localhost 2181

3.2 使用 zkCli 连接测试

# 进入容器并使用 zkCli 连接
docker exec -it zookeeper-standalone zkCli.sh

# 在 zkCli 中执行测试命令
[zk: localhost:2181(CONNECTED) 0] ls /
[zk: localhost:2181(CONNECTED) 1] create /test "hello"
[zk: localhost:2181(CONNECTED) 2] get /test
[zk: localhost:2181(CONNECTED) 3] quit

四、常用运维命令

4.1 服务管理

# 进入部署目录
cd /data/zookeeper/  # 或 docker-compose.yaml 所在目录

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看日志（实时）
docker-compose logs -f

# 查看最近100行日志
docker-compose logs --tail=100

4.2 查看服务状态

# 查看容器状态
docker ps | grep zookeeper

# 查看 ZooKeeper 服务状态
docker exec zookeeper-standalone zkServer.sh status

# 查看容器资源使用情况
docker stats zookeeper-standalone

4.3 数据备份

# 备份数据目录
sudo tar -czf zk-backup-$(date +%Y%m%d-%H%M%S).tar.gz /data/zookeeper/data

# 恢复数据（需要先停止服务）
docker-compose down
sudo tar -xzf zk-backup-20260126-120000.tar.gz -C /
docker-compose up -d

五、常见问题排查

5.1 preload 相关报错

如果启动时遇到 preload 相关错误：

# 备份原文件
sudo cp /etc/ld.so.preload /etc/ld.so.preload.bak

# 清空 preload 文件
sudo sh -c '> /etc/ld.so.preload'

# 重启 Docker 服务
sudo systemctl restart docker

# 重新启动 ZooKeeper
cd /data/zookeeper/  # 或 docker-compose.yaml 所在目录
docker-compose up -d

5.2 容器启动失败

# 查看详细错误日志
docker-compose logs

# 检查端口是否被占用
sudo lsof -i :2181
# 如果被占用，杀掉进程或修改 docker-compose.yaml 中的端口映射

5.3 数据目录权限问题

# 修改目录权限
sudo chown -R 1000:1000 /data/zookeeper/data
sudo chown -R 1000:1000 /path/to/zookeeper/datalog

5.4 无法连接 ZooKeeper

# 检查防火墙规则
sudo iptables -L -n | grep 2181
# 或
sudo firewall-cmd --list-ports

# 开放端口（Ubuntu）
sudo ufw allow 2181/tcp

# 开放端口（CentOS）
sudo firewall-cmd --permanent --add-port=2181/tcp
sudo firewall-cmd --reload

5.5 Docker 镜像加载失败

# 检查镜像文件是否存在
ls -lh zookeeper_3.8.tar

# 重新加载镜像
docker load -i zookeeper_3.8.tar

# 如果镜像文件损坏，需要重新获取镜像文件

六、部署检查清单

部署完成后，请确认以下事项：

• 部署包已解压到目标目录
• Docker 已安装（Ubuntu 使用 snap install docker）
• ZooKeeper 镜像已加载（docker load -i zookeeper_3.8.tar）
• Docker Compose 已安装
• /data/zookeeper/data 目录已创建并设置权限
• datalog 目录已创建并设置权限
• 容器已成功启动（docker ps 可以看到）
• 2181 端口已监听（ss -antulp | grep 2181）
• 四字命令返回 imok（echo ruok | nc localhost 2181）
• zkCli 可以正常连接并操作

七、快速部署脚本

如果需要一键部署，可以创建以下脚本：

#!/bin/bash
# quick-deploy.sh - ZooKeeper 快速部署脚本

set -e

DEPLOY_DIR="/data/zookeeper"
DATA_DIR="/data/zookeeper/data"

echo "=== ZooKeeper 快速部署开始 ==="

# 检查是否在正确的目录
if [ ! -f "docker-compose.yaml" ]; then
    echo "错误: 请在包含 docker-compose.yaml 的目录下执行此脚本"
    exit 1
fi

# 检查 Docker
if ! command -v docker &> /dev/null; then
    echo "错误: Docker 未安装，请先安装 Docker"
    echo "Ubuntu: snap install docker"
    echo "CentOS: yum install docker-ce"
    exit 1
fi

if ! command -v docker-compose &> /dev/null; then
    echo "错误: Docker Compose 未安装，请先安装 Docker Compose"
    exit 1
fi

# 处理 preload 问题（如果需要）
if [ -f /etc/ld.so.preload ] && [ -s /etc/ld.so.preload ]; then
    echo "备份并清空 /etc/ld.so.preload..."
    sudo cp /etc/ld.so.preload /etc/ld.so.preload.bak
    sudo sh -c '> /etc/ld.so.preload'
fi

# 加载镜像（如果存在）
if [ -f "zookeeper_3.8.tar" ]; then
    echo "加载 ZooKeeper 镜像..."
    docker load -i zookeeper_3.8.tar
else
    echo "警告: zookeeper_3.8.tar 文件不存在，将使用 Docker Hub 镜像"
fi

# 创建数据目录
echo "创建数据目录..."
sudo mkdir -p $DATA_DIR
mkdir -p datalog
sudo chown -R 1000:1000 $DATA_DIR
sudo chown -R 1000:1000 datalog

# 启动服务
echo "启动 ZooKeeper 服务..."
docker-compose up -d

# 等待服务启动
echo "等待服务启动..."
sleep 5

# 验证服务
echo "验证服务状态..."
if docker ps | grep -q zookeeper-standalone; then
    echo "✓ 容器已启动"
else
    echo "✗ 容器启动失败，请查看日志: docker-compose logs"
    exit 1
fi

if echo ruok | nc localhost 2181 2>/dev/null | grep -q imok; then
    echo "✓ ZooKeeper 服务正常"
else
    echo "✗ ZooKeeper 服务异常，请检查: docker-compose logs"
    exit 1
fi

echo "=== 部署完成 ==="
echo "服务地址: localhost:2181"
echo "查看日志: docker-compose logs -f"
echo "停止服务: docker-compose down"

使用方法：

# 赋予执行权限
chmod +x quick-deploy.sh

# 在包含 docker-compose.yaml 的目录下执行
./quick-deploy.sh

八、总结

基于 zk_standalone_pkg 部署包的单机部署流程：

1. 解压部署包 ：unzip -q zk_standalone_pkg.zip
2. 处理 preload ：备份并清空 /etc/ld.so.preload（如遇到报错）
3. 安装 Docker ：Ubuntu 使用 snap install docker
4. 加载镜像 ：docker load -i zookeeper_3.8.tar
5. 安装 Docker Compose ：apt install docker-compose
6. 创建目录：创建数据目录和日志目录，设置权限
7. 启动服务 ：docker-compose up -d
8. 验证部署：检查容器状态、端口监听、服务健康度

预计时间分配：

• Docker 安装：5-10分钟
• 解压和准备：2分钟
• 加载镜像：1-2分钟
• 创建目录和启动：2分钟
• 验证部署：2分钟
• 总计：约15-20分钟

---

相关资源：

• ZooKeeper 官方文档
• Docker Hub - ZooKeeper 官方镜像
• Docker Compose 官方文档