跳至主内容
版本：4.3

管理插件

概述​

RabbitMQ 管理插件提供了基于 HTTP 的 API，用于管理和监控 RabbitMQ 节点和集群，同时还提供了一个基于浏览器的 UI 和一个命令行工具 rabbitmqadmin。

它会定期收集和汇总有关系统许多方面的数据。这些指标会在 UI 中呈现给操作人员。它提供的 API 可供监控系统使用；不过，对于长期存储、告警、可视化、图表分析等需求，推荐使用 Prometheus。

该插件还提供了用于分析节点内存使用情况的工具，以及与监控、指标、用户、权限和拓扑管理相关的其他功能。此前它还提供定义导出和导入功能。这些现在已成为 RabbitMQ 的核心功能，不再需要或依赖此插件。

本指南涵盖

该插件还提供了扩展点，其他插件（如 rabbitmq-top 或 rabbitmq-shovel-management）可利用这些扩展点来扩展 UI。

管理 UI 和外部监控系统​

重要

在可能的情况下，请优先选择外部监控选项。基础设施和内核级监控对于任何生产系统来说都至关重要。

管理 UI 及其 HTTP API 是 RabbitMQ 内置的监控选项。对于开发环境以及难以或无法引入外部监控的环境，这是一个方便的选择。

然而，管理 UI 存在一些局限性

  • 监控系统与被监控系统交织在一起
  • 存在一定的开销
  • 仅存储近期数据（以小时计，而非几天或几个月）
  • 拥有基础的用户界面
  • 其设计强调易用性胜过最佳可用性。
  • 管理 UI 的访问权限通过 RabbitMQ 权限标签系统（或 JWT 令牌作用域约定）进行控制

对于生产系统，长期指标存储和服务（如 Prometheus 和 Grafana 或 ELK 堆栈）是更合适的选择。它们提供

  • 监控系统与被监控系统的解耦
  • 较低的开销
  • 长期指标存储
  • 访问额外的相关指标，例如 Erlang 运行时指标
  • 更强大且可定制的用户界面
  • 轻松共享指标数据：包括指标状态和仪表板
  • 指标访问权限不限于 RabbitMQ
  • 节点特定指标的收集和聚合，对单个节点故障更具弹性

自 3.8 版本起，RabbitMQ 对 Prometheus 和 Grafana 提供了原生支持。建议在生产环境中使用。

入门​

管理插件包含在 RabbitMQ 发行版中。与其他任何插件一样，它必须先启用才能使用。这可以通过 rabbitmq-plugins 完成

rabbitmq-plugins enable rabbitmq_management

插件激活后无需重启节点。

在自动化部署期间，可以通过 enabled_plugins 文件启用该插件。

用法​

管理 UI 访问​

可以使用 Web 浏览器通过 http://node-hostname:15672/ 访问管理 UI。

例如，对于运行在主机名为 warp10.local 的机器上的节点，拥有足够权限的用户可以通过 http://warp10.local:15672/ 或 https://:15672/（前提是 localhost 解析正确）进行访问。

请注意，UI 和 HTTP API 端口（通常为 15672）不支持 AMQP 0-9-1、AMQP 1.0、STOMP 或 MQTT 连接。这些客户端应使用单独的端口。

用户必须被授予权限才能访问管理 UI。

主要功能​

管理 UI 实现为单页应用，依赖于 HTTP API。部分功能包括

  • 声明、列出和删除交换器、队列、绑定、用户、虚拟主机和用户权限。

  • 监控队列长度、消息速率（全局以及每个队列、交换器或通道）、队列资源使用情况、节点 GC 活动、客户端连接的数据速率等。

  • 监控节点资源使用情况：套接字和文件描述符、内存使用分解、可用磁盘空间以及节点间通信链路的带宽使用情况。

  • 管理用户（需要当前用户的管理权限）。

  • 管理策略和运行时参数（需要当前用户的足够权限）。

  • 导出架构（虚拟主机、用户、权限、队列、交换器、绑定、参数、策略）并在节点启动时导入。这可用于恢复目的或自动化配置新节点和集群。

  • 强制关闭客户端连接，清除队列。

  • 发送和接收消息（在开发环境和故障排查中非常有用）。

UI 应用支持最新版本的 Google Chrome、Safari、Firefox 和 Microsoft Edge 浏览器。

集群中的管理 UI 访问​

任何启用了 rabbitmq_management 插件的集群节点都可用于访问管理 UI 或供监控工具收集数据。它会连接到其他节点并收集它们的统计信息，然后进行汇总并返回给客户端。

要访问管理 UI，用户必须通过身份验证并拥有特定权限（获得授权）。这将在下一节中介绍。

访问与权限​

管理 UI 需要身份验证和授权，就像 RabbitMQ 要求连接的客户端进行验证一样。除了通过身份验证外，管理 UI 的访问还受用户标签控制。这些标签使用 rabbitmqctl 进行管理。默认情况下，新创建的用户没有任何标签。

有关用户和凭据管理的一般建议，请参阅部署指南。

标签能力
（无）无法访问管理插件
management

用户可以通过消息协议执行的任何操作，外加

  • 列出他们可以通过 AMQP 登录的虚拟主机

  • 查看“他们”虚拟主机中的所有队列、交换器和绑定

  • 查看并关闭他们自己的通道和连接

  • 查看涵盖其所有虚拟主机的“全局”统计信息，包括其中其他用户的活动

policymaker

“management”标签的所有功能，外加

  • 查看、创建和删除他们可以通过 AMQP 登录的虚拟主机的策略和参数

monitoring

“management”标签的所有功能，外加

  • 列出所有虚拟主机，包括他们无法通过消息协议访问的虚拟主机

  • 查看其他用户的连接和通道
  • 查看节点级数据，如内存使用和集群信息
  • 查看所有虚拟主机的真正全局统计信息
administrator

“policymaker”和“monitoring”标签的所有功能，外加

  • 创建和删除虚拟主机
  • 查看、创建和删除用户
  • 查看、创建和删除权限
  • 关闭其他用户的连接

请注意，由于“administrator”拥有“monitoring”的所有权限，而“monitoring”拥有“management”的所有权限，因此每个用户通常只需要一个标签即可。

