消息队列 / 知识点

RabbitMQ 开发与排障手册

手册条目

在不中断或最小化中断的情况下更新服务端和客户端证书。

轮换 TLS 证书

用于在 RabbitMQ 节点运行期间替换服务端证书、私钥和信任链,并通过清空 PEM 缓存让新建 TLS 连接立即读取新文件。若同时更换签发 CA,必须先建立新旧 CA 的重叠信任窗口,避免服务端或客户端在切换瞬间批量握手失败。:contentReference[oaicite:0]{index=0}

轮换路径

仅更新同一 CA 签发的服务端叶子证书时,可逐节点执行“预检、替换、清缓存、握手验证”。更换 CA 或 mTLS 客户端证书时,顺序必须是:先让双方同时信任旧 CA 和新 CA,再更换服务端与客户端叶子证书,确认旧证书不再使用后才删除旧 CA。

RabbitMQ TLS 证书分阶段轮换流程

轮换前检查

先确认新证书在有效期内、SAN 覆盖客户端实际连接的主机名、证书链可验证,并且证书与私钥属于同一密钥对。RabbitMQ 进程还必须能够读取三个 PEM 文件;否则清缓存后,新连接可能立即出现 unknown ca、bad certificate 或密钥读取错误。

bash
set -euo pipefail

NEW_DIR=/secure/staging/rmq-1

openssl x509 -in "$NEW_DIR/server.pem" \
  -noout -subject -issuer -dates -ext subjectAltName
openssl verify -CAfile "$NEW_DIR/ca-bundle.pem" "$NEW_DIR/server.pem"

CERT_PUB=$(openssl x509 -in "$NEW_DIR/server.pem" -pubkey -noout \
  | openssl pkey -pubin -outform DER 2>/dev/null | sha256sum | awk '{print $1}')
KEY_PUB=$(openssl pkey -in "$NEW_DIR/server-key.pem" -pubout -outform DER 2>/dev/null \
  | sha256sum | awk '{print $1}')
test "$CERT_PUB" = "$KEY_PUB"
echo "certificate and private key match"

预期输出

text
subject=<SUBJECT>
issuer=<ISSUER>
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
    DNS:rmq.example.com
/secure/staging/rmq-1/server.pem: OK
certificate and private key match

<SUBJECT>、<ISSUER> 和 <TIME> 会随证书变化;若 openssl verify 非 OK 或最后一行未出现,不要覆盖线上文件。

在线替换与重载

在每个节点本机准备 .next 文件,再用同文件系统内的 mv 替换,最后清空该节点的 PEM 缓存。一次只处理一个节点,并保持其余节点继续接流量;配置中的 ssl_options.certfile、keyfile、cacertfile 路径应保持不变。RabbitMQ 官方轮换流程就是替换磁盘文件后调用 ssl:clear_pem_cache()。:contentReference[oaicite:1]{index=1}

bash
set -euo pipefail

NODE='rabbit@rmq-1'
TLS_DIR=/etc/rabbitmq/tls
NEW_DIR=/secure/staging/rmq-1

# 先完整写入临时文件,避免 RabbitMQ 读取到半写入内容。
install -o rabbitmq -g rabbitmq -m 0644 \
  "$NEW_DIR/ca-bundle.pem" "$TLS_DIR/ca-bundle.pem.next"
install -o rabbitmq -g rabbitmq -m 0644 \
  "$NEW_DIR/server.pem" "$TLS_DIR/server.pem.next"
install -o rabbitmq -g rabbitmq -m 0600 \
  "$NEW_DIR/server-key.pem" "$TLS_DIR/server-key.pem.next"

mv "$TLS_DIR/ca-bundle.pem.next" "$TLS_DIR/ca-bundle.pem"
mv "$TLS_DIR/server.pem.next" "$TLS_DIR/server.pem"
mv "$TLS_DIR/server-key.pem.next" "$TLS_DIR/server-key.pem"

rabbitmqctl -n "$NODE" eval 'ssl:clear_pem_cache().'

预期输出

text
ok

ok 只表示缓存清理调用成功,不代表证书链、SAN 或客户端 mTLS 身份已经验证通过。

验证新证书

从真实客户端网络路径发起新握手,不要只检查节点本机文件。启用 mTLS 时保留 -cert 与 -key;仅验证服务端证书时删除这两个参数。客户端通常会校验证书链以及 SAN 或 CN 是否匹配连接主机名。:contentReference[oaicite:2]{index=2}

bash
openssl s_client -connect rmq.example.com:5671 -servername rmq.example.com -CAfile /etc/ssl/certs/rabbitmq-ca-bundle.pem -cert /etc/rabbitmq/client/client.pem -key /etc/rabbitmq/client/client-key.pem -verify_return_error </dev/null 2>&1 | grep -E 'Protocol|Cipher|Verification|Verify return code'

预期输出

text
Protocol version: TLSv1.3
Ciphersuite: <CIPHER>
Verification: OK

OpenSSL 1.1.x 可能显示 Verify return code: 0 (ok);协议和密码套件以实际协商结果为准。随后让应用建立一条新 RabbitMQ 连接并完成发布、确认和消费,才算业务验证完成。

风险、排障与兼容性

  • 直接切换 CA:客户端尚未信任新 CA,或 RabbitMQ 尚未信任新客户端 CA 时,会触发大面积 Unknown CA。安全替代是先发布包含新旧 CA 的 bundle,最后才移除旧 CA。
  • 证书与私钥不匹配:清缓存后新握手失败,现有长连接可能暂时掩盖故障。安全替代是上线前比较公钥摘要,并逐节点验证新连接。
  • SAN、有效期或权限错误:客户端会拒绝主机名不匹配、过期或尚未生效的证书;RabbitMQ 用户不可读私钥时也无法完成新握手。应恢复备份文件并再次清缓存。
  • 需要立即撤销旧客户端证书:TLS 会话恢复或尚未重连的长连接可能继续存在。应同步处理会话缓存策略、主动断开目标连接,并核对应用重连状态。
  • 命令不可用或版本行为不确定:先在测试节点执行 rabbitmqctl eval 'ssl:clear_pem_cache().'。若版本不支持,安全替代是排空并滚动重启单个节点,而不是同时重启整个集群。

速查顺序:双 CA 信任先行,叶子证书逐节点轮换,新连接验证通过,最后移除旧 CA。

目录与阅读设置

记录一个想法

RabbitMQ 开发与排障手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通