ZooKeeper Cluster 架构文档

ZooKeeper Cluster 架构文档

集群标识

1. 环境信息

1.1 Kubernetes 集群

1.2 工作节点分布

2. 集群架构概览

2.1 集群拓扑图

┌─────────────────────────────────────────────────────────────────────────────────┐ │ ZooKeeper Cluster: zookeeper-e93aadcf │ │ 版本: 3.7.1 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Quorum 集群 (3节点) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ Replica 0 │ │ Replica 1 │ │ Replica 2 │ │ │ │ │ │ Participant │ │ Participant │ │ Participant │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ Node: qfusion1 │ │ Node: qfusion4 │ │ Node: qfusion3 │ │ │ │ │ │ IP: 245.0.0.94 │ │ IP: 245.0.3.243 │ │ IP: 245.0.2.35 │ │ │ │ │ │ myid: 0 │ │ myid: 1 │ │ myid: 2 │ │ │ │ │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ │ │ │ │ │ │ │ └───────────────────────┼───────────────────────┘ │ │ │ │ │ │ │ │ │ ┌───────────┴───────────┐ │ │ │ │ │ Leader Election │ │ │ │ │ │ (Port 3888) │ │ │ │ │ └───────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Observer 节点 (只读副本) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────┐ │ │ │ │ │ Observer-0 │ │ │ │ │ │ │ │ │ │ │ │ Node: qfusion2 │ │ │ │ │ │ IP: 245.0.1.95 │ │ │ │ │ │ myid: 3 │ │ │ │ │ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘

2.2 集群规模统计

Sources

3. Pod 详细信息

3.1 Participant 节点

Replica 0

Replica 1

Replica 2

3.2 Observer 节点

4. 容器架构

4.1 Pod 容器组成

每个 ZooKeeper Pod 包含 2 个容器：

┌─────────────────────────────────────────────────────────────────────────┐ │ Pod │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ Container 1: zookeeper (主容器) │ │ │ ├───────────────────────────────────────────────────────────────────┤ │ │ │ Image: k8smaster.qfusion.irds/irds/zookeeper-3.7:v1.1.0 │ │ │ │ Image ID: sha256:15681693... │ │ │ │ Command: /usr/local/bin/zookeeperStart.sh │ │ │ │ Pull Policy: Always │ │ │ │ │ │ │ │ Resources: │ │ │ │ CPU Request: 500m │ │ │ │ CPU Limit: 1000m │ │ │ │ Memory Request: 2Gi │ │ │ │ Memory Limit: 2Gi │ │ │ │ │ │ │ │ Ports: │ │ │ │ 2181/tcp - client (客户端连接) │ │ │ │ 2888/tcp - quorum (集群通信) │ │ │ │ 3888/tcp - leader-election (领导者选举) │ │ │ │ 7000/tcp - metrics (Prometheus监控指标) │ │ │ │ 8080/tcp - admin-server (Jetty管理服务器) │ │ │ │ │ │ │ │ Health Checks: │ │ │ │ Liveness: exec [zookeeperLive.sh] │ │ │ │ delay=10s, timeout=10s, period=10s │ │ │ │ Readiness: exec [zookeeperReady.sh] │ │ │ │ delay=10s, timeout=10s, period=10s │ │ │ │ │ │ │ │ Lifecycle: │ │ │ │ PreStop: exec [zookeeperTeardown.sh] │ │ │ │ │ │ │ │ Volume Mounts: │ │ │ │ /conf - ConfigMap (zookeeper-e93aadcf-configmap) │ │ │ │ /data - PVC (持久化数据) │ │ │ │ /mnt/log - EmptyDir (日志) │ │ │ │ /etc/localtime - HostPath (时区) │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ Container 2: ssh (备份/管理容器) │ │ │ ├───────────────────────────────────────────────────────────────────┤ │ │ │ Image: k8smaster.qfusion.irds/irds/zookeeper-backup:v3.14.4 │ │ │ │ Image ID: sha256:47b43198... │ │ │ │ Pull Policy: IfNotPresent │ │ │ │ │ │ │ │ Resources: │ │ │ │ CPU Request: 250m │ │ │ │ CPU Limit: 500m │ │ │ │ Memory Request: 1Gi │ │ │ │ Memory Limit: 1Gi │ │ │ │ │ │ │ │ Security Context: │ │ │ │ Privileged: true │ │ │ │ Capabilities: │ │ │ │ - SYS_ADMIN │ │ │ │ - DAC_READ_SEARCH │ │ │ │ │ │ │ │ Volume Mounts: │ │ │ │ /conf - ConfigMap │ │ │ │ /data - PVC (共享主容器数据，用于备份) │ │ │ │ /mnt/log - EmptyDir │ │ │ │ /etc/localtime - HostPath │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

4.2 容器环境变量

zookeeper 容器环境变量

5. 存储架构

5.1 持久化卷声明 (PVC)

5.2 存储目录结构

