服务注册与分布式协调 / 系统课时
切换 Netty 并启用安全端口
切换 Netty 并启用安全端口
客户端 TLS 不能只靠增加一个端口完成:ZooKeeper 服务端必须使用支持 TLS 的 Netty 连接工厂,并为 secureClientPort 配置证书材料。本节保留普通端口用于迁移,同时启用独立 TLS 端口并验证安全入口可建立会话。
学习目标
- 能切换到
NettyServerCnxnFactory并配置secureClientPort - 能区分
clientPort与secureClientPort的职责 - 能用 TLS 客户端实际验证安全端口,而不是只看进程是否启动
配置普通端口与安全端口
先准备服务端 keystore 和 truststore,并确认 ZooKeeper 进程账户可读。下面是 zoo.cfg 的片段示例:2181 继续接受明文客户端,2281 专门接受 TLS 客户端,两者同时存在时就是迁移期的双端口模式。
clientPort=2181
secureClientPort=2281
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<PATH>/server-keystore.p12
ssl.keyStore.password=<KEYSTORE_PASSWORD>
ssl.keyStore.type=PKCS12
ssl.trustStore.location=<PATH>/server-truststore.p12
ssl.trustStore.password=<TRUSTSTORE_PASSWORD>
ssl.trustStore.type=PKCS12
ssl.clientAuth=needsecureClientPort 不会把 clientPort 自动变成 TLS。只要 clientPort 仍保留,明文入口就仍然存在;如果最终要求客户端链路全部加密,应在迁移完成并确认所有客户端都已切换后再移除普通端口。

重启后先检查监听入口
完成配置后按现有运维方式重启单个节点,再检查两个端口是否进入监听状态。以下命令只验证 TCP 监听,不等同于 TLS 已经可用。
ss -lnt | awk '$4 ~ /:(2181|2281)$/ {print $4}'预期输出
<HOST>:2181
<HOST>:2281<HOST> 可能显示为 0.0.0.0、[::]、* 或具体绑定地址。若只有 2181,优先检查 serverCnxnFactory 是否确实切到 Netty、secureClientPort 是否被当前配置文件加载,以及 keystore/truststore 路径和密码是否有效。
用 Netty TLS 客户端完成会话验证
只看到 2281 监听还不够,因为证书链、主机名校验或双向 TLS 都可能在握手阶段失败。下面使用 ZooKeeper 自带 CLI,通过 JVM 参数启用 Netty 客户端和安全连接,并提供客户端证书及信任库。
export CLIENT_JVMFLAGS="-Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty -Dzookeeper.client.secure=true -Dzookeeper.ssl.keyStore.location=<PATH>/client-keystore.p12 -Dzookeeper.ssl.keyStore.password=<KEYSTORE_PASSWORD> -Dzookeeper.ssl.keyStore.type=PKCS12 -Dzookeeper.ssl.trustStore.location=<PATH>/client-truststore.p12 -Dzookeeper.ssl.trustStore.password=<TRUSTSTORE_PASSWORD> -Dzookeeper.ssl.trustStore.type=PKCS12"
printf 'ls /\nquit\n' | <PATH>/bin/zkCli.sh -server zk1.example.com:2281预期结果
WATCHER::
WatchedEvent state:SyncConnected
[...]根节点列表内容会随集群实际数据变化,因此用 [...] 表示动态结果;关键验收点是客户端进入 SyncConnected,随后 ls / 能返回结果。如果握手在建立会话前失败,应优先检查客户端是否信任服务端证书、服务端在 ssl.clientAuth=need 时是否信任客户端证书,以及证书中的主机名或 SAN 是否覆盖实际连接地址。
迁移时避免把 TLS 与端口可达混为一谈
clientPort 和 secureClientPort 是两个独立入口。防火墙放通 2281、进程监听 2281、TLS 握手成功、ZooKeeper 会话建立是四个不同层次的检查点,应按这个顺序定位问题。
当安全端口能够通过 Netty TLS 客户端稳定建立会话,并且业务客户端已全部切换后,才算真正完成客户端链路入口的 TLS 化,而不是仅仅在配置文件里增加了 secureClientPort。