插件 (Plugins)
概述
本指南涵盖
等等。
插件开发包含在单独的指南中。
基础知识
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 上）或分号（在带有 PowerShell 的 Windows 上）分隔
内置插件目录根据定义是与版本无关的：其内容会随版本发布而更改。因此，其确切路径（默认情况下）也包含版本号，例如 /usr/lib/rabbitmq/lib/rabbitmq_server-3.11.6/plugins。由于这个原因，将第三方插件自动安装到此目录更困难且更容易出错，因此不推荐这样做。
为解决此问题，插件目录可以是多个路径的列表，用冒号（在 Linux、MacOS、BSD 上）或分号（在带有 PowerShell 的 Windows 上）分隔
- 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 发行版发布的插件通常被称为第 1 层插件。前提是使用标准的发行版软件包，它们不需要安装，但在使用前需要启用。
除了与服务器捆绑的插件外，RabbitMQ 团队还提供由社区作者贡献的精选插件的二进制下载。有关详细信息，请参阅社区插件页面。
在 GitHub、GitLab、Bitbucket 和类似服务上可以找到更多插件。
开源 RabbitMQ 中的第 1 层（核心）插件
下表列出了随 RabbitMQ 一起发布的第 1 层（核心）插件。
| 插件名称 | 描述 |
|---|---|
| rabbitmq_auth_backend_ldap | 使用外部 LDAP 服务器的身份验证和授权插件。 |
| rabbitmq_auth_backend_oauth2 | 使用 OAuth 2.0 协议的身份验证和授权插件。 |
| rabbitmq_auth_backend_http | 使用外部 HTTP API 的身份验证和授权插件。 |
| rabbitmq_auth_mechanism_ssl | 使用 SASL EXTERNAL 的身份验证机制插件，用于通过 TLS (x509) 客户端证书进行身份验证。 |
| rabbitmq_consistent_hash_exchange | 一致性哈希交换机。 |
| rabbitmq_federation | 跨广域网（WAN）和管理域的可扩展消息传递。 |
| rabbitmq_federation_management | 在管理 API 和 UI 中显示联邦状态。仅在将 rabbitmq_federation 与 |
| rabbitmq_jms_topic_exchange | 一种用于 RabbitMQ JMS 客户端的特殊交换机类型。 |
| rabbitmq_management | 基于 HTTP 的管理/监控 API，以及基于浏览器的 UI。 |
| rabbitmq_management_agent | 当在集群中的部分节点上安装管理插件时，必须在所有集群节点上启用 |
| rabbitmq_mqtt | MQTT 5 和 3.1.1 支持。 |
| rabbitmq_prometheus | Prometheus 监控支持。 |
| rabbitmq_sharding | 提示 考虑使用 流和分区流 代替此插件。它们针对相同的用例集，但在与 RabbitMQ 流协议客户端库一起使用时效率要高得多。 一个为 RabbitMQ 提供分片队列的插件。分片由交换机执行，即消息将由我们定义为分片的交换机分布在“分片”队列中。 |
| rabbitmq_shovel | 一个为 RabbitMQ 提供的插件，用于将消息从一个代理上的队列“铲”（shovel）到另一个代理上的交换机。 |
| rabbitmq_shovel_management | 在管理 API 和 UI 中显示 Shovel 状态。仅在将 |
| rabbitmq_stomp | 在 RabbitMQ 中提供 STOMP 协议支持。 |
| rabbitmq_tracing | 向管理插件添加消息跟踪。以多种格式记录来自 firehose 的消息。 |
| rabbitmq_trust_store | 提供客户端 x509 证书信任存储。 |
| rabbitmq_web_stomp | STOMP-over-WebSockets：一个桥接器，通过 WebSockets 将 |
| rabbitmq_web_mqtt | MQTT-over-WebSockets：一个桥接器，通过 WebSockets 将 rabbitmq_mqtt 暴露给 Web 浏览器。 |
| rabbitmq_web_stomp_examples | 向 |
| rabbitmq_web_mqtt_examples | 向 |
VMware Tanzu RabbitMQ® 中的附加插件
下表列出了仅在 Tanzu RabbitMQ® 中提供的插件。有关详细信息，请参阅 Tanzu RabbitMQ 中的独有功能。
| 插件名称 | 描述 |
|---|---|
| inet_tcp_compress_dist | 集群内压缩，显著减少 RabbitMQ 节点之间的流量。 |
| rabbitmq_delayed_queue | 延迟/计划消息传递队列类型。消息被保留直到其计划投递时间，支持相对延迟和绝对时间戳。使用基于 Ra 的复制和 RocksDB 进行持久化。 |
| rabbitmq_distributed_shovel |
|
| rabbitmq_schema_definition_sync | 暖备用复制 (Warm Standby Replication) 的一部分。使用 AMQP 1.0 将架构定义从上游（主）集群持续复制到一个或多个下游（备用）集群。 |
| rabbitmq_warm_standby | 提供统一的 API，用于在跨数据中心部署中启用和管理 暖备用复制。 |
| rabbitmq_web_amqp | WebSocket 上的 AMQP 1.0，使基于浏览器的应用程序能够使用 AMQP 1.0 与 RabbitMQ 通信。 |
| rabbitmq_web_amqp_examples | 浏览器应用程序通过 WebSocket 与 RabbitMQ 进行 AMQP 1.0 通信的基本示例。 |
已停止维护
以下所有插件均已停止维护。它们不再随 RabbitMQ 发行版发布，也不再由 RabbitMQ 核心团队积极维护。
rabbitmq_auth_backend_amqprabbitmq_management_visualiser