/mnt/log/ # EmptyDir - 日志目录 ├── server.log # ZooKeeper 服务日志 /data/ # PVC - 数据目录 ├── version-2/ # 快照和事务日志目录 │ ├── snapshot.0 # 快照文件 │ └── log.0 # 事务日志 ├── zoo.cfg.dynamic # 动态配置文件 └── myid # 节点ID文件 /conf/ # ConfigMap - 配置目录 ├── zoo.cfg # 主配置文件 ├── log4j.properties # 日志配置 ├── jaas.config # SASL认证配置 └── env.sh # 环境变量脚本

5.3 存储策略

6. 网络架构

6.1 服务列表

6.2 端口映射

6.3 网络端点

内部客户端端点

zookeeper-e93aadcf-client.qfusion-admin.svc.cluster.local:2181 246.102.223.122:2181

Headless 服务端点 (直接访问各节点)

zookeeper-e93aadcf-0.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181 zookeeper-e93aadcf-1.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181 zookeeper-e93aadcf-2.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181 zookeeper-e93aadcf-observer-0.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181

6.4 Endpoints 详情

Client Service Endpoints

245.0.0.94:2181 (Replica-0) 245.0.3.243:2181 (Replica-1) 245.0.2.35:2181 (Replica-2) 245.0.1.95:2181 (Observer-0)

Admin Server Endpoints

245.0.0.94:8080 (Replica-0) 245.0.3.243:8080 (Replica-1) 245.0.2.35:8080 (Replica-2) 245.0.1.95:8080 (Observer-0)

Headless Service Endpoints

245.0.0.94:2181,2888,3888,7000,8080 (Replica-0) 245.0.3.243:2181,2888,3888,7000,8080 (Replica-1) 245.0.2.35:2181,2888,3888,7000,8080 (Replica-2) 245.0.1.95:2181,2888,3888,7000,8080 (Observer-0)

7. ZooKeeper 配置详解

7.1 主配置文件 (zoo.cfg)

# 基础配置 skipACL=yes # 跳过ACL检查 standaloneEnabled=false # 禁用单机模式 dataDir=/data # 数据目录 admin.serverPort=8080 # 管理服务器端口 # 时间配置 (单位: 毫秒) tickTime=2000 # 心跳时间间隔 (2秒) initLimit=10 # 初始连接超时 (10*tickTime=20秒) syncLimit=2 # 同步超时 (2*tickTime=4秒) # 性能配置 globalOutstandingLimit=1000 # 全局未完成请求限制 preAllocSize=65536 # 预分配磁盘空间大小 (64KB) snapCount=10000 # 每N个事务写一次快照 commitLogCount=500 # 提交日志数量 snapSizeLimitInKb=4194304 # 快照大小限制 (4GB) # 连接配置 maxCnxns=0 # 最大连接数 (0=无限制) maxClientCnxns=60 # 每个客户端最大连接数 # 会话超时配置 minSessionTimeout=4000 # 最小会话超时 (4秒) maxSessionTimeout=40000 # 最大会话超时 (40秒) # 自动清理配置 autopurge.purgeInterval=1 # 自动清理间隔 (小时) autopurge.snapRetainCount=3 # 保留的快照数量 # 网络配置 quorumListenOnAllIPs=false # 不监听所有IP # 四字命令白名单 4lw.commands.whitelist=cons, envi, conf, crst, srvr, stat, mntr, ruok # Prometheus 监控配置 metricsProvider.exportJvmInfo=true # 导出JVM信息 metricsProvider.httpPort=7000 # 指标端口 metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider # 动态配置 reconfigEnabled=true # 启用动态重配置 dynamicConfigFile=/data/zoo.cfg.dynamic # 动态配置文件路径

7.2 环境配置 (env.sh)

#!/usr/bin/env bashDOMAIN=zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.localQUORUM_PORT=2888LEADER_PORT=3888CLIENT_HOST=zookeeper-e93aadcf-clientCLIENT_PORT=2181ADMIN_SERVER_HOST=zookeeper-e93aadcf-admin-serverADMIN_SERVER_PORT=8080CLUSTER_NAME=zookeeper-e93aadcfCLUSTER_SIZE=3

7.3 日志配置 (log4j.properties)

# 日志根配置 zookeeper.root.logger=CONSOLE,ROLLINGFILE zookeeper.console.threshold=INFO zookeeper.log.dir=/mnt/log zookeeper.log.file=server.log zookeeper.log.threshold=INFO # RollingFile 配置 log4j.appender.ROLLINGFILE.MaxFileSize=10MB # 单个日志文件最大10MB log4j.appender.ROLLINGFILE.MaxBackupIndex=10 # 保留10个历史文件

7.4 SASL 认证配置 (jaas.config)

Server { org.apache.zookeeper.server.auth.DigestLoginModule required user_qfusion="mcd@loHmiDdoI0E9"; }; Client { org.apache.zookeeper.server.auth.DigestLoginModule required username="qfusion" password="mcd@loHmiDdoI0E9"; };

8. 调度与亲和性

8.1 Pod 反亲和性规则

