版本：4.2

插件 (Plugins)

概述

本指南涵盖

RabbitMQ 中的插件支持
如何使用CLI 工具启用插件
插件目录
如何在部署时预配置节点上的插件
解决一些常见问题
插件支持级别

等等。

插件开发另见一篇指南。

基础知识

RabbitMQ 支持插件。插件以各种方式扩展核心代理功能：支持更多协议、系统状态监控、额外的 AMQP 0-9-1 交换类型、节点联合等。许多功能以插件的形式实现，这些插件包含在核心发行版中。

本指南涵盖了 RabbitMQ 发行版最新版本中的插件机制和插件。第三方插件可以单独安装。还有一套精选插件。

插件在节点启动时或运行时通过CLI 工具激活。要在启动时激活插件，必须启用它。要启用插件，请使用rabbitmq-plugins

rabbitmq-plugins enable <plugin-name>

例如，要启用 Kubernetes 对等发现插件

rabbitmq-plugins enable rabbitmq_peer_discovery_k8s

要禁用插件，请使用

rabbitmq-plugins disable <plugin-name>

例如，要禁用rabbitmq-TOP插件

rabbitmq-plugins disable rabbitmq_top

可以使用 rabbitmq-plugins list 获取本地可用插件（在节点的插件目录中）及其状态（启用或禁用）的列表。

rabbitmq-plugins list

列出可用的插件，不带图例标题（顶部标记说明）

rabbitmq-plugins list -s

以 JSON 格式列出可用的插件

rabbitmq-plugins list --formatter=json

启用插件的不同方式

rabbitmq-plugins 命令通过联系正在运行的节点来启用或禁用插件，告诉它按需启动或停止插件。可以使用 -n 选项联系任意节点来指定不同的节点。

在启用插件之前运行节点并非总是实用或对操作员友好。在这些情况下，rabbitmq-plugins 提供了一种替代方法。如果指定了 --offline 标志，该工具将不联系任何节点，而是直接修改包含已启用插件列表的文件（恰当地命名为 enabled_plugins）。此选项通常最适合节点预配自动化。

enabled_plugins 文件通常位于节点数据目录或 /etc 下，与配置文件一起。该文件包含一个以点结尾的插件名称列表。例如，当启用rabbitmq_management 和rabbitmq_shovel 插件时，文件内容将如下所示：

[rabbitmq_management,rabbitmq_management_agent,rabbitmq_shovel].

请注意，插件的依赖项未列出。具有正确依赖项元数据的插件将在插件激活时在那里指定其依赖项，并首先启用它们。与针对正在运行的节点的 rabbitmq-plugins disable 调用不同，对文件的更改需要重启节点。

该文件可以由部署工具生成。这是另一种对自动化友好的方法。当需要禁用插件时，应将其从列表中删除，并重启节点。

有关 rabbitmq-plugins 的更多信息，请查阅手册页。

插件目录

RabbitMQ 从本地文件系统加载插件。插件以存档（.ez 文件）形式分发，其中包含编译的代码模块和元数据。由于某些插件随 RabbitMQ 一起提供，每个节点至少有一个默认插件目录。路径因包类型而异，可以使用 RABBITMQ_PLUGINS_DIR 环境变量覆盖。有关各种平台上的默认值，请参阅文件和目录位置指南。

提示

插件目录可以是冒号分隔的路径列表（在 Linux、MacOS、BSD 上）或分号分隔的路径列表（Windows 上的 PowerShell）

内置插件目录根据定义是与版本无关的：其内容会随着发布版本的不同而变化。其确切路径（默认情况下）也包含版本号，例如 /usr/lib/rabbitmq/lib/rabbitmq_server-3.11.6/plugins。因此，将第三方插件自动安装到此目录会更难且更容易出错，因此不推荐。

为解决此问题，插件目录可以是冒号分隔的路径列表（在 Linux、MacOS、BSD 上）或分号分隔的路径列表（Windows 上的 PowerShell）

bash
PowerShell

# Example rabbitmq-env.conf file that features a colon-separated list of plugin directories
PLUGINS_DIR="/usr/lib/rabbitmq/plugins:/usr/lib/rabbitmq/lib/rabbitmq_server-3.11.6/plugins"

# Example rabbitmq-env-conf.bat file that features a colon-separated list of plugin directories
PLUGINS_DIR="C:\Example\RabbitMQ\plugins;C:\Example\RabbitMQ\rabbitmq_server-3.11.6\plugins"

不包含特定于版本的组件且在 RabbitMQ 包安装程序升级期间不被更新的插件目录路径最适合安装第三方插件。预配自动化工具可以依赖这些目录是稳定的，并且仅由它们管理。

第三方插件目录将因平台和安装方法而异。例如，/usr/lib/rabbitmq/plugins 是 RabbitMQ Debian 包使用的第三方插件目录路径。

可以通过在运行 RabbitMQ 节点的计算机上执行 rabbitmq-plugins directories 命令来查找插件目录。

rabbitmq-plugins directories -s
# => Plugin archives directory: /path/to/rabbitmq/plugins
# => Plugin expansion directory: /path/to/node/node-plugins-expand
# => Enabled plugins file: /path/to/enabled_plugins

