插件
概述
本指南涵盖
以及更多。
插件开发 在单独的指南中介绍。
基础知识
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发行版一起提供的插件通常称为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 | 跨广域网和管理域的可扩展消息传递。 |
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_shovel | RabbitMQ的一个插件,用于将消息从一个代理上的队列发送到另一个代理上的交换机。 |
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®中的其他插件
下表列出了仅在Tanuz RabbitMQ®中可用的插件。
插件名称 | 描述 |
---|---|
rabbitmq_schema_definition_sync | 暖备复制的一部分。 |
rabbitmq_standby_replication | 暖备复制的一部分。 |
已停用
以下所有插件均已**停用**。它们不再随RabbitMQ发行版一起提供,也不再由RabbitMQ核心团队积极维护。
rabbitmq_auth_backend_amqp
rabbitmq_management_visualiser