跳至主要内容
版本：4.0

命令行工具

目录​

本指南涵盖了与 RabbitMQ CLI 工具使用相关的许多主题

概述​

标准 RabbitMQ CLI 工具​

RabbitMQ 附带多个命令行工具，每个工具都有一组相关的命令

在 Windows 上，以上工具名称将以 .bat 结尾，例如，Windows 安装中的 rabbitmqctl 将命名为 rabbitmqctl.bat。

其他工具​

其他工具是可选的，可以从 GitHub 获取

不同的工具涵盖不同的使用场景。例如，rabbitmqctl 通常仅对 RabbitMQ 管理员可用，因为它提供了对节点的完全控制，包括虚拟主机、用户和权限管理、对节点数据进行破坏性操作等。

rabbitmqadmin 构建在 HTTP API 之上并使用不同的机制，并且仅要求 HTTP API 端口对外部连接开放。

即使 CLI 工具与服务器一起提供，大多数命令 也可用于操作远程节点。插件可以 提供 CLI 命令，这些命令将由 CLI 工具为显式启用的插件发现。

系统和环境要求​

RabbitMQ CLI 工具需要安装 兼容的 Erlang/OTP 版本。

这些工具假设系统区域设置是 UTF-8 区域设置（例如 en_GB.UTF-8 或 en_US.UTF-8）。如果不是这种情况，工具可能仍然可以正常工作，但不能保证。在非 UTF-8 区域设置中将发出警告。

安装​

除了 rabbitmqadmin 之外，以上所有工具都与 RabbitMQ 一起提供，并且可以在安装根目录下的 sbin 目录中找到。对于大多数程序包类型，该目录在安装时会添加到 PATH 中。这意味着核心工具（如 rabbitmq-diagnostics 和 rabbitmqctl）在每个安装了 RabbitMQ 的节点上都可用。

通用 Unix 程序包 用户必须确保安装根目录下的 sbin 目录已添加到 PATH 中，以便更轻松地进行交互式使用。非交互式用例可以使用完整路径或相对路径，而无需修改 PATH 环境变量。

rabbitmqadmin 是一个独立工具（除了 Python 3 之外没有其他依赖项），可以从正在运行的节点下载或 直接从 GitHub 下载。

如果需要从远程节点进行交互，请下载并解压缩 通用 Unix 程序包 或使用 Windows 安装程序。

除了 身份验证 之外，核心 CLI 工具的所有配置都是可选的。

需要特定参数的命令会在用法部分列出它们，并在执行时报告任何缺少的参数。

使用帮助命令发现命令​

要找出可用的命令，请使用 help 命令

rabbitmqctl help

rabbitmq-diagnostics help

该命令可以显示特定命令的用法信息

rabbitmq-diagnostics help status

或者，可以使用 --help 选项

rabbitmqctl --help

rabbitmq-diagnostics --help

包括各个命令

rabbitmq-diagnostics status --help

rabbitmqctl​

rabbitmqctl 是随 RabbitMQ 提供的原始 CLI 工具。它支持各种操作，主要是在管理（操作）方面。

这包括

  • 停止节点
  • 访问节点状态、有效配置、健康检查
  • 虚拟主机管理
  • 用户和权限管理
  • 策略管理
  • 列出队列、连接、通道、交换机、使用者
  • 集群成员管理

等等。

rabbitmqctl 使用 共享密钥身份验证机制（如下所述）与服务器节点通信。

rabbitmq-queues​

rabbitmq-queues 允许操作员管理 复制队列 的副本。它与 RabbitMQ 一起提供。

大多数命令仅支持联机模式（当目标节点正在运行时）。

rabbitmq-queues 使用 共享密钥身份验证机制（如下所述）与服务器节点通信。

rabbitmq-streams​

rabbitmq-streams 允许操作员管理 流 的副本。它与 RabbitMQ 一起提供。

大多数命令仅支持联机模式（当目标节点正在运行时）。

rabbitmq-streams 使用 共享密钥身份验证机制（如下所述）与服务器节点通信。

rabbitmq-diagnostics​

rabbitmq-diagnostics 是检查节点状态的主要工具。它有许多命令允许操作员研究系统的各个方面。它与 RabbitMQ 一起提供。

