服务注册与分布式协调 / 系统课时
为各节点签发对等 TLS 证书
为各节点签发对等 TLS 证书
本节为 ZooKeeper quorum 通信准备可用于双向 TLS 的身份材料:给每个节点签发独立私钥和证书,把实际通信主机名与地址写入 SAN,并生成节点 keystore 与统一 truststore,最后在启用 TLS 前完成链路校验。
学习目标
- 按
server.x使用的 FQDN 与通信地址设计证书 SAN。 - 为每个节点生成独立私钥、CA 签名证书、PKCS12 keystore 与 truststore。
- 验证证书链、主机名和双向认证材料,避免在切换 quorum TLS 时因身份不匹配失联。
先确定每个节点的证书身份
quorum TLS 是对等认证:每个成员既充当 TLS 服务端,也会作为 TLS 客户端连接其他成员。因此节点证书应同时允许 serverAuth 与 clientAuth,每台机器拥有独立私钥,并共同信任同一个受控 CA。
证书的 SAN 要覆盖 ZooKeeper 实际用于连接的身份。若 server.x 写的是 zk1.example.com,至少包含 DNS:zk1.example.com;若部署会直接按 IP 校验,再加入对应 IP:<IP>。不要只依赖 CN,也不要为了省事给三台节点复用同一张私钥证书。

