服务注册与分布式协调 / 系统课时
客户端与服务端 TLS
客户端与服务端 TLS
本节把 ZooKeeper 的客户端链路从明文连接改为 TLS,并进一步启用双向认证。完成后,你会知道服务端与客户端各自需要什么证书材料,如何配置安全端口,以及怎样验证握手失败究竟是端口、证书还是信任链问题。
学习目标
- 区分密钥库与信任库在 TLS 握手中的职责
- 配置
secureClientPort、Netty 与双向 TLS - 使用 ZooKeeper CLI 验证安全连接并定位常见握手错误
先理清证书与信任关系
每一端都需要解决两个问题:向对方证明“我是谁”,以及判断“我是否信任你”。密钥库存放本端私钥和证书链;信任库存放受信任 CA 或对端证书。服务端用自己的密钥库出示服务器证书,客户端用信任库验证它;启用 ssl.clientAuth=need 后,客户端还必须出示客户端证书,服务端再用自己的信任库验证客户端。
生产环境应使用组织 CA 或受控私有 CA 签发证书,并让证书 SAN 覆盖实际连接使用的 DNS 名称或 IP。不要通过关闭主机名校验来掩盖证书名称不匹配,这会削弱对中间人攻击的防护。

配置服务端安全端口
示例采用 PKCS12。假设 server.p12 已包含服务端私钥和完整证书链,truststore.p12 已导入签发客户端证书的 CA;密码文件只保存对应口令,并由 ZooKeeper 进程账户最小权限读取。ZooKeeper 3.8+ 可使用 passwordPath,避免把口令直接写进 zoo.cfg。
secureClientPort=2281
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<PATH>/server.p12
ssl.keyStore.type=PKCS12
ssl.keyStore.passwordPath=<PATH>/server-store.pass
ssl.trustStore.location=<PATH>/truststore.p12
ssl.trustStore.type=PKCS12
ssl.trustStore.passwordPath=<PATH>/truststore.pass
ssl.clientAuth=need这段配置只开放安全客户端端口。若正在从明文端口迁移,可暂时同时保留 clientPort=2181 与 secureClientPort=2281,先让客户端切换完成,再移除明文端口;不要把“同时监听两个端口”误认为同一个端口能自动识别明文和 TLS。
配置客户端并验证
客户端连接安全端口时也必须使用 Netty,并设置 zookeeper.client.secure=true。因为服务端要求双向认证,客户端密钥库必须含客户端私钥和证书链,客户端信任库必须信任服务器证书的签发 CA。
CLIENT_JVMFLAGS="-Dzookeeper.client.secure=true -Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty -Dzookeeper.ssl.keyStore.location=<PATH>/client.p12 -Dzookeeper.ssl.keyStore.type=PKCS12 -Dzookeeper.ssl.keyStore.passwordPath=<PATH>/client-store.pass -Dzookeeper.ssl.trustStore.location=<PATH>/truststore.p12 -Dzookeeper.ssl.trustStore.type=PKCS12 -Dzookeeper.ssl.trustStore.passwordPath=<PATH>/truststore.pass" bin/zkCli.sh -server zk1.example.com:2281预期输出(会话序号可能不同):
[zk: zk1.example.com:2281(CONNECTED) <ID>]进入 CONNECTED 交互提示说明 TLS 握手和 ZooKeeper 会话都已建立。生产客户端应把集群多个安全端口都写入连接串,例如 zk1.example.com:2281,zk2.example.com:2281,zk3.example.com:2281,以保留故障切换能力。
握手失败时按层定位
先确认客户端连接的是 secureClientPort,再检查双方是否使用 Netty。随后检查证书有效期、SAN、证书链和信任库;当 ssl.clientAuth=need 时,还要确认客户端确实提供了带私钥的证书,而不是只有 CA 证书。
如果错误表现为“不受信任的证书”,修复信任链;如果是主机名不匹配,修复 SAN;如果服务端要求客户端证书而客户端未提供,则补齐客户端密钥库。只有 TLS 握手和 ZooKeeper 会话都成功,才算安全端口真正可用。