服务注册与分布式协调 / 系统课时
让 Java 客户端通过 TLS 连接
让 Java 客户端通过 TLS 连接
这一节把已经开放安全端口的 ZooKeeper 接到 Java 客户端:切换为 Netty 连接实现,开启 secure 模式并加载信任库,再通过一次读写和 JVM TLS 握手日志确认业务请求确实走加密通道。
学习目标
- 为 Java 客户端启用
ClientCnxnSocketNetty与zookeeper.client.secure - 正确加载服务端 CA 信任库并连接
secureClientPort - 用业务请求和 TLS 握手日志同时验证加密链路
明确安全端口与客户端模式
ZooKeeper 的 secureClientPort 专门接收 TLS 客户端连接,而 Java 客户端要使用安全端口,必须改用 org.apache.zookeeper.ClientCnxnSocketNetty 并开启 zookeeper.client.secure=true。普通 NIO 客户端直接连安全端口并不会自动升级为 TLS。([Apache ZooKeeper][1])
片段示例:如果本节只验证服务端证书和链路加密,服务器端可显式关闭客户端证书要求;证书路径、数据目录和其他集群参数仍按现有部署保留。
secureClientPort=<PORT>
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<PATH>/server-keystore.p12
ssl.keyStore.password=<PASSWORD>
ssl.keyStore.type=PKCS12
ssl.clientAuth=nonessl.clientAuth=none 只适用于单向 TLS。若服务器已经要求 mTLS,则不要为了让客户端“连得上”而关闭它,而应同时给客户端配置自己的 keyStore。当前 ZooKeeper 的 ssl.clientAuth 支持 none、want、need,默认值为 need。([Apache ZooKeeper][1])

配置并运行 Java 客户端
可运行 Java 主程序如下。前提是项目已经引入与目标集群兼容的 ZooKeeper Java 客户端依赖;连接地址必须填写安全端口,而不是原来的明文 clientPort。
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooDefs;
import org.apache.zookeeper.ZooKeeper;
public class TlsZooKeeperClient {
public static void main(String[] args) throws Exception {
String connectString =
System.getenv().getOrDefault("ZK_CONNECT", "zk1.example.com:2281");
CountDownLatch connected = new CountDownLatch(1);
ZooKeeper zk = new ZooKeeper(connectString, 10_000, event -> {
if (event.getState() == Watcher.Event.KeeperState.SyncConnected) {
connected.countDown();
}
});
if (!connected.await(10, TimeUnit.SECONDS)) {
zk.close();
throw new IllegalStateException("ZooKeeper TLS connection timed out");
}
String path = "/tls-check";
byte[] expected = "encrypted".getBytes(StandardCharsets.UTF_8);
if (zk.exists(path, false) == null) {
zk.create(
path,
expected,
ZooDefs.Ids.OPEN_ACL_UNSAFE,
CreateMode.PERSISTENT);
} else {
zk.setData(path, expected, -1);
}
byte[] data = zk.getData(path, false, null);
System.out.println("state=" + zk.getState());
System.out.println("data=" + new String(data, StandardCharsets.UTF_8));
zk.close();
}
}示例故意使用开放 ACL,只隔离验证传输层;权限控制应在后续安全策略中单独收紧。启动时用系统属性切换 Netty、安全模式和信任库,并打开 JDK 的握手调试信息,确认 TLS 在 ZooKeeper 会话建立前已经完成。
ZK_CONNECT=<HOST>:<PORT> java \
-Djavax.net.debug=ssl:handshake \
-Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty \
-Dzookeeper.client.secure=true \
-Dzookeeper.ssl.trustStore.location=<PATH>/client-truststore.p12 \
-Dzookeeper.ssl.trustStore.password=<PASSWORD> \
-Dzookeeper.ssl.trustStore.type=PKCS12 \
-cp "<PATH>/classes:<PATH>/lib/*" \
TlsZooKeeperClient预期输出
<TLS_HANDSHAKE_DETAILS>
state=CONNECTED
data=encrypted<TLS_HANDSHAKE_DETAILS> 代表随 JDK 版本变化的握手调试行;应能看到 ClientHello、ServerHello、证书校验和协商出的 TLS 协议相关信息。<HOST>、<PORT>、<PATH> 与证书密码按实际环境替换。
同时验证“连通”和“加密”
程序打印 CONNECTED 只能证明 ZooKeeper 会话建立成功;真正确认加密还要看到 TLS 握手先于 ZooKeeper 业务请求完成。若关闭 zookeeper.client.secure 后同一地址无法正常建立 ZooKeeper 会话,而启用 secure 后可以读写 /tls-check,说明客户端确实在使用安全端口。
ZooKeeper 默认启用服务端主机名校验。连接串里的主机名必须出现在服务端证书可接受的名称范围中;生产环境不要通过关闭 zookeeper.ssl.hostnameVerification 来掩盖证书 SAN 配置错误。([Apache ZooKeeper][1])
失败时按握手层定位
出现 Connection refused 时先检查 <HOST>:<PORT> 是否真的是 secureClientPort 以及服务端是否监听;出现 SSLHandshakeException 或 PKIX 路径错误时检查客户端 trustStore 是否信任签发服务端证书的 CA;出现主机名校验失败时检查连接串主机名与服务端证书 SAN。
最重要的边界是把“ZooKeeper 会话失败”和“TLS 握手失败”分开处理:前者进入 ZooKeeper 协议层后再排查超时、ACL 等问题,后者应先修正端口、证书链、信任库或主机名,业务代码本身通常不是根因。