常规的 RabbitMQ 资源权限仍然适用于监控人员和管理员；仅仅因为用户是监控人员或管理员，并不意味着他们可以通过管理插件或其他方式获得对交换器、队列和绑定的完全访问权限。

所有用户只能列出他们拥有任何权限的虚拟主机内的对象。

仅监控（只读）访问​

有些用户专门为可观测性目的而创建。更具体地说，这些用户需要列出所有对象并检查其指标，但不具备添加或删除实体（队列、流、交换器、绑定等）的权限。此类用户也不需要发布或消费消息。

这可以通过以下方式实现：

  1. 创建一个标记为 monitoring 的用户
  2. 授予该用户空的（即不匹配任何对象）权限（configure、read、write）

这两个步骤都可以使用管理 UI 或 HTTP API 完成；或者如果这些选项不可用或不是最优选，也可以使用 CLI 工具

命令行示例：创建仅具有监控访问权限的用户​

以下示例创建了一个对管理 UI/HTTP API 具有完全访问权限的用户（即所有虚拟主机和管理功能）

# See the Access Control guide to learn about user management.
#
# Password is provided as a command line argument.
# Note that certain characters such as !, &, $, #, and so on must be escaped to avoid
# special interpretation by the shell.
rabbitmqctl add_user 'monitoring' '2a55f70a841f18b97c3a7db939b7adc9e34a0f1b'

# tag user 'monitoring' with a tag of the same name
rabbitmqctl set_user_tags 'monitoring' 'monitoring'

# grant the user empty permissions
rabbitmqctl set_permissions --vhost 'vhost-name' 'monitoring' '^$' '^$' '^$'

使用 OAuth 2 进行身份验证​

您可以配置 RabbitMQ 使用 JWT 编码的 OAuth 2.0 访问令牌来验证客户端应用程序，但是，要在管理 UI 中使用 OAuth 2.0 身份验证，您必须单独进行配置。

在管理 UI 中启动 OAuth 2.0 身份验证有两种方式

  • 服务启动的登录。这是 OAuth 方法，也是管理 UI 中启动身份验证的默认方式。它使用 带有 PKCE 的 OAuth 2.0 授权码流程将用户重定向到配置的 OAuth 2.0 提供程序进行验证。验证成功后，用户会获得一个访问令牌，然后被重定向回管理 UI 并自动登录。管理 UI 已针对这些 OAuth 2.0 提供程序进行了测试：

  • 身份提供程序启动的登录。对于这种类型的登录，用户必须携带访问令牌来到 RabbitMQ。这种类型的身份验证在向已认证用户提供各种应用程序/服务访问权限的门户中很常见。其中一个服务可以是一个或多个 RabbitMQ 集群。当用户请求访问 RabbitMQ 集群时，门户会将用户重定向到 RabbitMQ 的管理 UI，并携带为该用户和 RabbitMQ 集群颁发的访问令牌。此类型的身份验证在子部分 Identity-Provider initiated logon 中介绍。

要在管理 UI 中配置 OAuth 2.0，您需要最低配置。但是，根据您的用例，您可能需要额外的配置

最低配置​

第一部分是在管理 UI 中使用 OAuth 2.0 身份验证所需的最低配置。以下各节解释了如何根据用例进一步配置 OAuth 2.0。

鉴于 OAuth 2.0 插件的以下配置

auth_oauth2.resource_server_id = new_resource_server_id
auth_oauth2.issuer = https://my-oauth2-provider.com/realm/rabbitmq

要使用 OAuth 2.0 身份验证，请在管理 UI 中应用以下配置

management.oauth_enabled = true
management.oauth_client_id = rabbit_user_client
management.oauth_scopes = <SPACE-SEPARATED LIST OF SCOPES. See below>

  • oauth_enabled 是必填字段

  • oauth_client_id 是必填字段。它是 OAuth 提供程序中与此 RabbitMQ 集群关联的 OAuth 客户端 ID，用于代表用户请求令牌。

  • oauth_scopes 是必填字段，除了 OAuth 提供程序自动授予与 oauth_client_id 关联的作用域的情况外，始终必须设置。oauth_scopes 是一个空格分隔的字符串列表，用于指示应用程序请求哪些权限。大多数 OAuth 提供程序仅颁发包含用户身份验证期间所请求作用域的令牌。RabbitMQ 在用户身份验证期间随其 oauth_client_id 一起发送此字段。如果未设置此字段，RabbitMQ 默认为 openid profile。

在上述配置下，当用户访问管理 UI 时，会发生以下两个事件

  1. RabbitMQ 使用 auth_oauth2.issuer 中找到的 URL 下载 OpenID 提供程序配置。在 OAuth 2.0 指南中了解更多信息

    警告

    如果 RabbitMQ 无法下载 OpenID 提供程序配置，它会显示一条错误消息，并且 OAuth 2.0 身份验证选项将在管理 UI 中被禁用

    警告

    management.oauth_metadata_url 和 management.oauth_resource_servers.$id.oauth_metadata_url 已弃用。您应该按照此处的说明配置 OpenId Discovery 端点的路径。这两个设置在 RabbitMQ 4.2.0 中将不再存在。在此之前，RabbitMQ 将继续支持它们，直到您更新配置。

    提示

    如果您过去因为提供程序使用了略有不同的 OpenId Discovery 端点 URL 而配置了 auth_oauth2.metadata_url，那么从 RabbitMQ 4.1 开始，您应该配置正确的路径和/或包含任何额外参数。请阅读文档的这一部分，其中解释了如何执行此操作。auth_oauth2.metadata_url 可能在未来版本中弃用。

  2. RabbitMQ 会显示一个标签为“Click here to login”的按钮。当用户点击该按钮时，管理 UI 会启动 OAuth 2.0 授权码流程，将用户重定向到身份提供程序进行身份验证并获取令牌。

配置客户端密钥​

重要提示：从 OAuth 2.0 的角度来看，管理 UI 是一个公共应用，这意味着它无法安全地存储凭据（例如 client_secret）。这意味着 RabbitMQ 在对用户进行身份验证时不应提供 client_secret。

