管理插件
概述
RabbitMQ 管理插件提供了一个基于 HTTP 的 API,用于管理和监控 RabbitMQ 节点和集群,以及一个基于浏览器的 UI 和一个命令行工具 rabbitmqadmin。
它定期收集和聚合关于系统许多方面的数据。这些指标在 UI 中暴露给人工操作员。它提供的 API 可以被监控系统使用,但是,对于长期存储、警报、可视化、图表分析等,推荐选项是 Prometheus。
该插件还提供了用于分析节点内存使用情况的工具,以及其他与监控、指标、用户、权限和拓扑管理相关的功能。以前,它还提供了定义导出和导入功能。这些现在是 RabbitMQ 的核心功能,不需要或依赖此插件。
本指南涵盖以下内容
- 基本用法 管理 UI
- 管理插件提供的 HTTP API
- 通用插件配置
- HTTP API 前面的 反向代理(Nginx 或 Apache)
- 如何为管理 UI 及其底层 API 启用 HTTPS
- 此插件如何在 多节点集群中运行
- 如何禁用指标收集以专门使用 Prometheus 进行监控
- 如何创建 仅用于监控目的的具有有限权限的用户
- 使用 OAuth 2 进行身份验证
- 严格传输安全,内容安全策略,跨域资源共享,以及 其他安全相关的标头 控制
- 统计信息收集间隔
- 消息速率模式(速率保真度)和 数据保留间隔
- HTTP API 请求日志记录
- 如何设置 管理 UI 登录会话超时
- 如何重置此插件使用的统计信息数据库
该插件还提供了扩展点,其他插件(例如 rabbitmq-top 或 rabbitmq-shovel-management)使用这些扩展点来扩展 UI。
管理 UI 和外部监控系统
在可能的情况下,首选外部监控选项。基础设施和内核级监控对于任何生产系统来说也至关重要。
管理 UI 及其 HTTP API 是 RabbitMQ 的内置 监控选项。对于开发和难以或不可能引入外部监控的环境,这是一个方便的选项。
但是,管理 UI 有许多限制
- 监控系统与被监控系统交织在一起
- 一定的开销
- 它只存储最近的数据(考虑小时,而不是天或月)
- 它有一个基本的用户界面
- 它的设计 强调易用性而不是最佳可用性。
- 管理 UI 访问通过 RabbitMQ 权限标签系统(或 JWT 令牌范围的约定)控制
长期指标存储和可视化服务,例如 Prometheus 和 Grafana 或 ELK stack,更适合生产系统。它们提供
- 监控系统与被监控系统的解耦
- 更低的开销
- 长期指标存储
- 访问其他相关的指标,例如 Erlang 运行时 指标
- 更强大且可自定义的用户界面
- 指标数据共享的便利性:指标状态和仪表板
- 指标访问权限不是 RabbitMQ 特有的
- 节点特定指标的收集和聚合,这更能抵抗单个节点故障
从 3.8 开始,RabbitMQ 为 Prometheus 和 Grafana 提供了首要支持。建议在生产环境中使用。
入门指南
管理插件包含在 RabbitMQ 发行版中。像任何其他 插件一样,它必须先启用才能使用。这可以使用 rabbitmq-plugins 完成
rabbitmq-plugins enable rabbitmq_management
插件激活后不需要重启节点。
在自动化部署期间,可以通过 已启用插件文件启用插件。
用法
管理 UI 访问
可以使用 Web 浏览器通过 http://节点主机名:15672/
访问管理 UI。
例如,对于在主机名为 warp10.local
的机器上运行的节点,具有足够权限的用户可以通过 http://warp10.local:15672/
或 http://localhost: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 | 用户可以通过消息传递协议执行的任何操作,外加
|
policymaker | “management”可以执行的所有操作,外加
|
monitoring | “management”可以执行的所有操作,外加
|
administrator | “policymaker”和“monitoring”可以执行的所有操作,外加
|
请注意,由于“administrator”执行“monitoring”执行的所有操作,而“monitoring”执行“management”执行的所有操作,因此每个用户通常最多只需要一个标签。
正常的 RabbitMQ 资源权限仍然适用于监视器和管理员;仅仅因为用户是监视器或管理员,并不意味着他们可以通过管理插件或其他方式完全访问交换机、队列和绑定。
所有用户只能列出他们对其具有任何权限的虚拟主机中的对象。
仅监控(只读)访问
一些用户专门为可观察性目的而创建。更具体地说,此类用户需要列出所有对象并检查其指标,但没有权限来添加或删除实体(队列、流、交换机、绑定等等)。此类用户也不需要发布或消费消息。
这可以通过以下方式完成
- 创建一个标记为
monitoring
的用户 - 授予其权限(
configure
,read
,write
),这些权限为空(将不匹配任何对象)
这两个步骤都可以使用管理 UI 或 HTTP API 完成,或者,如果这些选项不可用或不是最佳选择,则可以使用 CLI 工具
rabbitmqctl add_user
可用于创建用户rabbitmqctl set_permissions
用于授予用户所需的权限,最后,rabbitmqctl set_user_tags
用monitoring
标记它,这将授予他们管理 UI 访问权限
命令行示例:创建仅具有监控访问权限的用户
以下示例创建一个用户,该用户对管理 UI/HTTP API 具有完全访问权限(即,所有虚拟主机和管理功能)
- bash
- PowerShell
- cmd
# 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' '^$' '^$' '^$'
# See the Access Control guide to learn about user management.
#
# password is provided as a command line argument
rabbitmqctl.bat add_user 'monitoring' '9a55f70a841f18b97c3a7db939b7adc9e34a0f1d'
# passwords with special characters must be quoted correctly
rabbitmqctl.bat add_user 'monitoring' '"w63pnZ&LnYMO(t"'
# grant the user empty permissions
rabbitmqctl.bat set_permissions --vhost 'vhost-name' 'monitoring' '^$' '^$' '^$'
rem See the Access Control guide to learn about user management.
rem password is provided as a command line argument
rabbitmqctl.bat add_user "monitoring" "9a55f70a841f18b97c3a7db939b7adc9e34a0f1d"
rem passwords with special characters must be quoted correctly
rabbitmqctl.bat add_user "monitoring" "w63pnZ&LnYMO(t"
rem 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 集群颁发的访问令牌。子章节 身份提供商发起的登录 介绍了这种类型的身份验证。
要在管理 UI 中配置 OAuth 2.0,您需要一个最低配置。但是,您可能需要额外的配置,具体取决于您的用例
- 客户端密钥
- 允许管理 HTTP API 的基本身份验证和 OAuth 2 身份验证
- 允许管理 UI 的基本身份验证和 OAuth 2 身份验证
- 注销管理 UI
- 为授权和令牌端点配置额外参数
- 特别注意 CSP 标头
connect-src
- 身份提供商发起的登录
- 支持多个 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
是一个必填字段。它是与此 RabbitMQ 集群在 OAuth 提供商中关联的 OAuth 客户端 ID,用于代表用户请求令牌。oauth_scopes
是一个必填字段,必须始终设置,除非 OAuth 提供商自动授予与oauth_client_id
关联的作用域。oauth_scopes
是一个以空格分隔的字符串列表,指示应用程序正在请求哪些权限。大多数 OAuth 提供商仅颁发在用户身份验证期间请求的作用域的令牌。RabbitMQ 在用户身份验证期间将此字段与其oauth_client_id
一起发送。如果未设置此字段,RabbitMQ 默认为openid profile
。
给定上述配置,当用户访问管理 UI 时,会发生以下两个事件
-
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 将继续支持它们。提示如果您过去使用
auth_oauth2.metadata_url
是因为您的提供商使用了略有不同的 OpenId Discovery 端点 url,那么从 RabbitMQ 4.1 开始,您应该改为配置正确的路径和/或包含任何其他参数。请阅读 文档的这一部分,其中解释了如何执行此操作。auth_oauth2.metadata_url
在未来的版本中可能会被弃用。 -
RabbitMQ 显示一个带有标签 “点击此处登录” 的按钮。当用户点击该按钮时,管理 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> http://localhost:15672/api/vhosts
以及
curl -i --header "authorization: Basic <encoded credentials>" http://localhost:15672/api/vhosts
要切换到仅使用 OAuth 2 对管理 HTTP 访问进行身份验证,请将 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>" http://localhost:15672/api/vhosts
除了 GET /definitions
和 POST /definitions
端点之外,所有端点都是如此。这些端点需要令牌在 token
查询字符串参数中传递。
允许管理 UI 的基本身份验证和 OAuth 2 身份验证
当使用 management.oauth_enabled = true
时,仍然可以在管理 UI 中使用 HTTP 基本身份验证。
默认情况下,management.oauth_disable_basic_auth
的值为 true
,这意味着当启用 OAuth 2 时,管理 UI 仅接受 OAuth 2 身份验证。管理 UI 显示一个带有标签 点击此处登录 的按钮,如下面的屏幕截图所示:
要支持 OAuth 2.0 和基本身份验证,请将 management.oauth_disable_basic_auth
配置键设置为 false
...
management.oauth_disable_basic_auth = false
...
现在,管理 UI 除了用于 OAuth 2 身份验证的 点击此处登录 按钮外,还显示用于基本身份验证的用户名/密码登录表单
注销管理 UI
RabbitMQ 实现了 OpenID Connect RP-Initiated Logout 1.0 规范,用于注销管理 UI 和 OAuth 提供商中的用户。它的工作方式如下
- 用户单击 注销。
- 如果 OpenId Connect Discovery 端点 返回
end_session_endpoint
,则管理 UI 向该端点发送注销请求,以关闭 OAuth 提供商中用户的会话。当请求完成时,用户也会从管理 UI 中注销。 - 如果没有返回
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 端点 列入白名单。
例如,如果您使用值 default-src 'self'
配置了 CSP 标头,则默认情况下,您正在设置 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
,并且期望 JWT 令牌在 access_token
表单字段中。这是 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。
支持多个 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 除了带有标签 点击此处登录 的按钮外,还会显示一个下拉列表。下拉列表每个资源有一个选项。选项的标签默认为资源的 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
登录类型所需的最低设置。以下示例公开了资源 rabbit_prod
,其中包含其 oauth_client_id
和 label
。如果您未指定 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 布局,其中基本身份验证在管理 UI 中被禁用 (management.oauth_disable_basic_auth = true
)。
具有基本身份验证的管理 UI 截图
这是激活基本身份验证的管理 UI (management.oauth_disable_basic_auth = false
)。
故障排除
OAuth 2 启用集群中管理 UI 访问的故障排除 是一个专门介绍常见 OAuth 2 特定问题的配套指南。
HTTP API
API 端点
请参阅 HTTP API 参考。
HTTP API 和监控
API 旨在用于基本的可观察性任务。Prometheus 和 Grafana 建议用于长期指标存储、警报、异常检测等等。
任何激活了 rabbitmq-management
插件的集群节点都可以用于管理 UI 访问或 HTTP API 访问。它将连接到其他节点并收集它们的统计信息,然后聚合并向客户端返回响应。
在节点集群中使用 API 时,无需单独通过 HTTP API 联系每个节点。而是联系一个随机节点或位于集群前面的负载均衡器。
HTTP API 客户端和工具
rabbitmqadmin 是一个 Python 命令行工具,用于与 HTTP API 交互。它可以从任何启用了管理插件的 RabbitMQ 节点下载,地址为 http://node-hostname:15672/cli/
。
有关多种语言的 HTTP API 客户端,请参阅 开发者工具。
某些 API 端点返回大量信息。可以通过过滤 HTTP GET
请求返回的列来减少数据量。有关详细信息,请参阅 最新的 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
可以配置 API 端点将使用的接口,类似于 消息传递协议监听器,使用 management.tcp.ip
键
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)
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 选项
管理插件使用的嵌入式 Web 服务器 Cowboy 提供了许多选项,可用于自定义服务器的行为。大多数选项是在 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 分钟分辨率保留 1 天。它以 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
如果与外部监控系统一起使用,禁用指标收集是首选选项,因为这减少了统计信息收集和聚合在 Broker 中引起的开销。如果统计信息只是暂时禁用,或者在某些 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 的框架嵌入,从而缓解某些类型的跨框架脚本攻击
# prohibits iframe embedding of the UI
management.csp.policy = frame-ancestors 'none'
严格传输安全 (HSTS)
可以配置 HTTP API 响应使用的 严格传输安全标头 值
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
示例
RabbitMQ 的示例配置文件,该文件启用了请求日志记录,将统计信息间隔增加到 10 秒,并显式地将其余相关参数设置为其默认值,如下所示
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
或此插件提供的 HTTP API(包括 rabbitmqadmin
)导出和导入定义。
请参阅 定义指南。
集群中的指标收集和 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" http://localhost:15672/api nocanon
ProxyPass "/" http://localhost:15672/
ProxyPassReverse "/" http://localhost: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 的概览页面包含重置单个节点以及集群中所有节点的统计信息数据库的按钮。
通过 HTTP API 发布和消费
可以使用 HTTP API 发布和消费消息。不建议使用这种消息传递方式:首选 RabbitMQ 支持的二进制消息传递协议之一。以这种方式发布和消费将更加高效,并将提供对各种消息传递协议功能(如 确认)的访问。
在 长生命周期消息传递协议连接 不是一种选择的环境中,通过 HTTP API 发布可能很有用。