它支持联机模式（当目标节点正在运行时）和脱机模式（更改在节点重新启动时生效）。

rabbitmq-diagnostics 使用 共享密钥身份验证机制（如下所述）与服务器节点通信。

rabbitmq-plugins​

rabbitmq-plugins 是一个管理插件的工具：列出、启用和禁用它们。它与 RabbitMQ 一起提供。

它支持联机模式（当目标节点正在运行时）和脱机模式（更改在节点重新启动时生效）。

rabbitmq-plugins 使用 共享密钥身份验证机制（如下所述）与服务器节点通信。

rabbitmq-upgrade​

rabbitmq-upgrade 是一个专门用于升级前、升级和升级后操作的工具。它与 RabbitMQ 一起提供。

大多数命令仅支持联机模式（当目标节点正在运行时）。

rabbitmq-upgrade 使用 共享密钥身份验证机制（如下所述）与服务器节点通信。

脱机模式​

--offline 是 rabbitmq-plugins 命令支持的一个标志。提供时，该工具将避免联系目标节点，而是直接对插件文件进行操作。

当使用 --offline 标志时，该命令将依赖于 环境变量 来确定在何处查找本地节点的插件目录。

例如，它将像 RabbitMQ 节点一样尊重和使用 RABBITMQ_PLUGINS_DIR 环境变量值。当为服务器节点覆盖 RABBITMQ_PLUGINS_DIR 时，也必须为调用 CLI 工具的本地操作系统用户设置相同的变量。

身份验证​

除了 rabbitmqadmin 之外，RabbitMQ 工具使用 共享密钥身份验证机制。这要求 节点间和 CLI 通信端口（默认情况下）对目标节点上的外部连接开放。

对远程服务器节点使用 CLI 工具​

CLI 工具可用于与远程节点以及本地节点通信。节点由 节点名称 标识。如果未指定节点名称，则假定 rabbit@{local hostname} 为目标。联系远程节点时，将应用相同的 身份验证要求。

要联系远程节点，请使用 rabbitmqctl、rabbitmq-diagnostics 和其他核心 CLI 工具接受的 --node（-n）选项。以下示例联系节点 [email protected] 以了解其状态

rabbitmq-diagnostics status -n [email protected]

某些命令，例如

rabbitmq-diagnostics status

可用于任何节点。其他，例如

rabbitmqctl shutdown

或

rabbitmqctl wait

只能在其目标节点所在的同一主机或同一容器中运行。这些命令通常依赖于或修改本地环境中的某些内容，例如本地启用的插件文件。

节点名称​

RabbitMQ 节点由节点名称标识。节点名称由两部分组成，一个前缀（通常为 rabbit）和主机名。例如，[email protected] 是一个节点名称，前缀为 rabbit，主机名为 node1.messaging.svc.local。

集群中的节点名称必须唯一。如果多个节点在给定主机上运行（这在开发和 QA 环境中通常是这种情况），则它们必须使用不同的前缀，例如 rabbit1@hostname 和 rabbit2@hostname。

CLI 工具使用节点名称识别和寻址服务器节点。大多数 CLI 命令都针对称为目标节点的节点调用。要指定目标节点，请使用 --node（-n）选项。例如，要对节点 [email protected] 运行健康检查

rabbitmq-diagnostics -n rabbit@warp10 check_alarms

某些命令同时接受目标节点和另一个节点名称。例如，rabbitmqctl forget_cluster_node 同时接受目标节点（将执行操作的节点）和要删除的节点的名称。

在集群中，节点使用节点名称相互识别和联系。有关详细信息，请参阅集群指南。

节点启动时，它会检查是否已为其分配节点名称。这是通过 RABBITMQ_NODENAME 环境变量 完成的。如果未显式配置任何值，则节点会解析其主机名并在其前面加上 rabbit 来计算其节点名称。

如果系统对主机名使用完全限定域名 (FQDN)，则必须将 RabbitMQ 节点和 CLI 工具配置为使用所谓的长节点名称。对于服务器节点，可以通过将 RABBITMQ_USE_LONGNAME 环境变量 设置为 true 来完成此操作。

对于 CLI 工具，必须设置 RABBITMQ_USE_LONGNAME 或指定 --longnames 选项

