ZooKeeper 是一个分布式协调服务。很多人第一次接触它，是因为 Kafka、Dubbo、HBase 或旧项目注册中心里出现了它。真正搭集群时，最容易困惑的是几个配置：tickTime、initLimit、syncLimit、dataDir、clientPort 和 server.N。
这篇不展开完整源码，只把“集群配置为什么这么写”讲清楚。理解这些参数以后，再看 Docker Compose、伪集群和生产集群就不会只是在复制配置。
ZooKeeper 解决的是协调问题
ZooKeeper 本身不是业务数据库，也不是消息队列。它更像一个强一致的协调组件，用来保存少量元数据，并在多个节点之间完成一致性协作。
常见用途包括：
- 服务注册和发现；
- 分布式锁；
- 配置元数据；
- Leader 选举；
- 集群成员状态协调。
也正因为它偏协调，不适合把大量业务数据塞进去。ZooKeeper 更适合保存“小而关键”的状态。
集群节点为什么通常是奇数
ZooKeeper 依赖过半机制。只要超过半数节点可用，集群就可以继续对外提供服务。
例如：
- 3 个节点，允许 1 个节点故障；
- 5 个节点，允许 2 个节点故障；
- 7 个节点，允许 3 个节点故障。
为什么常见是 3、5、7，而不是 4、6？因为 4 个节点仍然只能容忍 1 个节点故障，过半需要 3 个；和 3 节点相比，容错并没有提升，还增加了成本。6 个节点也只能容忍 2 个故障，和 5 节点相同。
所以小规模集群常见 3 节点，要求更高再到 5 节点。
tickTime：心跳的基础时间单位
tickTime 是 ZooKeeper 的基础时间单位，单位是毫秒。很多集群超时配置不是直接写毫秒，而是写多少个 tick。
例如：
tickTime=2000表示一个 tick 是 2 秒。
后面的 initLimit 和 syncLimit 都会基于这个时间单位计算。因此 tickTime 不只是一个心跳间隔，它会影响集群对慢节点、网络抖动和初始化同步的容忍程度。
tickTime 不能无限调大。调大以后，集群对异常感知会变慢；调小以后，网络稍微抖动就可能误判。日常先用默认或接近默认的值，再根据真实网络和日志调整。
initLimit：Follower 初始同步能等多久
initLimit 表示 Follower 和 Leader 建立初始连接、完成初始化同步时，最多允许等待多少个 tick。
例如：
tickTime=2000
initLimit=10表示初始同步大约最多等待 20 秒。
这个参数主要影响节点启动、重启、加入集群时的容忍度。如果数据量较大、磁盘较慢、网络较差，初始化同步可能需要更久，initLimit 太小就容易导致节点刚启动就失败。
但它也不应该随便调得很大。过大的初始化等待会让问题暴露变慢。合理做法是结合日志看是不是频繁发生初始化超时，再判断是参数小了，还是磁盘、网络、快照体积或节点负载出了问题。
syncLimit：正常同步请求能等多久
syncLimit 表示 Follower 和 Leader 在正常运行期间，请求和应答之间最多允许间隔多少个 tick。
例如：
tickTime=2000
syncLimit=5表示正常同步大约最多等待 10 秒。
如果 Follower 在这个时间内没有跟上 Leader，它可能会被认为不可用并重新连接。这个参数和运行期网络抖动、GC 暂停、磁盘写入延迟都有关系。
排查集群不稳定时，不要只看 syncLimit。如果节点经常掉线，需要同时看：
- JVM GC 是否有长暂停；
- 磁盘是否抖动；
- 网络延迟是否异常；
- 机器负载是否过高；
- 快照和事务日志目录是否合理。
参数只能提高容忍度，不能解决底层资源问题。
dataDir 和 dataLogDir：快照与事务日志
dataDir 是 ZooKeeper 保存快照数据的目录。很多配置里还会看到 dataLogDir，用于保存事务日志。
示例：
dataDir=/var/lib/zookeeper/data
dataLogDir=/var/lib/zookeeper/log
clientPort=2181如果没有单独配置 dataLogDir，事务日志也可能和数据目录放在一起。生产环境里通常会关注磁盘性能和目录隔离，因为事务日志写入延迟会影响整体响应。
不要把生产数据目录放在临时目录里。临时目录可能被系统清理，容器环境里也可能随着容器销毁而丢失。无论是 Docker 还是物理机，都应该明确挂载持久化目录。
clientPort：客户端连接端口
clientPort 是客户端连接 ZooKeeper 的端口，常见默认值是 2181。
在单机伪集群里，因为多个节点跑在同一台机器上，客户端端口不能冲突，所以常见写法是：
clientPort=2181
clientPort=2182
clientPort=2183但在真实多机器集群里，每台机器都有自己的 IP，通常都可以使用同一个 2181。
理解这一点以后，就不会把伪集群里的端口差异误认为生产集群也必须这么写。
server.N：集群成员声明
server.N 用来声明集群里的每个节点。
格式通常是：
server.N=host:peerPort:electionPort含义是：
N是服务器编号；host是服务器地址；peerPort是节点之间同步通信端口；electionPort是选举通信端口。
例如三节点集群：
server.1=zoo1:2888:3888
server.2=zoo2:2888:3888
server.3=zoo3:2888:3888每个节点还需要知道自己的编号。常见方式是在数据目录里写一个 myid 文件，内容就是对应的数字。比如 zoo1 的 myid 是 1，就对应 server.1。
如果用官方 Docker 镜像，也可以通过环境变量传入：
environment:
ZOO_MY_ID: 1
ZOO_SERVERS: server.1=zoo1:2888:3888 server.2=zoo2:2888:3888 server.3=zoo3:2888:3888关键是编号和节点要对得上。编号错了，集群会出现很难读的连接和选举问题。
Docker Compose 伪集群要注意什么
本地学习时，可以用 Docker Compose 起三个 ZooKeeper 容器。示意结构如下：
services:
zoo1:
image: zookeeper:3.9
hostname: zoo1
ports:
- "2181:2181"
volumes:
- ./zookeeper/zoo1/data:/data
- ./zookeeper/zoo1/datalog:/datalog
environment:
ZOO_MY_ID: 1
ZOO_SERVERS: server.1=zoo1:2888:3888 server.2=zoo2:2888:3888 server.3=zoo3:2888:3888另外两个节点类似，只是 hostname、宿主机端口和 ZOO_MY_ID 不同。
注意几个点：
- 本地目录使用相对路径或明确的项目目录，不要把个人机器绝对路径写进公开文档。
- 容器之间用服务名通信，比如
zoo1、zoo2、zoo3。 - 宿主机暴露端口只是为了本机连接，不影响容器内部互联端口。
- 启动前可以先跑配置校验，再后台启动。
常见命令：
docker compose -f zookeeper-compose.yml config -q
docker compose -f zookeeper-compose.yml up -d
docker compose -f zookeeper-compose.yml ps如果使用自定义 compose 文件名，-f 要跟在 docker compose 后面，而不是放到子命令后面。
节点掉线后会怎样
ZooKeeper 集群里，Leader 掉线和 Follower 掉线影响不同。
如果 Leader 掉线，剩余节点会进行新一轮选举。只要剩余节点仍然过半，就能选出新的 Leader 并继续服务。
如果少数 Follower 掉线，集群通常仍然可用。掉线节点恢复后，会重新加入集群，并从 Leader 同步数据。
这也是 ZooKeeper 强调过半可用的原因。它不是要求每个节点都活着，而是要求多数派能形成一致决策。
但这不代表可以忽略掉线。频繁掉线会增加选举和同步成本，也说明底层资源可能不稳定。生产环境通常需要进程守护、监控告警和日志巡检。
性能优化先看资源瓶颈
ZooKeeper 性能问题常见不是靠调一个参数解决。
可以优先看：
- JVM 堆设置是否合理；
- 是否发生长时间 GC；
- 磁盘延迟是否过高；
- 事务日志目录是否和慢磁盘混用；
- 网络是否有抖动；
- 客户端连接数是否过多；
- 是否把大量业务数据写入 ZooKeeper。
ZooKeeper 适合保存协调元数据，不适合作为大容量存储。如果节点数量、watch 数量、znode 数量持续膨胀，也要回头看业务模型是否用错了。
小结
理解 ZooKeeper 集群配置，可以先抓住这条线：
tickTime 是基础时间单位，initLimit 控制启动和初始同步容忍度，syncLimit 控制运行期同步容忍度，dataDir 和 dataLogDir 关系到持久化，clientPort 给客户端连接，server.N 声明集群成员和通信端口。
本地伪集群主要用于理解端口和节点关系；生产集群则更关注奇数节点、过半机制、磁盘、网络、GC 和监控。配置能帮你表达集群拓扑，但稳定性最终还是要靠资源、观测和正确使用方式。
