跳到主要内容
版本: 4.1

插件

概述

本指南涵盖

以及更多。

插件开发在单独的指南中介绍。

基础知识

RabbitMQ 支持插件。插件以多种方式扩展核心 Broker 功能:支持更多协议、系统状态监控、额外的 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_managementrabbitmq_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)分隔

# 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"

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

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

插件目录可以通过在运行 RabbitMQ 节点的 host 上执行 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 core 的依赖
  • 插件版本与 RabbitMQ core 不兼容

找不到第三方插件

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

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

另一个常见原因是插件归档文件(.ez 文件)下载到的插件目录与服务器的目录不匹配。

插件目录可以通过在运行 RabbitMQ 节点的 host 上执行 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 发行版一起发布的插件通常称为 tier 1 插件。前提是使用了标准发行包,它们不需要安装,但确实需要在使用前启用。

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

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

开源 RabbitMQ 中的 Tier 1(核心)插件

下表列出了随 RabbitMQ 发布的 tier 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 中显示 Federation 状态。仅当将 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 支持。

rabbitmq_prometheus

Prometheus 监控支持。

rabbitmq_shovel

RabbitMQ 的一个插件,用于将消息从一个 Broker 上的队列铲到另一个 Broker 上的交换机。

rabbitmq_shovel_management

在管理 API 和 UI 中显示 Shovel 状态。仅当将 rabbitmq_shovelrabbitmq_management 结合使用时才有用。在异构集群中,应将其安装在与 RabbitMQ 管理插件 相同的节点上。

rabbitmq_stomp

在 RabbitMQ 中提供 STOMP 协议 支持。

rabbitmq_tracing

将消息跟踪添加到管理插件。以几种格式记录来自 firehose 的消息。

rabbitmq_trust_store

提供客户端 x509 证书信任存储。

rabbitmq_web_stomp

STOMP-over-WebSockets:一个桥接器,使用 WebSockets 将 rabbitmq_stomp 暴露给 Web 浏览器。

rabbitmq_web_mqtt

MQTT-over-WebSockets:一个桥接器,使用 WebSockets 将 rabbitmq_mqtt 暴露给 Web 浏览器。

rabbitmq_web_stomp_examples

rabbitmq_web_stomp 添加一些基本示例:一个简单的“echo”服务和一个基本的基于画布的协作工具。

rabbitmq_web_mqtt_examples

rabbitmq_web_mqtt 添加一些基本示例:一个简单的“echo”服务和一个基本的基于画布的协作工具。

VMware Tanzu RabbitMQ® 中的其他插件

下表列出了仅在 Tanuz RabbitMQ® 中可用的插件。

插件名称描述
rabbitmq_schema_definition_sync

Warm Standby Replication 的一部分。

rabbitmq_standby_replication

Warm Standby Replication 的一部分。

已弃用

以下所有插件均已弃用。它们不再随 RabbitMQ 发行版一起发布,也不再由 RabbitMQ 核心团队积极维护。

  • rabbitmq_auth_backend_amqp
  • rabbitmq_management_visualiser
© . All rights reserved.