消息队列 / 知识点

RabbitMQ 开发与排障手册

手册条目

确认服务端与 CLI 版本,避免因版本不一致导致命令或功能判断错误。

检查 RabbitMQ 版本

在出现“命令不存在、参数不识别、节点行为与文档不一致”时,先同时记录本机 CLI 与目标节点版本。rabbitmqctl version 读取当前命令行工具版本,rabbitmq-diagnostics server_version 连接节点读取服务端版本,二者不能互相替代。

基本语法

以下命令适合在 RabbitMQ 节点主机或容器内执行。服务端命令需要节点正在运行,并且当前操作系统用户持有与节点一致的 Erlang cookie。

bash
# CLI 版本来自当前 PATH;服务端版本来自正在运行的目标节点。
cli_version="$(rabbitmqctl -q version)"
server_version="$(rabbitmq-diagnostics -q server_version)"
printf 'CLI_VERSION=%s\nSERVER_VERSION=%s\n' "$cli_version" "$server_version"

预期输出

text
CLI_VERSION=<CLI_VERSION>
SERVER_VERSION=<SERVER_VERSION>

<CLI_VERSION> 与 <SERVER_VERSION> 会替换为实际语义版本号。两者相同,说明当前 CLI 与节点来自同一 RabbitMQ 发布版本;两者不同,先确认是否调用了错误安装目录、宿主机 CLI 或另一台节点。

高频用法

本机节点直接执行基本命令。检查远程短名称节点时使用 rabbitmq-diagnostics -q -n rabbit@mq01 server_version;集群使用完整域名节点名时同时增加 --longnames。Docker 或 Kubernetes 环境应进入目标容器或 Pod 执行,避免把宿主机 CLI 版本误当成容器内版本。

升级排查时再执行 rabbitmq-diagnostics -q erlang_version 记录 Erlang/OTP 版本,并用 rabbitmqctl list_feature_flags 检查功能标志。RabbitMQ 版本一致并不代表 Erlang 版本、插件和功能标志也一致。

风险与边界

版本查询本身是只读操作,但 server_version 依赖节点名解析、CLI 通信端口和 Erlang cookie。连接失败只能说明 CLI 未能认证或访问节点,不能据此判断服务端版本损坏。

不要在共享终端历史、脚本参数或进程列表中明文传递 --erlang-cookie;可能导致集群控制凭据泄露。优先使用权限正确的本地 cookie 文件,并以 RabbitMQ 服务账户或受控运维账户执行。

发现版本不一致时不要直接覆盖安装包或重启全部节点,可能造成滚动升级中断、功能标志不兼容或集群失去可用多数。安全做法是先核对支持矩阵和升级路径,再逐节点处理。

排障清单

  • command not found:用 command -v rabbitmqctl 和 command -v rabbitmq-diagnostics 检查 PATH;包安装版常位于 RabbitMQ 的 sbin 目录。
  • CLI 版本异常:用 type -a rabbitmqctl 查找同名命令,确认没有命中旧版本、别名或宿主机工具。
  • unable to perform an operation on node:核对 -n 节点名、短名或长名模式、主机名解析、节点是否启动以及 cookie 文件所有者和权限。
  • 远程节点失败:确认节点间与 CLI 通信端口可达;不要只检查 AMQP 的 <PORT> 端口。

兼容性

Windows 使用 rabbitmqctl.bat 和 rabbitmq-diagnostics.bat。较旧安装若没有 server_version 子命令,可运行 rabbitmqctl status,从 RabbitMQ version 字段读取服务端版本;此时仍应单独执行 rabbitmqctl version 获取 CLI 版本。

目录与阅读设置

记录一个想法

RabbitMQ 开发与排障手册

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

登录哪都通