但是，可能存在某些 OAuth 提供程序在初始用户身份验证请求或令牌刷新请求时需要 client_secret。例如，UAA 服务器需要 client_secret 来刷新令牌。对于这些情况，可以按如下所示配置 oauth_client_secret

management.oauth_enabled = true
management.oauth_client_id = rabbit_user_client
management.oauth_client_secret = rabbit_user_client
management.oauth_scopes = openid profile rabbitmq.*

为管理 HTTP API 允许基础和 OAuth 2 身份验证​

当使用 management.oauth_enabled = true 时，仍然可以使用 HTTP 基础身份验证针对 HTTP API 进行验证。这意味着以下两个示例都将有效

# swap <token> for an actual token
curl -i -u ignored:<token> https://:15672/api/vhosts

以及

curl -i --header "authorization: Basic <encoded credentials>" https://:15672/api/vhosts

要切换为仅针对管理 HTTP 访问使用 OAuth 2 进行身份验证，请将 management.disable_basic_auth 配置键设置为 true

...
management.disable_basic_auth = true
...

当将 management.disable_basic_auth 设置为 true 时，只有 Bearer（基于令牌）授权方法有效，例如

# swap <token> for an actual token
curl -i --header "authorization: Bearer <token>" https://:15672/api/vhosts

这适用于除 GET /definitions 和 POST /definitions 之外的所有端点。这些端点要求令牌通过 token 查询字符串参数传递。

为管理 UI 允许基础和 OAuth 2 身份验证​

当使用 management.oauth_enabled = true 时，仍然可以使用 HTTP 基础身份验证登录管理 UI。

默认情况下，management.oauth_disable_basic_auth 的值为 true，这意味着当启用 OAuth 2 时，管理 UI 仅接受 OAuth 2 身份验证。管理 UI 显示一个带有标签 Click here to login 的按钮，如下面的屏幕截图所示： Single OAuth 2.0 resource, with oauth_disable_basic_auth = true

要同时支持 OAuth 2.0 和基础身份验证，请将 management.oauth_disable_basic_auth 配置键设置为 false

...
management.oauth_disable_basic_auth = false
...

现在，除了用于 OAuth 2 身份验证的 Click here to login 按钮外，管理 UI 还显示一个用于基础身份验证的用户名/密码登录表单

Single OAuth 2.0 resource, with oauth_disable_basic_auth = false

退出管理 UI​

RabbitMQ 实现了 OpenID Connect RP-Initiated Logout 1.0 规范，用于从管理 UI 和 OAuth 提供程序中注销用户。其工作方式如下

  1. 用户点击 Logout。
  2. 如果 OpenId Connect Discovery 端点返回 end_session_endpoint，管理 UI 会向该端点发送注销请求，以关闭用户在 OAuth 提供程序中的会话。请求完成后，用户也将从管理 UI 注销。
  3. 如果没有返回 end_session_endpoint，则用户仅从管理 UI 注销。
信息

如果 OpenId Connect Discovery 端点未返回 end_session_endpoint，您可以在 OAuth 2.0 身份验证后端插件中进行配置。

警告

RabbitMQ 3.13.1 及更早版本要求 OpenId Connect Discovery 端点返回 end_session_endpoint，OAuth 2.0 身份验证才能正常工作。

还有两种额外的情况可能会触发注销。一种情况是当 OAuth 令牌过期时。尽管 RabbitMQ 会在令牌过期前在后台更新它，但如果令牌确实过期了，用户会被注销。第二种情况是当管理 UI 会话超过了 登录会话超时中配置的最大允许时间时。

配置授权和令牌端点的额外参数​

有些 OAuth 2.0 提供程序需要在发送到授权端点和/或令牌端点的请求中包含额外参数。这些是自定义参数。管理 UI 已经发送了 OAuth 2.0 授权码流程所需的所有参数。

以下是为授权和令牌端点设置名为 audience 的额外参数的示例

management.oauth_authorization_endpoint_params.audience = some-audience-id
management.oauth_token_endpoint_params.audience = some-audience-id

您可以根据需要配置任意数量的参数。

特别注意 CSP 标头 connect-src​

为了支持 OAuth 2.0 协议，RabbitMQ 会向 OpenId Connect Discovery 端点发出异步 REST 调用。如果您覆盖了默认的 CSP 标头，则必须确保 connect-src CSP 指令将 OpenId Connect Discovery 端点加入白名单。

例如，如果您将 CSP 标头配置为 default-src 'self'，则默认情况下您设置了 connect-src 'self'，这意味着您拒绝 RabbitMQ 访问任何外部端点；从而禁用了 OAuth 2.0。

除了 connect-src CSP 标头外，RabbitMQ 还需要 CSP 指令 unsafe-eval 和 unsafe-inline，否则 OAuth 2.0 功能可能无法正常工作。

身份提供程序启动的登录​

默认情况下，管理 UI 使用 OAuth 2.0 授权码流程来验证和授权用户。然而，在某些场景下，用户更希望在不参与额外登录流程的情况下被自动重定向到 RabbitMQ。通过使用 OAuth 2.0 代理和 Web 门户，可以避免这些额外的登录流程。用户只需单击一次，即可携带在后台获取的令牌直接导航到管理 UI。这被称为 身份提供程序启动的登录。

RabbitMQ 公开了一个名为 management.oauth_initiated_logon_type 的设置，其默认值为 sp_initiated。要使用 身份提供程序启动的登录，请将其设置为 idp_initiated。

management.oauth_enabled = true
management.oauth_initiated_logon_type = idp_initiated
management.oauth_provider_url = https://my-web-portal

使用之前的设置，管理 UI 会公开 HTTP 端点 /login，该端点接受 content-type: application/x-www-form-urlencoded，并期望在 access_token 表单字段中包含 JWT 令牌。这是 Web 门户将用户重定向到管理 UI 的端点。此外，当用户进入管理 UI 时，RabbitMQ 也接受 HTTP Authorization 标头中的 JWT 令牌。

对于 sp_initiated 登录类型，如果设置了 auth_oauth2.issuer，则无需配置 oauth_provider_url。但是，对于 idp_initiated 流程，auth_oauth2.issuer URL 不一定是要将用户重定向到的验证 URL。当发生这种情况时，management.oauth_provider_url 会覆盖 auth_oauth2.issuer URL。