podAntiAffinity:preferredDuringSchedulingIgnoredDuringExecution:-weight:20podAffinityTerm:labelSelector:matchExpressions:-key:appoperator:Invalues:-zookeeper-e93aadcftopologyKey:kubernetes.io/hostname

说明: 尽量将 ZooKeeper Pod 调度到不同的节点上，权重为20（软约束）

8.2 节点分布

9. 安全与认证

9.1 ServiceAccount

9.2 Secret

9.3 安全上下文

ssh 容器 (备份容器)

privileged:truecapabilities:add:-SYS_ADMIN-DAC_READ_SEARCH

10. 监控与健康检查

10.1 健康检查配置

Liveness Probe (存活探针)

exec:command:[zookeeperLive.sh]initialDelaySeconds:10timeoutSeconds:10periodSeconds:10failureThreshold:3

Readiness Probe (就绪探针)

exec:command:[zookeeperReady.sh]initialDelaySeconds:10timeoutSeconds:10periodSeconds:10failureThreshold:3successThreshold:1

10.2 Prometheus 监控指标

10.3 四字命令

11. Operator 管理

11.1 ZooKeeper Operator

11.2 Operator 启动参数

zookeeper-operator\-metrics-bind-address=127.0.0.1:6000

11.3 Web 管理界面

12. 资源汇总

12.1 单 Pod 资源

12.2 集群总资源 (4 Pods)

12.3 Operator 资源

13. 自定义资源 (CRD)

13.1 ZookeeperCluster CR

apiVersion:zookeeper.pravega.io/v1beta1kind:ZookeeperClustermetadata:name:zookeeper-e93aadcfnamespace:qfusion-adminspec:replicas:3# Participant 副本数observerReplicas:1# Observer 副本数maxUnavailableReplicas:1# 最大不可用副本数image:repository:k8smaster.qfusion.irds/irds/zookeeper-3.7tag:v1.1.0pullPolicy:AlwaysstorageType:Persistence# 存储类型iopsQuota:2000# IOPS 配额persistence:reclaimPolicy:Deletespec:storageClassName:csi-localpvaccessModes:[ReadWriteOnce]resources:requests:storage:20Gi

13.2 集群状态

status:replicas:4# 总副本数readyReplicas:4# 就绪副本数internalClientEndpoint:246.102.223.122:2181externalClientEndpoint:N/Amembers:ready:-zookeeper-e93aadcf-0-0-zookeeper-e93aadcf-1-0-zookeeper-e93aadcf-2-0-zookeeper-e93aadcf-observer-0-0conditions:-type:PodsReadystatus:"True"-type:Errorstatus:"False"-type:Upgradingstatus:"False"

14. 标签 (Labels)

14.1 集群级别标签

14.2 Pod 额外标签

15. Finalizers

16. 连接示例

16.1 客户端连接字符串

# 集群连接字符串 (推荐)zookeeper-e93aadcf-client.qfusion-admin.svc.cluster.local:2181# 直连所有节点 (高可用)zookeeper-e93aadcf-0.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181,\zookeeper-e93aadcf-1.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181,\zookeeper-e93aadcf-2.zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local:2181

16.2 获取集群状态

# 设置 KUBECONFIGexportKUBECONFIG=/bpx/.145-admin.conf# 查看 ZooKeeper 集群状态kubectl get ZookeeperCluster zookeeper-e93aadcf-nqfusion-admin# 查看 Pods 状态kubectl get pods-nqfusion-admin-lapp=zookeeper-e93aadcf# 查看服务kubectl get svc-nqfusion-admin-lapp=zookeeper-e93aadcf# 查看 PVCkubectl get pvc-nqfusion-admin-lapp=zookeeper-e93aadcf# 连接到 ZooKeeper (需要先 exec 进入 Pod)kubectlexec-it-nqfusion-admin zookeeper-e93aadcf-0-0-czookeeper -- /bin/bash

17. 运维参考

17.1 常用命令

# 四字命令检查echoruok|nc245.0.0.942181# 检查节点是否正常echosrvr|nc245.0.0.942181# 获取服务器详情echomntr|nc245.0.0.942181# 获取监控指标echocons|nc245.0.0.942181# 列出客户端连接# Prometheus 指标curlhttp://245.0.0.94:7000/metrics# Admin Servercurlhttp://245.0.0.94:8080/commands

17.2 日志查看

# ZooKeeper 主容器日志kubectl logs-nqfusion-admin zookeeper-e93aadcf-0-0-czookeeper# 实时跟踪日志kubectl logs-f-nqfusion-admin zookeeper-e93aadcf-0-0-czookeeper# 查看备份容器日志kubectl logs-nqfusion-admin zookeeper-e93aadcf-0-0-cssh

17.3 故障排查

18. 附录

18.1 文档版本

18.2 相关文档

• ZooKeeper 官方文档
• QFusion 平台文档
• Kubernetes StatefulSet 文档

本文档由 AI 自动生成，基于 Kubernetes 集群 145 的实时配置