Ubuntu 24.04 生产环境 Apache ZooKeeper 3.8.6 安装与配置指南项目说明适用系统Ubuntu 24.04 LTSZooKeeper 版本3.8.6稳定版安装目录/data/zookeeper数据目录/data/zk-data日志目录/data/logs/zookeeper运行用户zookeeper专用系统用户客户端端口2181服务管理systemd一、背景说明Apache ZooKeeper 是一个分布式协调服务为分布式系统提供配置管理、命名服务、分布式同步和组服务等功能。它是 Kafka、HBase、Dubbo 等众多分布式系统的核心依赖。版本选择说明ZooKeeper 3.8.6 是当前稳定版本相比 3.6.x 系列主要改进包括日志框架从 Log4j 1.x 迁移至LogBack更安全、更灵活支持 JDK 8、11、17推荐使用 JDK 11增强的 AdminServer 和监控指标多项性能优化和安全修复生产环境提示生产环境应部署3 或 5 个节点的 ZooKeeper 集群Ensemble。本指南涵盖单机部署并附有集群配置要点。二、前提条件拥有服务器的root 权限或sudo权限已安装Java 8 或更高版本ZooKeeper 3.8.x 支持 JDK 8生产环境推荐 JDK 11服务器能够访问互联网下载软件包最低硬件配置2 CPU 核心、4 GB 内存、20 GB 可用磁盘空间注意如果尚未安装 JDK请参考《Ubuntu 24.04 生产环境 Adoptium Temurin JDK 8 安装与配置指南》完成安装。三、安装步骤3.1 创建专用运行用户为保障生产环境安全ZooKeeper 应使用专属系统用户运行。sudoadduser--system--no-create-home--groupzookeeper3.2 创建目录结构# 下载目录sudomkdir-p/data# 安装目录sudomkdir-p/data/zookeeper# 数据目录sudomkdir-p/data/zk-data# 日志目录sudomkdir-p/data/logs/zookeeper# 设置目录所有权sudochown-Rzookeeper:zookeeper /data/zookeepersudochown-Rzookeeper:zookeeper /data/zk-datasudochown-Rzookeeper:zookeeper /data/logs/zookeeper3.3 下载 ZooKeeper进入/data目录下载 ZooKeeper 3.8.6 二进制包。cd/datasudowgethttps://downloads.apache.org/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz提示如果下载速度较慢可替换为国内镜像源如华为云镜像sudowgethttps://repo.huaweicloud.com/apache/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz3.4 解压并安装sudotar-xzfapache-zookeeper-3.8.6-bin.tar.gz-C/data/zookeeper --strip-components1--strip-components1参数会解压内容直接放入/data/zookeeper而非创建版本号子目录。3.5 验证安装文件ls-la/data/zookeeper应看到bin、conf、lib等目录。四、配置 ZooKeeper4.1 创建配置文件ZooKeeper 提供示例配置文件需复制为zoo.cfg并进行修改。sudocp/data/zookeeper/conf/zoo_sample.cfg /data/zookeeper/conf/zoo.cfgsudochownzookeeper:zookeeper /data/zookeeper/conf/zoo.cfg4.2 编辑配置文件sudovim/data/zookeeper/conf/zoo.cfg单机模式基本配置# 时间单元毫秒 tickTime2000 # 初始同步超时tick 数 initLimit10 # 请求确认超时tick 数 syncLimit5 # 数据目录 dataDir/data/zk-data # 客户端端口 clientPort2181 # 最大客户端连接数 maxClientCnxns60 # 自动清理配置生产环境推荐 autopurge.snapRetainCount3 autopurge.purgeInterval1 # 日志目录覆盖默认的 logs 目录 dataLogDir/data/logs/zookeeper配置项说明配置项说明推荐值tickTime基本时间单元毫秒2000initLimitFollower 初始同步超时tick 数10syncLimit请求确认超时tick 数5dataDir快照存储目录/data/zk-datadataLogDir事务日志存储目录/data/logs/zookeeperclientPort客户端连接端口2181maxClientCnxns最大客户端连接数60autopurge.snapRetainCount保留快照数量3autopurge.purgeInterval清理间隔小时1五、配置 systemd 服务5.1 创建环境变量文件⚠️ 关键格式说明systemd 的EnvironmentFile要求文件内容必须遵循KEYvalue格式禁止使用export关键字否则变量不会被加载导致日志目录等配置失效。sudovim/etc/default/zookeeper写入以下内容注意不带exportZOOCFGDIR/data/zookeeper/conf ZOO_LOG_DIR/data/logs/zookeeper ZOO_LOG4J_PROPINFO,ROLLINGFILE验证文件格式cat/etc/default/zookeeper输出应为ZOOCFGDIR/data/zookeeper/conf ZOO_LOG_DIR/data/logs/zookeeper ZOO_LOG4J_PROPINFO,ROLLINGFILE5.2 创建服务单元文件配置说明ZooKeeper 的zkServer.sh start启动后会进入后台运行并在数据目录下生成zookeeper_server.pid文件。因此systemd 服务需要使用Typeforking并指定PIDFile以便 systemd 正确跟踪进程状态。如果使用Typesimplesystemd 会在脚本退出后认为服务已停止导致服务被终止。sudovim/etc/systemd/system/zookeeper.service粘贴以下内容[Unit] DescriptionApache ZooKeeper Server Afternetwork.target [Service] Typeforking Userzookeeper Groupzookeeper EnvironmentFile/etc/default/zookeeper PIDFile/data/zk-data/zookeeper_server.pid ExecStart/data/zookeeper/bin/zkServer.sh start ExecStop/data/zookeeper/bin/zkServer.sh stop ExecReload/data/zookeeper/bin/zkServer.sh restart Restarton-failure RestartSec3s [Install] WantedBymulti-user.target关键配置项说明配置项说明Typeforking适用于后台启动的服务systemd 通过 PID 文件跟踪进程PIDFile/data/zk-data/zookeeper_server.pid指定 PID 文件路径ZooKeeper 自动生成EnvironmentFile/etc/default/zookeeper加载环境变量注意文件内不能有 export5.3 重载 systemd 配置sudosystemctl daemon-reload5.4 启动并启用服务sudosystemctl start zookeepersudosystemctlenablezookeepersudosystemctl status zookeeper六、验证部署6.1 检查服务状态sudosystemctl status zookeeper预期输出Active: active (running)。6.2 检查 ZooKeeper 运行模式/data/zookeeper/bin/zkServer.sh status单机模式输出Mode: standalone。6.3 验证日志文件位置ls-la/data/logs/zookeeper/预期输出应看到zookeeper.out或滚动日志文件。6.4 通过客户端连接测试/data/zookeeper/bin/zkCli.sh-server127.0.0.1:2181在 CLI 中测试基本命令# 创建节点 create /my_test hello_zookeeper # 读取节点 get /my_test # 删除节点 delete /my_test # 退出 quit6.5 验证端口监听sudoss-tlnp|grep2181预期输出显示 ZooKeeper 正在监听0.0.0.0:2181。七、生产环境集群配置扩展生产环境应部署3 或 5 个节点的 ZooKeeper 集群。7.1 修改 zoo.cfg每个节点在zoo.cfg末尾添加集群节点定义# 集群节点定义 # server.idhost:port1:port2 # id: 节点唯一标识对应 myid 文件 # port1: Follower 与 Leader 通信端口默认 2888 # port2: Leader 选举端口默认 3888 server.1zk-node01:2888:3888 server.2zk-node02:2888:3888 server.3zk-node03:2888:38887.2 创建 myid 文件每个节点在每个节点的数据目录中创建myid文件内容为节点编号# 节点 1echo1|sudotee/data/zk-data/myid# 节点 2echo2|sudotee/data/zk-data/myid# 节点 3echo3|sudotee/data/zk-data/myid7.3 配置 hosts 解析确保所有节点可通过主机名相互访问sudovim/etc/hosts添加10.0.49.215 zk-node01 10.0.49.216 zk-node02 10.0.49.217 zk-node037.4 防火墙配置集群节点间需要开放以下端口sudoufw allow2888/tcpsudoufw allow3888/tcp7.5 启动集群在所有节点上依次启动 ZooKeepersudosystemctl start zookeeper检查集群状态任一节点/data/zookeeper/bin/zkServer.sh status集群模式下应输出Mode: follower或Mode: leader。八、生产环境最佳实践8.1 硬件与部署建议建议项说明节点数量奇数个3 或 5保证多数派可用跨可用区部署将节点分布在不同可用区避免单点故障独立子网部署在独立私有子网通过安全组限制访问Java 堆内存设置合理的堆大小通常 2-4GB避免交换磁盘性能建议使用 SSDZooKeeper 对磁盘 IO 敏感8.2 JVM 内存调优ZooKeeper 3.8.x 可通过zkServer.sh中的ZK_SERVER_HEAP变量调整堆内存sudovim/data/zookeeper/bin/zkEnv.sh在文件开头添加exportZK_SERVER_HEAP20488.3 安全加固加固项说明访问控制启用 ACL访问控制列表保护数据模型网络隔离仅允许特定微服务子网和跳板机访问 2181 端口专用用户使用zookeeper用户运行最小权限原则四字命令谨慎启用4lw.commands.whitelist避免信息泄露8.4 监控与运维项目说明四字命令启用4lw.commands.whiteliststat,ruok,conf,envi用于监控日志清理启用autopurge自动清理旧快照和事务日志监控集成接入 Prometheus/Zabbix 等监控系统九、常用管理命令操作命令启动服务sudo systemctl start zookeeper停止服务sudo systemctl stop zookeeper重启服务sudo systemctl restart zookeeper查看状态sudo systemctl status zookeeper查看运行模式/data/zookeeper/bin/zkServer.sh status连接客户端/data/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181查看日志sudo tail -f /data/logs/zookeeper/zookeeper.out查看监听端口sudo ss -tlnp | grep 2181十、常见问题排查10.1 启动失败状态为inactive (dead)问题现象可能原因解决方法zkServer.sh status显示Error contacting serviceZooKeeper 启动后立即停止检查/etc/default/zookeeper是否包含export关键字修正后重启Ignoring invalid environment assignmentEnvironmentFile中使用了export去掉export仅保留KEYvalue格式服务启动后systemctl status显示inactivesystemd 服务使用Typesimple无法跟踪后台进程确认服务文件使用Typeforking并指定PIDFile日志文件未生成在指定目录ZOO_LOG_DIR变量未生效检查环境变量文件格式是否正确无 export10.2 其他常见问题问题现象可能原因解决方法端口 2181 已被占用其他服务占用sudo ss -tlnp | grep 2181查看占用进程集群节点无法通信hosts 解析或防火墙问题检查/etc/hosts和防火墙规则客户端连接失败ZooKeeper 未启动或端口未监听检查systemctl status zookeeper和端口监听日志中出现No such file or directory日志目录不存在或权限错误确认/data/logs/zookeeper存在且属主为zookeeper10.3 环境变量格式快速检查# 检查环境变量文件格式不应包含 exportcat/etc/default/zookeeper# 正确输出无 export# ZOOCFGDIR/data/zookeeper/conf# ZOO_LOG_DIR/data/logs/zookeeper# ZOO_LOG4J_PROPINFO,ROLLINGFILE# 验证 systemd 是否正确加载了环境变量sudosystemctl show zookeeper--propertyEnvironment10.4 手动前台启动调试如果服务仍然无法启动可以手动前台运行以查看详细错误sudo-uzookeeper /data/zookeeper/bin/zkServer.sh start-foreground输出会直接打印在终端帮助定位具体错误。按CtrlC停止。十一、安装信息汇总项目值ZooKeeper 版本3.8.6下载包路径/data/apache-zookeeper-3.8.6-bin.tar.gz安装目录/data/zookeeper配置文件/data/zookeeper/conf/zoo.cfg数据目录/data/zk-data日志目录/data/logs/zookeeper运行用户zookeeper客户端端口2181集群通信端口2888Follower 与 Leader 通信选举端口3888Leader 选举环境变量文件/etc/default/zookeeper无 export 关键字systemd 服务/etc/systemd/system/zookeeper.servicesystemd 类型TypeforkingPIDFile启动脚本/data/zookeeper/bin/zkServer.sh文档版本2.2适用系统Ubuntu 24.04 LTSZooKeeper 版本3.8.6最后更新2026-07-18