# this example assumes that host1.messaging.eng.coolcorporation.banana is a hostname
# that successfully resolves
rabbitmq-diagnostics -n [email protected] check_alarms --longnames

容器化环境中的注意事项​

当 RabbitMQ 在容器中运行时，运行 CLI 工具的两种常见方法是

  1. 在容器本身内执行此操作，使用docker exec 和类似的工具
  2. 转发相关的节点间通信端口 并从主机执行

使用这种方法可能会出现两个常见问题。

主机和容器之间共享密钥不匹配​

当在主机中运行 CLI 工具时，本地共享密钥 必须与容器中的共享密钥匹配。如果不匹配，CLI 工具将无法进行身份验证，也无法对目标节点执行任何操作。

共享密钥播种竞争条件​

危险

如果容器使用的共享密钥 未预先播种，则必须允许节点启动，然后才能对它运行 CLI 命令

当 CLI 工具在未预先播种共享密钥 的主机上运行，并且在本地启动的 RabbitMQ 节点有机会创建 cookie 文件之前，它会创建一个混乱的情况，其中播种的密钥可能会在节点启动期间被覆盖。

结果，CLI 工具可能无法进行身份验证，RabbitMQ 节点可能无法访问已创建的文件，从而停止并出现错误，以及其他源于密钥不匹配的事实导致的问题场景。

选项和位置参数​

RabbitMQ CLI 工具在很大程度上遵循现有的、长期建立的命令行参数解析约定。本节提供了一些示例，并重点介绍了边缘情况和鲜为人知的功能。

不同的命令采用不同的参数。有些是命名选项，例如 --node（缩写为 -n），有些是位置参数，例如

rabbitmqctl add_user <username> <password>

一个具体的例子

rabbitmqctl add_user "a-user" "a-pa$$w0rd"

除了一个例外，选项可以在位置参数之前或之后提供：双连字符 (--) 之后的所有内容都将被视为位置参数

# all values after the double hyphen (--) will be treated as positional arguments,
# even if they begin with a hyphen or a double hyphen
rabbitmqctl add_user --node [email protected] -- "a-user" "a-pa$$w0rd"

当位置参数以连字符或双连字符开头（例如生成的密码）时，必须使用显式位置参数分隔符，以确保它们不被解析为选项

# Since "--!a-pa$$w0rd" is explicitly provided as a positional argument, it won't
# be mistakenly considered for an unsupported option, even though it starts with a double hyphen
rabbitmqctl add_user --node [email protected] -- "a-user" "--!a-pa$$w0rd"

选项值可以作为 --option <value> 或 --option=<value> 传递。当值以连字符 (-) 开头时，必须使用后一种变体，否则它将被视为选项

# an alternative way of providing an option value
rabbitmqctl add_user --node=[email protected] -- "a-user" "a-pa$$w0rd"

rabbitmqctl、rabbitmq-diagnostics、rabbitmq-plugins 和 rabbitmq-queues 支持命令别名。

RabbitMQ 节点和 CLI 工具（除了 rabbitmqadmin）使用 cookie 来确定是否允许它们相互通信。要使 CLI 工具和节点能够通信，它们必须具有相同的共享密钥，称为 Erlang cookie。cookie 只是一个最多 255 个字符的字母数字字符字符串。它通常存储在本地文件中。该文件必须只能由所有者访问（例如，具有 600 或类似的 UNIX 权限）。每个集群节点必须具有相同的 cookie。

如果文件不存在，则 Erlang VM 会在 RabbitMQ 服务器启动时使用随机生成的值自动创建一个。

Erlang cookie 生成应在集群部署阶段完成，理想情况下应使用自动化和编排工具。

Linux、MacOS、*BSD​

在 UNIX 系统上，cookie 通常位于 /var/lib/rabbitmq/.erlang.cookie（服务器使用）和 $HOME/.erlang.cookie（CLI 工具使用）。请注意，由于 $HOME 的值因用户而异，因此有必要为每个将使用 CLI 工具的用户放置一个 cookie 文件的副本。这适用于非特权用户和 root。

RabbitMQ 节点将在启动初期记录其有效用户的 home 目录位置。

社区 Docker 镜像和 Kubernetes​