从身份提供程序启动的登录中注销​

如果配置了 end_session_endpoint，则在注销时用户会被重定向到该端点。否则，用户会被重定向到 management.oauth_provider_url。当身份提供程序必须在重定向到其根 URL 之前关闭用户会话并执行清理工作时，请使用 end_session_endpoint。

以下示例使用 keycloak 身份提供程序。end_session_endpoint 指向代理的 sign_out 端点

auth_oauth2.issuer = https://keycloak:8443/realms/test
auth_oauth2.end_session_endpoint = https://:8442/oauth2/sign_out?rd=https://keycloak:8443/realms/test/protocol/openid-connect/logout

支持多个 OAuth 2.0 资源​

先决条件​

要在管理 UI 中配置多个 OAuth 2.0 资源，您首先需要在 OAuth 2.0 插件中配置它们。假设您拥有以下包含四个 OAuth 2.0 资源的 OAuth 2.0 插件配置

auth_oauth2.issuer = http://some_idp_url
auth_oauth2.scope_prefix = rabbitmq.
auth_oauth2.resource_servers.1.id = rabbit_prod
auth_oauth2.resource_servers.2.id = rabbit_dev
auth_oauth2.resource_servers.3.id = rabbit_qa
auth_oauth2.resource_servers.4.id = rabbit_internal

接下来的各节将在管理 UI 中配置这些资源。

OAuth 2.0 资源如何向用户呈现​

当在管理 UI 中配置了多个 OAuth 2.0 资源时，RabbitMQ 除了显示标签为 Click here to logon 的按钮外，还会显示一个下拉菜单。下拉菜单中每个资源对应一个选项。选项的标签默认是资源的 ID，但您可以覆盖它。

信息

资源按照它们被配置的顺序进行列出。

您可以让某些资源配置为 sp_initiated 登录，而其他资源配置为 idp_initiated 登录。您可以禁用某个资源，使其不会在下拉菜单中作为选项出现。

可选：为所有资源设置通用设置​

如果大多数资源具有相同的配置值，您可以按如下方式进行设置

management.oauth_enabled = true
management.oauth_initiated_logon_type = sp_initiated
management.oauth_scopes = openid rabbitmq.tag:management rabbitmq.read:*/*

这里我们配置了所有资源（或绝大多数资源）需要 sp_initiated 登录类型，并且向授权服务器申请的作用域为 openid rabbitmq.tag:management rabbitmq.read:*/*。

信息

sp_initiated 是 management.oauth_initiated_logon_type 的默认值，因此您不需要配置它。

覆盖每个资源的默认 oauth_initiated_logon_type​

假设资源 rabbit_qa 需要 idp_initiated 登录，但为所有资源配置的登录类型是 sp_initiated。下面的配置覆盖了该资源的登录类型以及 OAuth 提供程序的 URL。

management.oauth_resource_servers.3.id = rabbit_qa
management.oauth_resource_servers.3.label = RabbitMQ QA
management.oauth_resource_servers.3.oauth_initiated_logon_type = idp_initiated
management.oauth_resource_servers.3.oauth_provider_url = http://qa_url

如有必要，设置 oauth_client_id 设置以及每个资源的标签​

接下来，为每个使用 sp_initiated 登录类型的资源配置 oauth_client_id。

这是 sp_initiated 登录类型所需的最低设置。以下示例公开了带有 oauth_client_id 和 label 的资源 rabbit_prod。如果您不指定 label，管理 UI 将改用 id。

management.oauth_resource_servers.1.id = rabbit_prod
management.oauth_resource_servers.1.oauth_client_id = rabbit_prod_mgt_ui
management.oauth_resource_servers.1.label = RabbitMQ Production

