ZooKeeper Cluster 架构文档

目录标题

• ZooKeeper Cluster 架构文档
• • 集群标识
  • 1. 环境信息
  • • 1.1 Kubernetes 集群
    • 1.2 工作节点分布
  • 2. 集群架构概览
  • • 2.1 集群拓扑图
    • 2.2 集群规模统计
  • 3. Pod 详细信息
  • • 3.1 Participant 节点
    • • Replica 0
      • Replica 1
      • Replica 2
    • 3.2 Observer 节点
  • 4. 容器架构
  • • 4.1 Pod 容器组成
    • 4.2 容器环境变量
    • • zookeeper 容器环境变量
  • 5. 存储架构
  • • 5.1 持久化卷声明 (PVC)
    • 5.2 存储目录结构
    • 5.3 存储策略
  • 6. 网络架构
  • • 6.1 服务列表
    • 6.2 端口映射
    • 6.3 网络端点
    • • 内部客户端端点
      • Headless 服务端点 (直接访问各节点)
    • 6.4 Endpoints 详情
    • • Client Service Endpoints
      • Admin Server Endpoints
      • Headless Service Endpoints
  • 7. ZooKeeper 配置详解
  • • 7.1 主配置文件 (zoo.cfg)
    • 7.2 环境配置 (env.sh)
    • 7.3 日志配置 (log4j.properties)
    • 7.4 SASL 认证配置 (jaas.config)
  • 8. 调度与亲和性
  • • 8.1 Pod 反亲和性规则
    • 8.2 节点分布
  • 9. 安全与认证
  • • 9.1 ServiceAccount
    • 9.2 Secret
    • 9.3 安全上下文
    • • ssh 容器 (备份容器)
  • 10. 监控与健康检查
  • • 10.1 健康检查配置
    • • Liveness Probe (存活探针)
      • Readiness Probe (就绪探针)
    • 10.2 Prometheus 监控指标
    • 10.3 四字命令
  • 11. Operator 管理
  • • 11.1 ZooKeeper Operator
    • 11.2 Operator 启动参数
    • 11.3 Web 管理界面
  • 12. 资源汇总
  • • 12.1 单 Pod 资源
    • 12.2 集群总资源 (4 Pods)
    • 12.3 Operator 资源
  • 13. 自定义资源 (CRD)
  • • 13.1 ZookeeperCluster CR
    • 13.2 集群状态
  • 14. 标签 (Labels)
  • • 14.1 集群级别标签
    • 14.2 Pod 额外标签
  • 15. Finalizers
  • 16. 连接示例
  • • 16.1 客户端连接字符串
    • 16.2 获取集群状态
  • 17. 运维参考
  • • 17.1 常用命令
    • 17.2 日志查看
    • 17.3 故障排查
  • 18. 附录
  • • 18.1 文档版本
    • 18.2 相关文档

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 bash

DOMAIN=zookeeper-e93aadcf-headless.qfusion-admin.svc.cluster.local
QUORUM_PORT=2888
LEADER_PORT=3888
CLIENT_HOST=zookeeper-e93aadcf-client
CLIENT_PORT=2181
ADMIN_SERVER_HOST=zookeeper-e93aadcf-admin-server
ADMIN_SERVER_PORT=8080
CLUSTER_NAME=zookeeper-e93aadcf
CLUSTER_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: 20
podAffinityTerm:
labelSelector:
matchExpressions:
– key: app
operator: In
values:
– zookeeper–e93aadcf
topologyKey: kubernetes.io/hostname

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

8.2 节点分布

9. 安全与认证

9.1 ServiceAccount

9.2 Secret

9.3 安全上下文

ssh 容器 (备份容器)

privileged: true
capabilities:
add:
– SYS_ADMIN
– DAC_READ_SEARCH

10. 监控与健康检查

10.1 健康检查配置

Liveness Probe (存活探针)

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

Readiness Probe (就绪探针)

exec:
command: [zookeeperReady.sh]
initialDelaySeconds: 10
timeoutSeconds: 10
periodSeconds: 10
failureThreshold: 3
successThreshold: 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/v1beta1
kind: ZookeeperCluster
metadata:
name: zookeeper–e93aadcf
namespace: qfusion–admin
spec:
replicas: 3 # Participant 副本数
observerReplicas: 1 # Observer 副本数
maxUnavailableReplicas: 1 # 最大不可用副本数

image:
repository: k8smaster.qfusion.irds/irds/zookeeper–3.7
tag: v1.1.0
pullPolicy: Always

storageType: Persistence # 存储类型
iopsQuota: 2000 # IOPS 配额

persistence:
reclaimPolicy: Delete
spec:
storageClassName: csi–localpv
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 20Gi

13.2 集群状态

status:
replicas: 4 # 总副本数
readyReplicas: 4 # 就绪副本数
internalClientEndpoint: 246.102.223.122:2181
externalClientEndpoint: N/A

members:
ready:
– zookeeper–e93aadcf–0–0
– zookeeper–e93aadcf–1–0
– zookeeper–e93aadcf–2–0
– zookeeper–e93aadcf–observer–0–0

conditions:
– type: PodsReady
status: "True"
– type: Error
status: "False"
– type: Upgrading
status: "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 获取集群状态

# 设置 KUBECONFIG
export KUBECONFIG=/bpx/.145-admin.conf

# 查看 ZooKeeper 集群状态
kubectl get ZookeeperCluster zookeeper-e93aadcf -n qfusion-admin

# 查看 Pods 状态
kubectl get pods -n qfusion-admin -l app=zookeeper-e93aadcf

# 查看服务
kubectl get svc -n qfusion-admin -l app=zookeeper-e93aadcf

# 查看 PVC
kubectl get pvc -n qfusion-admin -l app=zookeeper-e93aadcf

# 连接到 ZooKeeper (需要先 exec 进入 Pod)
kubectl exec -it -n qfusion-admin zookeeper-e93aadcf-0-0 -c zookeeper — /bin/bash

17. 运维参考

17.1 常用命令

# 四字命令检查
echo ruok | nc 245.0.0.94 2181 # 检查节点是否正常
echo srvr | nc 245.0.0.94 2181 # 获取服务器详情
echo mntr | nc 245.0.0.94 2181 # 获取监控指标
echo cons | nc 245.0.0.94 2181 # 列出客户端连接

# Prometheus 指标
curl http://245.0.0.94:7000/metrics

# Admin Server
curl http://245.0.0.94:8080/commands

17.2 日志查看

# ZooKeeper 主容器日志
kubectl logs -n qfusion-admin zookeeper-e93aadcf-0-0 -c zookeeper

# 实时跟踪日志
kubectl logs -f -n qfusion-admin zookeeper-e93aadcf-0-0 -c zookeeper

# 查看备份容器日志
kubectl logs -n qfusion-admin zookeeper-e93aadcf-0-0 -c ssh

17.3 故障排查

18. 附录

18.1 文档版本

18.2 相关文档

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

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