Docker 社区 RabbitMQ 镜像 使用 RABBITMQ_ERLANG_COOKIE 环境变量值填充 cookie 文件。

使用此镜像的配置管理和容器编排工具必须确保集群中的每个 RabbitMQ 节点容器都使用相同的值。

在 Kubernetes 上下文中，必须在部署文件中指定该值。例如，这可以在RabbitMQ Kubernetes 示例存储库中看到。

Windows​

在 Windows 上，cookie 位置取决于一些因素

  • HOMEDRIVE 和 HOMEPATH 环境变量是否都已设置
  • Erlang 版本：20.2 之前（任何RabbitMQ 的维护版本系列都不再支持这些版本）或 20.2 及更高版本
Erlang 20.2 或更高版本​

对于从 20.2 开始的 Erlang 版本，cookie 文件位置为

  • %HOMEDRIVE%%HOMEPATH%\.erlang.cookie（对于用户 %USERNAME%，通常为 C:\Users\%USERNAME%\.erlang.cookie），如果 HOMEDRIVE 和 HOMEPATH 环境变量都已设置
  • %USERPROFILE%\.erlang.cookie（通常为 C:\Users\%USERNAME%\.erlang.cookie），如果 HOMEDRIVE 和 HOMEPATH 未都设置
  • 对于 RabbitMQ Windows 服务 - %USERPROFILE%\.erlang.cookie（通常为 C:\WINDOWS\system32\config\systemprofile）

如果使用 Windows 服务，则应将 cookie 从 C:\Windows\system32\config\systemprofile\.erlang.cookie 复制到运行 rabbitmqctl.bat 等命令的用户期望的位置。

使用 CLI 和运行时命令行参数覆盖​

或者，可以将选项“-setcookie <value>”添加到 RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS 环境变量值 以覆盖 RabbitMQ 节点使用的 cookie 值

RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-setcookie cookie-value"

CLI 工具可以使用命令行标志获取 cookie 值

rabbitmq-diagnostics status --erlang-cookie "cookie-value"

两者都是最不安全的选项，通常不建议使用。

CLI 工具​

从版本 3.8.6 开始，rabbitmq-diagnostics 包含一个命令，该命令提供有关 CLI 工具使用的 Erlang cookie 文件的相关信息

rabbitmq-diagnostics erlang_cookie_sources

该命令将报告有效用户、用户 home 目录和 cookie 文件的预期位置

Cookie File

Effective user: antares
Effective home directory: /home/cli-user
Cookie file path: /home/cli-user/.erlang.cookie
Cookie file exists? true
Cookie file type: regular
Cookie file access: read
Cookie file size: 20

Cookie CLI Switch

--erlang-cookie value set? false
--erlang-cookie value length: 0

Env variable  (Deprecated)

RABBITMQ_ERLANG_COOKIE value set? false
RABBITMQ_ERLANG_COOKIE value length: 0

服务器节点​

节点启动时，它将记录其有效用户的 home 目录位置

node           : rabbit@cdbf4de5f22d
home dir       : /var/lib/rabbitmq

除非任何服务器目录 被覆盖，否则节点将在第一次启动时查找 cookie 文件，并在该目录中创建 cookie 文件（如果该文件尚不存在）。

在以上示例中，cookie 文件的位置将是/var/lib/rabbitmq/.erlang.cookie。

主机名解析​

从RabbitMQ 3.8.6开始，CLI 工具提供了两个命令来帮助验证节点上的主机名解析是否按预期工作。这些命令并非旨在替代dig和其他专门的 DNS 工具，而是提供了一种在考虑Erlang 运行时主机名解析器功能的情况下执行最基本检查的方法。

这些命令在网络指南中进行了介绍。

身份验证失败​

当 cookie 配置错误（例如，不完全相同）时，RabbitMQ 节点将记录诸如“来自不允许的节点的连接尝试”、“”、“无法自动集群”之类的错误。

例如，当 CLI 工具连接并尝试使用不匹配的密钥值进行身份验证时

2020-06-15 13:03:33 [error] <0.1187.0> ** Connection attempt from node 'rabbitmqcli-99391-rabbit@warp10' rejected. Invalid challenge reply. **

当诸如rabbitmqctl之类的 CLI 工具无法对 RabbitMQ 进行身份验证时，消息通常会显示