上面示例中的第一个目录是第三方插件目录。第二个目录包含随 RabbitMQ 一起提供的插件，并且在升级期间随安装的 RabbitMQ 版本变化而变化。

rabbitmq-plugins

使用环境变量覆盖插件目录时，本地操作系统用户调用 CLI 工具时也必须设置相同的环境变量。

如果未这样做，rabbitmq-plugins 离线模式将无法找到正确的目录。

已启用插件文件

节点上当前已启用插件的列表存储在一个文件中。该文件通常称为已启用插件文件。根据包类型，它通常位于 etc 目录或节点的数据目录中。其路径可以使用 RABBITMQ_ENABLED_PLUGINS_FILE 环境变量覆盖。作为用户，您通常不必考虑该文件，因为它由节点和 rabbitmq-plugins（在 --offline 模式下使用时）管理。

部署自动化工具必须确保本地 RabbitMQ 节点可读写该文件。在需要预配置插件的环境中，可以在部署时生成该文件。列表中的插件名称与 rabbitmq-plugins list 列出的名称完全相同。

文件内容是一个 Erlang 术语文件，包含一个列表

[rabbitmq_management,rabbitmq_management_agent,rabbitmq_mqtt,rabbitmq_stomp].

请注意，尾随的点很重要，不能省略。

插件扩展（解压）

并非所有插件都可以从存档 .ez 文件加载。因此，RabbitMQ 会在启动时将插件存档解压到单独的目录中，然后将该目录添加到其代码路径。此目录称为扩展插件目录。它通常由 RabbitMQ 完全管理，但如果节点目录更改为非标准目录，则很可能需要覆盖该目录。可以使用 RABBITMQ_PLUGINS_EXPAND_DIR 环境变量完成。该目录必须可供 RabbitMQ 节点的有效操作系统用户读写。

故障排除

提示

绝大多数第三方插件激活问题都源于文件系统权限不足。

如果安装了第三方插件但找不到，最可能的原因是：

插件目录不正确
rabbitmq-plugins 和服务器使用不同的插件目录
rabbitmq-plugins 和服务器使用不同的启用插件文件
插件未声明对 RabbitMQ 核心的依赖
插件版本与 RabbitMQ 核心不兼容

找不到第三方插件

当启用插件但服务器无法找到它时，它将报告错误。由于任何插件名称都可以传递给 rabbitmq-plugins，请仔细检查名称。

# note the typo
rabbitmq-plugins enable rabbitmq_managemenr
# => Error:
# => {:plugins_not_found, [:rabbitmq_managemenr]}

另一个常见原因是下载插件存档（.ez 文件）的插件目录与服务器的插件目录不匹配。

可以通过在运行 RabbitMQ 节点的计算机上执行 rabbitmq-plugins directories 命令来查找插件目录。

rabbitmq-plugins directories -s
# => Plugin archives directory: /path/to/rabbitmq/plugins
# => Plugin expansion directory: /path/to/node/node-plugins-expand
# => Enabled plugins file: /path/to/enabled_plugins

上面示例中的第一个目录是第三方插件目录。第二个目录包含随 RabbitMQ 一起提供的插件，并且在升级期间随安装的 RabbitMQ 版本变化而变化。

可以使用 which 等工具来查找 rabbitmq-plugins，并确定它是否来自预期的安装。

which rabbitmq-plugins
# => /path/to/rabbitmq/installation/sbin/rabbitmq-plugins

插件无法启用

在某些环境（尤其是开发环境）中，rabbitmq-plugins 来自与正在运行的服务器节点不同的安装。当使用二进制分发包安装节点，但 CLI 工具来自本地包管理器（如 apt 或 Homebrew）时，就会出现这种情况。

在这种情况下，CLI 工具将拥有一个与服务器不同的已启用插件文件，并且操作将失败并出现错误。

rabbitmq-plugins enable rabbitmq_top
Enabling plugins on node rabbit@warp10:
# =>  rabbitmq_top
# =>  The following plugins have been configured:
# =>    rabbitmq_management
# =>    rabbitmq_management_agent
# =>    rabbitmq_shovel
# =>    rabbitmq_shovel_management
# =>    rabbitmq_top
# =>    rabbitmq_web_dispatch
# =>  Applying plugin configuration to rabbit@warp10...
# =>  Error:
# =>  {:enabled_plugins_mismatch, '/path/to/installation1/etc/rabbitmq/enabled_plugins', '/path/to/installation2/etc/rabbitmq/enabled_plugins'}

上面错误中的第一个路径对应于 rabbitmq-plugins 使用的已启用插件文件，第二个路径是目标 RabbitMQ 节点使用的。

可以使用 rabbitmqctl environment 来检查服务器使用的有效已启用插件文件路径。

rabbitmq-plugins directories -s
# => Plugin archives directory: /path/to/rabbitmq/plugins
# => Plugin expansion directory: /path/to/node/node-plugins-expand
# => Enabled plugins file: /path/to/enabled_plugins

导致插件无法启用的其他常见原因可能包括插件存档和/或插件扩展目录权限不足，无法满足服务器节点的有效用户。换句话说，节点无法使用这些目录来完成插件激活和加载。