用受控 CA 签发三节点证书
组织已有内部 CA 时应直接走正式签发流程。下面的 Bash 示例用于实验或封闭环境:在一台受保护的签发主机上生成一个演示 CA,再为三台节点分别签发证书。把 <PATH> 替换为安全工作目录,把三个 <IP> 分别替换为节点真实 quorum 地址,并通过环境变量提供 STOREPASS。
#!/usr/bin/env bash
set -euo pipefail
umask 077
ROOT="<PATH>"
ZK1_IP="<IP>"
ZK2_IP="<IP>"
ZK3_IP="<IP>"
: "${STOREPASS:?请先通过环境变量提供 STOREPASS}"
CA_DIR="$ROOT/ca"
OUT_DIR="$ROOT/issued"
CA_KEY="$CA_DIR/quorum-ca.key"
CA_CERT="$CA_DIR/quorum-ca.crt"
mkdir -p "$CA_DIR" "$OUT_DIR"
if [[ ! -s "$CA_KEY" || ! -s "$CA_CERT" ]]; then
rm -f "$CA_KEY" "$CA_CERT" "$CA_DIR/quorum-ca.srl"
openssl req -x509 -newkey rsa:4096 -nodes -sha256 -days 3650 -subj "/CN=ZooKeeper Quorum CA" -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign" -keyout "$CA_KEY" -out "$CA_CERT" >/dev/null 2>&1
fi
issue_node() {
local host="$1"
local ip="$2"
local dir="$OUT_DIR/$host"
rm -rf "$dir"
mkdir -p "$dir"
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out "$dir/node.key" >/dev/null 2>&1
openssl req -new -sha256 -key "$dir/node.key" -subj "/CN=$host" -out "$dir/node.csr" >/dev/null 2>&1
cat > "$dir/ext.cnf" <<EOF
basicConstraints=critical,CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth,clientAuth
subjectAltName=DNS:${host},IP:${ip}
EOF
openssl x509 -req -sha256 -days 365 -in "$dir/node.csr" -CA "$CA_CERT" -CAkey "$CA_KEY" -CAcreateserial -extfile "$dir/ext.cnf" -out "$dir/node.crt" >/dev/null 2>&1
openssl verify -CAfile "$CA_CERT" "$dir/node.crt" >/dev/null
openssl x509 -in "$dir/node.crt" -noout -checkhost "$host" >/dev/null
openssl x509 -in "$dir/node.crt" -noout -checkip "$ip" >/dev/null
openssl pkcs12 -export -name "$host" -inkey "$dir/node.key" -in "$dir/node.crt" -certfile "$CA_CERT" -out "$dir/quorum-keystore.p12" -passout "pass:$STOREPASS" >/dev/null 2>&1
keytool -importcert -noprompt -alias quorum-ca -file "$CA_CERT" -keystore "$dir/quorum-truststore.p12" -storetype PKCS12 -storepass "$STOREPASS" >/dev/null 2>&1
printf '%s\n' "$STOREPASS" > "$dir/keystore.pass"
printf '%s\n' "$STOREPASS" > "$dir/truststore.pass"
printf 'READY %s\n' "$host"
}
issue_node "zk1.example.com" "$ZK1_IP"
issue_node "zk2.example.com" "$ZK2_IP"
issue_node "zk3.example.com" "$ZK3_IP"预期输出
READY zk1.example.com
READY zk2.example.com
READY zk3.example.com脚本成功意味着三项检查都已通过:证书链能回到同一 CA、DNS SAN 与节点 FQDN 匹配、IP SAN 与传入地址匹配。签发完成后只把每台节点自己的 quorum-keystore.p12、quorum-truststore.p12 与两个受限密码文件分发到对应服务器;CA 私钥 quorum-ca.key 必须继续留在签发端。
把私钥与信任链映射到 ZooKeeper
每个节点的 keystore 内含本机私钥、节点证书和 CA 链;truststore 只需要包含允许签发 quorum 成员证书的 CA。三台节点可以使用相同 CA truststore,但绝不能共享同一个 keystore。
准备阶段可以先保持 sslQuorum=false,把路径和认证策略放好,等所有节点材料都验证通过后再进行集群级 TLS 切换。
sslQuorum=false
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.quorum.keyStore.location=<PATH>/quorum-keystore.p12
ssl.quorum.keyStore.type=PKCS12
ssl.quorum.keyStore.passwordPath=<PATH>/keystore.pass
ssl.quorum.trustStore.location=<PATH>/quorum-truststore.p12
ssl.quorum.trustStore.type=PKCS12
ssl.quorum.trustStore.passwordPath=<PATH>/truststore.pass
ssl.quorum.clientAuth=need
ssl.quorum.hostnameVerification=truessl.quorum.clientAuth=need 要求连接方必须出示可被信任链验证的证书;ssl.quorum.hostnameVerification=true 则让对端身份继续受主机名约束。passwordPath 适用于支持该选项的 ZooKeeper 版本;较旧版本需要改用对应 password 属性,并把配置文件本身纳入秘密管理。
在节点上复核分发结果
分发后不要直接启用 TLS,先在每台节点本地确认两个 PKCS12 文件可读且密码正确。以下命令读取密码文件,只输出最终判定,不打印秘密内容。
set -e
KEYSTORE_PASS="$(cat "<PATH>/keystore.pass")"
TRUSTSTORE_PASS="$(cat "<PATH>/truststore.pass")"
keytool -list -keystore "<PATH>/quorum-keystore.p12" -storetype PKCS12 -storepass "$KEYSTORE_PASS" >/dev/null
keytool -list -keystore "<PATH>/quorum-truststore.p12" -storetype PKCS12 -storepass "$TRUSTSTORE_PASS" >/dev/null
echo TLS_MATERIAL_OK预期输出
TLS_MATERIAL_OK切换前的验收条件
启用 quorum TLS 前应同时满足:每台节点拥有唯一私钥;节点证书含正确 DNS SAN,按需含 IP SAN;证书允许 serverAuth 与 clientAuth;所有节点 truststore 信任同一有效 CA;ZooKeeper 运行账号能读取 keystore、truststore 和密码文件;CA 私钥不在任何 ZooKeeper 节点上。
这些条件全部成立后,双向 TLS 才具备稳定的身份基础。后续真正切换 sslQuorum 时,任何节点出示错误证书、未知 CA 或不匹配主机名,都会在建立 quorum 会话之前被 TLS 层拒绝。