11.1.7 配置参数与运行模式

ZooKeeper 的配置以 zoo.cfg 为核心，参数分为基础运行、会话与超时、数据与日志、网络与性能、安全与认证、集群与选举等几类。理解各参数的默认值、作用范围与相互关系，是保障稳定性与可运维性的关键。本节给出配置示例、运行模式、排错与练习。

原理草图：参数作用域与运行模式#

核心参数与解释（带示例）#

基础参数
- tickTime：基本时间单元（毫秒），影响会话与选举；常见 2000。
- dataDir：快照与事务日志默认目录。
- dataLogDir：事务日志目录，建议与 dataDir 分离。
- clientPort：客户端端口，默认 2181。
- admin.serverPort：管理端口（3.5+），默认 8080。

会话与超时
- initLimit：Follower 与 Leader 初始同步允许的 tick 数。
- syncLimit：心跳与同步最大延迟 tick 数。
- minSessionTimeout / maxSessionTimeout：限制客户端会话超时范围。

数据与日志
- snapCount：事务数达到阈值触发快照，默认 100000。
- autopurge.snapRetainCount / autopurge.purgeInterval：快照保留与清理策略。
- preAllocSize：事务日志预分配，减少碎片。

网络与性能
- maxClientCnxns：单 IP 连接数限制。
- globalOutstandingLimit：未完成请求上限。
- serverCnxnFactory：连接工厂（NIO/Netty）。
- jute.maxbuffer：单次请求最大大小。

安全与认证
- authProvider.x、requireClientAuthScheme：启用认证。
- ssl.*：启用 TLS/SSL。

集群与选举
- server.X=host:peerPort:electionPort[:role]：集群成员。
- quorumListenOnAllIPs：容器环境常用。

配置与启动示例（可执行）#

单机模式示例

# 1) 准备目录
sudo mkdir -p /data/zk/snapshot /data/zk/logs
sudo chown -R $USER:$USER /data/zk

# 2) 编辑配置文件
cat >/opt/zookeeper/conf/zoo.cfg <<'EOF'
tickTime=2000
dataDir=/data/zk/snapshot
dataLogDir=/data/zk/logs
clientPort=2181
initLimit=10
syncLimit=5
autopurge.snapRetainCount=5
autopurge.purgeInterval=24
admin.serverPort=8080
EOF

# 3) 启动
/opt/zookeeper/bin/zkServer.sh start

# 4) 预期效果：返回 "STARTED"

三节点集群模式示例（Quorum）

# 假设三台主机: zk1(10.0.0.1), zk2(10.0.0.2), zk3(10.0.0.3)
# 每台机器执行以下内容，只是 myid 不同

sudo mkdir -p /data/zk/snapshot /data/zk/logs
sudo chown -R $USER:$USER /data/zk

cat >/opt/zookeeper/conf/zoo.cfg <<'EOF'
tickTime=2000
dataDir=/data/zk/snapshot
dataLogDir=/data/zk/logs
clientPort=2181
initLimit=10
syncLimit=5
autopurge.snapRetainCount=5
autopurge.purgeInterval=24
server.1=10.0.0.1:2888:3888
server.2=10.0.0.2:2888:3888
server.3=10.0.0.3:2888:3888
quorumListenOnAllIPs=true
EOF

# 写入 myid（必须与 server.X 对应）
echo "1" >/data/zk/snapshot/myid   # zk1
# echo "2" >/data/zk/snapshot/myid # zk2
# echo "3" >/data/zk/snapshot/myid # zk3

/opt/zookeeper/bin/zkServer.sh start

Observer 读扩展示例

# 在新增节点上设置 observer 角色
cat >/opt/zookeeper/conf/zoo.cfg <<'EOF'
tickTime=2000
dataDir=/data/zk/snapshot
dataLogDir=/data/zk/logs
clientPort=2181
initLimit=10
syncLimit=5
server.1=10.0.0.1:2888:3888
server.2=10.0.0.2:2888:3888
server.3=10.0.0.3:2888:3888
server.4=10.0.0.4:2888:3888:observer
EOF

echo "4" >/data/zk/snapshot/myid
/opt/zookeeper/bin/zkServer.sh start

运行模式与特性对照#

Standalone：单节点，开发测试用。
Pseudo-Cluster：单机多实例，验证分布式行为。
Quorum：生产标准模式，至少 3 节点，容忍 (N-1)/2 故障。
Read-Only：readonlymode.enabled=true，失去法定人数允许读。
Observer：不参与投票，提升读吞吐。

排错与验证（命令+现象）#

检查角色

echo stat | nc 127.0.0.1 2181
# 预期: Mode: leader / follower / observer

检查端口

ss -lntp | egrep '2181|2888|3888|8080'
# 预期: 集群节点需监听 2181/2888/3888

常见问题与定位
1. 频繁选举/抖动

grep -E 'LEADING|FOLLOWING|LOOKING' /data/zk/logs/zookeeper.out
# 处理: 增大 tickTime 或 initLimit/syncLimit；检查网络延迟

myid 不一致

cat /data/zk/snapshot/myid
# 处理: 确保与 zoo.cfg 的 server.X 对应

磁盘写入慢/快照爆满

du -sh /data/zk/snapshot /data/zk/logs
# 处理: 启用 autopurge，或分离 dataLogDir

请求过大导致异常

grep -i 'jute.maxbuffer' /data/zk/logs/zookeeper.out
# 处理: 评估并适度调高 jute.maxbuffer

练习#

用 3 台虚拟机搭建 Quorum 集群，验证 stat 输出的角色分布。
人为降低 syncLimit，模拟网络延迟并观察重选举日志。
将 dataLogDir 与 dataDir 分离后，比较事务日志增长速度。
新增一个 Observer 节点，观察其不参与投票但可提供读服务。