服务注册与分布式协调 / 系统课时

排查 Quorum TLS 启动失败

排查 Quorum TLS 启动失败

Quorum TLS 启动失败常表现为无法选主、选举连接反复断开或握手超时。排查时要同时核对节点证书身份、各节点一致的 TLS 配置,以及当前还能形成多少个彼此可通信的投票成员,才能区分握手故障与多数派丢失。

学习目标

  • 从选主现象反推 quorum 连接、TLS 握手与多数派状态
  • 核对节点证书身份、quorum 端口和 TLS 配置是否一致
  • 区分证书故障、主机名或端口不一致、滚动升级兼容问题与多数派不足

先判断是 TLS 失败还是多数派已经丢失

ZooKeeper 集群必须由多数投票成员互通后才能稳定选主。三节点集群需要至少两个投票成员形成通信;因此一台节点 TLS 配错可能只让该节点掉队,两台节点互相无法完成握手则会直接导致无 leader。

ZooKeeper Quorum TLS 启动失败诊断图

先从每台节点保存同一时间窗口的日志。重点看是否先出现 TCP 连接错误,再出现 TLS 握手错误,还是握手成功后仍不断进入 LOOKING 状态。顺序能帮助你判断故障位于网络层、TLS 层还是选举层。

核对 quorum 成员和端口

所有节点的 server.x 映射必须描述同一组成员,并且主机名应与证书 SAN 的设计一致。下面用 shell 从配置中抽取最关键的 quorum 项,避免人工浏览整份配置遗漏差异;实际路径以部署为准。

bash
CFG=/etc/zookeeper/zoo.cfg

grep -E '^(server\.|sslQuorum|portUnification|ssl\.quorum\.)' "${CFG}" | sort

预期输出

text
server.1=zk1.example.com:2888:3888
server.2=zk2.example.com:2888:3888
server.3=zk3.example.com:2888:3888
sslQuorum=true
<OTHER_SSL_QUORUM_SETTINGS>

三台机器执行后,server.x 成员、quorum 端口和 election 端口应一致;只有指向本机证书或密钥文件的位置可以按节点不同。若一台节点写了错误主机名、端口或成员 ID,先修配置再看 TLS,因为对错误目标做证书诊断没有意义。

校验证书身份和互信

Quorum TLS 是节点到节点通信,同一节点既可能作为连接发起方,也可能作为接收方。因此只验证“本机能读到 keystore”不够,还要确认每台节点的证书身份能被其他节点接受。

先检查本机 quorum keystore 中证书的主题、签发者、有效期和 SAN。下面以 PKCS12 为例;JKS 也可用同一 keytool 命令。

bash
KEYSTORE=/etc/zookeeper/pki/quorum-keystore.p12
STOREPASS='<PASSWORD>'

keytool -list -v \
  -keystore "${KEYSTORE}" \
  -storepass "${STOREPASS}"

预期输出

text
Entry type: PrivateKeyEntry
Owner: <NODE_SUBJECT>
Issuer: <CA_SUBJECT>
Valid from: <TIME> until: <TIME>
SubjectAlternativeName [
  DNSName: <NODE_FQDN>
]

<NODE_FQDN> 应覆盖该节点在 server.x 中实际使用的主机名。如果 server.2 指向 zk2.example.com,而 zk2 证书只包含 DNS:zk2,开启主机名校验时就会失败。

再检查 quorum truststore 是否包含签发其他节点证书的 CA:

bash
TRUSTSTORE=/etc/zookeeper/pki/quorum-truststore.p12
STOREPASS='<PASSWORD>'

keytool -list \
  -keystore "${TRUSTSTORE}" \
  -storepass "${STOREPASS}"

预期输出

text
<CA_ALIAS>, <TIME>, trustedCertEntry,
Certificate fingerprint (SHA-256): <FINGERPRINT>

如果集群使用不同中间 CA 签发节点证书,truststore 必须能构建出每条完整链。不要只比较证书文件名,应比较签发者和指纹。

直接验证节点之间的 TLS 路径

Quorum 端口不是普通 ZooKeeper 客户端端口,但可以用 OpenSSL 验证目标端口能否建立 TLS、服务端证书是否可被信任,以及证书 SAN 是否匹配目标主机名。先对配置中的 quorum 通信端口做检查;若你的版本或配置把 TLS 握手落在其他 quorum socket 上,应以实际配置为准。

bash
PEER=zk2.example.com
PORT=2888
CAFILE=/etc/zookeeper/pki/ca.pem
LOCAL_CERT=/etc/zookeeper/pki/quorum-client.pem
LOCAL_KEY=/etc/zookeeper/pki/quorum-client-key.pem

openssl s_client \
  -connect "${PEER}:${PORT}" \
  -servername "${PEER}" \
  -CAfile "${CAFILE}" \
  -cert "${LOCAL_CERT}" \
  -key "${LOCAL_KEY}" \
  -verify_hostname "${PEER}" \
  -verify_return_error </dev/null

预期输出

text
Verification: OK
Verify return code: 0 (ok)

如果 TCP 连接被拒绝,优先检查监听端口、地址绑定和防火墙;如果能建立 TCP 但证书验证失败,再回到 truststore、SAN、有效期和客户端认证。上例显式携带本节点用于 quorum 的 PEM 证书与私钥,用来覆盖双向认证场景;若生产凭据保存在 JKS 或 PKCS12 中,应使用等价证书材料测试,不要把临时导出的私钥留在磁盘。

处理滚动升级与配置不一致

Quorum TLS 最容易在“部分节点已经启用 TLS、部分节点仍只说纯明文”时失败。迁移阶段要确保所用 ZooKeeper 版本支持你的切换方案,并让所有节点按同一顺序推进;不要同时修改成员列表、端口和证书体系,否则失败后很难判断是哪一层引入变化。

可以在每台机器生成一份关键配置摘要并比较。下面命令可直接执行:

bash
CFG=/etc/zookeeper/zoo.cfg

grep -E '^(server\.|sslQuorum|portUnification|ssl\.quorum\.)' "${CFG}" \
  | sed 's/[[:space:]]//g' \
  | sort \
  | sha256sum

预期输出

text
<CHECKSUM>  -

三台节点若设计上应使用同一份 quorum TLS 配置,摘要应一致。若不一致,先用 diff 找出具体键值差异;证书路径确实按节点不同的环境,不应直接要求整份摘要完全相同,而应只比较公共配置项。

用多数派验证修复是否完成

修复单节点后,不要只看该节点进程“启动成功”。三节点集群至少要确认两台投票成员建立稳定 quorum 通信并完成选主,然后再确认第三台能加入且不再反复进入 LOOKING。

如果一台节点证书错误但另外两台互信正常,集群通常仍能形成 2/3 多数派;若修复后仍无 leader,应继续检查第二条独立故障路径,例如另一台节点端口不通或证书也过期。相反,如果所有节点 TLS 握手都成功却仍无法选主,就应把排查重心移出 TLS,检查 myid、成员配置、磁盘状态和选举日志。

最终验收应同时满足:各节点证书身份与 server.x 主机名一致、quorum 互信链完整、节点间握手稳定、公共 TLS 配置符合迁移阶段设计,并且集群能够形成多数派并维持稳定 leader。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 Quorum TLS 启动失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通