2.1 单机模式：从环境准备到第一次心跳

2.1 单机模式：从环境准备到第一次心跳

本节摘要：单机模式是学习 ZooKeeper 的沙盘：装好 JDK，下载解压，写一份最小配置，启动后用四字命令与 zkCli 完成首次验证。本节同时交代目录规划与日志查看习惯，为集群部署养成本地查证的手感。

十分钟沙盘，三十分钟值回票价

生产环境没人用单机模式——一台机器宕机服务全停，多数派无从谈起。但学习阶段它有不可替代的价值：启动快、日志干净、随手删掉数据目录就能重来。后面第三章的客户端代码、第五章的判例复现，全都建议先在单机版上跑通，再搬到集群。本节把这个沙盘一次搭好。

环境准备只有两条硬要求：JDK 8 及以上（ZooKeeper 3.5 之后的服务端是纯 Java 实现），以及一个没有空格与中文的用户目录——Windows 下路径里带空格曾坑过无数初学者，脚本解析会出莫名其妙的错。内存给 1 GB 足够实验用，磁盘上预留几 GB 给事务日志。

从下载到启动

以 Linux 为例，走一遍完整流程，每步都给了验证点：

# 1. 确认 JDK 就绪（1.8 以上均可）
$ java -version
openjdk version "1.8.0_402"

# 2. 解压到规划好的目录，这里用 /opt，避免用户目录的权限纠缠
$ tar -xzf apache-zookeeper-3.8.4-bin.tar.gz -C /opt/
$ cd /opt/apache-zookeeper-3.8.4-bin

# 3. 从模板复制一份最小配置（conf 下只有模板，没有现成的 zoo.cfg）
$ cp conf/zoo_sample.cfg conf/zoo.cfg

# 4. 启动（前台模式便于观察，生产用 start）
$ bin/zkServer.sh start-foreground
# 看到日志出现如下字样即启动成功：
# INFO  [main:Environment@98] - Server environment:zookeeper.version=3.8.4
# INFO  [main:NIOServerCnxnFactory@666] - binding to port 0.0.0.0/0.0.0.0:2181
​

新开一个终端验证服务确实在应答：

# 四字命令 ruok：活着吗？活着应答 imok
$ echo ruok | nc 127.0.0.1 2181
imok

# zkCli 建立会话并做一次读写
$ bin/zkCli.sh -server 127.0.0.1:2181
[zk] create /hello "world"
Created /hello
[zk] get /hello
world
​

两分钟内完成"进程起来、端口应答、读写可用"三层验证，这个顺序在集群部署时同样适用——先确认活着，再确认能用，最后才谈调优。

最小配置里藏着的三个节奏参数

单机模式的 zoo.cfg 只有三行是必需的，但每一行都值得读懂，因为它们在集群章节会成倍重要：

# tickTime：心跳与选举的最小时间单位，毫秒。2000 表示每 2 秒一个节拍
tickTime=2000
# dataDir：事务日志与快照的落盘目录，性能敏感，别放 NFS 与慢盘
dataDir=/var/lib/zookeeper
# clientPort：客户端连接端口，约定俗成 2181
clientPort=2181
​

tickTime 是全服务器的节拍器：会话超时的最小颗粒、选举的超时计算、心跳间隔，全部以它为单位换算。单机版里它只影响节奏快慢，集群版里它直接决定两台机器之间"等多久才算失联"。dataDir 是案卷库的地址，事务日志的写盘速度直接封顶写入性能——把它和 dataLogDir 分开、放到独立磁盘，是 6.4 节性能优化的第一招。

日志查看的习惯从这里养成

单机版前台启动的好处是日志扑面而来。你应当学会抓三类关键行：角色宣告（Leader? false... 或 standalone 字样，一眼确认模式）、会话事件（Session established / Session closed，排查客户端连接问题时全靠它）、异常堆栈（KeeperException 家族，每种异常在第六章都有对应的排障路径）。把日志当案卷读，是运维视角的第一课。

# 后台模式与常规操作：重启、停止、查看状态
$ bin/zkServer.sh start     # 后台启动
$ bin/zkServer.sh status    # 查看角色：standalone / leader / follower
Mode: standalone
$ bin/zkServer.sh stop      # 停止
​

status 输出的 Mode 字段值得专门记一笔：单机版永远是 standalone，集群版会给出 leader 或 follower。第六章排障时，这个字段是判断"集群还是单点在撑"的第一现场证据。

要点回顾

• 单机版定位：学习沙盘与客户端试验场，不进生产；一台机器无所谓多数派，宕机即停摆。
• 启动验证三连：进程日志、ruok 应答 imok、zkCli 实际读写，三层确认缺一不可。
• tickTime 是节拍器：心跳、选举、会话超时都按它换算，集群模式下牵一发动全身。
• dataDir 决定写入上限：事务日志放本地高速盘，与数据快照分盘是后续优化的基础。

常见疑问

问：启动报端口被占用怎么办？ 大概率是之前残留的 Java 进程。用 jps 找到 QuorumPeerMain 进程停掉，或改 clientPort 换端口实验。生产环境固定 2181 是为了运维习惯统一，实验环境随意，但客户端命令要同步改。

下一节把三台机器拉进来，看真正的法庭如何组建。

两个环境细节的补充

日志级别调优。默认日志级别为 INFO，学习期够用；长跑实验机上可调成 WARN 减少噪音。方式是在 conf 目录的日志配置文件里调整，或启动参数覆盖：

# 环境变量方式覆盖 JVM 参数与日志目录
$ export ZK_LOG4J_PROP=WARN
$ export ZOO_LOG_DIR=/var/log/zookeeper
$ bin/zkServer.sh start
# 验证：tail 日志文件，WARN 以下不再输出
​

JDK 版本的坑。3.8 线在 JDK 8、11、17 上均可运行，但 JDK 17 下需注意默认 GC 行为变化带来的停顿差异——会话超时的计算对停顿敏感（4.4 节的原则）。实验环境建议与服务端生产规划用同一个大版本，避免"实验没问题、上线 GC 抖"的错位。

延伸追问

问：Windows 上能跑吗？ 能，包里带 zkServer.cmd。但生产清一色 Linux；Windows 下路径分隔符与脚本兼容性常出小坑，实验能用即可，别在它身上花时间。