* epmd reports node 'rabbit' running on port 25672
* TCP connection succeeded but Erlang distribution failed
* suggestion: hostname mismatch?
* suggestion: is the cookie set correctly?
* suggestion: is the Erlang distribution using TLS?

这意味着从 CLI 工具到 RabbitMQ 节点的 TCP 连接成功，但服务器拒绝了身份验证尝试。该消息还提到了导致此问题的几个最常见原因，接下来将介绍这些原因。

cookie 文件放置错误或 cookie 值不匹配是此类故障最常见的场景。

RabbitMQ 节点在启动时记录其 cookie 哈希值。CLI 工具在无法对目标节点进行身份验证时打印其 cookie 哈希值。

当使用较新的 Erlang/OTP 版本时，身份验证失败将包含更多信息，并且可以更好地识别 cookie 不匹配的情况

rabbit@warp10:
  * connected to epmd (port 4369) on warp10
  * epmd reports node 'rabbit' running on port 25672
  * TCP connection succeeded but Erlang distribution failed

  * Authentication failed (rejected by the remote node), please check the Erlang cookie

current node details:
- node name: 'rabbitmq-cli-63@warp10'
- home dir: /home/username
- cookie hash: Sg08R8+G85EYHZ3H/9NUfg==

可能原因 2：节点名称类型不匹配​

如果 RabbitMQ 节点配置为使用长节点名称（RABBITMQ_USE_LONGNAME 导出为 true），则 CLI 工具也应通过相同的环境变量或 3.7.0 中引入的--longnames 命令行标志来使用长节点名称。

可能原因 3：节点间连接需要 TLS​

如果 RabbitMQ 设置为使用 TLS 加密节点间和 CLI 连接，则 CLI 工具也必须使用 TLS，因此需要其他选项。来自其他节点和 CLI 工具的非 TLS 连接将失败。

可能原因 4：主机名不匹配​

其他原因包括目标 RabbitMQ 节点使用的节点名称与提供给 CLI 工具的主机名不匹配（例如，通过-n标志）。例如，如果节点使用[email protected]作为其名称，但rabbitmqctl被调用为

rabbitmq-diagnostics status -n [email protected]

那么即使rmq-dev.eng.megacorp.local和rmq1.eng.megacorp.local解析到相同的 IP 地址，服务器也将拒绝rabbitmqctl的身份验证尝试。这种情况相对罕见。

当使用较新的 Erlang/OTP 版本时，身份验证失败将包含更多信息，并且可以更好地识别主机名不匹配的情况

rabbit@localhost:
  * connected to epmd (port 4369) on localhost
  * epmd reports node 'rabbit' running on port 25672
  * TCP connection succeeded but Erlang distribution failed

  * Hostname mismatch: node "rabbit@warp10" believes its host is different. Please ensure that hostnames resolve the same way locally and on "rabbit@warp10"


current node details:
- node name: 'rabbitmq-cli-30@warp10'
- home dir: /Users/antares
- cookie hash: Sg08R8+G85EYHZ3H/9NUfg==

其他可能原因​

与任何网络连接一样，CLI 到节点的连接也可能因以下原因而失败

  • 主机名解析失败
  • IP 路由错误
  • TCP 端口访问被阻止（防火墙等）

等等。

RabbitMQ 网络指南包含有关网络相关问题故障排除的部分。

管理节点​

获取节点状态​

要检索节点状态，请使用rabbitmq-diagnostics status或rabbitmq-diagnostics.bat status，并可选择使用--node目标

rabbitmq-diagnostics  status

rabbitmq-diagnostics  status --node [email protected]

启动节点​

RabbitMQ 节点的启动方式取决于使用的包类型

  • 在现代 Linux 发行版上使用 Debian 和 RPM 包时，节点是使用systemd管理的
  • 在使用 Windows 安装程序时，节点通常由Windows 服务管理器管理
  • 在使用 Homebrew 公式时，节点使用brew services管理
  • 在使用通用 UNIX 构建或二进制 Windows 构建时，节点分别使用安装根目录中的sbin/rabbitmq-server和sbin/rabbitmq-server.bat启动

停止节点​

要停止节点，请考虑使用启动节点时使用的相同服务管理工具，这取决于安装 RabbitMQ 时使用的包类型。