插件的 CLI 命令未被发现

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

插件级别

随 RabbitMQ 发行版一起提供的插件通常被称为一级插件。如果使用标准的发行版包，则无需安装，但在使用前需要启用。

除了随服务器捆绑的插件外，RabbitMQ 团队还提供社区作者贡献的精选插件的二进制下载。有关更多详细信息，请参阅社区插件页面。

在 GitHub、GitLab、Bitbucket 和类似服务上还可以找到更多插件。

开源 RabbitMQ 中的一级（核心）插件

下表列出了随 RabbitMQ 一起提供的一级（核心）插件。

插件名称	描述
rabbitmq_auth_backend_ldap	使用外部 LDAP 服务器的认证和授权插件。 LDAP 插件文档
rabbitmq_auth_backend_oauth2	使用 OAuth 2.0 协议的认证和授权插件。 OAuth 2.0 插件文档
rabbitmq_auth_backend_http	使用外部 HTTP API 的认证和授权插件。此插件的 README
rabbitmq_auth_mechanism_ssl	使用 SASL EXTERNAL 通过 TLS（x509）客户端证书进行身份验证的身份验证机制插件。此插件的 README
rabbitmq_consistent_hash_exchange	一致性哈希交换。此插件的 README
rabbitmq_federation	跨 WAN 和管理域的可扩展消息传递。联合插件文档
rabbitmq_federation_management	在管理 API 和 UI 中显示联合状态。仅在使用 rabbitmq_federation 与 `rabbitmq_management` 结合使用时有用。在异构集群中，应将其安装在与 rabbitmq_management 相同的节点上。
rabbitmq_jms_topic_exchange	用于 RabbitMQ JMS 客户端的特殊交换类型。
rabbitmq_management	通过 HTTP 的管理/监控 API，以及基于浏览器的 UI。管理插件文档
rabbitmq_management_agent	在集群的部分节点上安装管理插件时，所有集群节点都必须启用 `rabbitmq_management_agent`，否则将不会收集某些节点的统计信息。
rabbitmq_mqtt	MQTT 5 和 3.1.1 支持。 MQTT 插件文档
rabbitmq_prometheus	Prometheus 监控支持。使用 Prometheus 插件进行监控的文档
rabbitmq_sharding	提示考虑使用流和分区流而不是此插件。它们针对的是同一套用例，但在与 RabbitMQ 流协议客户端库一起使用时效率更高。一个为 RabbitMQ 提供的插件，它提供分片队列。分片由交换机执行，也就是说，消息将由我们定义为分片的交换机分区到“分片”队列中。此插件的 README
rabbitmq_shovel	一个为 RabbitMQ 提供的插件，它将消息从一个代理上的队列“铲”到另一个代理上的交换机。 Shovel 插件文档
rabbitmq_shovel_management	在管理 API 和 UI 中显示Shovel 状态。仅在使用 `rabbitmq_shovel` 与 `rabbitmq_management` 结合使用时有用。在异构集群中，应将其安装在与RabbitMQ 管理插件相同的节点上。
rabbitmq_stomp	为 RabbitMQ 提供STOMP 协议支持。 STOMP 插件文档
rabbitmq_tracing	为管理插件添加消息跟踪。以几种格式记录来自firehose 的消息。
rabbitmq_trust_store	提供客户端 x509 证书信任库。此插件的 README
rabbitmq_web_stomp	STOMP-over-WebSockets：一个使用 WebSockets 将 `rabbitmq_stomp` 暴露给 Web 浏览器的桥梁。 web-stomp 插件文档
rabbitmq_web_mqtt	MQTT-over-WebSockets：一个使用 WebSockets 将rabbitmq_mqtt 暴露给 Web 浏览器的桥梁。 web-mqtt 插件文档
rabbitmq_web_stomp_examples	为 `rabbitmq_web_stomp` 添加了一些基本示例：一个简单的“回声”服务和一个基本的基于画布的协作工具。此插件的 README
rabbitmq_web_mqtt_examples	为 `rabbitmq_web_mqtt` 添加了一些基本示例：一个简单的“回声”服务和一个基本的基于画布的协作工具。此插件的 README

VMware Tanzu RabbitMQ® 中的附加插件

下表列出了仅在Tanuz RabbitMQ® 中提供的插件。

插件名称	描述
rabbitmq_schema_definition_sync	属于热备用复制。
rabbitmq_standby_replication	属于热备用复制。

已停用

以下所有插件均已**停用**。它们不再随 RabbitMQ 发行版提供，也不再由 RabbitMQ 核心团队积极维护。

rabbitmq_auth_backend_amqp
rabbitmq_management_visualiser

概述​

基础知识​

启用插件的不同方式​

插件目录​

rabbitmq-plugins​

已启用插件文件​

插件扩展（解压）​

故障排除​

找不到第三方插件​

插件无法启用​

插件的 CLI 命令未被发现​

插件级别​

开源 RabbitMQ 中的一级（核心）插件​

VMware Tanzu RabbitMQ® 中的附加插件​

已停用​

概述