跳至主内容
版本：4.2

命令行工具

目录​

本指南涵盖了与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的每个节点上都可用。

Generic UNIX包用户必须确保将安装根目录下的sbin目录添加到PATH以便于交互式使用。非交互式用例可以在不修改PATH环境变量的情况下使用完整路径或相对路径。

rabbitmqadmin 是一个独立的工具，它通过GitHub releases分发。

如果需要从远程节点进行交互，请下载并解压通用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工具的本地OS用户设置相同的值。

身份验证​

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

使用CLI工具连接到远程服务器节点​

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

要联系远程节点，请使用rabbitmqctl、rabbitmq-diagnostics和其他核心CLI工具接受的--node（-n）选项。以下示例联系节点rabbit@remote-host.local以获取其状态

rabbitmq-diagnostics status -n rabbit@remote-host.local

一些命令，例如

rabbitmq-diagnostics status

可以针对任何节点使用。而另一些命令，例如

rabbitmqctl shutdown

或

rabbitmqctl wait

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

节点名称​

RabbitMQ节点由节点名称标识。节点名称包含两部分，一个前缀（通常是rabbit）和一个主机名。例如，rabbit@node1.messaging.svc.local是一个节点名，其前缀为rabbit，主机名为node1.messaging.svc.local。

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

CLI工具使用节点名称来标识和寻址服务器节点。大多数CLI命令都是针对称为目标节点的节点调用的。要指定目标节点，请使用--node（-n）选项。例如，在节点rabbit@warp10.local上运行运行状况检查

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 rabbit@host1.messaging.eng.coolcorporation.banana 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 rabbit@host1.messaging.eng.coolcorporation.banana -- "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 rabbit@host1.messaging.eng.coolcorporation.banana -- "a-user" "--!a-pa$$w0rd"

选项值可以传递为--option <value>或--option=<value>。后者变体必须在值以连字符（-）开头时使用，否则它将被视为一个选项

# an alternative way of providing an option value
rabbitmqctl add_user --node=rabbit@host1.messaging.eng.coolcorporation.banana -- "a-user" "a-pa$$w0rd"

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

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

如果文件不存在，Erlang VM将在RabbitMQ服务器启动时自动创建一个具有随机生成值的Cookie。

Erlang cookie的生成应在集群部署阶段完成，最好使用自动化和编排工具。

Linux、MacOS、*BSD​

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

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

社区Docker镜像和Kubernetes​

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

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

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

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

该命令将报告有效用户、用户主目录以及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

服务器节点​

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

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

除非服务器目录被覆盖，否则该目录就是节点在首次启动时查找cookie文件（如果不存在则创建）的目录。

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

主机名解析​

从RabbitMQ 3.8.6开始，CLI工具提供了两个命令，有助于验证节点上的主机名解析是否按预期工作。这些命令不是为了取代dig和其他专用DNS工具，而是提供了一种在考虑Erlang运行时主机名解析器功能的情况下进行大多数基本检查的方法。

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

身份验证失败​

当cookie配置不正确时（例如，不一致），RabbitMQ节点将记录诸如“Connection attempt from disallowed node”、“Could not auto-cluster”之类的错误。

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

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

当CLI工具（如rabbitmqctl）无法与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标志）不匹配。例如，如果节点以rabbit@rmq1.eng.megacorp.local作为其名称运行，但rabbitmqctl被调用为

rabbitmq-diagnostics status -n rabbit@rmq-dev.eng.megacorp.local

那么即使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 rabbit@target-hostname.local

启动节点​

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 rabbit@target-hostname.local

rabbitmqadmin​

rabbitmqadmin是一个基于RabbitMQ HTTP API构建的命令行工具。它不是rabbitmqctl的替代品，并提供对管理UI提供的最常用操作的一个子集。

rabbitmqadmin使用HTTP API身份验证机制（基本HTTP身份验证）。

它是一个原生二进制文件，必须单独下载，而不是RabbitMQ发行版的一部分。

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

客户端连接、通道和队列将分布在集群节点之间。运营商需要能够检查和监控所有集群节点上的这些资源。

CLI工具，如rabbitmqctl和rabbitmq-diagnostics，提供了检查资源和集群范围状态的命令。一些命令侧重于单个节点的状态（例如，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

仅当调用的命令不是由工具提供的时，才会咨询该文件。

© . This site is unofficial and not affiliated with VMware.