服务注册与分布式协调 / 系统课时
排查 Quorum TLS 启动失败
排查 Quorum TLS 启动失败
Quorum TLS 启动失败常表现为无法选主、选举连接反复断开或握手超时。排查时要同时核对节点证书身份、各节点一致的 TLS 配置,以及当前还能形成多少个彼此可通信的投票成员,才能区分握手故障与多数派丢失。
学习目标
- 从选主现象反推 quorum 连接、TLS 握手与多数派状态
- 核对节点证书身份、quorum 端口和 TLS 配置是否一致
- 区分证书故障、主机名或端口不一致、滚动升级兼容问题与多数派不足
先判断是 TLS 失败还是多数派已经丢失
ZooKeeper 集群必须由多数投票成员互通后才能稳定选主。三节点集群需要至少两个投票成员形成通信;因此一台节点 TLS 配错可能只让该节点掉队,两台节点互相无法完成握手则会直接导致无 leader。

先从每台节点保存同一时间窗口的日志。重点看是否先出现 TCP 连接错误,再出现 TLS 握手错误,还是握手成功后仍不断进入 LOOKING 状态。顺序能帮助你判断故障位于网络层、TLS 层还是选举层。
核对 quorum 成员和端口
所有节点的 server.x 映射必须描述同一组成员,并且主机名应与证书 SAN 的设计一致。下面用 shell 从配置中抽取最关键的 quorum 项,避免人工浏览整份配置遗漏差异;实际路径以部署为准。
CFG=/etc/zookeeper/zoo.cfg
grep -E '^(server\.|sslQuorum|portUnification|ssl\.quorum\.)' "${CFG}" | sort预期输出
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 命令。
KEYSTORE=/etc/zookeeper/pki/quorum-keystore.p12
STOREPASS='<PASSWORD>'
keytool -list -v \
-keystore "${KEYSTORE}" \
-storepass "${STOREPASS}"预期输出
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:
TRUSTSTORE=/etc/zookeeper/pki/quorum-truststore.p12
STOREPASS='<PASSWORD>'
keytool -list \
-keystore "${TRUSTSTORE}" \
-storepass "${STOREPASS}"预期输出
<CA_ALIAS>, <TIME>, trustedCertEntry,
Certificate fingerprint (SHA-256): <FINGERPRINT>如果集群使用不同中间 CA 签发节点证书,truststore 必须能构建出每条完整链。不要只比较证书文件名,应比较签发者和指纹。
直接验证节点之间的 TLS 路径
Quorum 端口不是普通 ZooKeeper 客户端端口,但可以用 OpenSSL 验证目标端口能否建立 TLS、服务端证书是否可被信任,以及证书 SAN 是否匹配目标主机名。先对配置中的 quorum 通信端口做检查;若你的版本或配置把 TLS 握手落在其他 quorum socket 上,应以实际配置为准。
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预期输出
Verification: OK
Verify return code: 0 (ok)如果 TCP 连接被拒绝,优先检查监听端口、地址绑定和防火墙;如果能建立 TCP 但证书验证失败,再回到 truststore、SAN、有效期和客户端认证。上例显式携带本节点用于 quorum 的 PEM 证书与私钥,用来覆盖双向认证场景;若生产凭据保存在 JKS 或 PKCS12 中,应使用等价证书材料测试,不要把临时导出的私钥留在磁盘。
处理滚动升级与配置不一致
Quorum TLS 最容易在“部分节点已经启用 TLS、部分节点仍只说纯明文”时失败。迁移阶段要确保所用 ZooKeeper 版本支持你的切换方案,并让所有节点按同一顺序推进;不要同时修改成员列表、端口和证书体系,否则失败后很难判断是哪一层引入变化。
可以在每台机器生成一份关键配置摘要并比较。下面命令可直接执行:
CFG=/etc/zookeeper/zoo.cfg
grep -E '^(server\.|sslQuorum|portUnification|ssl\.quorum\.)' "${CFG}" \
| sed 's/[[:space:]]//g' \
| sort \
| sha256sum预期输出
<CHECKSUM> -三台节点若设计上应使用同一份 quorum TLS 配置,摘要应一致。若不一致,先用 diff 找出具体键值差异;证书路径确实按节点不同的环境,不应直接要求整份摘要完全相同,而应只比较公共配置项。
用多数派验证修复是否完成
修复单节点后,不要只看该节点进程“启动成功”。三节点集群至少要确认两台投票成员建立稳定 quorum 通信并完成选主,然后再确认第三台能加入且不再反复进入 LOOKING。
如果一台节点证书错误但另外两台互信正常,集群通常仍能形成 2/3 多数派;若修复后仍无 leader,应继续检查第二条独立故障路径,例如另一台节点端口不通或证书也过期。相反,如果所有节点 TLS 握手都成功却仍无法选主,就应把排查重心移出 TLS,检查 myid、成员配置、磁盘状态和选举日志。
最终验收应同时满足:各节点证书身份与 server.x 主机名一致、quorum 互信链完整、节点间握手稳定、公共 TLS 配置符合迁移阶段设计,并且集群能够形成多数派并维持稳定 leader。