ZooKeeper 3.4.13 单机安装详解

**摘要：**本文详细介绍了 ZooKeeper 3.4.13 单机版的完整安装与配置流程。内容涵盖环境准备（JDK 检查与安装）、ZooKeeper 下载解压、核心配置文件（zoo.cfg 与 log4j.properties）编写、环境变量配置、服务启动与状态检查、客户端连接测试、开机自启设置，以及常见问题排查。教程以 CentOS 7 为例，步骤清晰，适合初学者快速搭建 ZooKeeper 开发测试环境。

[1. 前言](#1. 前言)

[2. 环境准备](#2. 环境准备)

[2.1 检查 JDK 版本](#2.1 检查 JDK 版本)

[2.2 确认系统环境](#2.2 确认系统环境)

[3. 下载 ZooKeeper 3.4.13](#3. 下载 ZooKeeper 3.4.13)

[4. 解压与安装](#4. 解压与安装)

[5. 配置 ZooKeeper](#5. 配置 ZooKeeper)

[5.1 创建数据目录](#5.1 创建数据目录)

[5.2 编写 zoo.cfg 配置文件](#5.2 编写 zoo.cfg 配置文件)

5.3编辑log4j.properties

[6. 配置环境变量（可选）](#6. 配置环境变量（可选）)

[7. 启动 ZooKeeper](#7. 启动 ZooKeeper)

[8. 验证与测试](#8. 验证与测试)

[8.1 使用自带客户端连接](#8.1 使用自带客户端连接)

[8.2 检查端口监听](#8.2 检查端口监听)

[9. 配置开机自启（可选）](#9. 配置开机自启（可选）)

[10. 常见问题排查](#10. 常见问题排查)

[10.1 启动报错 "Error: Could not find or load main class"](#10.1 启动报错 "Error: Could not find or load main class")

[10.2 端口被占用](#10.2 端口被占用)

[10.3 dataDir 目录权限不足](#10.3 dataDir 目录权限不足)

[11. 总结](#11. 总结)

1. 前言

Apache ZooKeeper 是一个分布式协调服务，广泛应用于 Dubbo、Kafka、HBase 等分布式系统中，负责配置管理、命名服务、分布式锁、集群管理等功能。本文以 CentOS 7 环境为例，详细介绍 ZooKeeper 3.4.13 单机版的安装与配置流程，适合初学者快速上手。

2. 环境准备

安装 ZooKeeper 之前，需要确保系统中已安装 JDK。ZooKeeper 3.4.13 要求 JDK 1.7 及以上版本，推荐使用 JDK 1.8。

2.1 检查 JDK 版本

bash 复制代码

java -version

如果未安装 JDK，请先执行以下命令安装 OpenJDK 1.8：

bash 复制代码

yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel

2.2 确认系统环境

本文演示环境为 CentOS 7.6，其他 Linux 发行版（如 Ubuntu）操作步骤基本一致，仅包管理命令略有差异。

3. 下载 ZooKeeper 3.4.13

ZooKeeper 官方提供了各版本的镜像下载地址。推荐从 Apache 归档站点下载：

bash 复制代码

cd /usr/local/src
wget https://archive.apache.org/dist/zookeeper/zookeeper-3.4.13/zookeeper-3.4.13.tar.gz

如果服务器网络受限，也可以提前下载到本地，再通过 FTP/SCP 上传至服务器。

4. 解压与安装

将下载好的压缩包解压到 /usr/local/ 目录下，并重命名目录以方便后续维护：

bash 复制代码

tar -zxvf zookeeper-3.4.13.tar.gz -C /usr/local/
mv /usr/local/zookeeper-3.4.13 /usr/local/zookeeper

解压后的目录结构如下：

bin/：存放启动、停止脚本以及客户端命令行工具。
conf/ ：配置文件目录，核心配置为 zoo.cfg。
lib/：ZooKeeper 运行所需的依赖 jar 包。
data/（需手动创建）：存放快照和事务日志。

5. 配置 ZooKeeper

5.1 创建数据目录

bash 复制代码

mkdir -p /usr/local/zookeeper/data

5.2 编写 zoo.cfg 配置文件

进入 conf 目录，将示例配置文件复制为实际使用的配置文件：

bash 复制代码

cd /usr/local/zookeeper/conf
cp zoo_sample.cfg zoo.cfg

编辑 zoo.cfg，修改以下关键参数：

bash 复制代码

vim zoo.cfg

核心配置项说明：

properties 复制代码

# ZooKeeper 基本时间单元，单位为毫秒，所有超时时间都以此为基础
tickTime=2000
Follower 启动时与 Leader 同步数据的超时时间
initLimit=10
Follower 与 Leader 之间心跳的最大延迟
syncLimit=5
快照和事务日志的存储目录
dataDir=/usr/local/zookeeper/data
dataLogDir=/usr/local/zookeeper/data-log
客户端连接端口
clientPort=2181

单机部署只需关注上述几项配置即可，dataDir 务必指向实际存在且有写入权限的目录。

5.3编辑log4j.properties

bash 复制代码

vim log4j.properties

修改日志目录

bash 复制代码

zookeeper.tracelog.dir=/home/erbao/zookeeper/zookeeper-3.4.13/logs
zookeeper.log.dir=/home/erbao/zookeeper/zookeeper-3.4.13/logs

6. 配置环境变量（可选）

为方便在任何目录下直接使用 ZooKeeper 命令，建议将其 bin 目录追加到系统 PATH 中：

bash 复制代码

echo 'export ZOOKEEPER_HOME=/usr/local/zookeeper' >> /etc/profile
echo 'export PATH=$ZOOKEEPER_HOME/bin:$PATH' >> /etc/profile
source /etc/profile

7. 启动 ZooKeeper

执行以下命令启动 ZooKeeper 服务：

bash 复制代码

cd /usr/local/zookeeper/bin
./zkServer.sh start

启动成功后，终端输出类似：

text 复制代码

ZooKeeper JMX enabled by default
Using config: /usr/local/zookeeper/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED

查看服务状态：

bash 复制代码

./zkServer.sh status

单机模式下状态显示为 standalone，表示 ZooKeeper 已成功运行。

8. 验证与测试

8.1 使用自带客户端连接

ZooKeeper 提供了命令行客户端 zkCli.sh，用于连接服务并执行读写操作：

bash 复制代码

./zkCli.sh -server 127.0.0.1:2181

连接成功后进入交互式命令行，可以测试以下基本操作：

bash 复制代码

# 创建节点
create /test "hello-zookeeper"
查看节点数据
get /test
列出根节点下的所有子节点
ls /
删除节点
delete /test

8.2 检查端口监听

bash 复制代码

netstat -tlnp | grep 2181

如果看到端口 2181 处于 LISTEN 状态，说明 ZooKeeper 服务已正常监听。

9. 配置开机自启（可选）

使用 systemd 管理 ZooKeeper 服务，方便开机自动启动和服务管理。创建服务文件：

bash 复制代码

vim /etc/systemd/system/zookeeper.service

写入以下内容：

ini 复制代码

[Unit]
Description=Apache ZooKeeper
After=network.target
[Service]
Type=forking
Environment=ZOO_LOG_DIR=/usr/local/zookeeper/logs
ExecStart=/usr/local/zookeeper/bin/zkServer.sh start
ExecStop=/usr/local/zookeeper/bin/zkServer.sh stop
ExecReload=/usr/local/zookeeper/bin/zkServer.sh restart
Restart=on-failure
[Install]
WantedBy=multi-user.target

启用并启动服务：

bash 复制代码

systemctl daemon-reload
systemctl enable zookeeper
systemctl start zookeeper

10. 常见问题排查

10.1 启动报错 "Error: Could not find or load main class"

通常是 JDK 未安装或 JAVA_HOME 环境变量未配置。请检查 java -version 是否正常输出，必要时在 /etc/profile 中配置 JAVA_HOME。

10.2 端口被占用

如果 2181 端口已被其他进程占用，可以在 zoo.cfg 中修改 clientPort 为其他端口（如 2182），然后重启服务。

10.3 dataDir 目录权限不足

确保 dataDir 指定的目录存在且当前用户有读写权限，否则 ZooKeeper 无法写入快照和日志文件，导致启动失败。

11. 总结

本文详细介绍了 ZooKeeper 3.4.13 单机版的完整安装流程，涵盖环境准备、下载解压、配置编写、服务启动、客户端测试以及开机自启配置。单机模式主要用于开发测试和学习场景，生产环境中请务必部署奇数节点的集群模式以保证高可用。希望本文能帮助你快速搭建 ZooKeeper 环境，为后续的分布式系统学习打下基础。