要使用 RabbitMQ CLI 工具停止节点，请使用rabbitmqctl shutdown或rabbitmqctl.bat shutdown，并可选择使用--node目标

rabbitmqctl shutdown
rabbitmqctl shutdown --node [email protected]

rabbitmqadmin​

rabbitmqadmin 是一个构建在RabbitMQ HTTP API之上的命令行工具。它不是rabbitmqctl的替代品，而是提供了对管理 UI提供的最常用操作子集的访问。

该工具需要 Python 2.7.9 或更高版本。

rabbitmqadmin使用 HTTP API 身份验证机制（基本 HTTP 身份验证）。它必须从运行的节点或GitHub单独下载。

“节点本地”和“集群范围”命令​

客户端连接、通道和队列将分布在集群节点之间。操作员需要能够检查和监控所有集群节点上的此类资源。

诸如rabbitmqctl和rabbitmq-diagnostics之类的 CLI 工具提供了检查资源和集群范围状态的命令。一些命令侧重于单个节点的状态（例如，rabbitmq-diagnostics environment和rabbitmq-diagnostics status），其他命令则检查集群范围的状态。后者的一些示例包括rabbitmqctl list_connections、rabbitmqctl list_mqtt_connections、rabbitmqctl list_stomp_connections、rabbitmqctl list_users、rabbitmqctl list_vhosts等等。

此类“集群范围”命令通常会首先联系一个节点，发现集群成员并联系所有成员以检索并组合其各自的状态。例如，rabbitmqctl list_connections将联系所有节点，检索其 AMQP 0-9-1 和 AMQP 1.0 连接，并将它们全部显示给用户。用户不必手动联系所有节点。

假设集群的状态没有变化（例如，没有连接关闭或打开），则对两个不同的节点依次执行的两个 CLI 命令将产生相同或语义上相同的结果。“节点本地”命令可能不会产生相同的结果，因为两个节点很少具有完全相同的状态。

插件提供的命令​

RabbitMQ 插件可以提供 CLI 命令，这些命令将被rabbitmq-diagnostics、rabbitmq-queues、rabbitmqctl等工具发现。为了使插件命令可发现，必须显式启用该插件。

执行命令发现时，CLI 工具将参考已启用插件文件以确定要扫描哪些插件以查找命令。如果插件未包含在该文件中，例如因为它作为依赖项被隐式启用，则它不会列在已启用插件文件中，因此其 CLI 命令将不会被发现，并且不可用。

使用help命令查看可用的命令，包括核心命令和插件提供的命令。

命令别名​

rabbitmqctl、rabbitmq-diagnostics和rabbitmq-plugins支持命令别名。别名提供了一种定义某些命令及其参数的缩写版本的方法。例如，与其键入rabbitmqctl environment，不如定义一个别名rabbitmqctl env，它将扩展为rabbitmqctl environment，这样更方便。

别名从通过RABBITMQ_CLI_ALIASES_FILE环境变量指定的加载文件。

export RABBITMQ_CLI_ALIASES_FILE=/path/to/cli_aliases.conf

别名文件使用非常简单的 ini 风格的alias = command格式，例如

env = environment
st  = status --quiet

lp  = list_parameters --quiet
lq  = list_queues --quiet
lu  = list_users --quiet

cs  = cipher_suites --openssl-format --quiet

使用此别名文件，就可以使用

rabbitmqctl env

它将扩展为

rabbitmqctl environment

或

rabbitmqctl lq

它将扩展为

rabbitmqctl list_queues --quiet

以上示例中的最后一个别名配置了一个rabbitmq-diagnostics命令

rabbitmq-diagnostics cs

它将扩展为

rabbitmq-diagnostics cipher_suites --openssl-format --quiet

所有工具都以相同的方式处理别名。只要识别扩展后的命令，就可以将别名与任何工具甚至多个工具一起使用。例如，rabbitmqctl和rabbitmq-diagnostics都提供environment命令，因此env别名对两者都以完全相同的方式起作用

rabbitmq-diagnostics env

它将扩展为

rabbitmq-diagnostics environment

仅当调用的命令未由工具提供时，才会参考该文件。

© 2024 RabbitMQ. All rights reserved.