在此配置下，当用户选择选项 RabbitMQ Production 时，RabbitMQ 会启动 授权码流程，将用户带到 auth_oauth2.issuer 中配置的 URL，并带有以下设置

  • client_id : rabbit_prod_mgt_ui
  • resource : rabbit_prod
  • scopes : openid rabbitmq.tag:management rabbitmq.read:*/*

配置授权和令牌端点的额外参数​

有些 OAuth 2.0 提供程序需要在发送到授权端点和/或令牌端点的请求中包含额外参数。这些是自定义参数，按资源指定。管理 UI 已经发送了 OAuth 2.0 授权码流程所需的所有参数。

以下是为资源 some-resource-id 的两个端点设置名为 audience 的额外参数的示例

management.oauth_resource_servers.2.id = some-resource-id
management.oauth_resource_servers.2.oauth_authorization_endpoint_params.audience = some-resource-id
management.oauth_resource_servers.2.oauth_token_endpoint_params.audience = some-resource-id

可选：不在管理 UI 中公开某些资源​

您可能不想公开 OAuth 2.0 插件中配置的所有资源。例如，在以下示例中，您没有公开资源 rabbit_internal，该资源留给应用程序通过消息协议之一进行身份验证。

management.oauth_resource_servers.4.id = rabbit_internal
management.oauth_resource_servers.4.disabled = true

未开启基础身份验证的管理 UI 截图​

这是在管理 UI 中停用基础身份验证（management.oauth_disable_basic_auth = true）时的管理 UI 布局。

More than one OAuth 2.0 resource, with oauth_disable_basic_auth = true

开启基础身份验证的管理 UI 截图​

这是在开启基础身份验证（management.oauth_disable_basic_auth = false）时的管理 UI。

More than one OAuth 2.0 resource, with oauth_disable_basic_auth = false

预选或预定身份验证机制​

默认情况下，当用户导航到管理 UI 主页时，他们会看到所有可用的身份验证机制，并可以选择使用哪一种。然而，在某些场景下，用户可能会在预选或预定身份验证机制的情况下被路由到管理 UI。这允许外部系统引导用户进入特定的身份验证流程。

要预选或预定身份验证机制，必须将用户发送到带有适当请求参数的 /login 端点。然后，管理 UI 会根据其首选的身份验证机制将他们重定向回配置的主页。

以下请求参数控制其行为

预选模式 (preferred_auth_mechanism)​

使用 preferred_auth_mechanism 请求参数可以预选身份验证方法，同时仍显示所有选项。

  • OAuth 2.0 资源: /login?preferred_auth_mechanism=oauth2:rabbit_dev

    • 展开 OAuth 2.0 部分并折叠主页中的基础身份验证部分
    • 预选 OAuth 2.0 资源服务器，例如 rabbit_dev

  • 基础身份验证: /login?preferred_auth_mechanism=basic

    • 展开基础身份验证部分并折叠 OAuth 2.0 部分

严格模式 (strict_auth_mechanism)​

使用 strict_auth_mechanism 参数仅显示指定的身份验证方法。隐藏其他方法。

  • 仅 OAuth 2.0 资源: /login?strict_auth_mechanism=oauth2:rabbit_dev

    • 仅显示 rabbit_dev 资源服务器的 Click here to login 按钮
    • 不显示其他身份验证选项

  • 仅基础身份验证: /login?strict_auth_mechanism=basic

    • 仅显示基础身份验证表单
    • 不显示 OAuth 2.0 选项

故障排除​

在启用 OAuth 2 的集群中排查管理 UI 访问问题是一份配套指南，专门讨论常见的 OAuth 2 特定问题。

HTTP API​

API 端点​

请参阅 HTTP API 参考。

HTTP API 和监控​

该 API 旨在用于基础可观测性任务。对于长期指标存储、告警、异常检测等，建议使用 Prometheus 和 Grafana。

任何启用了 rabbitmq-management 插件的集群节点都可用于访问管理 UI 或 HTTP API。它会连接到其他节点并收集它们的统计信息，然后进行汇总并返回给客户端。

在节点集群中使用 API 时，无需分别联系每个节点。相反，只需联系任意节点或集群前端的负载均衡器即可。

HTTP API 客户端和工具​

rabbitmqadmin v2 是一款与 HTTP API 交互的命令行工具。

有关多种语言的 HTTP API 客户端，请参阅 开发者工具。

最大 HTTP 请求体限制​

少数 RabbitMQ HTTP API 端点可能会接收较大的负载，最显著的是用于 定义导入 的端点。

默认的 HTTP 请求体限制为 20 MiB。如果在集群中不使用如此大的定义文件，则可以减小此限制

# lowers the maximum HTTP request body size that will be accepted
# to 1 MiB
management.http.max_body_size = 1000000

当客户端发出的请求体超过限制时，将返回 400 Bad Request 响应。

在 HTTP API 前使用反向代理​

可能需要在 RabbitMQ 集群前端设置反向代理。如果使用默认虚拟主机 (/)，RabbitMQ 的反向代理设置可能需要小心处理路径中的编码斜杠。

如果不使用默认虚拟主机，则不需要支持编码 URI 的额外设置。换句话说，Nginx 和 Apache 的配置都只需要任何基于 HTTP 的服务的标准最低要求。

Nginx​

如果 RabbitMQ HTTP API 访问被配置为根位置 (/)，则该位置路径末尾不能有斜杠

# trailing slash in the location must be omitted only if default RabbitMQ virtual host is used
location / {
    proxy_pass http://rabbitmq-host:15672;
}

如果将使用不同的位置来代理 HTTP API 请求，则必须使用 URI 重写规则

# these rewrites are only if default RabbitMQ virtual host is used
location ~* /rabbitmq/api/(.*?)/(.*) {
    proxy_pass http://rabbitmq-host:15672/api/$1/%2F/$2?$query_string;
}

location ~* /rabbitmq/(.*) {
    rewrite ^/rabbitmq/(.*)$ /$1 break;
    proxy_pass http://rabbitmq-host:15672;
}

Apache​

为了支持 URI 中的编码斜杠，Apache 要求用户显式启用 AllowEncodedSlashes。

# required only if default RabbitMQ virtual host is used
AllowEncodedSlashes On

对于 Apache 虚拟主机，Apache 需要同时启用 mod_proxy 和 mod_proxy_http。该位置还需要 nocanon 设置

ProxyPassReverse / http://rabbitmq-host:15672/
# "nocanon" is required only if default RabbitMQ virtual host is used
ProxyPass / http://rabbitmq-host:15672/ nocanon

配置​

有几个配置选项会影响管理插件。这些通过 RabbitMQ 的主要 配置文件进行管理。

可以配置 HTTP API 和管理 UI 以使用不同的端口或网络接口、启用 HTTPS 等。

虽然很少需要，但可以配置多个监听器（端口），例如既启用 HTTPS 又保留对仅能使用 HTTP（无 TLS）的客户端的支持。

端口​

端口使用 management.tcp.port 键进行配置

management.tcp.port = 15672

类似于 消息协议监听器，可以使用 management.tcp.ip 键配置 API 端点使用的接口

management.tcp.ip = 0.0.0.0

要检查运行中的节点使用的接口和端口，请使用 rabbitmq-diagnostics

rabbitmq-diagnostics -s listeners
# => Interface: [::], port: 15672, protocol: http, purpose: HTTP API
# => Interface: [::], port: 15671, protocol: https, purpose: HTTP API over TLS (HTTPS)

或 诸如 lsof、ss 或 netstat 等工具。

HTTPS​

管理插件可以配置为使用 HTTPS。有关证书颁发机构、证书和私钥文件的更多信息，请参阅 TLS 指南。

management.ssl.port       = 15671
management.ssl.cacertfile = /path/to/ca_certificate.pem
management.ssl.certfile   = /path/to/server_certificate.pem
management.ssl.keyfile    = /path/to/server_key.pem
## This key must only be used if private key is password protected
# management.ssl.password   = bunnies

可以为 HTTPS 监听器配置更多 TLS 选项。

management.ssl.port       = 15671
management.ssl.cacertfile = /path/to/ca_certificate.pem
management.ssl.certfile   = /path/to/server_certificate.pem
management.ssl.keyfile    = /path/to/server_key.pem
## This key must only be used if private key is password protected
# management.ssl.password   = bunnies

management.ssl.honor_cipher_order   = true
management.ssl.honor_ecc_order      = true
management.ssl.client_renegotiation = false
management.ssl.secure_renegotiate   = true

management.ssl.versions.1 = tlsv1.2
management.ssl.versions.2 = tlsv1.1

management.ssl.ciphers.1 = ECDHE-ECDSA-AES256-GCM-SHA384
management.ssl.ciphers.2 = ECDHE-RSA-AES256-GCM-SHA384
management.ssl.ciphers.3 = ECDHE-ECDSA-AES256-SHA384
management.ssl.ciphers.4 = ECDHE-RSA-AES256-SHA384
management.ssl.ciphers.5 = ECDH-ECDSA-AES256-GCM-SHA384
management.ssl.ciphers.6 = ECDH-RSA-AES256-GCM-SHA384
management.ssl.ciphers.7 = ECDH-ECDSA-AES256-SHA384
management.ssl.ciphers.8 = ECDH-RSA-AES256-SHA384
management.ssl.ciphers.9 = DHE-RSA-AES256-GCM-SHA384

## Usually RabbitMQ nodes do not perform peer verification of HTTP API clients
## but it can be enabled if needed. Clients then will have to be configured with
## a certificate and private key pair.
##
## See ./ssl#peer-verification for details.
# management.ssl.verify = verify_peer
# management.ssl.fail_if_no_peer_cert = true

以下是经典配置格式中的相同示例。

警告

提供经典配置格式示例主要是为了完整性，强烈建议使用现代 rabbitmq.conf 格式来配置此插件。

%% The classic config format example is provided primarily for completeness sake,
%% using the modern `rabbitmq.conf` format for configuring this plugin is highly recommended.
[
  {rabbitmq_management,
   [
    {ssl_config, [{port,     15671},
                  {ssl,      true},
                  {cacertfile, "/path/to/ca_certificate.pem"},
                  {certfile,   "/path/to/server_certificate.pem"},
                  {keyfile,    "/path/to/server_key.pem"},

                  %% don't do peer verification to HTTPS clients
                  {verify,               verify_none},
                  {fail_if_no_peer_cert, false},

                  {client_renegotiation, false},
                  {secure_renegotiate,   true},
                  {honor_ecc_order,      true},
                  {honor_cipher_order,   true},

                  {versions,['tlsv1.2']},
                  {ciphers, ["ECDHE-ECDSA-AES256-GCM-SHA384",
                             "ECDHE-RSA-AES256-GCM-SHA384",
                             "ECDHE-ECDSA-AES256-SHA384",
                             "ECDHE-RSA-AES256-SHA384",
                             "ECDH-ECDSA-AES256-GCM-SHA384",
                             "ECDH-RSA-AES256-GCM-SHA384",
                             "ECDH-ECDSA-AES256-SHA384",
                             "ECDH-RSA-AES256-SHA384",
                             "DHE-RSA-AES256-GCM-SHA384"
                            ]}
                ]}
   ]}
 ].

同时使用 HTTP 和 HTTPS​

可以在不同端口同时使用 HTTP 和 HTTPS

management.tcp.port       = 15672

management.ssl.port       = 15671
management.ssl.cacertfile = /path/to/ca_certificate.pem
management.ssl.certfile   = /path/to/server_certificate.pem
management.ssl.keyfile    = /path/to/server_key.pem

相同的配置键可用于配置单个监听器（仅 HTTP 或仅 HTTPS），并与 Web STOMP 和 Web MQTT 使用的配置键匹配。

高级 HTTP 选项​

Cowboy 是管理插件使用的嵌入式 Web 服务器，它提供了许多可用于自定义服务器行为的选项。大多数选项是在 RabbitMQ 3.7.9 中引入的。

响应压缩​

响应压缩默认开启。要显式启用它，请使用 management.tcp.compress

management.tcp.compress = true

客户端不活动超时​

某些 HTTP API 端点响应很快，而另一些端点可能需要向客户端返回或流式传输大量数据集（例如数千个连接），或者执行与输入时间成正比的操作（例如 导入大型定义文件）。在这些情况下，处理请求所需的时间可能会超过 Web 服务器以及 HTTP 客户端的某些超时限制。

可以使用 management.tcp.idle_timeout、management.tcp.inactivity_timeout、management.tcp.request_timeout 选项来调整 Cowboy 超时。

  • management.tcp.inactivity_timeout 控制 HTTP(S) 客户端的 TCP 连接不活动超时。当达到此值时，连接将被 HTTP 服务器关闭。
  • management.tcp.request_timeout 控制客户端必须发送 HTTP 请求的时间窗口。
  • management.tcp.idle_timeout 控制客户端在 HTTP 请求上下文中必须发送更多数据（如果有）的时间窗口。

如果 HTTP 客户端和管理 HTTP 服务器之间使用了负载均衡器或代理，则 inactivity_timeout 和 idle_timeout 的值应至少与负载均衡器使用的超时和不活动值一样大，通常建议更大。

以下是一些修改超时的示例配置片段

# Configures HTTP (non-encrypted) listener timeouts
management.tcp.idle_timeout       = 120000
management.tcp.inactivity_timeout = 120000
management.tcp.request_timeout    = 10000
# Configures HTTPS (TLS-enabled) listener timeouts
management.ssl.idle_timeout       = 120000
management.ssl.inactivity_timeout = 120000
management.ssl.request_timeout    = 10000

所有值均以毫秒为单位。它们的默认值各不相同

  • management.tcp.inactivity_timeout 的默认值为 300 秒
  • management.tcp.request_timeout 的默认值为 60 秒
  • management.tcp.idle_timeout 的默认值为 5 秒

建议如果需要更改不活动或空闲超时，management.tcp.inactivity_timeout 的值应等于或大于 management.tcp.idle_timeout。

management.tcp.request_timeout 通常不需要增加，因为客户端在建立 TCP 连接后会很快发送请求。

HTTP 请求日志记录​

默认情况下，RabbitMQ 节点不会记录任何 HTTP API 请求。

要启用 HTTP API 访问日志记录，请使用 management.http_log_dir 键来配置目录路径，以便节点可以在该目录中创建访问日志文件

management.http_log_dir = /path/to/a/writeable/directory

要使更改生效，请重启插件或节点。

统计信息间隔​

默认情况下，服务器将每 5 秒（5000 毫秒）触发一次统计事件。管理插件中显示的消息速率值是根据此期间计算的。

在拥有大量统计信息发射实体（如 连接、通道、队列）的环境中，增加此值将减少统计信息收集的 CPU 资源消耗。

为此，请将 collect_statistics_interval 配置键的值设置为所需的间隔（以毫秒为单位）并重启节点

# 15s
collect_statistics_interval = 15000

消息速率​

默认情况下，管理插件显示全局以及每个队列、通道、交换器和虚拟主机的消息速率。这些被称为 基础 消息速率。

它还可以显示通道到交换器、交换器到队列以及队列到通道的所有组合的消息速率。这些被称为 详细 消息速率。详细消息速率默认处于禁用状态，因为当存在大量通道、队列和交换器组合时，它们可能会占用大量内存。

或者，也可以完全禁用消息速率。这有助于降低插件的 CPU 资源消耗。

消息速率模式由 management.rates_mode 配置键控制

# supported values: basic, detailed, none
management.rates_mode = basic

支持的值为 basic（默认值）、detailed 和 none。

采样（数据点）保留​

管理插件将保留一些数据样本，例如消息速率和队列长度。根据数据保留的时间长短，UI 图表上的某些时间范围选项可能不完整或不可用。

有三种策略

  • global：为概览和虚拟主机页面保留数据的时长
  • basic：为单个连接、通道、交换器和队列保留数据的时长
  • detailed：为连接、通道、交换器和队列对之间的消息速率保留数据的时长（如“消息速率细分”下所示）

以下是配置示例

management.sample_retention_policies.global.minute  = 5
management.sample_retention_policies.global.hour    = 60
management.sample_retention_policies.global.day = 1200

management.sample_retention_policies.basic.minute = 5
management.sample_retention_policies.basic.hour   = 60

management.sample_retention_policies.detailed.10 = 5

上述示例中的配置以 5 秒的分辨率（每 5 秒采样一次）保留全局数据 1 分钟，然后以 1 分钟（60 秒）的分辨率保留 1 小时，最后以 20 分钟的分辨率保留一天。它以 5 秒的分辨率保留基础数据 1 分钟，以 1 分钟（60 秒）的分辨率保留 1 小时，并仅保留详细数据 10 秒。

这三种策略均为强制性的，且必须至少包含一个保留设置（周期）。

禁用统计信息和指标收集​

可以禁用 UI 和 HTTP API 中的统计信息，以便仅将它们用于操作。如果正在使用外部监控解决方案（如 Prometheus 和 Grafana），这是一个有用的功能。如果以以下任何方式禁用了统计信息，UI 中的所有图表和详细统计信息都将被隐藏。

为了彻底禁用内部指标收集，必须在 rabbitmq_management_agent 插件中设置 disable_metrics_collector 标志。Prometheus 插件即使在收集被禁用的情况下也能正常工作。

management_agent.disable_metrics_collector = true

如果正在与外部监控系统一起使用，建议禁用指标收集，因为这减少了代理中统计信息收集和聚合导致的开销。如果统计信息只是暂时禁用，或者在某些 HTTP API 查询中不需要它们，则可以在 rabbitmq_management 插件中禁用统计信息聚合。禁用标志也可以作为 URI 中的查询字符串的一部分传递。

目前 Prometheus 插件无法报告单个队列的总数，因此有一个配置选项允许在 queues 端点中列出 messages、messages_ready 和 messages_unacknowledged。

以下是禁用统计信息但在 queues 页面中返回单个队列总数的配置示例

management.disable_stats = true
management.enable_queue_totals = true

内容安全策略 (CSP)​

可以配置 HTTP API 响应使用的 CSP 标头值。默认值为 script-src 'self' 'unsafe-eval' 'unsafe-inline'; object-src 'self'

management.csp.policy = script-src 'self' 'unsafe-eval' 'unsafe-inline'; object-src 'self'

该值可以是任何有效的 CSP 标头字符串

management.csp.policy = default-src https://rabbitmq.eng.example.local

也允许使用通配符

management.csp.policy = default-src 'self' *.eng.example.local

CSP 策略 frame-ancestors 指令可用于防止管理 UI 被嵌入到 frame 中，从而减轻某些类型的跨框架脚本攻击

# prohibits iframe embedding of the UI
management.csp.policy = frame-ancestors 'none'

严格传输安全 (HSTS)​

可以配置 HTTP API 响应使用的 Strict Transport Security 标头值

management.hsts.policy = max-age=31536000; includeSubDomains

跨源资源共享 (CORS)​

默认情况下，管理 UI 应用将使用 跨源资源共享（也称为 CORS）机制拒绝访问非源自其自身的网站。可以将某些源列入白名单

management.cors.allow_origins.1 = https://origin1.org
management.cors.allow_origins.2 = https://origin2.org

可以使用通配符允许任何源使用 API。这对于可能向公众公开 UI 应用的部署是极不推荐的。

management.cors.allow_origins.1 = *

CORS 预检请求由浏览器缓存。管理插件默认定义了 30 分钟的超时。该值可以更改。它以秒为单位进行配置

management.cors.allow_origins.1 = https://origin1.org
management.cors.allow_origins.2 = https://origin2.org
management.cors.max_age         = 3600

其他与安全相关的标头​

可以为管理 UI 和 HTTP API 响应设置更多与安全相关的标头。请注意，其中一些已被 CORS 和浏览器安全领域的其他新发展所取代。

支持的标头包括

management.headers.content_type_options = nosniff
management.headers.xss_protection = 1; mode=block
management.headers.frame_options = DENY

它们可以与上述 CORS、HSTS、CSP 标头结合使用

management.hsts.policy = max-age=31536000; includeSubDomains
management.csp.policy = default-src 'self'; script-src 'self' 'unsafe-eval'

management.headers.content_type_options = nosniff
management.headers.xss_protection = 1; mode=block
management.headers.frame_options = DENY

登录会话超时​

用户登录后，Web UI 登录会话默认会在 8 小时后过期。可以使用 login_session_timeout 设置来配置不同的超时时间。

该值应为整数：它控制登录会话的长度（以分钟为单位）。时间一到，用户将被注销。

以下示例将会话超时设置为 1 小时

management.login_session_timeout = 60

路径前缀​

某些环境需要为管理插件的所有 HTTP 请求使用自定义前缀。management.path_prefix 设置允许为管理插件中的所有 HTTP 请求处理程序设置任意前缀。

将 management.path_prefix 设置为 /my-prefix 会指定所有 API 请求使用 URI host:port/my-prefix/api/[...]

管理 UI 登录页面将具有 URI host:port/my-prefix/ - 请注意，在这种情况下，必须包含尾随斜杠。

management.path_prefix = /my-prefix

示例​

一个开启请求日志记录、将统计信息间隔增加到 10 秒并显式设置一些其他相关参数为其默认值的 RabbitMQ 示例配置文件如下所示

listeners.tcp.default = 5672

collect_statistics_interval = 10000

## Note: this uses the core `load_definitions` key over
## now deprecated `management.load_definitions`
# load_definitions = /path/to/exported/definitions.json

management.tcp.port = 15672
management.tcp.ip   = 0.0.0.0

management.ssl.port       = 15671
management.ssl.ip         = 0.0.0.0
management.ssl.cacertfile = /path/to/ca_certificate.pem
management.ssl.certfile   = /path/to/server_certificate.pem
management.ssl.keyfile    = /path/to/server_key.pem

management.http_log_dir = /path/to/rabbit/logs/http

management.rates_mode = basic

# Configure how long aggregated data (such as message rates and queue
# lengths) is retained.
# Your can use 'minute', 'hour' and 'day' keys or integer key (in seconds)
management.sample_retention_policies.global.minute    = 5
management.sample_retention_policies.global.hour  = 60
management.sample_retention_policies.global.day = 1200

management.sample_retention_policies.basic.minute   = 5
management.sample_retention_policies.basic.hour = 60

management.sample_retention_policies.detailed.10 = 5

在启动时加载定义（架构）​

节点和集群存储的信息可以被视为架构、元数据或拓扑。用户、虚拟主机、队列、交换器、绑定、运行时参数都属于此范畴。

可以通过 rabbitmqctl、rabbitmqadmin 或此插件提供的 HTTP API 导出和导入定义。

请参阅 定义指南。

集群中的指标收集和 HTTP API​

客户端请求​

管理插件具有集群感知能力。它可以在集群中的一个或多个节点上启用，无论连接到哪个节点，都能查看有关整个集群的信息。

在部分节点上运行管理插件​

可以仅在集群节点的一个子集上部署管理插件。在这种情况下，只有运行该插件的节点才能处理客户端 HTTP API 请求。为了收集每个集群节点的指标，仍然需要在每个节点上启用 rabbitmq-management-agent 插件，否则该节点的指标将不可用。

集群中的聚合查询​

在集群中，HTTP API 在处理客户端请求时会执行集群范围的查询，这意味着它可能会受到网络分区、网络减速和无响应节点的影响。

节点间聚合查询的超时通过 net tick 机制控制。降低此值可能有助于减少最近变得无响应的节点带来的延迟。低于 10 秒的值可能会产生误报，必须避免。

与 HTTP API 相比，Prometheus 监控端点仅服务于节点本地数据，通常不受集群中其他节点故障或不可用的影响。

（反向 HTTP）代理设置​

可以通过任何符合 RFC 1738 的代理使 Web UI 可用。以下示例 Apache 配置说明了为使 Apache 符合要求而必需的最低指令。它假设管理 Web UI 位于默认端口 15672 上

AllowEncodedSlashes      NoDecode
ProxyPass         "/api" https://:15672/api nocanon
ProxyPass         "/"    https://:15672/
ProxyPassReverse  "/"    https://:15672/

重启统计信息数据库​

统计信息数据库完全存储在内存中。其所有内容都是瞬态的，应按此处理。

在现代版本中，每个节点都有自己的统计信息数据库，其中包含该节点上记录的统计信息的一部分。

可以使用 rabbitmqctl 或 HTTP API 端点重启给定节点上的统计数据库

DELETE /api/reset/:node
rabbitmqctl eval 'rabbit_mgmt_storage:reset().'

要重置所有节点上的整个统计信息数据库，请使用

DELETE /api/reset
rabbitmqctl eval 'rabbit_mgmt_storage:reset_all().'

内存使用分析和内存管理​

管理 UI 可用于检查节点的内存使用情况，包括显示按类别细分的统计。详细信息请参阅 内存使用分析指南。

管理数据库围绕定期触发的统计信息构建，受上述统计信息间隔的调节，或者在创建/声明某些组件（例如打开新连接或通道，或声明队列）或关闭/删除时触发。消息速率不会直接影响管理数据库的内存使用。

统计数据库消耗的总内存量取决于拓扑大小（例如队列数量）、并发连接和通道数量、事件触发间隔、有效的速率模式和保留策略。

触发统计信息的实体（连接、通道、队列、节点）会定期执行此操作。间隔可以使用 collect_statistics_interval 键进行配置

# sets the interval to 30 seconds
collect_statistics_interval = 30000

将间隔值增加到 30-60 秒将减少连接、通道和队列数量较多的系统的 CPU 占用和峰值内存消耗。缺点是：这些实体的指标将每 30-60 秒刷新一次。这在外部监控的生产系统中可能非常合理，但会使管理 UI 对操作人员来说不太方便。

通道和统计信息收集进程的内存使用可以通过设置 stats_event_max_backlog 参数来限制最大积压队列大小。如果积压队列已满，新的通道和队列统计信息将被丢弃，直到前一个统计信息被处理完毕。

统计间隔也可以在运行时更改。这样做对现有的连接、通道或队列不会产生任何影响，仅会影响新创建的统计信息发布实体。

rabbitmqctl eval 'application:set_env(rabbit, collect_statistics_interval, 60000).'

可以重启统计数据库（见上文），从而强制其释放所有内存。管理 UI 的概览（Overview）页面包含用于重置单个节点以及集群中所有节点的统计数据库的按钮。

通过 HTTP API 发布和消费消息​

可以使用 HTTP API 来发布和消费消息。但不建议采用这种消息传递方式：请优先使用 RabbitMQ 支持的二进制消息协议。通过二进制协议进行发布和消费的效率会显著更高，并且可以使用诸如确认机制（confirmations）等多种消息协议特性。

在无法使用长连接消息协议的环境中，通过 HTTP API 发布消息会非常有用。

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