红帽全球峰会配置 AMQ Broker
使开源包含更多
红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情，请参阅我们的首席技术官 Chris Wright 提供的消息。
第 1 章 概述
AMQ Broker 配置文件为代理实例定义重要设置。通过编辑代理的配置文件，您可以控制代理在环境中如何工作。
1.1. AMQ Broker 配置文件和位置
所有代理的配置文件都存储在 < broker_instance_dir> /etc 中。您可以通过编辑这些配置文件中的设置来配置代理。
每个代理实例使用以下配置文件：
broker.xml- 主配置文件。您可以使用此文件配置代理的大部分方面，如网络连接、安全设置、消息地址等。
bootstrap.xml-
AMQ Broker 用来启动代理实例的文件。您可以使用它来更改
broker.xml的位置，配置 web 服务器并设置一些安全设置。 logging.properties- 您可以使用此文件为代理实例设置日志记录属性。
artemis.profile- 您可以使用此文件来设置代理实例运行时使用的环境变量。
login.config,artemis-users.properties,artemis-roles.properties- 与安全相关的文件。您可以使用这些文件来设置对代理实例的用户访问身份验证。
1.2. 了解默认代理配置
您可以通过编辑 broker.xml 配置文件来配置大多数代理的功能。此文件包含默认设置，足以启动和操作代理。但是，您可能需要更改一些默认设置，并添加新设置来为您的环境配置代理。
默认情况下，broker.xml 包含以下功能的默认设置：
- 消息持久性
- acceptors
- 安全性
- 消息地址
默认消息持久性设置
默认情况下，AMQ Broker 持久性使用由磁盘上的一组文件组成的附加文件日志。日志会保存消息、事务和其他信息。
默认接受者设置
代理通过使用 acceptor 配置元素来侦听传入的客户端连接，以定义客户端可用于进行连接的端口和协议。默认情况下，AMQ Broker 包括每个支持的消息传递协议的接收器，如下所示。
默认安全设置
AMQ Broker 包含灵活的基于角色的安全模型，用于根据其地址将安全应用到队列。默认配置使用通配符将 amq 角色应用到所有地址（以数字符号 # 表示）。
默认消息地址设置
AMQ Broker 包含一个默认地址，它建立一组默认的配置设置，以应用到任何创建的队列或主题。
此外，默认配置定义了两个队列： DLQ (Dead Letter Queue)处理到达没有已知目的地的消息，Expiry Queue 包含其过期状态的消息，因此不应路由到其原始目的地。
1.3. 重新载入配置更新
默认情况下，代理会每 5000 毫秒检查配置文件中的更改。如果代理在配置文件的"上次修改"时间戳中检测到更改，代理会决定发生了配置更改。在这种情况下，代理会重新加载配置文件以激活更改。
当代理重新载入 broker.xml 配置文件时，它会重新载入以下模块：
地址设置和队列
重新加载配置文件时，地址设置决定了如何处理从配置文件中删除的地址和队列。您可以使用
config-delete-addresses和config-delete-queues属性设置它。更多信息请参阅 附录 B, 地址设置配置元素。安全设置
可以重新加载现有接收器上的 SSL/TLS 密钥存储和信任存储以建立新证书，而不影响现有客户端。连接的客户端（即使具有较旧或不同证书的用户）可以继续发送和接收消息。
证书撤销列表文件（使用 crlPath 参数配置）也可以重新加载。
diverts
配置重新加载会部署您添加的 任何新的 divert。但是，在重启代理前，从配置中删除或对 <
divert> 元素中的子元素的更改不会生效。
以下流程演示了如何更改代理检查代理对 broker.xml 配置文件更改的时间间隔。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在 <
;core> 元素中，添加<configuration-file-refresh-period> 元素并设置 refresh period （以毫秒为单位）。这个示例将配置刷新周期设置为 60000 毫秒：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
如果出于某种原因无法访问配置文件，则可以使用 Management API 或控制台强制重新加载配置文件。可以使用 ActiveMQServerControl 上的管理操作 reloadConfigurationFile （） （通过 ObjectName org.apache.activemq.artemis:broker="BROKER_NAME" 或资源 名称服务器）重新加载配置文件。
其他资源
- 要了解如何使用管理 API，请参阅管理 AMQ Broker 中的 使用管理 API
1.4. 修改代理配置文件
如果您有多个共享常见配置设置的代理，您可以在单独的文件中定义通用配置，然后将这些文件包含在每个代理的 broker.xml 配置文件中。
您可以在代理间共享的最常见配置设置包括：
- addresses
- 地址设置
- 安全设置
流程
为您要共享的每个
broker.xml部分创建单独的 XML 文件。每个 XML 文件都只能包括来自
broker.xml的单个部分（例如，地址或地址设置，但不能同时包括两者）。顶级元素还必须定义元素命名空间(xmlns="urn:activemq:core")。本例演示了
my-security-settings.xml中定义的安全设置配置：my-security-settings.xml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
为每个应使用通用配置设置的代理打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您打开的每个
broker.xml文件，请执行以下操作：在
broker.xml的开头的 <configuration> 元素中，验证是否出现以下行：xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xi="http://www.w3.org/2001/XInclude"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 为每个包含共享配置设置的 XML 文件添加 XML 包括。
这个示例包括
my-security-settings.xml文件。broker.xml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果需要，验证
broker.xml以验证 XML 是否对 schema 有效。您可以使用任何 XML 验证器程序。这个示例使用
xmllint根据artemis-server.xsl模式验证broker.xml。xmllint --noout --xinclude --schema /opt/redhat/amq-broker/amq-broker-7.2.0/schema/artemis-server.xsd /var/opt/amq-broker/mybroker/etc/broker.xml /var/opt/amq-broker/mybroker/etc/broker.xml validates
$ xmllint --noout --xinclude --schema /opt/redhat/amq-broker/amq-broker-7.2.0/schema/artemis-server.xsd /var/opt/amq-broker/mybroker/etc/broker.xml /var/opt/amq-broker/mybroker/etc/broker.xml validatesCopy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 有关 XML 包含的更多信息(XIncludes)，请参阅 https://www.w3.org/TR/xinclude/。
1.4.1. 重新加载模块配置文件
当代理定期检查配置更改（根据 config-file-refresh-period 指定的频率），它不会自动检测通过 xi:include 在 broker.xml 配置文件中包含的配置文件的变化。例如，如果 broker.xml 包含 my-address-settings.xml，并且您对 my-address-settings.xml 进行配置更改，代理不会自动检测 my-address-settings.xml 中的更改，并重新载入配置。
要强制 重新载入 broker.xml 配置文件以及其中包含的任何修改的配置文件，您必须确保 broker.xml 配置文件的"最后修改"时间戳已更改。您可以使用标准 Linux touch 命令更新 broker.xml 的最新修改时间戳，而无需进行任何其他更改。例如：
touch -m <broker_instance_dir>/etc/broker.xml
$ touch -m <broker_instance_dir>/etc/broker.xml
另外，您可以使用管理 API 来强制重新载入 Broker。可以使用 ActiveMQServerControl 上的管理操作 reloadConfigurationFile （） （通过 ObjectName org.apache.activemq.artemis:broker="BROKER_NAME" 或资源 名称服务器）重新加载配置文件。
其他资源
- 要了解如何使用管理 API，请参阅管理 AMQ Broker 中的 使用管理 API
1.4.2. 禁用外部 XML Entity (XXE)处理
如果您不想在 broker.xml 文件中包含的独立文件中对代理配置进行模块化，您可以禁用 XXE 处理来保护 AMQ Broker 免受 XXE 安全漏洞。如果您没有模块化代理配置，红帽建议您禁用 XXE 处理。
流程
-
打开 &
lt;broker_instance_dir>/etc/artemis.profile文件。 将新参数
-Dartemis.disableXxe添加至 Java 系统参数的JAVA_ARGS列表。-Dartemis.disableXxe=true
-Dartemis.disableXxe=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
保存
artemis.profile文件。
1.5. 扩展 JAVA 类路径
默认情况下，< broker_instance_dir>/lib 目录中的 JAR 文件会在运行时加载，因为目录是 Java 类路径的一部分。如果您希望 AMQ Broker 从 < broker_instance_dir> /lib 以外的目录中加载 JAR 文件，您必须将该目录添加到 Java classpath 中。
要在 Java 类路径中添加目录，您可以使用以下方法之一：
-
在 &
lt;broker_instance_dir>/etc/artemis.profile文件中，将新属性artemis.extra.libs添加到系统属性的JAVA_ARGS列表中。 -
设置
ARTEMIS_EXTRA_LIBS环境变量。
以下是使用这两种方法添加到 Java 类路径中的以逗号分隔的目录列表示例：
-Dartemis.extra.libs=/usr/local/share/java/lib1,/usr/local/share/java/lib2
-Dartemis.extra.libs=/usr/local/share/java/lib1,/usr/local/share/java/lib2export ARTEMIS_EXTRA_LIBS=/usr/local/share/java/lib1,/usr/local/share/java/lib2
export ARTEMIS_EXTRA_LIBS=/usr/local/share/java/lib1,/usr/local/share/java/lib2
如果在 < broker_instance_dir>/etc/artemis.profile 文件中配置了 环境变量会被忽略。
artemis.extra.libs Java 系统属性，则 ARTEMIS_ EXTRA_LIBS
1.6. 文档惯例
本文档对 sudo 命令、文件路径和可替换值使用以下惯例：
sudo 命令
在本文档中，sudo 用于任何需要 root 特权的命令。使用 sudo 时，您应始终谨慎操作，因为任何更改都可能会影响整个系统。
有关使用 sudo 的更多信息，请参阅管理 sudo 访问。
关于在此文档中使用文件路径
在这个文档中，所有文件路径都对 Linux、UNIX 和类似操作系统（例如 /home/...）有效。如果您使用的是 Microsoft Windows，则应使用等效的 Microsoft Windows 路径（例如，C:\Users\...）。
可替换值
本文档有时会使用可替换值，您必须将这些值替换为特定于环境的值。可替换的值为小写，以尖括号(<>)括起，样式则使用斜体和 monospace 字体。用下划线(_)分隔多个词语。
例如，在以下命令中，将 <install_dir> 替换为您自己的目录名称。
<install_dir>/bin/artemis create mybroker
$ <install_dir>/bin/artemis create mybroker第 2 章 在网络连接中配置接收器和连接器
AMQ Broker 中使用两种类型的连接： 网络连接和 in-VM 连接。当双方位于不同的虚拟机上时，会使用网络连接，无论是在同一服务器还是物理远程上。当客户端（应用程序还是服务器）位于与代理相同的虚拟机上时，会使用 in-VM 连接。
网络连接使用 Netty。Netty 是一个高性能、低级网络库，它允许以几种不同方式配置网络连接；使用 Java IO 或 NIO、TCP 套接字、SSL/TLS 或通过 HTTP 或 HTTPS 隧道。Netty 还允许单个端口用于所有消息传递协议。代理将自动检测正在使用的协议，并将传入的消息定向到适当的处理程序以进行进一步处理。
网络连接的 URI 确定其类型。例如，在 URI 中指定 vm 会创建一个 in-VM 连接：
<acceptor name="in-vm-example">vm://0</acceptor>
<acceptor name="in-vm-example">vm://0</acceptor>
或者，在 URI 中指定 tcp 会创建网络连接。例如：
<acceptor name="network-example">tcp://localhost:61617</acceptor>
<acceptor name="network-example">tcp://localhost:61617</acceptor>以下章节描述了网络连接和内连接所需的两个重要配置元素： acceptors 和 connectors。这些部分介绍了如何为 TCP、HTTP 和 SSL/TLS 网络连接配置 acceptors 和连接器，以及 in-VM 连接。
2.1. 关于接受者
acceptors 定义如何向代理连接。每个接受者定义客户端可用于建立连接的端口和协议。下方显示了一个简单的接收器配置。
<acceptors> <acceptor name="example-acceptor">tcp://localhost:61617</acceptor> </acceptors>
<acceptors>
<acceptor name="example-acceptor">tcp://localhost:61617</acceptor>
</acceptors>
您在代理配置中定义的每个 acceptor 元素都包含在一个 acceptors 元素中。您可以为代理定义的 acceptors 数没有上限。默认情况下，AMQ Broker 包括每个支持的消息传递协议的接收器，如下所示：
2.2. 配置接受者
以下示例演示了如何配置 acceptor。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
acceptors元素中，添加新的acceptor元素。指定协议，并在代理上指定端口。例如：<acceptors> <acceptor name="example-acceptor">tcp://localhost:61617</acceptor> </acceptors>
<acceptors> <acceptor name="example-acceptor">tcp://localhost:61617</acceptor> </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的示例定义了 TCP 协议的接收器。代理在端口 61617 侦听使用 TCP 的客户端连接。
将键值对附加到为 acceptor 定义的 URI。使用
分号（）分隔多个键值对。例如：<acceptor name="example-acceptor">tcp://localhost:61617?sslEnabled=true;key-store-path=</path/to/key_store></acceptor>
<acceptor name="example-acceptor">tcp://localhost:61617?sslEnabled=true;key-store-path=</path/to/key_store></acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 配置现在定义了一个使用 TLS/SSL 的接收器，并定义到所需密钥存储的路径。
其他资源
- 有关 acceptors 和 connector 的可用选项的详情，请参考 附录 A, acceptor 和 Connector 配置参数。
2.3. 关于连接器
acceptors 定义代理如何接受连接，客户端使用的连接器定义它们如何连接到一个代理。
当代理本身充当客户端时，代理会在代理上配置连接器。例如：
- 当代理桥接到另一个代理时
- 当代理处理集群中的一个部分时
下方显示了一个简单的连接器配置。
<connectors> <connector name="example-connector">tcp://localhost:61617</connector> </connectors>
<connectors>
<connector name="example-connector">tcp://localhost:61617</connector>
</connectors>2.4. 配置连接器
以下示例演示了如何配置连接器。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
connector元素中，添加新的连接器元素。指定协议，并在代理上指定端口。例如：<connectors> <connector name="example-connector">tcp://localhost:61617</connector> </connectors>
<connectors> <connector name="example-connector">tcp://localhost:61617</connector> </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的示例为 TCP 协议定义了一个连接器。客户端可以使用连接器配置，使用 TCP 协议连接到端口 61617 上的代理。代理本身也可以将此连接器用于传出连接。
将键值对附加到为连接器定义的 URI。使用
分号（）分隔多个键值对。例如：<connector name="example-connector">tcp://localhost:61616?tcpNoDelay=true</connector>
<connector name="example-connector">tcp://localhost:61616?tcpNoDelay=true</connector>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 配置现在定义了一个连接器，它将
tcpNoDelay属性的值设置为true。将此属性的值设置为true可关闭连接的 Nagle 算法。nagle 的算法是一种算法，用于通过延迟传输小数据包并将其整合到大型数据包来提高 TCP 连接效率。
其他资源
- 有关 acceptors 和 connector 的可用选项的详情，请参考 附录 A, acceptor 和 Connector 配置参数。
- 要了解如何在 AMQ Core Protocol JMS 客户端中配置代理连接器，请参阅 AMQ Core Protocol JMS 文档中的 配置代理连接器。
2.5. 配置 TCP 连接
AMQ Broker 使用 Netty 提供基本的、未加密的、基于 TCP 的连接，这些连接可以配置为使用阻止 Java IO 或较新的、非阻塞的 Java NIO。对于与许多并发连接具有更好的可扩展性，首选 Java NIO。但是，当您担心支持数以千计的并发连接时，使用旧的 IO 有时会为您提供比 NIO 更好的延迟。
如果您在不可信网络中运行连接，您应该注意 TCP 网络连接是未加密的。如果安全是优先级，您可能需要考虑使用 SSL 或 HTTPS 配置来加密通过此连接发送的消息。详情请查看 第 5.1 节 “保护连接”。
使用 TCP 连接时，所有连接都由客户端启动。代理不会启动到客户端的任何连接。这适用于用于强制从一个方向启动连接的防火墙策略。
对于 TCP 连接，连接器 URI 的主机和端口定义用于连接的地址。
以下示例演示了如何配置 TCP 连接。
先决条件
您应该熟悉配置接收器和连接器。如需更多信息，请参阅：
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加一个新的 acceptor 或修改现有接收器。在连接 URI 中，指定
tcp作为协议。包括 IP 地址或主机名以及代理上的端口。例如：<acceptors> <acceptor name="tcp-acceptor">tcp://10.10.10.1:61617</acceptor> ... </acceptors>
<acceptors> <acceptor name="tcp-acceptor">tcp://10.10.10.1:61617</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据前面的示例，代理接受从连接到 IP 地址
10.10.10.1的端口61617的客户端的 TCP 通信。（可选）您可以采用类似的方式配置连接器。例如：
<connectors> <connector name="tcp-connector">tcp://10.10.10.2:61617</connector> ... </connectors>
<connectors> <connector name="tcp-connector">tcp://10.10.10.2:61617</connector> ... </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 当进行到指定的 IP 和端口
10.10.10.2:61617时，上例中的连接器由客户端（甚至代理本身）引用。
其他资源
- 有关 TCP 连接的可用配置选项的详情，请参考 附录 A, acceptor 和 Connector 配置参数。
2.6. 配置 HTTP 连接
HTTP 连接通过 HTTP 协议隧道数据包，在防火墙只允许 HTTP 流量的情况下非常有用。AMQ Broker 会自动检测是否使用 HTTP，因此为 HTTP 配置网络连接与为 TCP 配置连接相同。
先决条件
您应该熟悉配置接收器和连接器。如需更多信息，请参阅：
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加一个新的 acceptor 或修改现有接收器。在连接 URI 中，指定
tcp作为协议。包括 IP 地址或主机名以及代理上的端口。例如：<acceptors> <acceptor name="http-acceptor">tcp://10.10.10.1:80</acceptor> ... </acceptors>
<acceptors> <acceptor name="http-acceptor">tcp://10.10.10.1:80</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据前面的示例，代理接受从客户端连接到 IP 地址
10.10.10.1的端口80的 HTTP 通信。代理自动检测到 HTTP 协议正在使用，并相应地与客户端通信。（可选）您可以采用类似的方式配置连接器。例如：
<connectors> <connector name="http-connector">tcp://10.10.10.2:80</connector> ... </connectors>
<connectors> <connector name="http-connector">tcp://10.10.10.2:80</connector> ... </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用上例中显示的连接器，代理会在 IP 地址
10.10.10.2的端口80上创建一个出站 HTTP 连接。
其他资源
- HTTP 连接使用与 TCP 相同的配置参数，但它有一部分本身。有关 HTTP 连接所有可用配置选项的详情，请参考 附录 A, acceptor 和 Connector 配置参数。
- 有关说明如何使用 HTTP 的完整工作示例，请参阅 JMS HTTP 示例。
2.7. 配置安全网络连接
您可以使用 TLS/SSL 保护网络连接。更多信息请参阅 第 5.1 节 “保护连接”。
2.8. 配置 in-VM 连接
当多个代理位于同一个虚拟机上时，您可以使用 in-VM 连接，例如作为高可用性(HA)配置的一部分。in-VM 连接也可以供本地客户端在与代理相同的 JVM 中运行。
先决条件
您应该熟悉配置接收器和连接器。如需更多信息，请参阅：
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加一个新的 acceptor 或修改现有接收器。在连接 URI 中，将
vm指定为协议。例如：<acceptors> <acceptor name="in-vm-acceptor">vm://0</acceptor> ... </acceptors>
<acceptors> <acceptor name="in-vm-acceptor">vm://0</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上例中的 acceptor，代理接受来自 ID 为
0的代理的连接。其他代理必须在同一虚拟机中运行。（可选）您可以采用类似的方式配置连接器。例如：
<connectors> <connector name="in-vm-connector">vm://0</connector> ... </connectors>
<connectors> <connector name="in-vm-connector">vm://0</connector> ... </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 上例中的连接器定义了客户端如何在与客户端相同的虚拟机上运行的 ID 为
0来建立与代理中的 in-VM 连接。客户端可以是应用程序或其他代理。
第 3 章 在网络连接中配置消息传递协议
AMQ Broker 有一个可插拔协议架构，以便您可以轻松为网络连接启用一个或多个协议。
代理支持以下协议：
除了上述协议外，代理还支持自己的原生协议，称为"Core"。此协议的过去版本被称为 "HornetQ"，并由 Red Hat JBoss Enterprise Application Platform 使用。
3.1. 配置网络连接以使用消息传递协议
在使用协议前，您必须将协议与网络连接关联。（请参阅 第 2 章 在网络连接中配置接收器和连接器 来了解如何创建和配置网络连接。）默认配置位于文件 < broker_instance_dir>/etc/broker.xml 中，包括已经定义的多个连接。为方便起见，AMQ Broker 包括了每个支持的协议的接收器，以及支持所有协议的默认接收器。
默认接收器概述
以下是 broker.xml 配置文件中默认包括的 acceptors。
在给定网络连接器中启用协议的唯一要求是，将 protocol 参数添加到接受者的 URI 中。参数的值必须是用逗号分开的协议名称列表。如果 URI 中省略了 protocol 参数，则会启用所有协议。
例如，要创建一个接受者来使用 AMQP 协议在端口 3232 上接收信息，请按照以下步骤操作：
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
在 <
acceptors> 小节中添加以下行：
<acceptor name="ampq">tcp://0.0.0.0:3232?protocols=AMQP</acceptor>
<acceptor name="ampq">tcp://0.0.0.0:3232?protocols=AMQP</acceptor>默认接收器中的其他参数
在最小的 acceptor 配置中，您可以将协议指定为连接 URI 的一部分。但是，broker.xml 配置文件中的默认 acceptors 配置了一些额外的参数。下表详细介绍了为默认接收器配置的附加参数。
| acceptor (s) | 参数 | 描述 |
|---|---|---|
| all-protocols acceptor AMQP STOMP | tcpSendBufferSize |
TCP 发送缓冲区的大小（以字节为单位）。默认值为 |
| tcpReceiveBufferSize |
以字节为单位 TCP 接收缓冲区的大小。默认值为 TCP 缓冲区大小应根据您的网络带宽和延迟进行调优。 在摘要 TCP 发送/接收缓冲区大小中，应计算为： buffer_size = bandwidth * RTT.
其中带宽（以字节/秒为单位），网络往返用时(RTT)以秒为单位。可以使用 对于快速网络，您可能需要从默认值中增加缓冲区大小。 | |
| all-protocols acceptor AMQP STOMP HornetQ MQTT | useEpoll |
如果使用支持它的系统(Linux)，请使用 Netty epoll。与 NIO 传输相比，Netty 原生传输提供了更好的性能。此选项的默认值是 |
| all-protocols acceptor AMQP | amqpCredits |
AMQP 生成者可以发送的最大消息数，无论消息总数如何。默认值为 要了解有关如何使用分数阻止 AMQP 信息的更多信息，请参阅 第 7.3.2 节 “阻塞 AMQP 生成者”。 |
| all-protocols acceptor AMQP | amqpLowCredits |
代理 replenes producer 学分的较低阈值。默认值为 要了解有关如何使用分数阻止 AMQP 信息的更多信息，请参阅 第 7.3.2 节 “阻塞 AMQP 生成者”。 |
| HornetQ 兼容性接收器 | anycastPrefix |
当连接到一个使用 有关配置前缀以使客户端在连接到地址时指定路由类型的更多信息，请参阅 第 4.6 节 “在接受器配置中添加路由类型”。 |
| multicastPrefix |
当连接到一个使用 有关配置前缀以使客户端在连接到地址时指定路由类型的更多信息，请参阅 第 4.6 节 “在接受器配置中添加路由类型”。 |
其他资源
- 有关您可以为 Netty 网络连接配置的其他参数的详情，请参考 附录 A, acceptor 和 Connector 配置参数。
3.2. 使用带有网络连接的 AMQP
代理支持 AMQP 1.0 规格。AMQP 链接是用于源和目标（即客户端和代理）之间消息的单向协议。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
添加或配置一个
acceptor来接收 AMQP 客户端，方法是包括一个值为AMQP的protocols参数作为 URI 的一部分。如下例所示：
<acceptors> <acceptor name="amqp-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor> ... </acceptors>
<acceptors>
<acceptor name="amqp-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor>
...
</acceptors>在前面的示例中，代理接受端口 5672 上的 AMQP 1.0 客户端，这是默认的 AMQP 端口。
AMQP 链接有两个端点，即发送者和接收器。当发送者传输消息时，代理会将其转换为内部格式，以便将其转发到代理上的目的地。接收器通过代理连接到目的地，并在发送信息前将消息重新转换为 AMQP。
如果 AMQP 链接是动态的，则会创建一个临时队列，并将远程源或远程目标地址设置为临时队列的名称。如果链接不是动态的，则使用远程目标或源的地址作为队列。如果远程目标或源不存在，则会发送一个例外。
链接目标也可以是 Coordinator，它用于将底层会话作为事务处理，可以回滚或提交它。
AMQP 允许每个会话使用多个事务，即 amqp:multi-txns-per- sn，但当前版本的 AMQ Broker 将只支持每个会话的单个事务。
AMQP 中的分布式事务(XA)详情在规格的 1.0 版本中没有提供。如果您的环境需要支持分布式事务，建议您使用 AMQ 核心协议 JMS。
有关协议及其功能的更多信息，请参阅 AMQP 1.0 规格。
3.2.1. 使用 AMQP 链接作为主题
与 JMS 不同，AMQP 协议不包括主题。但是，仍然可以将 AMQP 用户或接收器视为订阅，而不仅仅是队列上的消费者。默认情况下，任何附加到带有前缀 jms.topic. 的地址的接收链接被视为订阅，并且创建了订阅队列。订阅队列是 durable 或 volatile，具体取决于 Terminus Durability 如何配置，如下表中捕获：
| 要为仅多播队列… 创建这种类型的订阅 | 将 Terminus Durability 设置为此… |
|---|---|
| Durable |
|
| 非持久性 |
|
持久队列的名称由容器 ID 和链接名称组成，如 my-container-id:my-link-name。
AMQ Broker 还支持 qpid-jms 客户端，并将遵守其主题的使用，而不考虑用于地址的前缀。
3.2.2. 配置 AMQP 安全性
代理支持 AMQP SASL 身份验证。有关如何在代理上配置基于 SASL 的身份验证的更多信息，请参阅 安全性。
3.3. 使用带有网络连接的 MQTT
代理支持 MQTT v3.1.1 和 v5.0 （以及旧的 v3.1 代码消息格式）。MQTT 是到服务器、发布/订阅消息传递协议的轻量级客户端。MQTT 可减少消息传递开销和网络流量，以及客户端的代码占用。由于这些原因，MQTT 非常适合受限制的设备，如传感器和参与者，并很快成为了用于互联网(IoT)的事实标准通信协议。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 - 添加一个启用 MQTT 协议的接收器。例如：
<acceptors> <acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT</acceptor> ... </acceptors>
<acceptors>
<acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT</acceptor>
...
</acceptors>MQTT 带有一些有用的功能，其中包括：
- 服务质量
- 每个消息都可以定义与之关联的服务质量。代理会尝试以最高质量的服务级别向订阅者发送信息。
- 保留消息
可以为特定地址保留消息。针对该地址的新订阅者在任何其他消息之前接收最后保留的消息，即使客户端连接前发送了保留的消息。
保留的消息存储在名为
sys.mqtt.<topic name> 的队列中，并保留在队列中，直到客户端删除保留的消息或配置了到期信息，直到消息过期为止。当队列为空时，队列不会被删除，除非您明确删除队列。例如，以下配置会删除队列：<address-setting match="$sys.mqtt.retain.#"> <auto-delete-queues>true</auto-delete-queues> <auto-delete-addresses>true</auto-delete-addresses> </address-setting>
<address-setting match="$sys.mqtt.retain.#"> <auto-delete-queues>true</auto-delete-queues> <auto-delete-addresses>true</auto-delete-addresses> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 通配符订阅
- MQTT 地址是分层的，类似于文件系统的层次结构。客户端可以订阅特定主题或层次结构的整个分支。
- 邮件
- 客户端可以将"will 消息"设置为其连接数据包的一部分。如果客户端通常断开连接，代理会将 will message 发布到指定的地址。其他订阅者收到消息，可以相应地做出反应。
有关 MQTT 协议的更多信息，请参阅规格。
3.3.1. 配置 MQTT 属性
您可以将键值对附加到 MQTT acceptor 中，以配置连接属性。例如：
<acceptors> <acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT;receiveMaximum=50000;topicAliasMaximum=50000;maximumPacketSize;134217728; serverKeepAlive=30;closeMqttConnectionOnPublishAuthorizationFailure=false</acceptor> ... </acceptors>
<acceptors>
<acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT;receiveMaximum=50000;topicAliasMaximum=50000;maximumPacketSize;134217728;
serverKeepAlive=30;closeMqttConnectionOnPublishAuthorizationFailure=false</acceptor>
...
</acceptors>- receiveMaximum
-
通过在需要确认前指定代理可以从客户端接收的最大 QoS 数量和 2 个消息来启用 flow-control。默认值为
65535。值-1禁用从客户端到代理的 flow-control。这与将值设置为 0 的影响相同，但会减小 CONNACK 数据包的大小。 - topicAliasMaximum
-
为客户端指定代理支持的最大别名数。默认值为
65535。值 -1 可防止代理告知客户端主题别名限制。这与将值设置为 0 的影响相同，但会减小 CONNACK 数据包的大小。 - maximumPacketSize
-
指定代理可以接受的最大数据包大小。默认值为
268435455。值 -1 可防止代理通知客户端的最大数据包大小，这意味着对于传入数据包的大小不会强制实施任何限制。 - serverKeepAlive
-
指定代理保持不活跃客户端连接打开的持续时间。只有在少于为客户端配置的 keep-alive 值或为客户端配置的值为 0 时，配置的值才会应用到连接。默认值为
60秒。值-1表示代理始终接受客户端的 keep alive 值（即使该值是 0）。 - closeMqttConnectionOnPublishAuthorizationFailure
-
默认情况下，如果因为缺少授权而 PUBLISH 数据包失败，代理会关闭网络连接。如果您希望代理发送正确认而不是关闭网络连接，请将
closeMqttConnectionOnPublishAuthorizationFailure设置为false。
3.4. 使用带有网络连接的 OpenWire
代理支持 OpenWire 协议，它允许 JMS 客户端直接与代理通信。使用此协议与较旧版本的 AMQ Broker 通信。
目前 AMQ Broker 支持仅使用标准 JMS API 的 OpenWire 客户端。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加或修改
接收器，使其包括OPENWIRE作为protocol参数的一部分，如下例所示：<acceptors> <acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor> ... </acceptors>
<acceptors> <acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
在前面的示例中，代理将监听端口 61616 用于传入的 OpenWire 命令。
如需了解更多详细信息，请参阅 Openwire 示例。
3.5. 使用带有网络连接的 STOMP
Stomp 是一个文本线协议，它允许 STOMP 客户端与 STOMP Broker 进行通信。代理支持 STOMP 1.0、1.1 和 1.2。STOMP 客户端可用于多种语言和平台，使其成为互操作性的良好选择。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
配置现有的
acceptor或创建一个新的，其中包含值为STOMP的protocol参数，如下所示：
<acceptors> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor> ... </acceptors>
<acceptors>
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor>
...
</acceptors>
在上例中，代理接受端口 61613 上的 STOMP 连接，这是默认设置。
有关如何使用 STOMP 配置代理的示例，请参阅 STOMP 示例。
3.5.1. Stomp 限制
使用 STOMP 时，会有以下限制：
-
代理目前不支持虚拟主机，这意味着
CONNECT帧中的host标头被忽略。 -
消息确认不是事务的。
ACK帧不能是事务的一部分，如果设置了事务标头，它会被忽略。
3.5.2. 为 STOMP 消息提供 ID
当通过 JMS 使用者或 QueueBrowser 接收 STOMP 消息时，消息默认不包含任何 JMS 属性，如 JMSMessageID。但是，您可以使用代理参数在每个传入的 STOMP 消息上设置消息 ID。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
对于用于 STOMP 连接的
acceptor，将stompEnableMessageId参数设置为true，如下例所示：
<acceptors> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor> ... </acceptors>
<acceptors>
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor>
...
</acceptors>
通过使用 stompEnableMessageId 参数，使用此接收器发送的每个 stomp 消息都添加了额外的属性。属性键为 amq-message-id，值是前缀为 "STOMP" 的内部消息 ID 的 String 表示，如下例所示：
amq-message-id : STOMP12345
amq-message-id : STOMP12345
如果配置中没有指定 stompEnableMessageId，则默认值为 false。
3.5.3. 将连接时间设置为 live
STOMP 客户端必须在关闭其连接之前发送 DISCONNECT 帧。这允许代理关闭任何服务器端资源，如会话和消费者。但是，如果 STOMP 客户端在不发送 DISCONNECT 帧的情况下退出，或者如果失败，代理将无法立即知道客户端是否仍然处于活动状态。因此，STOMP 连接被配置为 "Time to Live" (TTL)为 1 分钟。这意味着，如果代理闲置超过 1 分钟，代理会停止与 STOMP 客户端的连接。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
将
connectionTTL参数添加到用于 STOMP 连接的acceptor的 URI 中，如下例所示：
<acceptors> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTTL=20000</acceptor> ... </acceptors>
<acceptors>
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTTL=20000</acceptor>
...
</acceptors>
在前面的示例中，使用 stomp-acceptor 的任何 stomp 连接都会将其 TTL 设置为 20 秒。
STOMP 协议的版本 1.0 不包含任何心跳帧。因此，用户负责确保数据在 connection-ttl 中发送，或者代理会假定客户端已死机并清理服务器端资源。使用版本 1.1 时，您可以使用 core-beats 来维护 stomp 连接的生命周期。
将代理默认时间设置为 live
如前文所述，STOMP 连接的默认 TTL 为一分钟。您可以通过在代理配置中添加 connection-ttl-override 属性来覆盖这个值。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
添加
connection-ttl-override属性，并为新默认值提供值（毫秒）。它属于 <core> 小节，如下所示。
在前面的示例中，STOMP 连接的默认生存时间(TTL)被设置为 30 秒，30000 毫秒。
3.5.4. 从 JMS 发送和接收和使用 STOMP 消息
STOMP 主要是一个文本性协议。为了更容易与 JMS 交互，STOMP 实施会检查 内容长度 标头的存在，以决定如何将 STOMP 消息映射到 JMS。
| 如果您希望 STOMP 消息映射到 … | 消息 should…。 |
|---|---|
| JMS TextMessage |
不包括 |
| JMS BytesMessage |
包括一个 |
当将 JMS 消息映射到 STOMP 时，也会应用相同的逻辑。STOMP 客户端可以确认是否存在 content-length 标头，以确定消息正文的类型（字符串或字节数）。
有关消息标头的更多信息，请参阅 STOMP 规格。
3.5.5. 将 STOMP 目的地映射到 AMQ Broker 地址和队列
在发送消息和订阅时，STOMP 客户端通常包含一个 目的地 标头。目标名称是字符串值，映射到代理上的目的地。在 AMQ Broker 中，这些目的地映射到 addresses 和 queues。有关目的地帧的更多信息，请参阅 STOMP 规格。
取一个发送以下消息的 STOMP 客户端示例（包括 headers 和 body）：
SEND destination:/my/stomp/queue hello queue a ^@
SEND
destination:/my/stomp/queue
hello queue a
^@
在这种情况下，代理会将消息转发到与地址 /my/stomp/queue 关联的任何队列。
例如，当 STOMP 客户端发送一条消息时（使用 SEND 帧），指定的目的地映射到一个地址。
当客户端发送 SUBSCRIBE 或 UNSUBSCRIBE 帧时，它的工作方式相同，但在这种情况下，AMQ Broker 将 目的地映射 到队列。
SUBSCRIBE destination: /other/stomp/queue ack: client ^@
SUBSCRIBE
destination: /other/stomp/queue
ack: client
^@
在前面的示例中，代理会将 目的地映射 到队列 /other/stomp/queue。
将 STOMP 目的地映射到 JMS 目的地
JMS 目的地也映射到代理地址和队列。如果要使用 STOMP 发送消息到 JMS 目的地，stomp 目的地必须遵循相同的约定：
通过
jms.queue添加队列名称来发送或订阅 JMS Queue。例如，要将信息发送到ordersJMS Queue，STOMP 客户端需要发送帧：SEND destination:jms.queue.orders hello queue orders ^@
SEND destination:jms.queue.orders hello queue orders ^@Copy to Clipboard Copied! Toggle word wrap Toggle overflow 通过添加主题名称以
jms.topic形式发送或订阅 JMS 主题。例如，要订阅库存JMS 主题，STOMP 客户端必须发送类似如下的帧：SUBSCRIBE destination:jms.topic.stocks ^@
SUBSCRIBE destination:jms.topic.stocks ^@Copy to Clipboard Copied! Toggle word wrap Toggle overflow
第 4 章 配置地址和队列
4.1. 地址、队列和路由类型
在 AMQ Broker 中，寻址模型包括三个主要概念： 地址、队列和 路由类型。
一个地址 代表消息传递端点。在配置中，典型的地址被赋予一个唯一名称、一个或多个队列，以及路由类型。
队列与 地址关联。每个地址可以有多个队列。当传入消息与地址匹配后，该消息将发送到一个或多个队列，具体取决于配置的路由类型。可以将队列配置为自动创建和删除。您还可以配置一个地址（以及其关联队列）作为 durable。持久化队列中的消息可以在崩溃或重启代理时存活，只要队列中的消息也具有持久性。相反，非持久化队列中的消息不会丢失崩溃或代理重启后，即使消息本身是持久的。
路由类型决定了 消息如何发送到与地址关联的队列。在 AMQ Broker 中，您可以使用两种不同的路由类型配置地址，如表中所示。
| 如果您希望您的消息路由到… | 使用此路由类型… |
|---|---|
| 匹配地址中的单个队列，以点对点的方式 |
|
| 匹配地址中的每个队列以发布订阅的方式 |
|
地址必须至少有一个定义的路由类型。
每个地址可以定义多个路由类型，但不推荐这样做。
如果一个地址同时定义了两个路由类型，并且客户端没有其首选项，则代理会默认使用 multicast 类型。
其他资源
有关配置的更多信息：
-
点到点的消息使用
anycast路由类型，请参阅 第 4.3 节 “为点到点消息传递配置地址” -
使用
multicast路由类型发布订阅消息传递，请参阅 第 4.4 节 “为发布订阅消息传递配置地址”
-
点到点的消息使用
4.1.1. 地址和队列命名要求
在配置地址和队列时请注意以下要求：
为确保客户端可以连接到队列，无论客户端使用哪个线协议，您的地址和 队列名称不应包含 以下任意字符：
&::,?>-
数字符号（
#）和星号（*）字符被保留为通配符表达式，在地址和队列名称中不应使用它们。更多信息请参阅 第 4.2.1 节 “AMQ Broker 通配符语法”。 - 地址和队列名称不应包含空格。
-
要分隔地址或队列名称中的词语，请使用配置的分隔符字符。默认分隔符字符是句点(
.)。更多信息请参阅 第 4.2.1 节 “AMQ Broker 通配符语法”。
4.2. 将地址设置应用到一组地址
在 AMQ Broker 中，您可以使用通配符表达式代表匹配的地址名称，将 address-setting 元素中指定的配置应用到 一组 地址。
以下小节论述了如何使用通配符表达式。
4.2.1. AMQ Broker 通配符语法
AMQ Broker 使用特定语法来代表地址设置中的通配符。通配符也可以在安全设置中使用，并在创建使用者时使用。
-
通配符表达式包含一个以句点(
.)分隔的词语。 数字符号 (
#) 和星号 (*) 字符还有特殊的用处，可以替代一个词，例如：- 数字符号字符表示"匹配任何 0 个或更多连续的词"。在表达式的末尾使用它。
- 星号字符表示"匹配单个单词"。在您的表达式中的任何位置使用它。
匹配不是按照字符进行的，而是根据分割的字符段进行的。例如，一个 address-setting 项被配置为匹配名称中带有 my 的队列将不匹配名为 myqueue 的队列。
当多个 address-setting 元素与地址匹配时，代理覆盖配置将最小特定匹配项的配置用作基准。表达式中的字面字符比通配符更具体，星号 (*) 比数字符号更具体 (#)。例如，my.destination 和 my.* 都会匹配地址 my.destination。在这种情况下，代理首先应用 my opg 下找到的配置，因为通配符表达式比字面 小。接下来，代理覆盖 my.destination address 设置元素的配置，它会覆盖任何使用 my ClusterClaim 共享的配置。例如，假设与 my.destination 关联的队列将 max-delivery-attempts 设置为 3，last-value-queue 设为 false。
下表中的示例说明了如何使用通配符来匹配一组地址。
| Example | 描述 |
|---|---|
|
|
|
|
|
匹配 |
|
|
匹配 |
|
|
匹配 |
4.2.2. 配置字面匹配
在字面匹配中，通配符将被视为字面字符，以匹配包含通配符的地址。例如，字面匹配中的 hash (#)字符可以匹配 orders. Slack 但没有匹配地址的地址，如 orders.retail 或 orders.wholeell。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在配置字面匹配项前，请使用
literal-match-markers参数来定义限制字面匹配项的字符。在以下示例中，使用括号来限制字面匹配。<core> ... <literal-match-markers>()</literal-match-markers> ... </core>
<core> ... <literal-match-markers>()</literal-match-markers> ... </core>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在定义了限制字面匹配项的标记后，在
address 设置 match 参数中指定匹配项，包括标记。以下示例为名为orders."" 的地址配置字面匹配，以启用该特定地址的指标。<address-settings> <address-setting match="(orders.#)"> <enable-metrics>true</enable-metrics> </address-setting> </address-settings><address-settings> <address-setting match="(orders.#)"> <enable-metrics>true</enable-metrics> </address-setting> </address-settings>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.2.3. 配置代理通配符语法
以下流程演示了如何自定义用于通配符地址的语法。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在配置中添加 <
wildcard-addresses> 部分，如下例所示。Copy to Clipboard Copied! Toggle word wrap Toggle overflow enabled-
当设置为
true时，指示代理使用您的自定义设置。 delimiter-
提供自定义字符作为
分隔符替代默认字符（.）。 any-words-
作为
any-words的值提供的字符代表“匹配 0 个或更多个序列”，并将替换默认的#。在表达式的末尾使用此字符。 单词-
作为
single-word的值提供的字符代表“匹配一个词”，并将替换默认的*。在您的表达式中的任何位置使用此字符。
4.3. 为点到点消息传递配置地址
点到点消息传递是一个常见场景，其中生成者发送的消息只有一个消费者。AMQP 和 JMS 消息生成者和使用者可以利用点对点的消息传递队列，例如：为确保在点到点的方式中队列与一个接收消息的地址相关联，在您的代理配置中为给定的 address项定义一个 anycast 路由类型。
当消息在一个使用 anycast 的地址上接收时，代理会找到与地址关联的队列，并将消息路由到它。然后，消费者可能会请求使用该队列的消息。如果多个用户连接到同一队列，则消息会在消费者之间平均分配，只要使用者可以平等地处理它们。
下图显示了点对点的消息传递示例。
图 4.1. 点到点的消息传递
4.3.1. 配置基本点到点消息
以下流程演示了如何使用单一队列为点到点消息传递配置地址。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 使用一个
address所选的queue项环绕一个anycast配置项。确保address和queue元素的name属性的值相同。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.3.2. 为多个队列配置点到点消息传递
您可以在使用 anycast 路由类型的地址上定义多个队列。代理在所有关联的队列中平均分配发送到 anycast 地址的信息。通过指定 完全限定域名 (FQQN)，您可以将客户端连接到特定的队列。如果多个消费者连接到同一队列，代理会在消费者之间平均分配消息。
下图显示了使用两个队列的点对点消息传递示例。
图 4.2. 使用两个队列的点到点消息传递
以下流程演示了如何为具有多个队列的地址配置点到点消息传递。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 使用在
address项中的queue项环绕一个anycast配置项。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
如果您有一个配置，如上面显示在集群中的多个代理间镜像的配置，集群可以以不对生产者和消费者不透明的方式实现平衡点到点的消息传递。确切的行为取决于如何为集群配置消息负载均衡策略。
其他资源
有关以下内容的更多信息：
- 指定完全限定域名，请参阅 第 4.9 节 “指定完全限定的队列名称”。
- 如何为代理集群配置消息负载均衡，请参阅 第 14.1.1 节 “代理集群如何平衡消息负载”。
4.4. 为发布订阅消息传递配置地址
在发布订阅场景中，消息将发送到每个消费者订阅一个地址。JMS 主题和 MQTT 订阅是发布-订阅消息传递的两个示例。为确保以发布订阅方式与地址接收信息关联的队列，您可以在代理配置中为给定 address 元素定义 多播 路由类型。
当在带有 多播 路由类型的地址上收到消息时，代理会将消息副本路由到与地址关联的每个队列。要减少复制开销，每个队列仅发送对消息 的引用，而不是完整副本。
下图显示了发布-订阅消息传递的示例。
图 4.3. 发布订阅消息传递
以下流程演示了如何为发布订阅消息传递配置地址。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 向地址添加一个空的
multicast配置元素。Copy to Clipboard Copied! Toggle word wrap Toggle overflow （可选）将一个或多个
queue项添加到地址中，并在它们间环绕multicas项。通常不需要这一步，因为代理会自动为客户端请求的每个订阅创建一个队列。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.5. 为点到点和发布订阅消息传递配置地址
您还可以使用点到点 和发布 订阅语义配置地址。
通常不建议将地址配置为同时使用点到点和发布订阅模式。但是，如果需要，它可能会有用。例如，一个名为 orders 的 JMS 队列，以及名为 order 的 JMS 主题。不同的路由类型使地址因客户端连接而异。在这种情况下，由 JMS 队列生成者发送的消息使用 anycast 路由类型。JMS 主题生成者发送的消息使用 multicast 路由类型。当 JMS 主题使用者连接到代理时，它将附加到自己的订阅队列。但是，JMS 队列消费者附加到 anycast 队列。
下图显示了同时使用的点对点和发布-订阅消息传递的示例。
图 4.4. 点到点和发布订阅消息传递
以下流程演示了如何为点到点和发布订阅消息传递配置地址。
这种情境的行为取决于所使用的协议。对于 JMS，主题和队列生成者和消费者之间有明确区分，这让逻辑直接变得简单。AMQP 等其他协议不会区分此区别。通过 AMQP 发送的消息以 anycast 和 multicast 路由，消费者默认为 anycast。更多信息请参阅 第 3 章 在网络连接中配置消息传递协议。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 使用在
address项中的queue项环绕一个anycast配置项。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 向地址添加一个空的
multicast配置元素。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意通常，代理会根据需要创建订阅队列，因此不需要列出
multicast元素中的特定队列元素。
4.6. 在接受器配置中添加路由类型
通常，如果一个消息由同时使用 anycast 和 multicast 的地址接收，一个 anycast 队列会接收消息，以及所有 multicast 队列。但是，当连接到地址时，客户端可以指定一个特定的前缀，以指定是否使用 anycast 或 multicast 连接。前缀是使用代理配置中接受者 URL 中的 anycastPrefix 和 multicastPrefix 参数指定的自定义值。
以下流程演示了如何为给定接受器配置前缀。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于给定的接收器，若要配置
anycast前缀，将anycastPrefix添加到配置的 URL。设置自定义值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据前面的配置，acceptor 被配置为使用
anycast://（anycast前缀）。如果客户端需要将信息只发送到anycast队列，客户端可以指定anycast://<my.destination>/。对于给定的接收器，若要配置
多播前缀，请将multicastPrefix添加到配置的 URL。设置自定义值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据前面的配置，acceptor 被配置为使用
multicast://作为多播前缀。如果客户端只需要发送到多播队列，客户端代码可以指定multicast://<my.destination
4.7. 配置订阅队列
在大多数情况下，不需要手动创建订阅队列，因为当客户端首次订阅某个地址时，协议管理器会自动创建订阅队列。请参阅 第 4.8.3 节 “协议管理器和地址” 了解更多信息。对于持久订阅，生成的队列名称通常是客户端 ID 和地址的连接。
以下小节演示了如何根据需要手动创建订阅队列。
4.7.1. 配置持久化订阅队列
当队列配置为持久订阅时，代理会为任何不活跃的用户保存消息，并在用户重新连接时将它们提供给订阅者。因此，在订阅队列后，客户端可以保证接收发送到队列的每个消息。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 将
durable配置元素添加到所选队列。设置true值。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意由于队列默认是持久化的，包括
durable元素，并将值设为true并不严格要求创建持久队列。但是，明确包含元素可让您稍后将队列的行为更改为非持久（如果需要）。
4.7.3. 配置非持久化订阅队列
非持久化订阅通常由相关协议管理器管理，这将创建和删除临时队列。
但是，如果要手动创建类似于非持久订阅队列的队列，您可以在队列中使用 purge-on-no-consumers 属性。当 purge-on-no-consumers 设为 true 时，队列不会启动接收消息，直到消费者连接为止。另外，当最后一个消费者与队列断开连接时，队列将被清除（即，其消息会被删除）。在新使用者连接到队列之前，队列不会收到任何进一步的消息。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 将
purge-on-no-consumers属性添加到每个所选队列。设置true值。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.8. 自动创建和删除地址和队列
您可以将代理配置为自动创建地址和队列，并在不再使用后删除它们。这会使您不必在客户端连接到每个地址前预配置每个地址。
4.8.1. 用于自动队列创建和删除的配置选项
下表列出了在配置 address-setting 元素时可用的配置元素，以自动创建和删除队列和地址。
如果您希望 address-setting to… | 添加此配置… |
|---|---|
| 当客户端向或试图使用映射到不存在的地址的队列中的消息时，创建地址。 |
|
| 当客户端向队列发送消息或尝试使用队列的消息时，创建队列。 |
|
| 当它不再有任何队列时，删除自动创建的地址。 |
|
| 当队列有 0 个消费者和 0 消息时，删除自动创建的队列。 |
|
| 如果客户端没有指定，使用一个特定的路由类型。 |
|
4.8.2. 配置自动创建和删除地址和队列
以下流程演示了如何配置自动创建和删除地址和队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 配置
address-setting以自动创建和删除。以下示例使用上表中提到的所有配置元素。Copy to Clipboard Copied! Toggle word wrap Toggle overflow address-setting-
address-setting元素的配置应用于与通配符地址activemq." 匹配的任何地址或队列。 auto-create-addresses- 当客户端请求连接到尚不存在的地址时，代理会创建地址。
auto-delete-addresses- 当它不再关联任何队列时，会自动创建的地址。
auto-create-queues- 当客户端请求连接到尚不存在的队列时，代理会创建队列。
auto-delete-queues- 当一个自动创建的队列不再包含任何消费者或消息时，会删除它。
default-address-routing-type-
如果客户端在连接时没有指定路由类型，代理会在向地址发送消息时使用
ANYCAST。默认值为MULTICAST。
其他资源
有关以下内容的更多信息：
- 在配置地址时可以使用的通配符语法，请参阅 第 4.2 节 “将地址设置应用到一组地址”。
- 路由类型，请参阅 第 4.1 节 “地址、队列和路由类型”。
4.8.3. 协议管理器和地址
称为 协议管理器 的组件将特定于协议的概念映射到 AMQ Broker 地址模型中使用的概念；队列和路由类型。在某些情况下，协议管理器可能会在代理上自动创建队列。
例如，当客户端发送地址 /house/room1/lights 和 /house/room2/lights 的 MQTT 订阅数据包时，MQTT 协议管理器可以理解这两个地址需要 多播 语义。因此，协议管理器首先会查找两个地址都启用了 多播。如果没有，它会尝试动态创建它们。如果成功，协议管理器会为客户端请求的每个订阅创建特殊的订阅队列。
每个协议的行为稍有不同。下表描述了当请求各种类型的 队列时，通常会发生什么情况。
| 如果队列是这个类型… | 协议管理器的典型操作是 … |
|---|---|
| 持久化订阅队列 |
查找适当的地址，并确保 特殊名称允许协议管理器快速识别所需的客户端订阅队列，客户端在以后断开连接并重新连接。 当客户端取消订阅队列时。 |
| 临时订阅队列 |
查找适当的地址，并确保 当客户端断开队列时。 |
| point-to-point 队列 |
查找适当的地址，并确保启用了 如果自动创建队列，则在没有消费者且没有消息后自动删除。 |
4.9. 指定完全限定的队列名称
在内部，代理会将对地址的客户端请求映射到特定队列。代理代表客户端决定将消息发送到哪个队列，或者从哪个队列接收消息。但是，更高级的用例可能需要客户端直接指定队列名称。在这些情况下，客户端可以使用 完全限定的队列名称 (FQQN)。FQQN 包括地址名称和队列名称，用 :: 分隔。
以下流程演示了如何在连接到具有多个队列的地址时指定 FQQN。
先决条件
您有一个配置了两个或多个队列的地址，如下例所示。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
流程
在客户端代码中，在从代理请求连接时使用地址名称和队列名称。使用两个冒号
::来分隔名称。例如：String FQQN = "my.address::q1"; Queue q1 session.createQueue(FQQN); MessageConsumer consumer = session.createConsumer(q1);
String FQQN = "my.address::q1"; Queue q1 session.createQueue(FQQN); MessageConsumer consumer = session.createConsumer(q1);Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.10. 配置分片队列
在队列中处理消息的通用模式，其中只需要部分顺序才能使用 队列分片。这意味着您可以定义一个作为单一逻辑队列的 anycast 地址，但它由多个底层物理队列支持。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加
address元素并设置name属性。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加
anycast路由类型，并包括所需的分片队列数量。在以下示例中，队列q1,q2, 和q3添加为anycast的目的地。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
根据上述配置，发送到 my.sharded.address 的消息会在 q1, q2 和 q3 之间均匀分布。在使用完全限定域名(FQQN)时，客户端可以直接连接到特定的物理队列。
要将特定消息绑定到特定队列，客户端可以为每个消息指定一个消息组。代理将消息分组到同一队列，一个消费者会全部处理它们。
其他资源
有关以下内容的更多信息：
- 完全限定域名，请参阅 第 4.9 节 “指定完全限定的队列名称”
- 消息分组，请参阅 AMQ Core Protocol JMS 文档中的使用消息组。https://docs.redhat.com/en/documentation/red_hat_amq_core_protocol_jms/7.11/html-single/using_amq_core_protocol_jms/index.html#using_message_groups
4.11. 配置最后的值队列
最后的值队列 是一种队列，当具有相同最后一个值 key 值的新消息放入队列中时，丢弃队列中的消息。通过此行为，最后一个值队列只保留同一键消息的最后一个值。
如果发送到队列的消息被分页，则 last-value 队列无法按预期工作。为具有最后一个值队列为 DROP,BLOCK 或 FAIL 的地址设置 address-full-policy 参数的值，以确保发送到这些队列的消息不会被分页。如需更多信息，请参阅 第 7.2 节 “配置消息丢弃”。
最后一个值队列的简单用例是监控股票价格，其中只有特定库存的最新价值是值得关注的。
如果没有配置的最后一个值 key 的消息发送到最后一个值队列，代理会将此消息作为 "normal" 消息处理。当配置了最后一个值键到达的新消息时，此类消息不会从队列中清除。
您可以单独配置最后一个值队列，或为与一组地址关联的所有队列。
以下流程演示了如何以这些方式配置最后一个值队列。
4.11.1. 单独配置最后的值队列
以下流程演示了如何单独配置最后一个值队列。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于给定队列，添加
last-value-key键并指定自定义值。例如：<address name="my.address"> <multicast> <queue name="prices1" last-value-key="stock_ticker"/> </multicast> </address><address name="my.address"> <multicast> <queue name="prices1" last-value-key="stock_ticker"/> </multicast> </address>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 或者，您可以配置最后一个值队列，它使用默认值最后一个值键名称
_AMQ_LVQ_NAME。为此，请将last-value键添加到给定的队列中。将值设为true。例如：<address name="my.address"> <multicast> <queue name="prices1" last-value="true"/> </multicast> </address><address name="my.address"> <multicast> <queue name="prices1" last-value="true"/> </multicast> </address>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.11.2. 为地址配置最后的值队列
以下流程演示了如何为地址 或一组 地址配置最后的值队列。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
address-setting元素中，对于匹配地址，添加default-last-value-key。指定一个自定义值。例如：<address-setting match="lastValue"> <default-last-value-key>stock_ticker</default-last-value-key> </address-setting>
<address-setting match="lastValue"> <default-last-value-key>stock_ticker</default-last-value-key> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，与
lastValue地址关联的所有队列都使用最后一个值键stock_ticker。默认情况下，不会设置default-last-value-key的值。要为 一组 地址配置最后的值队列，您可以指定一个地址通配符。例如：
<address-setting match="lastValue.*"> <default-last-value-key>stock_ticker</default-last-value-key> </address-setting>
<address-setting match="lastValue.*"> <default-last-value-key>stock_ticker</default-last-value-key> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 或者，您可以将与地址 或一组 地址关联的所有队列配置为使用默认最后一个值键名称
_AMQ_LVQ_NAME。要做到这一点，请添加default-last-value-queue而不是default-last-value-key。将值设为true。例如：<address-setting match="lastValue"> <default-last-value-queue>true</default-last-value-queue> </address-setting>
<address-setting match="lastValue"> <default-last-value-queue>true</default-last-value-queue> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 有关配置地址时可以使用的通配符语法的更多信息，请参阅 第 4.2 节 “将地址设置应用到一组地址”。
4.11.3. 最后一个值队列行为示例
本例显示了最后一个值队列的行为。
在 broker.xml 配置文件中，假设您添加了类似以下内容的配置：
<address name="my.address">
<multicast>
<queue name="prices1" last-value-key="stock_ticker"/>
</multicast>
</address>
<address name="my.address">
<multicast>
<queue name="prices1" last-value-key="stock_ticker"/>
</multicast>
</address>
上述配置创建一个名为 prices1 的队列，其最后一个值为 stock_ticker。
现在，假设客户端发送两个消息。每个信息对于属性 stock_ticker 有相同的 ATN 值。每个消息都有一个不同的值，用于名为 stock_price 的属性。每个消息都发送到同一队列 prices1。
TextMessage message = session.createTextMessage("First message with last value property set");
message.setStringProperty("stock_ticker", "ATN");
message.setStringProperty("stock_price", "36.83");
producer.send(message);
TextMessage message = session.createTextMessage("First message with last value property set");
message.setStringProperty("stock_ticker", "ATN");
message.setStringProperty("stock_price", "36.83");
producer.send(message);TextMessage message = session.createTextMessage("Second message with last value property set");
message.setStringProperty("stock_ticker", "ATN");
message.setStringProperty("stock_price", "37.02");
producer.send(message);
TextMessage message = session.createTextMessage("Second message with last value property set");
message.setStringProperty("stock_ticker", "ATN");
message.setStringProperty("stock_price", "37.02");
producer.send(message);
当有两个对于 stock_ticker 最后值键（这里是 ATN）具有相同值的信息到达 prices1 queue 时，最有最后的信息会保留在队列中，第一个信息会被删除。在命令行中，您可以输入以下行来验证此行为：
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());在本例中，您看到的输出是第二条消息，因为这两个消息对最后一个值键使用相同的值，并在第一个值后在队列中收到第二个消息。
4.11.4. 为最后的值队列强制使用非破坏性
当消费者连接到队列时，通常的行为是发送到该消费者的消息由消费者专门获取。当消费者确认收到消息时，代理会从队列中删除消息。
作为正常消耗的替代方案，您可以将队列配置为强制实施 非破坏性 消耗。在这种情况下，当队列向消费者发送消息时，该消息仍然可以由其他使用者接收。此外，即使消费者已使用了该消息，消息也会保留在队列中。当您强制执行这种非破坏性消耗行为时，消费者被称为队列 浏览器。
强制非破坏性消耗是最后一个值队列的一个有用的配置，因为它可确保队列始终为特定最后的值键保存最新的值。
以下流程演示了如何为最后一个值队列强制实施非破坏性消耗。
先决条件
您已单独配置了最后一个值队列，或针对与地址 或一组 地址关联的所有队列。如需更多信息，请参阅：
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 如果您之前将队列配置为最后一个值队列，请添加
非破坏性键。将值设为true。例如：<address name="my.address"> <multicast> <queue name="orders1" last-value-key="stock_ticker" non-destructive="true" /> </multicast> </address><address name="my.address"> <multicast> <queue name="orders1" last-value-key="stock_ticker" non-destructive="true" /> </multicast> </address>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果您之前为最后一个值队列配置了地址 或一组 地址，请添加
default-non-destructive键。将值设为true。例如：<address-setting match="lastValue"> <default-last-value-key>stock_ticker </default-last-value-key> <default-non-destructive>true</default-non-destructive> </address-setting>
<address-setting match="lastValue"> <default-last-value-key>stock_ticker </default-last-value-key> <default-non-destructive>true</default-non-destructive> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意默认情况下，
default-non-destructive的值为false。
4.12. 将过期的消息移到过期地址
对于最后一个值队列以外的队列，如果您只有非破坏性消费者，代理永远不会从队列中删除消息，从而导致队列大小随时间增加。要防止这种不受限制的队列大小增长，您可以在消息过期时配置，并指定代理将过期信息发送到的地址。
4.12.1. 配置消息到期
以下流程演示了如何配置消息到期。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，设置message-expiry-scan-period以指定代理扫描过期消息的频率。<configuration ...> <core ...> ... <message-expiry-scan-period>1000</message-expiry-scan-period> ...<configuration ...> <core ...> ... <message-expiry-scan-period>1000</message-expiry-scan-period> ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据前面的配置，代理每 1000 毫秒扫描一次过期的消息。
在
address-setting元素中用于匹配地址 或一组 地址，指定到期地址。另外，设置消息过期时间。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow expiry-address-
匹配地址或地址的到期地址。在前面的示例中，代理将
库存地址的过期消息发送到名为ExpiryAddress的过期地址。 expiry-delay代理应用到 使用默认 过期时间的信息的过期时间（以毫秒为单位）。默认情况下，消息的过期时间为 0，这意味着它们没有过期。
对于大于默认值的过期时间的消息，expiry-delay无效。例如，假设您将地址上的
expiry-delay设置为10，如上例中所示。如果默认过期时间为0的消息到达这个地址的队列，则代理会将消息的过期时间从0改为10。但是，如果使用20过期时间的另一条消息，则其过期时间不会改变。如果将 expiry-delay 设为-1，则禁用此功能。默认情况下，expiry-delay设置为-1。
另外，您可以指定最小和最大过期延迟值，而不是为
expiry-delay指定一个值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow min-expiry-delay- 代理应用到消息的最小过期时间（以毫秒为单位）。
max-expiry-delay代理应用到消息的最大过期时间（以毫秒为单位）。
代理应用
min-expiry-delay和max-expiry-delay的值，如下所示：-
对于默认过期时间为
0的信息，代理会将过期时间设置为指定的值max-expiry-delay。如果您还没有为max-expiry-delay指定一个值，代理会将过期时间设置为min-expiry-delay的指定的值。如果您还没有为min-expiry-delay指定一个值，代理不会更改消息的过期时间。 -
对于超过
max-expiry-delay的值的过期时间，代理会将过期时间设置为指定的值max-expiry-delay。 -
对于低于
min-expiry-delay值的过期时间，代理会将过期时间设置为指定的min-expiry-delay值。 -
对于带有
min-expiry-delay和max-expiry-delay值之间的过期消息，代理不会更改消息的过期时间。 -
如果您为
expiry-delay指定一个值（即与默认值-1不同的值），这将覆盖您为min-expiry-delay和max-expiry-delay指定的值。 -
min-expiry-delay和max-expiry-delay的默认值为-1 （即 disabled）。
-
对于默认过期时间为
在配置文件的
addresses元素中，配置之前为expiry-address指定的地址。在此地址上定义一个队列。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的示例配置将到期队列
ExpiryQueue与到期地址ExpiryAddress关联。
4.12.2. 自动创建到期资源
常见的用例是根据原始地址隔离过期的消息。例如，您可以选择将过期的消息从名为来自名为 stocks 的地址路由到一个名为 EXP.stocks 的过期队列。同样，您可以将过期的消息从名为 order 的地址路由到名为 EXP.orders 的过期队列。
这种类型的路由模式可以轻松地跟踪、检查和管理过期消息。但是，这种模式很难在使用主要自动创建的地址和队列的环境中实现。在这种环境中，管理员不希望手动创建地址和队列来保存过期消息所需的额外工作。
作为解决方案，您可以将代理配置为自动创建资源（即地址和队列）来处理给定地址 或一组 地址的过期消息。以下流程演示了一个示例。
先决条件
- 您已为给定地址 或一组 地址配置了到期地址。更多信息请参阅 第 4.12.1 节 “配置消息到期”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 找到您之前添加到配置文件的 &
lt;address-setting> 元素，以定义匹配地址 或一组 地址的到期地址。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 &
lt;address-setting> 元素中，添加指示代理自动创建到期资源（即地址和队列）的配置项以及如何命名这些资源。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow auto-create-expiry-resources指定代理是否自动创建到期地址和队列来接收过期的消息。默认值为
false。如果参数值设置为
true，代理会自动创建一个 <address> 元素来定义到期地址和关联的到期队列。自动创建的 <address> 元素的name 值与为 指定的 name 值匹配<expiry-address>。自动创建的过期队列有
multicast路由类型。默认情况下，代理命名到期队列，以匹配最初发送过期消息的地址，如库存。代理还为使用
_AMQ_ORIG_ADDRESS属性的到期队列定义一个过滤器。此过滤器确保到期队列仅接收发送到相应原始地址的消息。expiry-queue-prefix代理应用到自动创建过期队列的名称的前缀。默认值为
EXP。当您定义前缀值或保留默认值时，到期队列的名称是前缀和原始地址（如
EXP.stocks）的连接。expiry-queue-suffix- 代理应用到自动创建的过期队列的名称的后缀。默认值没有定义（即，代理没有应用后缀）。
您可以自行使用队列名称（例如，使用 AMQ Broker Core Protocol JMS 客户端）或使用完全限定的队列名称（例如，使用另一个 JMS 客户端时）直接访问到期队列。
由于到期地址和队列会自动创建，与删除自动创建的地址和队列相关的所有地址设置也适用于这些到期资源。
其他资源
- 有关用于配置自动创建的地址和队列的地址设置的更多信息，请参阅 第 4.8.2 节 “配置自动创建和删除地址和队列”。
4.13. 将未发送的消息移到死信地址
如果向客户端发送消息失败，您可能不希望代理持续尝试发送消息。为防止无限的尝试，您可以定义一个死信地址，以及一个或多个相关的死信队列。在进行了指定数量的发送尝试后，代理会从其原始队列中删除未发送的消息，并将消息发送到配置的死信地址。系统管理员稍后会消耗来自死信队列的未发送消息，以检查消息。
如果您没有为给定队列配置死信地址，代理会在指定次数尝试后从队列永久删除未发送的消息。
取消发送来自死信队列使用的消息具有以下属性：
_AMQ_ORIG_ADDRESS- 指定消息原始地址的字符串属性
_AMQ_ORIG_QUEUE- 指定消息原始队列的字符串属性
4.13.1. 配置死信地址
以下步骤演示了如何配置死信地址和关联的死信队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在与队列名称匹配的 &
lt;address-setting> 元素中，为死信地址名称和发送尝试次数设置值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow match-
代理在此
address-setting部分中应用配置的地址。您可以为 <address-setting> 元素的match属性指定通配符表达式。如果您希望将<address-setting>项中配置的死信设置与一组地址相匹配，可以使用通配符表达式。 dead-letter-address- 死信地址的名称。在本例中，代理将未发送的消息从队列 exampleQueue 移到死信地址 DLA。
max-delivery-attempts-
代理在将未发送消息移到配置的死信地址之前，代理进行的最大发送尝试数。在本例中，代理会在 3 次失败发送尝试后将未发送的消息移到死信地址。默认值为
10。如果您希望代理发出无限数量的重新发送尝试，请指定 1值。
在
addresses部分中，为死信地址 DLA 添加address元素。要将死信队列与死信地址关联，请为队列指定一个名称值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
在前面的配置中，您将名为 DLQ 的死信队列与死信地址 DLA 关联。
其他资源
- 有关在地址设置中使用通配符的详情，请参考 第 4.2 节 “将地址设置应用到一组地址”。
4.13.2. 自动创建死信队列
常见的用例是根据原始地址隔离未发送的消息。例如，您可以选择将来自 stocks 的未被成功发送的消息路由到一个名为 DLA.stocks 的队列，它有一个相关的名为 DLQ.stocks 的死信队列。同样，您可以将未发送的消息从名为 orders 的地址路由到一个名为 DLA.orders的死信地址。
这种类型的路由模式可以轻松地跟踪、检查和管理未发送的消息。但是，这种模式很难在使用主要自动创建的地址和队列的环境中实现。对于此类环境，系统管理员可能不希望手动创建地址和队列来保持未发送消息所需的额外工作。
作为解决方案，您可以将代理配置为自动创建地址和队列来处理未发送的消息，如以下步骤所示。
先决条件
- 您已为队列或一组队列配置了死信地址。更多信息请参阅 第 4.13.1 节 “配置死信地址”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 找到您之前添加的 <
;address-setting> 元素，为匹配的队列或一组队列定义死信地址。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在
<address-setting> 元素中，添加指示代理自动创建死信资源（即地址和队列）的配置项目以及如何命名这些资源。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow auto-create-dead-letter-resources指定代理是否自动创建死信地址和队列来接收未发送的消息。默认值为
false。如果
auto-create-dead-letter-resources设为true，代理会自动创建一个定义死信地址和关联的死信队列的 <address> 元素。自动创建的 <address> 元素的名称与您为 <dead-letter-address> 指定的名称值匹配。代理在自动创建的 <address> 元素
中定义的死信队列具有multicast路由类型。默认情况下，代理将死信队列命名为与未发送消息的原始地址匹配，例如stocks。代理还为使用
_AMQ_ORIG_ADDRESS属性的死信队列定义一个过滤器。此过滤器确保死信队列仅接收发送到相应原始地址的消息。dead-letter-queue-prefix代理应用到自动创建的死信队列的名称的前缀。默认值为
DLQ。当您定义前缀值或保留默认值时，死信队列的名称是前缀和原始地址（如
DLQ.stocks）的连接。dead-letter-queue-suffix- 代理应用到自动创建的死信队列的后缀。默认值没有定义（即，代理没有应用后缀）。
4.14. 过期或未发送 AMQP 消息上的注解和属性
在代理将过期或未发送 AMQP 消息移至您配置的过期或死信队列之前，代理会将注解和属性应用到消息。客户端可以根据这些属性或注解创建过滤器，以选择特定消息以从到期或死信队列中消耗。
代理应用的属性是 内部 属性。这些属性不会公开给客户端供常规使用，但 可以被 过滤器中的客户端指定。
下表显示了代理应用到过期或未发送 AMQP 消息的注解和内部属性。
| 注解名称 | 内部属性名称 | 描述 |
|---|---|---|
| x-opt-ORIG-MESSAGE-ID | _AMQ_ORIG_MESSAGE_ID | 原始消息 ID，在消息移到到期或死信队列之前。 |
| x-opt-ACTUAL-EXPIRY | _AMQ_ACTUAL_EXPIRY | 消息到期时间，指定自上次 epoch 开始以来的毫秒数。 |
| x-opt-ORIG-QUEUE | _AMQ_ORIG_QUEUE | 过期或未发送消息的原始队列名称。 |
| x-opt-ORIG-ADDRESS | _AMQ_ORIG_ADDRESS | 过期或未发送消息的原始地址名称。 |
其他资源
- 有关将 AMQP 客户端配置为根据注解过滤 AMQP 消息的示例，请参阅 第 13.3 节 “根据注解上的属性过滤 AMQP 消息”。
4.15. 禁用队列
如果您在代理配置中手动定义队列，则默认启用队列。
但是，在有些情况下，您可能需要定义一个队列，以便客户端可以订阅它，但无法准备好将队列用于消息路由。或者，在有些情况下，您可能希望停止到队列的消息流，但仍然保持客户端绑定到队列。在这些情况下，您可以禁用队列。
以下示例演示了如何禁用您在代理配置中定义的队列。
先决条件
- 您应该熟悉如何在代理配置中定义地址和相关队列。更多信息请参阅 第 4 章 配置地址和队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您之前定义的队列，添加
enabled属性。要禁用队列，请将此属性的值设置为false。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow enabled属性的默认值为true。当您将值设为false时，到队列的消息路由被禁用。
如果您禁用地址 上的所有 队列，发送到那个地址的任何消息都会被静默丢弃。
4.16. 限制连接到队列的用户数量
使用 max-consumers 属性限制连接到特定队列的用户数量。通过将 max-consumers 标志设置为 1 来创建专用消费者。默认值为 -1，这会设置无限数量的消费者。
以下流程演示了如何对可以连接到队列的用户数量设置限制。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于给定队列，添加
max-consumers键并设置值。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，只有 20 个使用者可以同时连接到队列
q3。若要创建专用消费者，请将
max-consumers设置为1。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要允许无限数量的使用者，请将
max-consumers设置为-1。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.17. 配置专用队列
专用队列是特殊的队列，每次将所有消息路由到一个消费者。当您希望所有消息被同一消费者按顺序处理时，此配置很有用。如果某个队列有多个消费者，则只有一个消费者将接收消息。如果该消费者与队列断开连接，则会选择另一个消费者。
4.17.1. 单独配置专用队列
以下流程演示了如何将给定队列单独配置为 exclusive。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于给定队列，添加
exclusive键。将值设为true。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.17.2. 为地址配置专用队列
以下步骤演示了如何配置地址 或一组 地址，以便所有关联的队列都是独占的。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
address-setting元素中，对于匹配地址，添加default-exclusive-queue键。将值设为true。<address-setting match="myAddress"> <default-exclusive-queue>true</default-exclusive-queue> </address-setting><address-setting match="myAddress"> <default-exclusive-queue>true</default-exclusive-queue> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，所有与
myAddress地址关联的队列都是独占的。默认情况下，default-exclusive-queue的值为false。要为 一组 地址配置专用队列，您可以指定一个地址通配符。例如：
<address-setting match="myAddress.*"> <default-exclusive-queue>true</default-exclusive-queue> </address-setting><address-setting match="myAddress.*"> <default-exclusive-queue>true</default-exclusive-queue> </address-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 有关配置地址时可以使用的通配符语法的更多信息，请参阅 第 4.2 节 “将地址设置应用到一组地址”。
4.18. 将特定地址设置应用到临时队列
例如，在使用 JMS 时，代理通过将通用唯一标识符(UUID)分配为地址名称和队列名称来创建 临时队列。
默认的 <address-setting match="#"> 会将配置的地址设置应用到所有队列，包括临时队列。如果只想将特定的地址设置应用到临时队列，您可以选择指定 temporary-queue-namespace，如下所述。然后，您可以指定与命名空间匹配的地址设置，代理会将这些设置应用到所有临时队列。
当临时队列被创建且临时队列命名空间存在时，代理会将 temporary-queue-namespace 值和配置的分隔符（默认 .）添加到地址名称。它使用它来引用匹配的地址设置。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加
temporary-queue-namespace值。例如：<temporary-queue-namespace>temp-example</temporary-queue-namespace>
<temporary-queue-namespace>temp-example</temporary-queue-namespace>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加一个
address-setting元素，其match值与临时队列命名空间对应。例如：<address-settings> <address-setting match="temp-example.#"> <enable-metrics>false</enable-metrics> </address-setting> </address-settings><address-settings> <address-setting match="temp-example.#"> <enable-metrics>false</enable-metrics> </address-setting> </address-settings>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 这个示例禁用代理创建的所有临时队列中的指标。
注意指定临时队列命名空间不会影响临时队列。例如，命名空间不会更改临时队列的名称。命名空间用于引用临时队列。
其他资源
- 有关在地址设置中使用通配符的详情，请参考 第 4.2 节 “将地址设置应用到一组地址”。
4.19. 配置环队列
通常，AMQ Broker 中的队列使用第一in、第一出(FIFO)语义。这意味着代理将消息添加到队列的尾部，并将它们从头中删除。环队列是特殊的队列类型，包含指定的固定数量的消息。当新消息到达但队列已包含指定数量时，代理会删除队列头的消息来维护固定队列大小。
例如，假设一个环队列配置的大小为 3 和生成者，按顺序发送消息 A、B、C 和 D。消息 C 到达队列后，队列中的消息数量已达到配置的环大小。此时，消息 A 位于队列的头部，而消息 C 则位于尾部。当消息 D 到达队列时，代理会将消息添加到队列的尾部。要维护固定的队列大小，代理会在队列头删除消息（即消息 A）。消息 B 现在位于队列的头部。
4.19.1. 配置环队列
以下步骤演示了如何配置环队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 要在不匹配地址上为没有设置显式环大小的所有队列定义默认环大小，请在
address-setting元素中为default-ring-size指定一个值。例如：<address-settings> <address-setting match="ring.#"> <default-ring-size>3</default-ring-size> </address-setting> </address-settings><address-settings> <address-setting match="ring.#"> <default-ring-size>3</default-ring-size> </address-setting> </address-settings>Copy to Clipboard Copied! Toggle word wrap Toggle overflow default-ring-size参数对于定义自动创建队列的默认大小特别有用。default-ring-size的默认值为-1 (即没有大小限制)。要在特定队列中定义环大小，请将
ring-size键添加到queue元素。指定一个值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
您可以在代理运行时更新 ring-size 的值。代理会动态应用更新。如果新的 ring-size 值低于先前值，代理不会立即从队列的头部删除消息，以强制实施新大小。发送到队列的新消息仍强制删除旧的消息，但队列不会达到其新的、缩减的大小，直到其自然地通过客户端正常使用消息。
4.19.2. 环队列故障排除
本节描述了环队列的行为与其配置不同的情况。
发送的消息和回滚
当消息发送到消费者时，消息处于"in-between"状态，其中消息在技术上不再在队列中，但尚未确认。消息会一直处于 in-delivery 状态，直到被消费者确认。处于 in-delivery 状态的消息无法从环队列中删除。
由于代理无法删除 in-delivery 消息，因此客户端可以将比环队列所允许的更多消息发送到环队列。例如，请考虑以下情况：
-
生产者将三个消息发送到配置了
ring-size="3"的环队列。 所有消息都会立即分配给消费者。
此时，
messageCount=3和 deliverCount=3。生产者向队列发送另一条消息。然后，将消息分配给消费者。
现在，
messageCount=4和deliverCount=4。消息计数为4大于配置的环大小3。但是，代理会义务来允许这种情况，因为它无法从队列中删除发送的消息。现在，假设消费者在不确认任何消息的情况下关闭。
在这种情况下，四个在发送中，未确认的消息将被取消回代理，并按它们所消耗的相反顺序添加到队列头。此操作会使队列超出其配置的环大小。由于环队列更喜欢队列尾部的消息，该队列会丢弃生成者发送的第一个消息，因为这是最后一个消息添加到队列的头。事务或核心会话回滚以同样的方式处理。
如果您直接使用核心客户端，或使用 AMQ Core Protocol JMS 客户端，您可以通过减少 consumerWindowSize 参数的值（默认为 1024 * 1024 字节）来最小化传输的消息数量。
调度的消息
当计划的消息发送到队列时，该消息不会立即添加到队列尾部，如正常消息。相反，代理将调度的消息保存在中间缓冲区中，并根据消息的详情将消息调度到队列的头部。但是，调度的消息仍然反映在队列的消息计数中。与 in-delivery 消息一样，此行为可能会使代理没有强制执行环队列大小。例如，请考虑以下情况：
在 12:00，生成者将消息
A发送到配置了ring-size="3"的环队列。该消息被调度为 12:05。此时，
messageCount=1和scheduledCount=1。在 12:01，生成者将消息
B发送到同一环队列。now,
messageCount=2和scheduledCount=1。在 12:02 时，生成者将消息
C发送到同一环队列。现在，
messageCount=3和scheduledCount=1。at 12:03, producer 将消息
D发送到同一环队列。现在，
messageCount=4和scheduledCount=1。队列的消息计数现在为
4，一个大于 配置的环大小3。但是，计划的消息还没有在技术上在队列中（即，它位于代理中并计划放置到队列中）。在预定的 12:05 时，代理会将消息放在队列的头部。但是，由于环队列已达到其配置大小，因此调度的消息A会立即被删除。
paged 信息
与发送中的调度消息和消息类似，页面的消息不计到代理强制执行的环队列大小，因为消息实际上是在地址级别上页面，而不是队列级别。页面的消息在技术上并非从技术上进行，尽管消息反映在队列的 messageCount 值中。
建议您不要将分页用于带有环队列的地址。相反，请确保整个地址可以适合内存。或者，将 address-full-policy 参数配置为 DROP, BLOCK 或 FAIL。
其他资源
- 当您配置 retroactive 地址时，代理会创建环队列的内部实例。如需更多信息，请参阅 第 4.20 节 “配置被动地址”。
4.20. 配置被动地址
将地址配置为 retroactive 可让您保留发送到该地址的消息，包括没有队列绑定到该地址时。当队列稍后创建并绑定到地址时，代理会主动将消息分发到这些队列。如果地址 没有配置为 retroactive，且还没有绑定到它的队列，代理会丢弃发送到该地址的消息。
当您配置 retroactive 地址时，代理会创建一个内部实例，它称为 环队列。环队列是特殊的队列类型，包含指定的固定数量的消息。队列达到指定大小后，到达队列的下一消息会强制从队列中最旧的消息。当您配置 retroactive 地址时，您可以间接指定内部环队列的大小。默认情况下，内部队列使用 multicast 路由类型。
由 retroactive 地址使用的内部环队列通过管理 API 公开。您可以检查指标并执行其他常见管理操作，如清空队列。环队列也贡献了地址的总内存用量，这会影响消息分页等行为。
以下流程演示了如何将地址配置为 retroactive。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 为
address-setting元素中的retroactive-message-count参数指定一个值。您指定的值定义您希望代理保留的消息数量。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意您可以在代理运行时，在
broker.xml配置文件或管理 API 中更新retroactive-message-count的值。但是，如果您 降低 此参数的值，则需要额外步骤，因为 retroactive 地址通过环队列实施。降低ring-size参数的环队列不会自动从队列中删除消息，以达到新的ring-size值。此行为是防止意外消息丢失的保护。在这种情况下，您需要使用管理 API 来手动减少环队列中的消息数量。
其他资源
- 有关环队列的更多信息，请参阅 第 4.19 节 “配置环队列”。
4.21. 为内部管理的地址和队列禁用公告消息
默认情况下，当 OpenWire 客户端连接到代理时，AMQ Broker 会创建有关地址和队列的公告信息。公告信息发送到代理创建的内部管理地址。这些地址会出现在与用户部署的地址和队列相同的 AMQ 管理控制台中。虽然它们提供了有用的信息，当代理管理大量目的地时，公告信息可能会导致不必要的后果。例如，消息可能会增加内存用量或压力连接资源。另外，当尝试显示所有为发送公告消息创建的地址时，AMQ 管理控制台可能会变得冲突。为避免这种情况，您可以使用以下参数来配置代理上公告消息的行为。
supportAdvisory-
将这个选项设置为
true以启用创建公告信息或false来禁用它们。默认值为true。 suppressInternalManagementObjects-
将这个选项设置为
true，将公告信息公开给管理服务，如 JMX registry 和 AMQ Management Console，或false（不公开它们）。默认值为true。
以下流程演示了如何在代理中禁用公告信息。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于 OpenWire 连接器，将
supportAdvisory和suppressInternalManagementObjects参数添加到配置的 URL。按照本节前面所述设置值。例如：<acceptor name="artemis">tcp://127.0.0.1:61616?protocols=CORE,AMQP,OPENWIRE;supportAdvisory=false;suppressInternalManagementObjects=false</acceptor>
<acceptor name="artemis">tcp://127.0.0.1:61616?protocols=CORE,AMQP,OPENWIRE;supportAdvisory=false;suppressInternalManagementObjects=false</acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.22. 迭代地址和队列
联邦支持在代理间传输消息，而无需代理位于通用集群中。代理可以独立，也可以在单独的集群中。另外，源和目标代理可以位于不同的管理域中，这意味着代理可能具有不同的配置、用户和安全设置。代理甚至可能会使用不同的 AMQ Broker 版本。
例如，联邦适合将信息从一个集群可靠地发送到另一个集群。这种传输可能会跨越广域网(WAN)、云基础架构的区域或互联网。如果从源代理连接到目标代理会丢失（例如，由于网络故障），则源代理会尝试重新建立连接，直到目标代理重新在线为止。当目标代理重新上线时，消息传输会恢复。
管理员可以使用地址和队列策略来管理联邦。策略配置可以匹配到特定的地址或队列，或者策略可以包含与一组地址或队列匹配的通配符表达式。因此，联邦可以动态应用，作为队列或地址被添加到匹配集合中，或从匹配的集合中删除。策略 可以包含多个 表达式，其中包括 和/或排除特定地址和队列。另外，多个策略可应用到代理或代理集群。
在 AMQ Broker 中，两个主要的联邦选项是 address federation 和 queue federation。这些选项在后续小节中进行了描述。
代理可以包含联邦 和 仅本地组件的配置。也就是说，如果您在代理中配置联邦，则不需要联合该代理上的所有内容。
4.22.1. 关于地址联邦
地址联邦类似于连接的代理之间的完整多播分布模式。例如，发送到 BrokerA 上地址的每个消息都传送到该代理上的每个队列。另外，每个信息都会传送到 BrokerB，所有附加队列都会被发送。
地址联邦动态将代理链接到远程代理中的地址。例如，如果本地代理希望从远程代理上的地址获取信息，则会在远程地址上自动创建队列。然后，远程代理上的消息会应用到此队列。最后，消息被复制到本地代理上的对应地址，因为它们最初直接发布到本地地址。
远程代理不需要重新配置，以允许联邦在其上创建地址。但是，本地 代理需要为远程地址授予权限。
4.22.2. 地址联邦的通用拓扑
下面介绍了一些使用地址联邦的拓扑。
- 对称拓扑
在对称拓扑中，生成者和消费者连接到每个代理。队列及其消费者可以接收由任一制作者发布的消息。对称拓扑的示例如下所示：
图 4.5. 在对称拓扑中的地址联邦
为对称拓扑配置地址联邦时，必须将地址策略的
max-hops属性的值设置为1。这样可确保 仅复制一次 消息，避免了循环复制。如果此属性设置为较大的值，则消费者将接收同一消息的多个副本。- 完整网格拓扑
完整的网格拓扑与对称设置类似。三个或者多个代理相互连接，从而创建一个完整的网格。在这个设置中，生成者和消费者连接到每个代理。队列及其消费者可以接收任何制作者发布的消息。此拓扑示例如下所示。
图 4.6. 在完整网格拓扑中地址联邦
与对称设置一样，当为完整网格拓扑配置地址联邦时，务必要将地址策略的
max-hops属性的值设置为1。这样可确保 仅复制一次 消息，避免了循环复制。- Ring 拓扑
在代理环中，每个联邦地址仅在环中只是另一个地址。此拓扑示例如下所示。
图 4.7. 在环拓扑中的地址联邦
当您为环拓扑配置联邦时，为了避免 cyclic 复制，务必要将地址策略的
max-hops属性设置为n-1的值，其中 n 是环中节点的数量。例如，在上面显示的环拓扑中，max-hops的值设为5。这样可确保环中的每个地址都会 精确看到消息一次。环拓扑的优点在于，根据您需要进行的物理连接数，它更便宜。但是，这种类型的拓扑的缺陷在于，如果单个代理失败，则整个环会失败。
- fan-out 拓扑
在 fan-out 拓扑中，单个主地址由联邦地址树链接。发布到主地址的任何消息都可以被连接到树中的任何代理接收。树可以配置为任何深度。树也可扩展，无需在树中重新配置现有代理。此拓扑示例如下所示。
图 4.8. 在 fan-out 拓扑中处理联邦
当您为 fan-out 拓扑配置联邦时，请确保将地址策略的
max-hops属性设置为n-1的值，其中 n 是树中的级别数。例如，在上面显示的 fan-out 拓扑中，max-hops的值设置为2。这可确保树中的每个地址都会 精确看到消息一次。
4.22.3. 支持在地址联邦配置中分离绑定
在配置地址联邦时，您可以在地址策略配置中添加对 divert 绑定的支持。添加此支持可让联邦响应分离绑定，以便为远程代理上的给定地址创建联邦消费者。
例如，假设地址策略中包含了一个名为 test.federation.source 的地址，并且不包括另一个名为 test.federation.target 的地址。通常，当一个队列在 test.federation.target 上创建，不会导致创建联邦消费者，因为地址不是地址策略的一部分。但是，如果您创建一个 divert 绑定，使得 test.federation.source 是源地址，test.federation.target 是转发地址，则会在转发地址处创建一个持久消费者。源地址仍然必须使用 multicast 路由类型，但目标地址可以使用 multicast 或 anycast。
示例用例是将 JMS 主题(多播地址 )重定向到 JMS 队列（任播地址）的 divert。这可实现传统消费者不支持 JMS 2.0 和共享订阅的主题上消息的负载平衡。
4.22.4. 配置联邦
您可以使用 Core 协议或从 7.12、AMQP 开始配置地址和队列联合。使用 AMQP 进行联邦提供以下优点：
- 如果客户端使用 AMQP 进行消息传递，使用 AMQP 进行联邦消除了在 AMQP 和核心协议之间转换消息的需求，反之亦然，如果联邦使用 Core 协议，则需要它。
- AMQP 联邦支持在单个传出连接上双向联合。这消除了远程代理需要重新连接到本地代理的需求，这是当您使用 Core 协议进行联邦时的要求，网络策略可能会阻止它们。
4.22.4.1. 使用 AMQP 配置联邦
您可以使用以下策略来使用 AMQP 配置地址和队列联邦：
- 本地地址策略将本地代理配置为监视对地址的需求，并在该需求存在时，在远程代理上的匹配地址上创建一个联合消费者，以联合信息到本地代理。
- 远程地址策略将远程代理配置为监视地址的需求，并在该需求存在时，在本地代理上的匹配地址上创建一个联合消费者，来联合远程代理的消息。
- 本地队列策略将本地代理配置为监视队列的需求，并在该需求存在时，在远程代理上的匹配队列上创建联合消费者，以联合消息到本地代理。
- 远程队列策略将远程代理配置为监视队列的需求，并在该需求存在时，在本地代理上的匹配队列上创建一个联合消费者，以联合消息到远程代理。
远程地址和队列策略发送到远程代理，并在远程代理中成为本地策略，以提供反向联邦连接。在为反向联邦连接应用策略时，接收策略的代理是本地代理，发送策略的代理是远程代理。通过在本地代理中配置远程地址和队列策略，您可以在单个代理上保留所有联邦配置，例如，这可能是 hub 和spoke 拓扑的一个有用方法。
4.22.4.1.1. 使用 AMQP 配置地址联邦
使用 & lt;broker-connections& gt; 元素使用 AMQP 配置地址联邦。
前提条件
< amqp-connection> 元素中指定的用户具有匹配远程代理上的地址和队列的读写权限。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加包含 &
lt;元素。在 &amqp-connection> 元素的 <broker connections>lt;amqp-connection> 元素中，指定远程代理的连接详情，并为联邦配置分配一个名称。例如：<broker-connections> <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example"> </amqp-connection> </broker-connections>
<broker-connections> <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example"> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加 &
lt;federation> 元素，并包括以下内容之一：-
一个
<local-address-policy> 元素，用于联合来自远程代理的信息到本地代理。 -
&
lt;remote-address-policy> 元素用于联邦来自本地代理的信息到远程代理。
以下示例显示了带有本地和远程地址策略的联邦元素。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 同一参数可以在本地和远程地址策略中配置。有效参数有：
- name
-
地址策略的名称。所有地址策略名称必须在 <
broker-connections> 元素中的 <federation> 元素内唯一。 - max-hops
-
消息在联邦期间可以进行的最大跃点数。默认值
0适合大多数简单的联邦部署。但是，在某些拓扑中，可能需要更大的值来防止消息循环。 - auto-delete
-
对于地址联邦，会在代理上创建持久化队列，其中消息被联邦。将此参数设置为 true，以在启动代理断开连接后标记自动删除的队列，并满足延迟和消息计数参数。如果要自动清理动态创建的队列，这个选项是一个有用的选项。默认值为
false，这意味着队列不会被自动删除。 - auto-delete-delay
-
在启动代理断开连接后，创建队列有资格自动删除前的时间（毫秒）。默认值为
0。 - auto-delete-message-count
-
队列的消息计数必须小于或等于队列之前，才能自动删除队列。默认值为
0。 - enable-divert-bindings
-
将 设置为
true可让 divert 绑定被侦听。如果地址的 divert 绑定与地址策略包含的地址匹配，则任何与 divert 的转发地址匹配的队列绑定都会创建需求。默认值为false。 - Include
匹配策略中要包含的地址的地址的匹配模式。您可以指定多个模式。如果没有指定模式，则策略中的所有地址都包含在策略中。
您可以指定一个准确的地址，如
queue.bbc.news。或者，您可以使用数字符号(TALM)通配符字符来指定匹配的地址集合。在前面的示例中，本地地址策略还包含以queue.news字符串开头的所有地址。- exclude
匹配从策略中排除的地址的地址匹配模式。您可以指定多个模式。如果没有指定模式，策略中没有包括任何地址。
您可以指定一个准确的地址，如
queue.bbc.news。或者，您可以使用数字符号(TALM)通配符字符来指定匹配的地址集合。在前面的示例中，本地地址策略排除以queue.news.sport字符串开头的所有地址。
-
一个
4.22.4.1.2. 使用 AMQP 配置队列联邦
流程
使用 & lt;broker connections& gt; 元素为 AMQP 配置队列联邦。
前提条件
< amqp-connection> 元素中指定的用户具有匹配远程代理上的地址和队列的读写权限。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加包含 &
lt;元素。在 &amqp-connection> 元素的 <broker connections>lt;amqp-connection> 元素中，指定远程代理的连接详情，并为联邦配置分配一个名称。例如：<broker-connections> <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example"> </amqp-connection> </broker-connections>
<broker-connections> <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example"> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加 &
lt;federation> 元素，并包括以下内容之一：-
一个
<local-queue-policy> 元素来联邦来自远程代理的信息到本地代理。 -
&
lt;remote-queue-policy> 元素用于联邦来自本地代理的信息到远程代理。
以下示例显示了包含本地队列策略的联邦元素。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - name
-
队列策略的名称。所有队列策略名称必须在 <
broker-connections> 元素的 <federation> 元素内唯一。 - Include
-
匹配地址和队列匹配模式的地址匹配模式，以匹配这些地址上的特定队列，以包含在策略中。与address-match参数一样，您可以为queue-match参数指定一个准确的名称，或者您可以使用通配符表达式来指定一组队列。在上例中，包含在所有地址间与.remote字符串匹配的队列（由地址匹配值#表示）。 - exclude
-
用于匹配地址和队列匹配模式的地址匹配模式，以匹配这些地址上的特定队列，以便从策略中排除。与address-match参数一样，您可以为queue-match参数指定一个准确的名称，或者您可以使用通配符表达式来指定一组队列。在上例中，排除在所有地址间与.local字符串匹配的队列（由地址匹配值#表示）被排除。 - priority-adjustment
-
调整联合消费者的值，以确保它们的优先级低于同一队列上的其他本地用户。默认值为
-1，这样可确保本地消费者的优先级高于联邦消费者。 - include-federated
当此参数的值设置为
false时，配置不会重新联邦已经被联邦的消费者（即联邦队列中的消费者）。这可避免发生在对称或闭环拓扑中，没有非联邦消费者和系统间的消息流。如果您没有闭循环拓扑，您可以将此参数的值设置为
true。例如，假设您有三个代理链： BrokerA、BrokerB 和 BrokerC，带有生成者位于 BrokerA 和位于 BrokerC 的消费者。在这种情况下，您希望 BrokerB 重新联邦消费者到 BrokerA。
-
一个
4.22.4.2. 使用核心协议配置联邦
您可以将消息和队列联邦配置为使用 Core 协议。
4.22.4.2.1. 为代理集群配置联邦
以下部分中的示例演示了如何配置 独立 本地和远程代理之间的地址和队列联邦。对于独立代理（联邦配置的名称以及任何地址和队列策略的名称）之间的联邦，本地代理和远程代理之间必须是唯一的。
但是，如果您要在集群中为代理配置联邦，则需要额外的要求。对于集群代理，联邦配置的名称以及该配置中的任何地址和队列策略的名称，对于该集群中的每个代理都必须相同。
确保同一集群中的代理使用相同的联邦配置和地址和队列策略名称，避免消息重复。例如，如果同一集群中的代理 有不同的 联邦配置名称，这可能会导致为同一地址创建多个不同命名的转发队列，从而导致下游消费者的消息重复。相反，如果同一集群中的代理 使用相同的 联邦配置名称，这基本上会创建复制的集群转发队列，这些队列对下游用户进行负载平衡。这可避免消息重复。
4.22.4.2.2. 配置上游地址联邦
以下示例演示了如何在独立代理之间配置上游地址联邦。在本例中，您要将本地（即 下游）代理中的联邦配置为一些远程（即 上游）代理。
先决条件
- 以下示例演示了如何配置独立代理间的地址联邦。但是，您还应熟悉为代理 集群配置 联邦的要求。更多信息请参阅 第 4.22.4.2.1 节 “为代理集群配置联邦”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加新的 <
federations>元素，其中包含 <federation>元素。例如：<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>Copy to Clipboard Copied! Toggle word wrap Toggle overflow name- 联邦配置的名称。在本例中，名称对应于本地代理的名称。
user- 用于与上游代理连接的共享用户名。
password- 用于与上游代理连接的共享密码。
注意如果远程代理的用户和密码凭证不同，您可以在将代理添加到配置中时为这些代理单独指定凭证。此流程稍后将对此进行说明。
在
federation元素中，添加一个 <address-policy>元素。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow name- 地址策略的名称。在代理中配置的所有地址策略都必须具有唯一的名称。
auto-delete-
在地址联邦过程中，本地代理会在远程地址上动态创建持久队列。
auto-delete属性的值指定在本地代理断开连接后队列是否应该被删除，auto-delete-delay和auto-delete-message-count属性的值也已达到。如果要自动清理动态创建的队列，这个选项是一个有用的选项。如果要防止本地代理长时间断开连接，则在远程代理上构建消息时，它也是一个有用的选项。但是，如果您希望消息在断开连接时始终为本地代理保持排队，则可能会将这个选项设置为false，以避免本地代理中的消息丢失。 auto-delete-delay- 本地代理断开连接后，此属性的值指定动态创建远程队列有资格自动删除的时间长度（以毫秒为单位）。
auto-delete-message-count- 本地代理断开连接后，此属性的值指定在该队列有资格自动删除前仍然处于动态创建远程队列中的最大消息数。
enable-divert-bindings-
将此属性设置为
true可让 divert 绑定被侦听。如果存在与地址策略包含地址匹配的地址的 divert 绑定，则与 divert 的转发地址匹配的队列绑定都将创建需求。默认值为false。 max-hops- 消息在联邦期间可以进行的最大跃点数。特定的拓扑需要此属性的特定值。要了解更多有关这些要求的信息，请参阅 第 4.22.2 节 “地址联邦的通用拓扑”。
transformer-ref- 转换器配置的名称。如果要在联邦消息传输过程中转换消息，您可以添加转换器配置。此流程稍后会描述转换器配置。
在 <
;address-policy> 元素中，添加 address-matching 模式，以便从地址策略包含和排除地址。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Include-
此元素的
address-match属性的值指定要包含在地址策略中的地址。您可以指定一个准确的地址，如queue.bbc.new或queue.usatoday。或者，您可以使用通配符表达式来指定匹配的地址 集合。在前面的示例中，地址策略还包含以字符串queue.news开头的所有 地址名称。 exclude-
此元素的
address-match属性的值指定要从地址策略中排除的地址。您可以指定一个准确的地址名称，或使用通配符表达式来指定匹配的地址 集合。在前面的示例中，地址策略排除以字符串queue.news.sport开头的所有 地址名称。
（可选）在
federation元素中，添加一个transformer元素来引用自定义转换器实施。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow name-
转换器配置的名称。此名称在本地代理中必须是唯一的。这是您指定为地址策略的
transformer-ref属性的值的名称。 class-name实施
org.apache.activemq.artemis.core.server.transformer.Transformer接口的用户定义类的名称。在传输消息前，通过消息调用转换器的
transform （）方法。这可让您在联邦前转换消息标头或正文。属性- 用于保存特定转换器配置的键值对。
在
federation元素内，添加一个或多个上游元素。每个upstream元素定义到远程代理的连接，以及要应用到该连接的策略。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow static-connectors-
包含
connector-ref元素列表，该元素引用本地代理的broker.xml配置文件中定义的连接器元素。连接器定义用于传出连接的传输(TCP、SSL、HTTP 等)和服务器连接参数（主机、端口等）。此流程的下一步演示了如何添加static-connectors元素中引用的连接器。 policy-ref- 在应用到上游代理的下游代理上配置的地址策略的名称。
您可以为
上游元素指定的附加选项如下所述：name-
上游代理配置的名称。在本例中，名称对应于名为
eu-east-1和eu-west-1的上游代理。 user-
创建与上游代理的连接时使用的用户名。如果没有指定，则使用在
federation元素配置中指定的共享用户名。 password-
创建与上游代理的连接时使用的密码。如果没有指定，则使用
联邦元素配置中指定的共享密码。 call-failover-timeout-
与
call-timeout类似，但在故障转移尝试期间调用时使用。默认值为-1，这意味着禁用超时。 call-timeout-
当联邦连接传输一个阻塞调用的数据包时，联邦连接会等待来自远程代理的回复。如果此时间过，连接会抛出异常。默认值为
30000。 check-period-
周期（以毫秒为单位）在本地代理发送到远程代理时连续的"keep-alive"消息之间检查联邦连接的健康状态。如果联邦连接健康，远程代理会响应每个 keep-alive 信息。如果连接不健康，则下游代理无法从上游代理接收响应，则使用名为 断路器 的机制来阻止联邦用户。如需更多信息，请参阅
circuit-breaker-timeout参数的描述。check-period参数的默认值为30000。 circuit-breaker-timeout- 下游和上游代理之间的单个连接可能由许多联合队列和地址消费者共享。如果代理之间的连接丢失，每个联邦消费者可能会尝试同时重新连接。为避免这种情况，称为 断路器 的机制会阻止消费者。当指定的超时值过后，断路器会重新尝试连接。如果成功，用户就会取消阻塞。否则，断路器再次应用。
connection-ttl-
如果联邦连接停止从远程代理接收信息，则联邦连接会保持活跃状态。默认值为
60000。 discovery-group-ref-
作为为上游代理连接定义静态连接器的替代选择，这个元素可以用来指定一个发现组，该组已在
broker.xml配置文件中配置。特别是，您可以将现有的发现组指定为此元素的discovery-group-name属性的值。有关发现组的更多信息，请参阅 第 14.1.6 节 “代理发现方法”。 ha-
指定是否为到上游代理的连接启用高可用性。如果此参数的值设置为
true，本地代理可以连接到上游集群中任何可用的代理，并在 live 上游代理关闭时自动切换到备份代理。默认值为false。 initial-connect-attempts-
downstream 代理将连接到上游代理的初始尝试数。如果在没有建立连接的情况下达到这个值，则上游代理会被视为永久离线。downstream 代理不再将消息路由到上游代理。默认值为
-1，这意味着没有限制。 max-retry-interval-
当连接到远程代理失败时，后续重新连接尝试之间的最大时间（以毫秒为单位）。默认值为
2000。 reconnect-attempts-
如果连接失败，下游代理将尝试重新连接上游代理的次数。如果在重新建立连接的情况下达到这个值，则上游代理会被视为永久离线。downstream 代理不再将消息路由到上游代理。默认值为
-1，这意味着没有限制。 retry-interval-
如果连接到远程代理失败，后续重新连接尝试之间周期（以毫秒为单位）。默认值为
500。 retry-interval-multiplier-
应用到
retry-interval参数的值的因子数。默认值为：1。 share-connection-
如果同一代理同时配置了下游和上游连接，那么将共享相同的连接，只要下游和上游配置都设置了这个参数的值设为
true。默认值为false。
在本地代理上，将连接器添加到远程代理。这些是在联合地址配置的
static-connectors元素中引用的连接器。例如：<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors>
<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.22.4.2.3. 配置下游地址联邦
以下示例演示了如何为独立代理配置下游地址联邦。
下游地址联邦允许您在一个或多个远程代理用来连接到本地代理的本地代理中添加配置。这种方法的优点是，您可以在单个代理中保留所有联邦配置。例如，这可能是 hub 和spoke 拓扑的一个有用的方法。
下游地址与上游地址配置与联邦连接的方向相反。因此，当您将远程代理添加到配置中时，这些代理会被视为 下游 代理。downstream 代理使用配置中的连接信息来连接本地代理，该代理现在被视为上游。这个示例稍后会说明这一点，当您为远程代理添加配置时。
先决条件
- 您应该熟悉上游地址联邦的配置。请参阅 第 4.22.4.2.2 节 “配置上游地址联邦”。
- 以下示例演示了如何配置独立代理间的地址联邦。但是，您还应熟悉为代理 集群配置 联邦的要求。更多信息请参阅 第 4.22.4.2.1 节 “为代理集群配置联邦”。
流程
-
在本地代理上，打开 <
;broker_instance_dir> /etc/broker.xml配置文件。 添加包括
<federation>项的<federations>项。例如：<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations><federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加地址策略配置。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果要在传输前转换消息，请添加转换器配置。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 为每个远程代理添加
downstream项。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如前面的配置所示，远程代理现在被视为本地代理的下游。downstream 代理使用配置中的连接信息来重新连接到本地（即 上游）代理。
在本地代理上，添加本地和远程代理使用的连接器和接收器来建立联邦连接。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow connector name="netty-connector"- 本地代理发送到远程代理的连接器配置。远程代理使用此配置连接到本地代理。
connector name="eu-west-1-connector",connector name="eu-east-1-connector"- 远程代理的连接器。本地代理使用这些连接器连接到远程代理，并共享远程代理需要连接到本地代理所需的配置。
acceptor name="netty-acceptor"- 接受与远程代理使用的连接器对应的本地代理中的 acceptor，以连接到本地代理。
4.22.4.2.4. 关于队列联邦
队列联邦提供了一种在不同远程代理间平衡单个队列的负载的方法。
为了实现负载平衡，本地代理会从远程队列检索消息，以满足来自本地消费者的消息的需求。下面是一个示例。
图 4.9. 对称队列联邦
远程队列不需要重新配置，它们不必位于同一代理或同一集群中。建立远程链接和联邦队列所需的所有配置都位于本地代理中。
4.22.4.2.4.1. 队列联邦的优点
以下是您可能选择配置队列联邦的一些原因。
- 增加容量
- 队列联邦可以创建在多个代理上分发的"逻辑"队列。这个逻辑分布式队列的容量比单一代理中的单个队列高。在这个设置中，尽可能多的信息会从最初发布到的代理中消耗。只有在需要负载均衡时，系统才会在联邦中移动信息。
- 部署多区域设置
在多区域设置中，您可能在一个区域或场所和消费者中有一个消息制作者。但是，您最好将生成者和消费者连接保留给给定区域。在这种情况下，您可以在生成者和消费者的每个区域中部署代理，并使用队列联邦在区域间的广域网(WAN)上移动消息。下面是一个示例。
图 4.10. 多区域队列联邦
- 安全企业 LAN 和 DMZ 间的通信
在网络安全中，非大区 (DMZ)是一个物理或逻辑子网，其中包含并公开企业面向外部的服务，通常是互联网。企业本地区域网络(LAN)的其余部分与防火墙后面的这个外部网络保持隔离。
在很多消息生成者位于 DMZ 中，以及安全企业 LAN 中的消费者时，可能并不合适，允许生成者连接到安全企业 LAN 中的代理。在这种情况下，您可以在 DMZ 中部署生成者可以将消息发布到的代理。然后，企业 LAN 中的代理可以连接到 DMZ 中的代理，并使用联邦队列从 DMZ 中的代理接收信息。
4.22.4.2.5. 配置上游队列联邦
以下示例演示了如何为独立代理配置上游队列联邦。在本例中，您要将本地（即 下游）代理中的联邦配置为一些远程（即 上游）代理。
先决条件
- 以下示例演示了如何配置独立代理间的队列联邦。但是，您还应熟悉为代理 集群配置 联邦的要求。更多信息请参阅 第 4.22.4.2.1 节 “为代理集群配置联邦”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在新的 <
federations> 元素中，添加一个 <federation>元素。例如：<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>Copy to Clipboard Copied! Toggle word wrap Toggle overflow name- 联邦配置的名称。在本例中，名称对应于下游代理的名称。
user- 用于与上游代理连接的共享用户名。
password- 用于与上游代理连接的共享密码。
注意- 如果对上游代理的用户和密码凭证不同，您可以在将代理添加到配置中时为这些代理单独指定凭证。此流程稍后将对此进行说明。
在
federation元素中添加 <queue-policy>元素。为 <queue-policy> 元素的属性指定值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow name- 队列策略的名称。在代理上配置的所有队列策略必须具有唯一的名称。
include-federated当此属性的值设为
false时，配置不会重新联邦已经被联邦的消费者（即联邦队列中的消费者）。这可避免在对称或闭环拓扑中发生，没有非联邦的消费者，并且系统间没有消息流。如果您没有 闭环拓扑，您可以将此属性的值设置为
true。例如，假设您有 3 个代理链：BrokerABrokerB和BrokerC，以及位于 BrokerA 的制作者，以及BrokerC的消费者。在这种情况下，您将希望BrokerB重新联邦消费者到BrokerA。priority-adjustment当消费者连接到队列时，在创建上游( 联邦)消费者时，会使用其优先级。联合消费者的优先级由
priority-adjustment属性的值调整。此属性的默认值为-1，这样可确保本地消费者在负载平衡期间优先于联合消费者。但是，您可以根据需要更改优先级调整的值。如果优先级调整不足，以防止太多信息迁移到联邦用户，这可能会导致消息在代理间返回或出现，您可以限制移到联邦消费者的消息大小。要限制批处理大小，请在联邦消费者的连接 URI 上将
consumerWindowSize值设置为0。tcp://<host>:<port>?consumerWindowSize=0
tcp://<host>:<port>?consumerWindowSize=0Copy to Clipboard Copied! Toggle word wrap Toggle overflow 将
consumerWindowSize值设置为0时，AMQ Broker 使用地址设置中的defaultConsumerWindowSize参数的值用于匹配地址，以确定可在代理之间移动的消息的批处理大小。defaultConsumerWindowSize属性的默认值为1048576字节。transformer-ref- 转换器配置的名称。如果要在联邦消息传输过程中转换消息，您可以添加转换器配置。此流程稍后会描述转换器配置。
在 <
;queue-policy> 元素中，添加地址匹配模式，以便从队列策略包含和排除地址。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Include此元素的
address-match属性的值指定要包含在队列策略中的地址。您可以指定一个准确的地址，如queue.bbc.new或queue.usatoday。或者，您可以使用通配符表达式来指定匹配的地址 集合。在前面的示例中，队列策略还包含以字符串queue.news开头的所有 地址名称。与
address-match属性相结合，您可以使用queue-match属性在队列策略中包含这些地址的特定队列。与address-match属性一样，您可以指定一个准确的队列名称，也可以使用通配符表达式来指定 一组 队列。在前面的示例中，数字符号 (#) 通配符代表在每个地址或包括在队列策略中的一组地址中的所有队列。exclude-
此元素的
address-match属性的值指定要从队列策略中排除的地址。您可以指定一个准确的地址，或使用通配符表达式来指定匹配的地址 集合。在前面的示例中，数字符号(#)通配符表示排除任何匹配跨越 所有地址中的queue-match属性的队列。在这种情况下，所有以字符串.local结尾的队列都会被排除。这表示某些队列被保留为本地队列，而不是联邦。
在
federation元素中，添加一个转换器元素来引用自定义转换器实施。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow name-
转换器配置的名称。在相关的代理中，这个名称必须是唯一的。您可以将此名称指定为地址策略的
transformer-ref属性的值。 class-name实施
org.apache.activemq.artemis.core.server.transformer.Transformer接口的用户定义类的名称。在传输消息前，通过消息调用转换器的
transform （）方法。这可让您在联邦前转换消息标头或正文。属性- 用于保存特定转换器配置的键值对。
在
federation元素内，添加一个或多个上游元素。每个upstream元素定义上游代理连接以及要应用到该连接的策略。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow static-connectors-
包含
connector-ref元素列表，该元素引用本地代理的broker.xml配置文件中定义的连接器元素。连接器定义用于传出连接的传输(TCP、SSL、HTTP 等)和服务器连接参数（主机、端口等）。以下流程的以下步骤演示了如何添加联邦队列配置的static-connectors元素引用的连接器。 policy-ref- 在应用到上游代理的下游代理上配置的队列策略的名称。
您可以为
上游元素指定的附加选项如下所述：name-
上游代理配置的名称。在本例中，名称对应于名为
eu-east-1和eu-west-1的上游代理。 user-
创建与上游代理的连接时使用的用户名。如果没有指定，则使用在
federation元素配置中指定的共享用户名。 password-
创建与上游代理的连接时使用的密码。如果没有指定，则使用
联邦元素配置中指定的共享密码。 call-failover-timeout-
与
call-timeout类似，但在故障转移尝试期间调用时使用。默认值为-1，这意味着禁用超时。 call-timeout-
当联邦连接传输一个阻塞调用的数据包时，联邦连接会等待来自远程代理的回复。如果此时间过，连接会抛出异常。默认值为
30000。 check-period-
周期（以毫秒为单位）在本地代理发送到远程代理时连续的"keep-alive"消息之间检查联邦连接的健康状态。如果联邦连接健康，远程代理会响应每个 keep-alive 信息。如果连接不健康，则下游代理无法从上游代理接收响应，则使用名为 断路器 的机制来阻止联邦用户。如需更多信息，请参阅
circuit-breaker-timeout参数的描述。check-period参数的默认值为30000。 circuit-breaker-timeout- 下游和上游代理之间的单个连接可能由许多联合队列和地址消费者共享。如果代理之间的连接丢失，每个联邦消费者可能会尝试同时重新连接。为避免这种情况，称为 断路器 的机制会阻止消费者。当指定的超时值过后，断路器会重新尝试连接。如果成功，用户就会取消阻塞。否则，断路器再次应用。
connection-ttl-
如果联邦连接停止从远程代理接收信息，则联邦连接会保持活跃状态。默认值为
60000。 discovery-group-ref-
作为为上游代理连接定义静态连接器的替代选择，这个元素可以用来指定一个发现组，该组已在
broker.xml配置文件中配置。特别是，您可以将现有的发现组指定为此元素的discovery-group-name属性的值。有关发现组的更多信息，请参阅 第 14.1.6 节 “代理发现方法”。 ha-
指定是否为到上游代理的连接启用高可用性。如果此参数的值设置为
true，本地代理可以连接到上游集群中任何可用的代理，并在 live 上游代理关闭时自动切换到备份代理。默认值为false。 initial-connect-attempts-
downstream 代理将连接到上游代理的初始尝试数。如果在没有建立连接的情况下达到这个值，则上游代理会被视为永久离线。downstream 代理不再将消息路由到上游代理。默认值为
-1，这意味着没有限制。 max-retry-interval-
当连接到远程代理失败时，后续重新连接尝试之间的最大时间（以毫秒为单位）。默认值为
2000。 reconnect-attempts-
如果连接失败，下游代理将尝试重新连接上游代理的次数。如果在重新建立连接的情况下达到这个值，则上游代理会被视为永久离线。downstream 代理不再将消息路由到上游代理。默认值为
-1，这意味着没有限制。 retry-interval-
如果连接到远程代理失败，后续重新连接尝试之间周期（以毫秒为单位）。默认值为
500。 retry-interval-multiplier-
应用到
retry-interval参数的值的因子数。默认值为：1。 share-connection-
如果同一代理同时配置了下游和上游连接，那么将共享相同的连接，只要下游和上游配置都设置了这个参数的值设为
true。默认值为false。
在本地代理上，将连接器添加到远程代理。这些是在联合地址配置的
static-connectors元素中引用的连接器。例如：<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors>
<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果您希望大型消息在联邦连接之间流，在用于联邦连接的连接器中将
consumerWindowSize参数设置为 -1。将consumerWindowSize参数设置为 -1 表示没有为此参数设置限制，这将允许大型消息跨连接流。例如：<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616?consumerWindowSize=-1</connector> <connector name="eu-east-1-connector">tcp://localhost:61617?consumerWindowSize=-1</connector> </connectors>
<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616?consumerWindowSize=-1</connector> <connector name="eu-east-1-connector">tcp://localhost:61617?consumerWindowSize=-1</connector> </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 有关大型信息的详情，请参考 第 8 章 处理大型消息。
4.22.4.2.6. 配置下游队列联邦
以下示例演示了如何配置下游队列联邦。
下游队列联邦允许您在一个或多个远程代理用来连接到本地代理的本地代理中添加配置。这种方法的优点是，您可以在单个代理中保留所有联邦配置。例如，这可能是 hub 和spoke 拓扑的一个有用的方法。
下游队列联邦将联邦连接的方向与上游队列配置相反。因此，当您将远程代理添加到配置中时，这些代理会被视为 下游 代理。downstream 代理使用配置中的连接信息来连接本地代理，该代理现在被视为上游。这个示例稍后会说明这一点，当您为远程代理添加配置时。
先决条件
- 您应该熟悉上游队列联邦的配置。请参阅 第 4.22.4.2.5 节 “配置上游队列联邦”。
- 以下示例演示了如何配置独立代理间的队列联邦。但是，您还应熟悉为代理 集群配置 联邦的要求。更多信息请参阅 第 4.22.4.2.1 节 “为代理集群配置联邦”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加包括
<federation>项的<federations>项。例如：<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加队列策略配置。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果要在传输前转换消息，请添加转换器配置。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 为每个远程代理添加
downstream项。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如前面的配置所示，远程代理现在被视为本地代理的下游。downstream 代理使用配置中的连接信息来重新连接到本地（即 上游）代理。
在本地代理上，添加本地和远程代理使用的连接器和接收器来建立联邦连接。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow connector name="netty-connector"- 本地代理发送到远程代理的连接器配置。远程代理使用此配置连接到本地代理。
connector name="eu-west-1-connector",connector name="eu-east-1-connector"- 远程代理的连接器。本地代理使用这些连接器连接到远程代理，并共享远程代理需要连接到本地代理所需的配置。
acceptor name="netty-acceptor"接受与远程代理使用的连接器对应的本地代理中的 acceptor，以连接到本地代理。
注意如果您希望大型消息在联邦连接之间流，在用于联邦连接的连接器中将
consumerWindowSize参数设置为 -1。将consumerWindowSize参数设置为 -1 表示没有为此参数设置限制，这将允许大型消息跨连接流。例如：<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616?consumerWindowSize=-1</connector> <connector name="eu-east-1-connector">tcp://localhost:61617?consumerWindowSize=-1</connector> </connectors>
<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616?consumerWindowSize=-1</connector> <connector name="eu-east-1-connector">tcp://localhost:61617?consumerWindowSize=-1</connector> </connectors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 有关大型信息的详情，请参考 第 8 章 处理大型消息。
第 5 章 保护代理
5.1. 保护连接
当代理连接到消息传递客户端或代理连接到其他代理时，您可以使用传输层安全(TLS)保护这些连接。
您可以使用两个 TLS 配置：
- 单向 TLS，其中只有代理提供证书。这是最常见的配置。
- 双向（或 mutual）TLS，代理和客户端（或其他代理）存在证书。
5.1.1. 配置单向 TLS
以下流程演示了如何为单向 TLS 配置给定接收器。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于给定的接收器，添加
sslEnabled键并将值设为true。另外，添加keyStorePath和keyStorePassword密钥。设置与代理密钥存储对应的值。例如：<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!</acceptor>
<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!</acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
5.1.2. 配置双向 TLS
以下步骤演示了如何配置双向 TLS。
先决条件
- 您必须已经为单向 TLS 配置给定接受者。更多信息请参阅 第 5.1.1 节 “配置单向 TLS”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您之前为单向 TLS 配置的 acceptor，请添加
needClientAuth密钥。将值设为true。例如：<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true</acceptor>
<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true</acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 上一步中的配置假定客户端证书由可信提供程序签名。如果客户端证书 没有由可信 供应商签名（例如，它是自签名），则代理需要将客户端的证书导入到信任存储中。在这种情况下，添加
trustStorePath和trustStorePassword密钥。设置与代理信任存储对应的值。例如：<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true;trustStorePath=../etc/client.truststore;trustStorePassword=5678!</acceptor>
<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true;trustStorePath=../etc/client.truststore;trustStorePassword=5678!</acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
AMQ Broker 支持多种协议，每个协议和平台有不同的方法来指定 TLS 参数。但是，在使用 Core Protocol （一个网桥）的客户端时，TLS 参数会在连接器 URL 上配置，类似于代理的 acceptor。
如果在 Java 虚拟机(JVM)信任存储中被列为可信证书，则 JVM 不会验证证书的到期日期。在生产环境中，红帽建议您使用由证书颁发机构签名的证书。
5.1.3. TLS 配置选项
下表显示了所有可用的 TLS 配置选项。
| 选项 | 备注 |
|---|---|
|
|
指定是否为连接启用 SSL。必须设为 |
|
| 在接受者中使用： 指向包含代理证书的代理上的 TLS 密钥存储的路径（无论是自签名还是由颁发机构签名）。
在连接器中使用： 指向包含客户端证书的客户端上的 TLS 密钥存储的路径。只有在使用双向 TLS 时，才会与连接器相关。虽然您可以在代理上配置这个值，但它由客户端下载和使用。如果客户端需要使用代理上设置的不同路径，它可以使用标准的 |
|
| 当用于 acceptor: 代理上的密钥存储的密码时。
在连接器中使用时： 客户端上密钥存储的密码。只有在使用双向 TLS 时，才会与连接器相关。虽然您可以在代理上配置这个值，但它由客户端下载和使用。如果客户端需要使用代理上设置的不同密码，那么它可以使用标准的 |
|
| 在 acceptor 中使用： 到代理上 TLS 信任存储的路径，该代理包含代理信任的所有客户端的密钥。只有在您使用双向 TLS 时，这才与接受者相关。
在连接器中使用： 客户端信任的所有代理的公钥的客户端上 TLS 信任存储的路径。虽然您可以在代理上配置这个值，但它由客户端下载和使用。如果客户端需要使用与服务器上设置的不同路径不同，那么它可以使用标准的 |
|
| 在 acceptor 中使用时： 代理上信任存储的密码。只有在您使用双向 TLS 时，这才与接受者相关。
在连接器中使用时： 客户端上的信任存储的密码。虽然您可以在代理上配置这个值，但它由客户端下载和使用。如果客户端需要使用代理上设置的不同密码，那么它可以使用标准的 |
|
| 用于接受者或连接器的 TLS 通信的、以逗号分隔的密码套件列表。
指定客户端应用程序支持的最安全密码套件。如果您指定了代理和客户端通用的、以逗号分隔的密码套件列表，或者您没有指定任何密码套件，则代理和客户端会相互协商要使用的密码套件。如果您不知道要指定的密码套件，您可以首先与以 debug 模式运行的客户端建立 broker-client 连接，以验证代理和客户端通用的密码套件。然后，在代理上配置
可用的密码套件取决于代理和客户端使用的 TLS 协议版本。如果在升级代理后默认 TLS 协议版本有变化，您可能需要选择较早的 TLS 协议版本，以确保代理和客户端可以使用通用密码套件。如需更多信息，请参阅 |
|
| 无论是在接收器或连接器上使用的，这是用于 TLS 通信的协议的逗号分隔列表。如果没有指定 TLS 协议版本，代理将使用 JVM 的默认版本。
如果代理为 JVM 使用默认 TLS 协议版本，且该版本在升级代理后发生了变化，则代理和客户端使用的 TLS 协议版本可能会不兼容。虽然建议您使用更新的 TLS 协议版本，但您可以在 |
|
|
此属性仅适用于接收器。它指示客户端连接到需要双向 TLS 的接收器。有效值为 |
5.2. 验证客户端
5.2.1. 客户端验证方法
要在代理中配置客户端身份验证，您可以使用以下方法之一：
- 用户名和密码的身份验证
使用以下选项之一直接验证用户凭证：
- 针对存储在代理中的一组属性文件检查凭证。您还可以配置一个 客户机 帐户，允许限制对代理的访问，并组合登录模块来支持更复杂的用例。
- 配置 轻量级目录访问协议 (LDAP)登录模块，以针对存储在中央 X.500 目录服务器中的用户数据检查客户端凭据。
- 基于证书的身份验证
- 配置双向 传输层安全 (TLS)，以要求代理和客户端同时为 mutual 身份验证提供证书。管理员还必须配置定义批准的客户端用户和角色的属性文件。这些属性文件存储在代理中。
- 基于 Kerberos 的身份验证
- 配置代理，以使用 简单身份验证和安全层 (SASL)框架中的 GSSAPI 机制为客户端验证 Kerberos 安全凭证。
以下章节描述了如何配置 user-and-password- 和基于证书的身份验证。
其他资源
要了解 LDAP 和 Kerberos 的完整身份验证和授权工作流，请参阅：
5.2.2. 根据属性文件配置用户和密码身份验证
AMQ Broker 支持灵活的基于角色的安全模型，以便根据其地址将安全应用到队列。队列绑定到地址一对一（用于点到点的消息传递）或多对一（用于发布订阅消息传递）。当消息发送到地址时，代理会查找绑定到该地址的队列集合，并将消息路由到那个队列集合。
当您需要基本用户和密码身份验证时，请使用 PropertiesLoginModule 来定义它。这个登录模块会根据保存在代理中的以下配置文件检查用户凭证：
artemis-users.properties- 用于定义用户和对应的密码
artemis-roles.properties- 用于定义角色并将用户分配给这些角色
login.config- 用于为用户和密码身份验证和客户机访问配置登录模块
artemis-users.properties 文件可以包含哈希密码，以保证安全性。
以下部分介绍了如何配置：
5.2.2.1. 配置基本用户和密码身份验证
以下步骤演示了如何配置基本用户和密码身份验证。
流程
打开 &
lt;broker_instance_dir> /etc/login.config配置文件。默认情况下，新的 AMQ Broker 7.13 实例中此文件包括以下行：Copy to Clipboard Copied! Toggle word wrap Toggle overflow activemq- 配置的别名。
org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule- 实施类。
足够指定
PropertiesLoginModule需要哪个级别的成功。您可以设置的值有：-
必需：需要登录模块才能成功。无论成功或失败如何，身份验证将继续在给定别名下配置的登录模块列表。 -
requisite：需要登录模块才能成功。失败会立即将控制权返回到应用。身份验证不会停机给定别名下配置的登录模块的列表。 -
sufficient: 登录模块不需要成功。如果成功，则控制会返回应用程序，身份验证也不会进一步继续。如果失败，身份验证会尝试继续在给定别名下配置的登录模块列表。 -
可选登录模块不是必需的。无论成功或失败如何，身份验证将继续在给定别名下配置的登录模块列表。
-
org.apache.activemq.jaas.properties.user- 指定为登录模块实现定义一组用户和密码的属性文件。
org.apache.activemq.jaas.properties.role- 指定将用户映射到登录模块实施定义的角色的属性文件。
-
打开 &
lt;broker_instance_dir> /etc/artemis-users.properties配置文件。 添加用户并为用户分配密码。例如：
user1=secret user2=access user3=myPassword
user1=secret user2=access user3=myPasswordCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
打开 &
lt;broker_instance_dir> /etc/artemis-roles.properties配置文件。 将角色名称分配给您之前添加到
artemis-users.properties文件中的用户。例如：admin=user1,user2 developer=user3
admin=user1,user2 developer=user3Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
打开 &
lt;broker_instance_dir> /etc/bootstrap.xml配置文件。 如有必要，将您的安全域别名（在这个实例中，activemq）添加到文件中，如下所示：
<jaas-security domain="activemq"/>
<jaas-security domain="activemq"/>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
5.2.2.2. 配置客户机访问
对于没有登录凭证的用户，或者凭证失败身份验证，您可以使用客户机帐户授予对代理的有限访问权限。
您可以使用 命令行参数创建启用了客户机访问权限的代理实例；-- allow-anonymous （其相反，即 -require-login）。
以下步骤演示了如何配置客户机访问。
先决条件
- 这个过程假设您已配置了基本用户和密码身份验证。如需更多信息，请参阅 第 5.2.2.1 节 “配置基本用户和密码身份验证”。
流程
-
打开之前为基本用户和密码身份验证配置的 &
lt;broker_instance_dir> /etc/login.config配置文件。 在您之前添加的属性登录模块配置后，添加客户机登录模块配置。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule- 实施类。
org.apache.activemq.jaas.guest.user- 分配给匿名用户的用户名。
org.apache.activemq.jaas.guest.role- 分配给匿名用户的角色。
根据前面的配置，如果用户提供凭证，则会激活用户和密码身份验证模块。如果用户不提供凭证，或者提供的凭证不正确，则会激活客户机身份验证。
5.2.2.2.1. 客户机访问示例
以下示例显示，在只有没有凭证的用户作为客户机登录的情况下，在用例中配置了客户机访问权限。在本例中，观察登录模块的顺序与之前的配置过程已撤销。另外，附加到属性登录模块的标志被改为 requisite。
根据上述配置，如果没有提供登录凭据，则会激活客户机身份验证模块。
对于这个用例，在客户机登录模块配置中，credentialsInvalidate 选项必须设置为 true。
如果提供了凭据，则会激活属性登录模块。凭证必须有效。
其他资源
-
有关 Java 身份验证和授权服务 (JAAS)的更多信息，请参阅您的 Java 供应商的文档。例如，对于配置
login.config的 Oracle 指南，请参阅 Oracle Java 文档中的 JAAS 登录 配置文件。 - 要了解如何配置 LDAP 登录模块以验证客户端凭证，请参阅 第 5.4.1 节 “配置 LDAP 以验证客户端”。
- 有关在配置文件中加密密码的更多信息，请参阅 第 5.10.2 节 “在配置文件中加密密码”。
5.2.3. 配置基于证书的身份验证
Java 身份验证和授权服务 (JAAS)证书登录模块处理使用传输层安全(TLS)的客户端的身份验证和授权。该模块需要使用双向 传输层安全 (TLS)，客户端需要使用自己的证书进行配置。身份验证在 TLS 握手期间执行，而不是由 JAAS 证书登录模块直接执行。
证书登录模块的角色是：
- 限制可接受的用户集合。只有用户 可辨识名称 (DN)在相关属性文件中明确列出，才能进行身份验证。
- 将组列表与收到的用户身份关联。这有助于授权。
- 需要存在传入客户端证书（默认情况下，TLS 层配置为将客户端证书存在为可选）。
certificate 登录模块将证书 DN 集合存储在一对扁平文本文件中。文件将用户名和组 ID 列表与每个 DN 关联。
证书登录模块由 org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule 类实现。
5.2.3.1. 配置代理以使用基于证书的身份验证
以下流程演示了如何将代理配置为使用基于证书的身份验证。
先决条件
- 您必须将代理配置为使用双向传输层安全(TLS)。更多信息请参阅 第 5.1.2 节 “配置双向 TLS”。
流程
从之前导入到代理密钥存储的用户证书获取 Subject Distinguished Names (DNs)。
将密钥存储文件中的证书导出到临时文件。例如：
keytool -export -file <file_name> -alias broker-localhost -keystore broker.ks -storepass <password>
keytool -export -file <file_name> -alias broker-localhost -keystore broker.ks -storepass <password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 打印导出的证书的内容：
keytool -printcert -file <file_name>
keytool -printcert -file <file_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 输出结果类似如下：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Owner条目是主题 DN。用于输入 Subject DN 的格式取决于您的平台。以上字符串也可以表示为;Owner: `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown`
Owner: `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown`Copy to Clipboard Copied! Toggle word wrap Toggle overflow
配置基于证书的身份验证。
打开 &
lt;broker_instance_dir> /etc/login.config配置文件。添加证书登录模块并引用用户和角色属性文件。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule- 实施类。
org.apache.activemq.jaas.textfiledn.user- 指定为登录模块实现定义一组用户和密码的属性文件。
org.apache.activemq.jaas.textfiledn.role- 指定将用户映射到登录模块实施定义的角色的属性文件。
打开 &
lt;broker_instance_dir> /etc/artemis-users.properties配置文件。用户及其对应的 DN 在此文件中定义。例如：system=CN=system,O=Progress,C=US user=CN=humble user,O=Progress,C=US guest=CN=anon,O=Progress,C=DE
system=CN=system,O=Progress,C=US user=CN=humble user,O=Progress,C=US guest=CN=anon,O=Progress,C=DECopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，基于上述配置，名为
system的用户映射到CN=system,O=Progress,C=USSubject DN。打开 &
lt;broker_instance_dir> /etc/artemis-roles.properties配置文件。可用的角色和包含这些角色的用户在此文件中定义。例如：admins=system users=system,user guests=guest
admins=system users=system,user guests=guestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的配置中，对于
users角色，您将以逗号分隔列表列出多个用户。请确保您的安全域别名（在本例中是 activemq）在
bootstrap.xml中引用，如下所示：<jaas-security domain="activemq"/>
<jaas-security domain="activemq"/>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
5.2.3.2. 为 AMQP 客户端配置基于证书的身份验证
使用 简单身份验证和安全层 (SASL) EXTERNAL 机制配置参数，在连接到代理时为基于证书的身份验证配置您的 AQMP 客户端。
代理会以验证任何证书的相同方式验证您的 AMQP 客户端的 Transport Layer Security (TLS)/Secure Sockets Layer (SSL) 证书：
- 代理读取客户端的 TLS/SSL 证书，以从证书的主题获取身份。
- 证书主题由证书登录模块映射到代理身份。然后，代理会根据其角色授权用户。
以下流程演示了如何为 AMQP 客户端配置基于证书的身份验证。要让您的 AMQP 客户端使用基于证书的身份验证，您必须将配置参数添加到客户端用于连接代理的 URI 中。
先决条件
您必须已配置：
- 双向 TLS。更多信息请参阅 第 5.1.2 节 “配置双向 TLS”。
- 使用基于证书的身份验证的代理。更多信息请参阅 第 5.2.3.1 节 “配置代理以使用基于证书的身份验证”。
流程
打开包含 URI 的资源以进行编辑：
amqps://localhost:5500
amqps://localhost:5500Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加参数
sslEnabled=true来为连接启用 TSL/SSL ：amqps://localhost:5500?sslEnabled=true
amqps://localhost:5500?sslEnabled=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow 添加与客户端信任存储和密钥存储相关的参数，以便使用代理启用 TSL/SSL 证书交换：
amqps://localhost:5500?sslEnabled=true&trustStorePath=<trust_store_path>&trustStorePassword=<trust_store_password>&keyStorePath=<key_store_path>&keyStorePassword=<key_store_password>
amqps://localhost:5500?sslEnabled=true&trustStorePath=<trust_store_path>&trustStorePassword=<trust_store_password>&keyStorePath=<key_store_path>&keyStorePassword=<key_store_password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加参数
saslMechanisms=EXTERNAL，以使用其 TSL/SSL 证书中找到的身份请求代理验证客户端：amqps://localhost:5500?sslEnabled=true&trustStorePath=<trust_store_path>&trustStorePassword=<trust_store_password>&keyStorePath=<key_store_path>&keyStorePassword=<key_store_password>&saslMechanisms=EXTERNAL
amqps://localhost:5500?sslEnabled=true&trustStorePath=<trust_store_path>&trustStorePassword=<trust_store_password>&keyStorePath=<key_store_path>&keyStorePassword=<key_store_password>&saslMechanisms=EXTERNALCopy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 有关 AMQ Broker 中基于证书验证的详情，请参考 第 5.2.3.1 节 “配置代理以使用基于证书的身份验证”。
- 有关配置 AMQP 客户端的更多信息，请访问红帽客户门户网站 以了解特定于您的客户端的产品文档。
5.3. 授权客户端
5.3.1. 客户端授权方法
要授权客户端在代理上执行操作，如创建和删除地址和队列，以及发送和接收信息，您可以使用以下方法：
- 基于用户和角色的授权
- 为经过身份验证的用户和角色配置代理安全设置。
- 配置 LDAP 以授权客户端
- 配置 轻量级目录访问协议 (LDAP)登录模块，以处理身份验证和授权。LDAP 登录模块根据存储在中央 X.500 目录服务器中的用户数据检查传入的凭据，并根据用户角色设置权限。
- 配置 Kerberos 以授权客户端
-
配置 Java 身份验证和授权服务 (JAAS)
Krb5LoginModule登录模块，将凭证传递给PropertiesLoginModule或LDAPLoginModule登录模块，它将 Kerberos 验证的用户映射到 AMQ Broker 角色。
5.3.2. 配置基于用户和基于角色的访问控制
5.3.2.1. 设置权限
权限通过 broker.xml 配置文件中的 < security-setting& gt; 元素根据队列（基于其地址）定义。您可以在配置文件的 <security-settings> 项中定义多个 <security-setting> 实例。您可以指定一个准确的地址匹配，或者使用数字符号(#)和星号(*)通配符字符来定义通配符匹配。
可将不同的权限分配给与地址匹配的队列集合。这些权限显示在下表中。
| 允许用户进行… | 使用此参数… |
|---|---|
| 创建地址 |
|
| 删除地址 |
|
| 在匹配地址下创建一个持久化队列 |
|
| 删除匹配地址下的持久队列 |
|
| 在匹配地址下创建一个非持久化队列 |
|
| 删除匹配地址下的非持久化队列 |
|
| 向匹配地址发送消息 |
|
| 使用队列绑定到匹配地址的消息 |
|
| 通过将管理消息发送到管理地址来调用管理操作 |
|
| 浏览绑定到匹配地址的队列 |
|
| 对管理操作子集具有只读访问权限 |
|
|
访问变异管理操作，这是任何未授予 |
|
对于每个权限，您可以指定授予该权限的角色列表。如果给定用户具有任何角色，则他们被授予该一组地址的权限。
以下章节显示了权限的一些配置示例。
5.3.2.1.1. 为单个地址配置消息 production
以下流程演示了如何为单个地址配置消息生产权限。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
<security-settings>项中添加一个单一的<security-setting>项。对于match键，指定一个地址。例如：<security-settings> <security-setting match="my.destination"> <permission type="send" roles="producer"/> </security-setting> </security-settings><security-settings> <security-setting match="my.destination"> <permission type="send" roles="producer"/> </security-setting> </security-settings>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，
生产者角色的成员具有地址my.destination的发送权限。
5.3.2.1.2. 为单个地址配置消息消耗
以下流程演示了如何为单个地址配置消息消耗权限。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
<security-settings>项中添加一个单一的<security-setting>项。对于match键，指定一个地址。例如：<security-settings> <security-setting match="my.destination"> <permission type="consume" roles="consumer"/> </security-setting> </security-settings><security-settings> <security-setting match="my.destination"> <permission type="consume" roles="consumer"/> </security-setting> </security-settings>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，
consumer角色的成员具有地址my.destination的consume权限。
5.3.2.1.3. 在所有地址上配置完整访问权限
以下步骤演示了如何配置对所有地址和相关队列的完整访问权限。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
<security-settings>项中添加一个单一的<security-setting>项。对于match键，若要配置为对所有地址的访问，使用数字符号 (#) 通配符字符。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，所有权限都授予所有队列上的 guest 角色成员。这在将匿名身份验证配置为为每个用户分配
guest角色的开发场景非常有用。
其他资源
- 要了解有关配置更复杂的用例的信息，请参阅 第 5.3.2.1.4 节 “配置多个安全设置”。
5.3.2.1.4. 配置多个安全设置
以下示例步骤演示了如何为匹配的一组地址单独配置多个安全设置。这与本节中前面的示例相反，它演示了如何为 所有地址授予完全访问权限
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
<security-settings>项中添加一个单一的<security-setting>项。对于match键，请包含数字符号(#)通配符字符，以将设置应用到匹配的 一组 地址。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow match=globalqueues.europe.#-
代理将数字符号(
#)通配符字符解释为"任意单词序列"。词语以句点(.)分隔。在本例中，安全设置适用于以字符串 globalqueues.europe开头的任何地址。 permission type="createDurableQueue"-
只有具有
admin角色的用户才能创建或删除持久队列，绑定到以字符串 globalqueues.europe开头的地址。 permission type="createNonDurableQueue"-
具有
admin、guest或europe-users角色的任何用户都可以创建和删除绑定到以字符串 globalqueues.europe开头的地址的临时队列。 权限 type="send"-
具有
admin或europe-users角色的任何用户可以发送消息到绑定至以字符串 globalqueues.europe开头的地址。 权限 type="consume"-
具有
admin或europe-users角色的任何用户可以消耗来自队列绑定到以字符串 globalqueues.europe开头的地址的消息。
（可选）要将不同的安全设置应用到更严格的地址集合，请添加另一个 <
security-setting>元素。对于match键，指定更具体的文本字符串。例如：<security-setting match="globalqueues.europe.orders.#"> <permission type="send" roles="europe-users"/> <permission type="consume" roles="europe-users"/> </security-setting>
<security-setting match="globalqueues.europe.orders.#"> <permission type="send" roles="europe-users"/> <permission type="consume" roles="europe-users"/> </security-setting>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在第二个
security-setting元素中，globalqueues.europe.orders.#的匹配比第一个security-setting元素中的globalqueues.europe.#匹配更加具体。对于与globalqueues.europe.orders.#匹配的任何地址，权限createDurableQueue,deleteDurableQueue,createNonDurableQueue,deleteNonDurableQueue不是从文件的第一个security-setting元素继承的。例如，对于地址globalqueues.europe.orders.plastics，存在的唯一权限是为europe-users角色发送和使用的权限。因此，由于一个
security-setting块中指定的权限不会被另一个继承，因此您可以通过不指定这些权限来有效地在更具体的security-setting块中拒绝权限。
5.3.2.1.5. 使用用户配置队列
自动创建队列时，队列将被分配连接客户端的用户名。此用户名作为元数据包含在队列中。名称由 JMX 和 AMQ Broker 管理控制台公开。
以下流程演示了如何将用户名添加到您在代理配置中手动定义的队列中。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于给定队列，
添加用户密钥。分配一个值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 根据上述配置，
admin用户分配到队列ExampleQueue。
- 在队列中配置用户不会更改该队列的任何安全语义 - 它仅用于该队列中的元数据。
用户之间的映射以及它们已由名为 安全管理器 的组件处理的角色。安全管理器从代理中存储的属性文件中读取用户凭证。默认情况下，AMQ Broker 使用
org.apache.activemq.artemis.spi.core.security.ActiveMQJAASSecurityManager安全管理器。此默认安全管理器提供与 JAAS 和 Red Hat JBoss Enterprise Application Platform (JBoss EAP)安全性的集成。要了解如何 使用自定义 安全管理器，请参阅 第 5.6.2 节 “指定自定义安全管理器”。
5.3.2.2. 配置基于角色的访问控制
基于角色的访问控制 (RBAC)用于限制对 MBeans 的属性和方法的访问。MBeans 是 AMQ Broker 公开管理 API 以支持管理操作的方式。
您可以使用以下方法之一限制对 MBeans 的访问：
-
在
management.xml文件中配置authorisation元素，这是默认的方法。 -
在
broker.xml文件中配置安全设置。
与更新 management.xml 文件不同，在更改 broker.xml 文件中的安全设置后不需要重启代理。
5.3.2.2.1. 在 management.xml 文件中配置基于角色的访问控制。
为管理操作配置基于角色的访问控制的默认方法是，在 management.xml 文件中配置 authorisation 元素。
以下示例步骤演示了如何将角色映射到特定的 MBeans 及其属性和方法。
先决条件
- 您定义了用户和角色。如需更多信息，请参阅 第 5.2.2.1 节 “配置基本用户和密码身份验证”。
流程
-
打开 &
lt;broker_instance_dir> /etc/management.xml配置文件。 搜索
role-access元素并编辑配置。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
在本例中，匹配应用到具有域名
org.apache.activemq.apache的任何 MBean 属性。 -
访问
view,update, 或amq角色来匹配 MBean 属性由您添加到角色的list*,get*,set*,is*, 和*访问方法控制。method="*"(通配符) 语法作为一个 catch-all 的方式，适用于没有在配置中列出的所有其他方法。配置中的每个访问方法都会转换为 MBean 方法调用。 -
调用的 MBean 方法与配置中列出的方法匹配。例如，如果您在带有
org.apache.activemq.artemis域的 MBean 上调用了listMessages的方法，则代理会将访问重新与list方法配置中定义的角色匹配。 您还可以使用完整的 MBean 方法名称来配置访问权限。例如：
<access method="listMessages" roles="view,update,amq"/>
<access method="listMessages" roles="view,update,amq"/>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
在本例中，匹配应用到具有域名
启动或重启代理。
-
在 Linux: &
lt;broker_instance_dir> /bin/artemis run 在 Windows: &
lt;broker_instance_dir> \bin\artemis-service.exe start您还可以通过添加与 MBean 属性匹配的
key属性来匹配域中的特定 MBeans。
-
在 Linux: &
5.3.2.2.1.1. 基于角色的访问控制示例
本节演示了以下应用基于角色的访问控制的示例：
以下示例演示了如何使用 key 属性将角色映射到指定域中的所有队列。
以下示例演示了如何使用 key 属性将角色映射到特定的命名队列。在本例中，命名队列为 exampleQueue。
以下示例演示了如何将角色映射到名称包含指定前缀的每个队列。在本例中，使用星号(*)通配符运算符匹配所有以前缀 example 开头的队列名称。
您可能希望为同一属性的不同集合（例如，不同的队列集合）映射角色。在这种情况下，您可以在配置文件中包含多个 match 元素。但是，同一域中可以有多个匹配项。
例如，请考虑两个 < ;match& gt; 元素，如下所示：
<match domain="org.apache.activemq.artemis" key="queue=example*">
<match domain="org.apache.activemq.artemis" key="queue=example*">和
<match domain="org.apache.activemq.artemis" key="queue=example.sub*">
<match domain="org.apache.activemq.artemis" key="queue=example.sub*">
根据此配置，org.apache.activemq.artemis 域中的名为 example.sub.queue 的队列与两个通配符键表达式匹配。因此，代理需要一个优先方案来决定哪组角色映射到队列；在第一个 match 项中指定的角色，或在第二个 match 项中指定的角色。
当同一域中有多个匹配项时，代理在映射角色时使用以下优先级方案：
- 与通配符匹配项相比，完全匹配会被优先排序
- 较长的通配符匹配的优先级超过较短的通配符匹配
在本例中，因为较长的通配符表达式与 example.sub.queue 的队列名称匹配，所以代理会应用在第二个 < match > 元素中配置的 role-mapping。
default-access 元素是没有使用 role-access 或 allowlist 配置处理的每个方法调用的 catch-all 元素。default-access 和 role-access 元素具有相同的 match 元素语义。
5.3.2.2.1.2. 配置 allowlist 元素
allowlist 是一组预先批准的域或 MBeans，不需要用户身份验证。您可以提供必须绕过身份验证的域列表或 MBeans 列表。例如，您可以使用 允许列表 指定运行 AMQ Broker 管理控制台所需的任何 MBeans。
以下示例流程演示了如何配置 allowlist 元素。
流程
-
打开 &
lt;broker_instance_dir> /etc/management.xml配置文件。 搜索
allowlist元素并编辑配置：<allowlist> <entry domain="hawtio"/> </allowlist>
<allowlist> <entry domain="hawtio"/> </allowlist>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在本例中，任何带有域
hawtio的 MBean 都会被允许访问，而无需身份验证。您还可以将 <entry domain="hawtio" key="type38:3.8）"/>的通配符条目用于 MBean 属性匹配。启动或重启代理。
-
在 Linux: &
lt;broker_instance_dir> /bin/artemis run -
在 Windows: &
lt;broker_instance_dir> \bin\artemis-service.exe start
-
在 Linux: &
5.3.2.2.2. 在 broker.xml 文件中配置基于角色的访问控制
您可以为 broker.xml 文件中的管理操作配置基于角色的访问控制，而不是 management.xml 文件。对 broker.xml 文件中权限的更新不需要代理重启来生效。
在 broker.xml 文件中，您可以为管理操作授予 view 或 edit 权限。特定管理操作可供具有 view 或 edit 权限的角色使用，由预定义的正则表达式控制。与正则表达式匹配的任何操作都可以被具有 查看 权限的角色访问，所有其他操作都需要 编辑权限。
先决条件
- 您定义了用户和角色。如需更多信息，请参阅 第 5.2.2.1 节 “配置基本用户和密码身份验证”。
流程
从
management.xml文件中删除authorisation元素配置，以防止代理使用这个文件中的默认 RBAC 配置。-
编辑 &
lt;broker_instance_dir>/etc/management.xml文件。 -
从文件中删除
作者元素配置。 -
保存 &
lt;broker_instance_dir>/etc/management.xml文件。
-
编辑 &
在 broker JVM 中添加环境变量，将代理配置为使用
broker.xml文件中的 RBAC 配置。-
打开 &
lt;broker_instance_dir>/etc/artemis.profile文件。 将以下参数添加到 Java 系统参数的
JAVA_ARGS 列表中：-Djavax.management.builder.initial=org.apache.activemq.artemis.core.server.management.ArtemisRbacMBeanServerBuilder-
保存
artemis.profile文件。
-
打开 &
-
打开 &
lt;broker_instance_dir> /etc/broker.xml文件，为管理操作配置 RBAC。 搜索
security-settings元素，再添加一个security-setting元素来管理操作。管理操作匹配地址的格式是：
<_management-rbac-prefix_>.<_resource type_>.<_resource name_>.<_operation_>management-rbac-prefix参数的默认值为mops。在以下示例中，匹配地址中的数字符号(TALM)将
admin角色视图和编辑权限授予所有 MBeans。Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
保存 &
lt;broker_instance_dir> /etc/broker.xml配置文件。
管理操作的基于角色的访问控制的其他示例
以下示例将 manager 角色 view 和 edit 权限授予一个 activemq.management 地址。操作位置中的星号 rolebinding 授予对所有操作的访问权限。
<security-setting match="mops.address.activemq.management.*"> <permission type="view" roles="manager"/> </security-setting>
<security-setting match="mops.address.activemq.management.*">
<permission type="view" roles="manager"/>
</security-setting>
以下示例有一个空角色列表，它拒绝所有用户使用代理 MBean 执行指定操作( forceFailover )。
<security-setting match="mops.broker.forceFailover"> <permission type="edit" roles=""/> </security-setting>
<security-setting match="mops.broker.forceFailover">
<permission type="edit" roles=""/>
</security-setting>5.3.2.3. 设置资源限值
有时，设置某些用户可以超出与授权和身份验证相关的正常安全设置之外的特定限制。
5.3.2.3.1. 配置连接和队列限制
以下示例步骤演示了如何限制用户可以创建的连接和队列数量。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 添加
resource-limit-settings元素。指定max-connections和max-queues的值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow max-connections-
定义匹配用户可以在代理上创建的会话数量。默认值为
-1，这意味着没有限制。如果要限制会话数量，请考虑从 AMQ 核心协议 JMS 客户端连接到代理的每个连接创建两个会话。 max-queues-
定义匹配用户可以创建的队列数。默认值为
-1，这意味着没有限制。
与您可以在代理配置的 address-setting 元素中指定的 匹配 字符串不同，您在 resource-limit-settings 中指定的匹配字符串 无法使用 通配符语法。相反，匹配字符串定义了应用资源限值设置的特定用户。
5.4. 使用 LDAP 进行身份验证和授权
LDAP 登录模块通过针对存储在中央 X.500 目录服务器中的用户数据检查传入的凭证来启用身份验证和授权。它通过 org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule 来实施。
5.4.1. 配置 LDAP 以验证客户端
以下示例演示了如何使用 LDAP 验证客户端。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
security-settings元素内，添加一个security-setting元素来配置权限。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 上述配置 将所有 队列的特定权限
分配给用户角色的成员。-
打开 &
lt;broker_instance_dir> /etc/login.config文件。 根据您使用的目录服务，配置 LDAP 登录模块。
如果您使用 Microsoft Active Directory 目录服务，请添加类似以下示例的配置：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果您使用 Microsoft Active Directory，并且需要为
connectionUsername属性指定的值包含一个空格（如OU=System Accounts），那么您必须将值包含在一对双引号中("")，并使用反斜杠(\)来转义每个双引号中的双引号。例如：connectionUsername="CN=Administrator,CN=Users,OU=\"System Accounts\",DC=example,DC=com"。如果您使用 ApacheDS 目录服务，请添加类似以下示例的配置：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow debug-
打开(
true)或关闭调试(false)。默认值为false。 initialContextFactory-
必须始终设置为
com.sun.jndi.ldap.LdapCtxFactory connectionURL-
使用 LDAP URL、_<ldap://Host:Port> 的目录服务器的位置。通过添加正斜杠
/，后跟目录树中特定节点的 DN，可以选择验证此 URL。Apache DS 的默认端口为10389，而 Microsoft AD 的默认端口为389。 connectionUsername-
打开目录服务器连接的用户的可分辨名称(DN)。例如：
uid=admin,ou=system。目录服务器通常需要客户端提供用户名/密码凭据才能打开连接。 connectionPassword-
与来自
connectionUsername的 DN 匹配的密码。在目录服务器中，在 Directory Information Tree (DIT)中，密码通常以userPassword属性存储在对应的目录条目中。 connectionProtocol- 支持任何值，但实际上并没有使用。必须明确设置这个选项，因为它没有默认值。
connectionTimeout指定代理可以连接到目录服务器的最大时间（以毫秒为单位）。如果代理此时无法连接到目录，它将中止连接尝试。如果为此属性指定 0 或更小的值，则会使用底层 TCP 协议的超时值。如果没有指定值，代理会无限期等待建立连接，或者底层网络超时。
当为连接池请求连接池时，此属性指定代理在达到最大池大小以及池中所有连接都处于使用时等待的时间。如果您指定了零个或更少值，代理会无限期等待连接可用。否则，当达到最大等待时间时，代理会中止连接尝试。
身份验证-
指定绑定到 LDAP 服务器时使用的验证方法。这个参数可以设置为
simple（这需要用户名和密码）或none（允许匿名访问）。 userBase-
选择要搜索用户条目的 DIT 的特定子树。子树由 DN 指定，用于指定子树的基本节点。例如，通过将此选项设置为
ou=User,ou=ActiveMQ,ou=system，对用户条目的搜索仅限于ou=User,ou=ActiveMQ,ou=system节点下的子树。 userSearchMatching-
指定一个 LDAP 搜索过滤器，它应用到
userBase所选的子树。详情请查看下面的 第 5.4.1.1 节 “搜索匹配参数” 部分。 userSearchSubtree-
指定用户条目的搜索深度，相对于
userBase指定的节点。此选项是一个布尔值。指定一个false值表示搜索会尝试与userBase节点的其中一个子条目匹配（映射到javax.naming.directory.SearchControls.ONELEVEL_SCOPE）。指定一个true值意味着搜索会尝试匹配属于userBase节点 子树的 任何条目（映射到javax.naming.directory.SearchControls.SUBTREE_SCOPE）。 userRoleName- 包含用户角色名称列表的用户条目属性名称。角色名称由代理的授权插件解释为组名称。如果省略这个选项，则不会从用户条目中提取角色名称。
readTimeout- 指定代理可以等待从目录服务器接收响应到 LDAP 请求的最长时间（以毫秒为单位）。如果代理没有收到来自目录服务器的响应，代理会中止请求。如果您指定了零个或更少值，或者您没有指定值，代理会无限期等待从目录服务器的响应到 LDAP 请求。
roleBase-
如果角色数据直接存储在目录服务器中，可以使用角色选项的组合(
roleBase,roleSearchMatching,roleSearchSubtree, 和roleName)作为指定userRoleName选项的替代选择。此选项选择 DIT 的特定子树来搜索 role/group 条目。子树由 DN 指定，用于指定子树的基本节点。例如，通过将此选项设置为ou=Group,ou=ActiveMQ,ou=system，搜索 role/group 条目仅限于ou=Group,ou=ActiveMQ,ou=system节点下的子树。 roleName- 包含 role/group 名称的角色条目的属性类型（如 C、O、OU 等）。如果省略此选项，则有效禁用角色搜索功能。
roleSearchMatching-
指定一个 LDAP 搜索过滤器，它应用到
roleBase所选的子树。详情请查看下面的 第 5.4.1.1 节 “搜索匹配参数” 部分。 roleSearchSubtree指定角色条目的搜索深度，相对于
roleBase指定的节点。如果设置为false（默认值），搜索会尝试匹配roleBase节点的其中一个子条目（映射到javax.naming.directory.SearchControls.ONELEVEL_SCOPE）。如果为true，它会尝试匹配属于角色 Base 节点的子树的任何条目（映射到javax.naming.directory.SearchControls.SUBTREE_SCOPE）。注意Apache DS 使用 DN 路径的
OID部分。Microsoft Active Directory 使用CN部分。例如，您可以使用 Apache DS 中的oid=testuser,dc=example,dc=com等 DN 路径，而您可以在 Microsoft Active Directory 中使用cn=testuser,dc=example,dc=com等 DN 路径。
- 启动或重启代理（服务或进程）。
5.4.1.1. 搜索匹配参数
userSearchMatching在传递给 LDAP 搜索操作前，此配置参数中提供的字符串值受到字符串替换，如
java.text.MessageFormat类实现。
这意味着，特殊字符串
{0}替换为用户名，如从传入的客户端凭据中提取。替换后，字符串将解释为 LDAP 搜索过滤器（语法由 IETF 标准 RFC 2254 定义）。
例如，如果此选项设置为
(uid={0})，并且收到的用户名是jdoe，则搜索过滤器会在字符串替换后变为(uid=jdoe)。
如果生成的搜索过滤器应用到用户 base,
ou=User,ou=ActiveMQ,ou=system指定的子树中，它将与条目uid=jdoe,ou=User,ou=ActiveMQ,ou=system匹配。
roleSearchMatching这的工作方式与
userSearchMatching选项类似，但它支持两个替换字符串。
替换字符串
{0}替换匹配用户条目的完整 DN （即用户搜索的结果）。例如，对于用户jdoe，替换的字符串可以是uid=jdoe,ou=User,ou=ActiveMQ,ou=system。
替换字符串
{1}会替换接收到的用户名。例如，jdoe.
如果此选项设为
(member=uid={1})，且接收到的用户名为jdoe，在进行了字符串替换后，搜索过滤器变为(member=uid=jdoe)（假设使用 ApacheDS 搜索过滤器语法）。
如果生成的搜索过滤器被应用由角色基础 (
ou=Group,ou=ActiveMQ,ou=system) 所选择的子树，它将匹配具有member属性等于uid=jdoe(member属性的值是一个 DN)。
必须始终设置这个选项，即使角色搜索被禁用，因为它没有默认值。如果使用 OpenLDAP，搜索过滤器的语法为
(member:=uid=jdoe)。
其他资源
- 有关搜索过滤器语法的简短介绍，请参阅 Oracle JNDI 教程。
5.4.2. 配置 LDAP 授权
LegacyLDAPSecuritySettingPlugin 安全设置插件读取之前在 AMQ 6 中由 LDAPAuthorizationMap 和 cachedLDAPAuthorizationMap 控制的安全信息，并在可能的情况下将这个信息转换为对应的 AMQ 7 安全设置。
AMQ 6 和 AMQ 7 中代理的安全实现与 AMQ 7 中不匹配。因此，插件在两个版本之间执行一些转换，以实现接近等效的功能。
以下示例演示了如何配置插件。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
security-settings元素内，添加security-setting-plugin元素。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow class-name-
实施是
org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin。 initialContextFactory-
用于连接到 LDAP 的初始上下文工厂。它必须始终设置为
com.sun.jndi.ldap.LdapCtxFactory（即默认值）。 connectionURL-
使用 LDAP URL 指定目录服务器的位置，<ldap://Host:Port> ;。您可选择通过添加正斜杠
/，后跟目录树中特定节点的可分辨名称(DN)来选择性地验证此 URL。例如：ldap://ldapserver:10389/ou=system。默认值为ldap://localhost:1024。 connectionUsername-
打开到目录服务器连接的用户的 DN。例如：
uid=admin,ou=system。目录服务器通常需要客户端提供用户名/密码凭据才能打开连接。 connectionPassword-
与来自
connectionUsername的 DN 匹配的密码。在目录服务器中，在 Directory Information Tree (DIT)中，密码通常以userPassword属性存储在对应的目录条目中。 connectionProtocol- 当前未使用。以后，这个选项可能会允许您选择与目录服务器的连接的安全套接字层(SSL)。必须明确设置这个选项，因为它没有默认值。
身份验证指定绑定到 LDAP 服务器时使用的验证方法。此参数的有效值为
simple（用户名和密码）或none（匿名）。默认值为simple。注意不支持 简单身份验证和安全层(SASL)身份验证。
上述配置示例中没有显示的其他设置有：
destinationBase-
指定其子对象为所有目的地提供权限的节点 DN。在这种情况下，DN 是一个字面值（即，没有对属性值执行字符串替换）。例如，此属性的典型值为
ou=destinations,o=ActiveMQ,ou=system。默认值为ou=destinations,o=ActiveMQ,ou=system。 filter-
指定 LDAP 搜索过滤器，它会在查找任何类型的目的地时使用该过滤器。搜索过滤器会尝试匹配队列或主题节点的其中一个子或后代。默认值为
(cn=*)。 roleAttribute-
指定节点的一个属性，它匹配其值是一个角色的 DN 的
filter。默认值为uniqueMember。 adminPermissionValue-
指定与
admin权限匹配的值。默认值为admin。 readPermissionValue-
指定匹配
read权限的值。默认值为读取。 writePermissionValue-
指定匹配
write权限的值。默认值为write。 enableListener-
指定是否启用自动接收 LDAP 服务器中的更新的监听程序，并实时更新代理的授权配置。默认值为
true。 mapAdminToManage指定是否将传统（即 AMQ 6）
admin的权限映射到 AMQ 7manage权限。下表中的映射语义的详情。默认值为false。LDAP 中定义的队列或主题的名称充当安全设置的"匹配"，权限值将从 AMQ 6 类型映射到 AMQ 7 类型，并且角色映射为 as-is。由于 LDAP 中定义的队列或主题的名称充当 security 设置的匹配项，因此安全性设置可能无法像 JMS 目的地一样应用。这是因为 AMQ 7 始终根据需要为 JMS 目的地添加前缀 "jms.queue." 或 "jms.topic."。
AMQ 6 有三种权限类型 -
读取、写和admin。ActiveMQ 网站( 安全 )上描述了这些权限类型。AMQ 7 有以下权限类型：
-
createAddress -
deleteAddress -
createDurableQueue -
deleteDurableQueue -
createNonDurableQueue -
deleteNonDurableQueue -
send -
Consume -
管理 浏览下表显示了安全设置插件如何将 AMQ 6 权限类型映射到 AMQ 7 权限类型：
Expand 表 5.3. 将 AMQ 6 权限类型映射到 AMQ 7 AMQ 6 权限类型 AMQ 7 权限类型 读取
使用、浏览
write
send
admin
createAddress, deleteAddress, createDurableQueue, deleteDurableQueue, createNonDurableQueue, deleteNonDurableQueue, manage (if
mapAdminToManageis set totrue)如下所述，在一些情况下，插件在 AMQ 6 和 AMQ 7 权限类型之间执行一些转换来实现等效性：
-
默认情况下，映射不包括 AMQ 7
管理权限类型，因为 AMQ 6 中没有类似的权限类型。但是，如果mapAdminToManage设为true，则该插件会将 AMQ 6admin权限映射到 AMQ 7管理权限。 -
AMQ 6 中的
admin权限类型决定代理是否自动创建一个目的地（如果目的地不存在），并且用户会向它发送消息。如果用户有向目的地发送消息的权限，AMQ 7 会自动允许自动创建目的地。因此，插件默认将旧的admin权限映射到上述 AMQ 7 权限。如果mapAdminToManage设为true，则该插件也会将 AMQ 6admin权限映射到 AMQ 7manage权限。
-
默认情况下，映射不包括 AMQ 7
-
allowQueueAdminOnRead是否将旧的读取权限映射到 createDurableQueue、createNonDurableQueue 和 deleteDurableQueue 权限，以便 JMS 客户端可以在不需要 admin 权限的情况下创建持久和非持久性订阅。这是 AMQ 6 中允许的。默认值为 false。
下表显示了当
allowQueueAdminOnRead为true时，安全设置插件如何将 AMQ 6 权限类型映射到 AMQ 7 权限类型：Expand 表 5.4. 当 allowQueueAdminOnRead 为 true时，将 AMQ 6 权限类型映射到 AMQ 7 AMQ 6 权限类型 AMQ 7 权限类型 读取
consume, browse, createDurableQueue, createNonDurableQueue, deleteDurableQueue
write
send
admin
createAddress, deleteAddress, deleteNonDurableQueue, manage （如果
mapAdminToManage设置为true）
5.4.3. 在 login.config 文件中加密密码
因为机构通常使用 LDAP 安全地存储数据，所以 login.config 文件可以包含代理与机构的 LDAP 服务器通信所需的配置。此配置文件通常包含登录 LDAP 服务器的密码，因此需要加密此密码。
先决条件
-
确保您已修改了
login.config文件来添加所需属性，如 第 5.4.2 节 “配置 LDAP 授权” 所述。
流程
以下流程演示了如何屏蔽 < broker_instance_dir> /etc/login.config 文件中的 connectionPassword 参数的值。
在命令提示符中，使用
mask工具来加密密码：<broker_instance_dir>/bin/artemis mask <password>
$ <broker_instance_dir>/bin/artemis mask <password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow result: 3a34fd21b82bf2a822fa49a8d8fa115d
result: 3a34fd21b82bf2a822fa49a8d8fa115dCopy to Clipboard Copied! Toggle word wrap Toggle overflow 打开 &
lt;broker_instance_dir> /etc/login.config文件。找到connectionPassword参数：connectionPassword = <password>
connectionPassword = <password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 将明文密码替换为加密值：
connectionPassword = 3a34fd21b82bf2a822fa49a8d8fa115d
connectionPassword = 3a34fd21b82bf2a822fa49a8d8fa115dCopy to Clipboard Copied! Toggle word wrap Toggle overflow 使用标识符
"ENC （）"嵌套加密值：connectionPassword = "ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"
connectionPassword = "ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
login.config 文件现在包含屏蔽的密码。由于密码使用 "ENC （）" 标识符嵌套，因此 AMQ Broker 在使用前对其进行解密。
其他资源
- 有关 AMQ Broker 中包含的配置文件的更多信息，请参阅 AMQ Broker 配置文件和位置。
5.4.4. 映射外部角色
您可以将外部身份验证供应商（如 LDAP）的角色映射到代理内部使用的角色。
要映射外部角色，请在 broker.xml 配置文件中的 security-settings 项中创建 role-mapping 条目。例如：
<security-settings>
...
<role-mapping from="cn=admins,ou=Group,ou=ActiveMQ,ou=system" to="my-admin-role"/>
<role-mapping from="cn=users,ou=Group,ou=ActiveMQ,ou=system" to="my-user-role"/>
</security-settings>
<security-settings>
...
<role-mapping from="cn=admins,ou=Group,ou=ActiveMQ,ou=system" to="my-admin-role"/>
<role-mapping from="cn=users,ou=Group,ou=ActiveMQ,ou=system" to="my-user-role"/>
</security-settings>- 角色映射是添加的。这意味着用户将保留原始角色以及新分配的角色。
- 角色映射仅影响授权队列访问的角色，不提供启用 Web 控制台访问的方法。
5.5. 使用 Kerberos 进行身份验证和授权
使用 AMQP 协议发送和接收消息时，客户端可以使用 Simple Authentication and Security Layer (SASL)框架中的 GSSAPI 机制发送 Kerberos 安全凭证。Kerberos 凭据也可用于授权，方法是将经过身份验证的用户映射到 LDAP 目录或基于文本的属性文件中配置的分配角色。
您可以将 SASL 与 传输层安全 (TLS)一起使用，以保护您的消息传递应用程序。SASL 提供用户身份验证，TLS 提供数据完整性。
在 AMQ Broker 可以验证和授权 Kerberos 凭证前，您必须部署和配置 Kerberos 基础架构。有关部署 Kerberos 的更多信息，请参阅您的操作系统文档。
- 对于 RHEL 7，请参阅使用 Kerberos。
- 对于 Windows，请参阅 Kerberos 身份验证概述。
- Oracle 或 IBM JDK 的用户应安装 Java Cryptography 扩展(JCE)。如需更多信息，请参阅 Oracle version of the JCE 或 IBM version of the JCE。
以下流程演示了如何为身份验证和授权配置 Kerberos。
5.5.1. 配置网络连接以使用 Kerberos
AMQ Broker 使用 简单身份验证和安全层 (SASL)框架中的 GSSAPI 机制与 Kerberos 安全凭证集成。要在 AMQ Broker 中使用 Kerberos，每个接受者验证或授权使用 Kerberos 凭证的客户端都必须配置为使用 GSSAPI 机制。
下面的步骤演示了如何配置接受器来使用 Kerberos。
先决条件
- 在 AMQ Broker 可以验证和授权 Kerberos 凭证前，您必须部署和配置 Kerberos 基础架构。
流程
停止代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 将 name-value 对
saslMechanisms=GSSAPI添加到acceptor的 URL 的查询字符串中。<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI </acceptor>
<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI </acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 上述配置意味着，acceptor 在验证 Kerberos 凭据时使用 GSSAPI 机制。
（可选）支持
PLAIN和ANONYMOUSSASL 机制。要指定多个机制，请使用逗号分隔的列表。例如：<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN </acceptor>
<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN </acceptor>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 结果是一个接受者，它使用
GSSAPI和PLAINSASL 机制。启动代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 有关 acceptors 的详情，请参考 第 2.1 节 “关于接受者”。
5.5.2. 使用 Kerberos 凭证验证客户端
AMQ Broker 支持 AMQP 连接的 Kerberos 身份验证，它们使用来自 简单身份验证和安全层 (SASL)框架的 GSSAPI 机制。
代理使用 Java 身份验证和授权服务 (JAAS)获取其 Kerberos 接收器凭证。Java 安装中包含的 JAAS 库与验证 Kerberos 凭证的登录模块 Krb5LoginModule 打包。有关 Krb5LoginModule 的更多信息，请参阅 Java 供应商中的文档。例如，Oracle 提供了关于其 Krb5LoginModule 登录模块的信息，作为其 Java 8 文档 的一部分。
先决条件
- 您必须启用接收器的 GSSAPI 机制，然后才能使用 Kerberos 安全凭证验证 AMQP 连接。更多信息请参阅 第 5.5.1 节 “配置网络连接以使用 Kerberos”。
流程
停止代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
打开 &
lt;broker_instance_dir> /etc/login.config配置文件。 添加名为
amqp-sasl-gssapi的配置范围。以下示例显示了在 JDK 的 Oracle 和 OpenJDK 版本中找到的Krb5LoginModule的配置。Copy to Clipboard Copied! Toggle word wrap Toggle overflow amqp-sasl-gssapi-
默认情况下，代理上的 GSSAPI 机制实现使用名为
amqp-sasl-gssapi的 JAAS 配置范围来获取其 Kerberos 接受器凭证。 Krb5LoginModule-
Krb5LoginModule的版本由 JDK 的 Oracle 和 OpenJDK 版本提供。通过引用 Java 供应商中的文档，验证Krb5LoginModule及其可用选项的完全限定类名称。 useKeyTab-
Krb5LoginModule配置为在验证主体时使用 Kerberos keytab。使用 Kerberos 环境中的工具生成 keytab。有关生成 Kerberos keytab 的详情，请查看厂商中的文档。 principal-
Principal 设置为
amqp/my_broker_host@example.com。这个值必须与 Kerberos 环境中创建的服务主体对应。有关创建服务主体的详情，请查看厂商中的文档。
启动代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
5.5.2.1. 使用其他配置范围
您可以通过将参数 saslLoginConfigScope 添加到 AMQP acceptor 的 URL 来指定备选配置范围。在以下配置示例中，参数 saslLoginConfigScope 被授予值 alternative-sasl-gssapi。结果是一个接受者，它使用名为 alternative 范围 alternative-sasl-gssapi，在 < broker_instance_dir>/etc/login.config 配置文件中声明。
<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN;saslLoginConfigScope=alternative-sasl-gssapi` </acceptor>
<acceptor name="amqp">
tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN;saslLoginConfigScope=alternative-sasl-gssapi`
</acceptor>5.5.3. 使用 Kerberos 凭证授权客户端
AMQ Broker 包括 JAAS Krb5LoginModule 登录模块的实现，用于在映射角色时供其他安全模块使用。模块将 Kerberos 验证的 Peer Principal 添加到主题的主体集中为 AMQ Broker UserPrincipal。然后，凭证可以传递给 PropertiesLoginModule 或 LDAPLoginModule 模块，它将 Kerberos 验证的 Peer Principal 映射到 AMQ Broker 角色。
Kerberos Peer Principal 没有以代理用户形式存在，仅作为角色成员存在。
先决条件
- 您必须启用 acceptor 的 GSSAPI 机制，然后才能使用 Kerberos 安全凭证授权 AMQP 连接。
流程
停止代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
打开 &
lt;broker_instance_dir> /etc/login.config配置文件。 添加 AMQ Broker
Krb5LoginModule和LDAPLoginModule的配置。通过引用 LDAP 供应商的文档来验证配置选项。示例配置如下所示：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意上例中显示的
Krb5LoginModule版本随 AMQ Broker 一起分发，并将 Kerberos 身份转换为代理身份，供其他 AMQ 模块用于角色映射。启动代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 有关在 AMQ Broker 中启用 GSSAPI 机制的更多信息，请参阅 第 5.5.1 节 “配置网络连接以使用 Kerberos”。
-
有关
PropertiesLoginModule的更多信息，请参阅 第 5.2.2.1 节 “配置基本用户和密码身份验证”。 -
有关
LDAPLoginModule的更多信息，请参阅 第 5.4.1 节 “配置 LDAP 以验证客户端”。
5.6. 指定安全管理器
代理使用一个名为安全管理器的组件来处理身份验证和授权。
AMQ Broker 包括两个安全管理器：
-
ActiveMQJAASSecurityManager安全管理器。此安全管理器提供与 JAAS 和 Red Hat JBoss Enterprise Application Platform (JBoss EAP)安全性的集成。这是 AMQ Broker 使用的默认安全管理器。 -
ActiveMQBasicSecurityManager安全管理器.这个基本安全管理器不支持 JAAS。相反，它支持通过用户名和密码凭据进行身份验证和授权。此安全管理器支持使用管理 API 添加、删除和更新用户。所有用户和角色数据都存储在代理绑定日志中。这意味着，对活跃代理所做的任何更改也适用于其被动备份代理。
作为包含的安全管理器的替代选择，系统管理员可能需要对代理安全实施进行更多控制。在这种情况下，也可以在代理配置中指定 自定义 安全管理器。自定义安全管理器是一个用户定义的类，它实现了 org.apache.activemq.artemis.core.security.ActiveMQSecurityManager5 接口。
以下子小节中的示例演示了如何配置要使用的代理：
- 基本安全管理器而不是默认的 JAAS 安全管理器
- 自定义安全管理器
5.6.1. 使用基本安全管理器
除了默认的 ActiveMQJAASSecurityManager 安全管理器外，AMQ Broker 还包括 ActiveMQBasicSecurityManager 安全管理器。
使用基本安全管理器时，所有用户和角色数据都存储在绑定日志中（如果您正在使用 JDBC 持久性，则绑定 表 ）因此，如果您配置了 primary-backup 代理组，则您在主代理上执行的任何用户管理都会在故障转移时自动反映在备份代理中。这可避免单独管理 LDAP 服务器，这是实现此行为的替代方法。
在配置和使用基本安全管理器前，请注意以下几点：
- 基本安全管理器不像默认的 JAAS 安全管理器一样可插拔。
- 基本安全管理器不支持 JAAS。相反，它只支持通过用户名和密码凭证进行身份验证和授权。
-
AMQ 管理控制台需要 JAAS。因此，如果您使用基本的安全管理器并希望使用控制台，您还需要为用户和密码身份验证配置
login.config配置文件。有关配置用户和密码身份验证的详情，请参考 第 5.2.2.1 节 “配置基本用户和密码身份验证”。 - 在 AMQ Broker 中，用户管理由代理管理 API 提供。此管理包括添加、列出、更新和删除用户和角色的功能。您可以使用 JMX、管理消息、HTTP （使用 Jolokia 或 AMQ 管理控制台）和 AMQ Broker 命令行界面来执行这些功能。由于代理直接存储此数据，因此代理必须正在运行才能管理用户。无法手动修改绑定数据。
- 任何通过 HTTP 的管理访问（例如，使用 Jolokia 或 AMQ 管理控制台）都由控制台 JAAS 登录模块处理。通过 JConsole 或其他远程 JMX 工具的访问由基本的安全管理器处理。管理消息由基本安全管理器处理。
5.6.1.1. 配置基本安全管理器
以下流程演示了如何将代理配置为使用基本安全管理器。
流程
-
打开 &
lt;broker-instance-dir> /etc/boostrap.xml配置文件。 在
security-manager元素中，为class-name属性指定完整的ActiveMQBasicSecurityManager类名称。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 因为您无法手动修改包含用户和角色数据的绑定数据，并且因为代理必须正在运行才能管理用户，因此建议在第一次引导时保护代理。要达到此目的，请定义一个 bootstrap 用户，然后使用它来添加其他用户。
在
security-manager元素中，添加bootstrapUser,bootstrapPassword, 和bootstrapRole属性，并指定值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow bootstrapUser- bootstrap 用户的名称。
bootstrapPassword- boostrap 用户的 Passsword。您还可以指定加密的密码。
bootstrapRoleboostrap 用户的角色。
注意如果您在配置中为 bootstrap 用户定义前面的属性，则每次启动代理时都会设置这些凭证，无论您在代理运行时所做的任何更改。
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
broker.xml配置文件中，找到为activemq.management#地址匹配默认定义的address-setting元素。这些默认地址设置如下所示：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在为
activemq.management#地址匹配的地址设置中，对于您在此流程前面指定的 bootstrap 角色名称，添加以下所需的权限：-
createNonDurableQueue -
createAddress -
Consume -
管理 -
send
例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
其他资源
-
有关
ActiveMQBasicSecurityManager类的更多信息，请参阅 ActiveMQ Artemis 核心 API 文档中的类 ActiveMQBasicSecurityManager。 - 要了解如何在配置文件中加密密码，请参阅 第 5.10 节 “在配置文件中加密密码”。
5.6.2. 指定自定义安全管理器
以下流程演示了如何在代理配置中指定自定义安全管理器。
流程
-
打开 &
lt;broker_instance_dir> /etc/boostrap.xml配置文件。 在
security-manager元素中，对于class-name属性，指定org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager5接口用户定义的实现的类。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
-
有关
ActiveMQSecurityManager5接口的更多信息，请参阅 ActiveMQ Artemis Core API 文档中的接口 ActiveMQSecurityManager5。
5.6.3. 运行自定义安全管理器示例程序
AMQ Broker 有一个示例程序，它演示了如何实现自定义安全管理器。在示例中，自定义安全管理器会记录身份验证和授权的详细信息，然后将详细信息传递到 ActiveMQJAASSecurityManager 实例（即默认安全管理器）。
以下流程演示了如何运行自定义安全管理器示例程序。
先决条件
- 您的机器被设置为运行 AMQ Broker 示例程序。如需更多信息，请参阅 运行 AMQ Broker 示例。
您下载了 自定义安全管理器示例。
流程
导航到包含自定义安全管理器示例的目录。以下示例假设您将示例下载到名为
amq-broker-examples的目录。cd amq-broker-examples/examples/features/standard/security-manager
$ cd amq-broker-examples/examples/features/standard/security-managerCopy to Clipboard Copied! Toggle word wrap Toggle overflow 运行示例。
mvn verify
$ mvn verifyCopy to Clipboard Copied! Toggle word wrap Toggle overflow
如果要在运行示例程序时手动创建并启动代理实例，请将上一步中的命令替换为 mvn -PnoServer verify。
其他资源
-
有关
ActiveMQJAASSecurityManager类的更多信息，请参阅 ActiveMQ Artemis Core API 文档中的 Class ActiveMQJAASSecurityManager。
5.7. 禁用安全性
默认启用 安全性。以下流程演示了如何禁用代理安全性。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，将security-enabled的值设置为false。<security-enabled>false</security-enabled>
<security-enabled>false</security-enabled>Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
如有必要，为
security-invalidation-interval指定一个新的值（以毫秒为单位）。此属性的值指定代理定期使安全登录无效。默认值为10000。
5.8. 禁用 FIPS 模式
Federal Information Processing Standard (FIPS) Publication 140-3 是一个标准，用于指定应用程序中使用的加密模块的安全要求。AMQ Broker 是 FIPS-tolerant，这意味着它在启用了 FIPS 的 RHEL 系统上自动运行。如果要允许代理接受使用非FIPS 兼容算法的客户端的连接，您可以在代理中禁用 FIPS 模式。如果您禁用 FIPS 模式，代理可以加载不兼容 FIPS 的加密模块。
如果代理使用 Red Hat build of OpenJDK，您可以使用以下步骤添加 Java 系统属性来禁用 FIPS 模式。如果代理没有使用红帽构建的 OpenJDK，您可以在操作系统级别禁用 FIPS。如需更多信息，请参阅 将 RHEL 切换到 FIPS 模式。
流程
-
打开 &
lt;broker_instance_dir>/etc/artemis.profile文件。 将以下参数添加到 Java 系统属性的
JAVA_ARGS列表中，以禁用代理上的 FIPS。-Dcom.redhat.fips=false
-Dcom.redhat.fips=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
保存
artemis.profile文件。
5.9. 跟踪来自验证的用户的消息
要启用跟踪并记录消息的来源（例如，对于安全审核目的），您可以使用 _AMQ_VALIDATED_USER 消息键。
在 broker.xml 配置文件中，如果 populate-validated-user 选项被设置为 true，则代理将使用 _AMQ_VALIDATED_USER 键将经过验证的用户的名称添加到消息中。对于 JMS 和 STOMP 客户端，此消息键映射到 JMSXUserID 密钥。
代理无法将经过验证的用户名添加到由 AMQP JMS 客户端生成的消息中。在客户端发送后修改 AMQP 消息的属性违反了 AMQP 协议。
对于基于其 SSL 证书进行身份验证的用户，由代理填充的验证用户名是证书的可辨识名称(DN)映射的名称。
在 broker.xml 配置文件中，如果启用了 security-enabled 为 false，并且 populate-validated-user 为 true，则代理会填充任何用户名（若有的话）。populate-validated-user 选项默认为 false。
您可以将代理配置为拒绝在发送消息时没有用户名（即 JMSXUserID 密钥）的消息。您可能会发现此选项对 AMQP 客户端很有用，因为代理无法为这些客户端发送的消息填充经过验证的用户名本身。
要将代理配置为拒绝客户端未设置 JMSXUserID 的消息，请将以下配置添加到 broker.xml 配置文件中：
<reject-empty-validated-user>true</reject-empty-validated-user>
<reject-empty-validated-user>true</reject-empty-validated-user>
默认情况下，reject-empty-validated-user 设置为 false。
5.10. 在配置文件中加密密码
默认情况下，AMQ Broker 将所有密码以纯文本形式存储在配置文件中。务必确保确保确保具有正确权限的所有配置文件，以防止未经授权的访问。您还可以加密或 屏蔽 纯文本密码，以防止不需要的查看器读取它们。
5.10.1. 关于加密密码
加密或 屏蔽 的 密码是纯文本密码的加密版本。加密的版本由 AMQ Broker 提供的 mask 命令行工具生成。有关 mask 工具的更多信息，请参阅命令行帮助文档：
<broker_instance_dir>/bin/artemis help mask
$ <broker_instance_dir>/bin/artemis help mask
要屏蔽密码，将其纯文本值替换为加密的值。屏蔽的密码必须由标识符 ENC （） 包装，以便在需要实际值时解密它。
在以下示例中，配置文件 < broker_instance_dir>/etc/bootstrap.xml 包含 keyStorePassword 和 trustStorePassword 参数的屏蔽密码。
<web bind="https://localhost:8443" path="web"
keyStorePassword="ENC(-342e71445830a32f95220e791dd51e82)"
trustStorePassword="ENC(32f94e9a68c45d89d962ee7dc68cb9d1)">
<app url="activemq-branding" war="activemq-branding.war"/>
</web>
<web bind="https://localhost:8443" path="web"
keyStorePassword="ENC(-342e71445830a32f95220e791dd51e82)"
trustStorePassword="ENC(32f94e9a68c45d89d962ee7dc68cb9d1)">
<app url="activemq-branding" war="activemq-branding.war"/>
</web>您可以在以下配置文件中使用屏蔽的密码。
- broker.xml
- bootstrap.xml
- management.xml
- artemis-users.properties
-
login.config （用于
LDAPLoginModule）
配置文件位于 < broker_instance_dir>/etc。
artemis-users.properties 仅支持已哈希的屏蔽密码。当用户在创建代理时，artemis-users.properties 默认包含哈希密码。默认 PropertiesLoginModule 不会解码 artemis-users.properties 文件中的密码，而是对输入进行哈希处理并比较两个用于密码验证的散列值。将哈希密码改为屏蔽的密码不允许访问 AMQ Broker 管理控制台。
broker.xml,bootstrap.xml,management.xml, 和 login.config 支持密码被屏蔽但不会被哈希处理。
5.10.2. 在配置文件中加密密码
以下示例演示了如何在 broker.xml 配置文件中屏蔽 cluster-password 的值。
流程
在命令提示符中，使用
mask工具来加密密码：<broker_instance_dir>/bin/artemis mask <password>
$ <broker_instance_dir>/bin/artemis mask <password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow result: 3a34fd21b82bf2a822fa49a8d8fa115d
result: 3a34fd21b82bf2a822fa49a8d8fa115dCopy to Clipboard Copied! Toggle word wrap Toggle overflow 打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件，其中包含您要屏蔽的纯文本密码：<cluster-password> <password> </cluster-password>
<cluster-password> <password> </cluster-password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 将明文密码替换为加密值：
<cluster-password> 3a34fd21b82bf2a822fa49a8d8fa115d </cluster-password>
<cluster-password> 3a34fd21b82bf2a822fa49a8d8fa115d </cluster-password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用标识符
ENC （）将加密值嵌套：<cluster-password> ENC(3a34fd21b82bf2a822fa49a8d8fa115d) </cluster-password>
<cluster-password> ENC(3a34fd21b82bf2a822fa49a8d8fa115d) </cluster-password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
配置文件现在包含加密的密码。由于密码使用 ENC （） 标识符嵌套，因此 AMQ Broker 在使用前对其进行解密。
其他资源
- 有关 AMQ Broker 中包含的配置文件的更多信息，请参阅 第 1.1 节 “AMQ Broker 配置文件和位置”。
5.10.3. 设置 codec 密钥以加密和解密密码
需要使用 codec 来加密和解密密码。如果没有配置自定义 codec，掩码 工具使用默认的 codec 来加密密码，AMQ Broker 使用相同的默认 codec 来解密密码。codec 配置了默认密钥，它提供底层加密算法来加密和解密密码。使用默认密钥会公开一个风险，这些密钥可能会被恶意的参与者用来解密您的密码。
当您使用 掩码 实用程序加密密码时，您可以指定自己的密钥字符串以避免使用默认的 codec 密钥。然后，您必须在 ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY 环境变量中设置相同的密钥字符串，以便代理可以解密密码。在环境变量中设置密钥可使其更安全，因为它不会在配置文件中保留。另外，您可以在启动代理前立即设置密钥，并在代理启动后立即取消设置它。
流程
使用
mask实用程序加密配置文件中的每个密码。对于key参数，指定用于加密密码的字符串。使用相同的密钥字符串加密每个密码。<broker_instance_dir>/bin/artemis mask --key <key> <password>
$ <broker_instance_dir>/bin/artemis mask --key <key> <password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 警告确保您在运行
mask工具时指定的密钥字符串记录来加密密码。您必须在环境变量中配置相同的键值，以允许代理解密密码。有关在配置文件中加密密码的更多信息，请参阅 第 5.10.2 节 “在配置文件中加密密码”。
在命令提示符中，将
ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY环境变量设置为您在加密每个密码时指定的密钥字符串。export ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY= <key>
$ export ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY= <key>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 启动代理。
./artemis run
$ ./artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 取消设置
ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY环境变量。unset ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY
$ unset ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEYCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果在启动代理后取消设置
ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY环境变量，您必须在每次启动代理前将其再次设置为同一密钥字符串。
5.11. 配置身份验证和授权缓存
默认情况下，AMQ Broker 将身份验证和授权响应成功的信息存储在单独的缓存中。您可以更改每个缓存中允许的默认条目数，以及缓存条目的持续时间。
-
打开 &
lt;broker-instance-dir>/etc/broker.xml配置文件。 要更改默认条目的最大数量
1000，在每个缓存中允许，请设置authentication-cache-size和authorization-cache-size参数。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果缓存达到设定的限制，则从缓存中删除最早使用的条目。
要更改默认持续时间(
10000毫秒)，用于缓存条目，请设置security-invalidation-interval参数。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果将
security-invalidation-interval参数设置为0，则禁用身份验证和授权缓存。
第 6 章 持久性消息数据
对于持久性（ storing）消息数据，AMQ Broker 有两个选项。
另外，您还可以将代理配置为 保留 任何消息数据。更多信息请参阅 第 6.3 节 “禁用持久性”。
代理使用不同的解决方案来持久保留消息日志之外的大型消息。请参阅 第 8 章 处理大型消息 了解更多信息。
代理也可以在低内存情况下配置为将信息分页到磁盘。请参阅 第 7.1 节 “配置消息分页” 了解更多信息。
有关 AMQ Broker 支持哪些数据库和网络文件系统的当前信息，请参阅红帽客户门户网站中的 Red Hat AMQ 7 支持的配置。
6.1. 在日志中保留消息数据
代理日志是磁盘上 一组仅 附加文件。每个文件都预先创建为固定大小，最初使用 padding 填充。当消息传递操作在代理上执行时，记录会附加到日志的末尾。附加记录允许代理最小化磁盘头移动和随机访问操作，通常是磁盘上的最慢的操作。当一个日志文件满时，代理会创建一个新日志文件。
日志文件大小是可配置的，从而最大程度减少每个文件使用的磁盘 cylinders 数。但是，现代磁盘拓扑比较复杂，代理无法控制文件映射到哪个循环。因此，日志文件大小难以精确控制。
代理使用的其他与持久性相关的功能有：
- 确定特定日志文件是否仍在使用的 垃圾回收 算法。如果日志文件不再使用，代理可以回收文件以供重复使用。
- 从日志中删除死空间并压缩数据的压缩算法。这会导致磁盘上使用较少的文件的日志。
- 支持本地事务。
- 在使用 JMS 客户端时支持扩展架构(XA)事务。
大多数日志都是以 Java 编写的。但是，与实际文件系统交互是抽象的，因此您可以使用不同的可插拔的实现。AMQ Broker 包括以下实现：
- NIO
- NIO （新 I/O）使用标准的 Java NIO 与文件系统接口。这提供了非常好的性能，并在具有 Java 6 或更高版本运行时的任何平台上运行。有关 Java NIO 的更多信息，请参阅 Java NIO。
- AIO
AIO (Aynshcronous I/O)使用精简原生打包程序与 Linux Asynchronous I/O 库(
libaio)进行通信。使用 AIO 时，代理会在数据进入磁盘后调用回来，从而避免了显式同步。默认情况下，代理尝试使用 AIO 日志，并在 AIO 不可用时回退到使用 NIO。与 Java NIO 相比，AIO 通常提供更好的性能。要了解如何安装
libaio，请参阅 第 6.1.1 节 “安装 Linux 同步 I/O 库”。
以下子小节中的流程演示了如何为基于日志的持久性配置代理。
6.1.1. 安装 Linux 同步 I/O 库
红帽建议使用 AIO 日志（而不是 NIO）来提高持久性性能。
无法与其他操作系统或早期版本的 Linux 内核一起使用 AIO 日志。
要使用 AIO 日志，您必须安装 Linux Asynchronous I/O 库(libaio)。要安装 libaio，请使用 yum 命令，如下所示：
yum install libaio
yum install libaio6.1.2. 配置基于日志的持久性
以下流程描述了如何查看代理用于基于日志的持久性的默认配置。您可以根据需要使用此描述来调整配置。
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。默认情况下，代理配置为使用基于日志的持久性，如下所示。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 启用持久性-
如果此参数的值设置为
true，代理将使用基于文件的日志进行消息持久性。 journal-type-
要使用的日志类型。如果设置为
ASYNCIO，代理首先会尝试使用 AIO。如果没有找到 AIO，代理将使用 NIO。 bindings-directory-
绑定日志的文件系统位置。默认值相对于 <
broker_instance_dir>目录。 journal-directory-
消息日志的文件系统位置。默认值相对于 <
broker_instance_dir>目录。 journal-datasync-
如果此参数的值被设置为
true，代理将使用fdatasync功能来确认磁盘写入。 journal-min-files- 代理启动时初始创建的日志文件数量。
journal-pool-files-
回收未使用的文件后要保留的文件数。默认值
-1表示在清理过程中不会删除任何文件。 journal-device-block-size- 存储设备上日志使用的数据块的最大大小（以字节为单位）。默认值为 4096 字节。
journal-file-size- 指定日志目录中每个日志文件的最大大小（以字节为单位）。当达到这个限制时，代理会启动新文件。这个参数还支持字节表示法（如 K、M、G）或二进制等效(Ki、Mi、Gi)。如果您的配置中没有指定此参数，则默认值为 10485760 字节(10MiB)。
journal-buffer-timeout- 指定代理清除日志缓冲区的频率（以纳秒为单位）。AIO 通常使用高于 NIO 的清空率，因此代理为 NIO 和 AIO 维护不同的默认值。如果未在配置中明确指定此参数，则 NIO 的默认值是 3333333 纳秒（每秒 300 次）。AIO 的默认值为 50000 纳秒（每秒 2000 次）。
journal-max-io最多可在 IO 队列中的写入请求数。如果队列已满，代理会阻止进一步的写入，直到有可用空间为止。
如果您使用 NIO，则该值应始终为
1。如果您使用 AIO，且此参数未在配置中明确指定，则默认值为500。
- 根据上述描述，根据您的存储设备的要求调整您的持久性配置。
其他资源
- 要了解可用于配置基于日志的持久性的所有参数，请参阅 附录 E, 消息传递日志配置元素。
6.1.3. 关于绑定日志
绑定日志用于存储与绑定相关的数据，如代理上部署的队列集合及其属性。它还存储 ID 序列计数器等数据。
绑定日志始终使用 NIO，因为与消息日志相比，它通常会降低吞吐量。此日志上的文件前缀为 activemq-bindings。每个文件的扩展也具有 .bindings，默认大小为 1048576 字节。
要配置绑定日志，请在 < broker_instance_dir> /etc/broker.xml 配置文件的 核心元素 中包含以下参数。
bindings-directory-
绑定日志的目录。默认值为 <
broker_instance_dir>/data/bindings。 create-bindings-dir-
如果此参数的值被设置为
true，则代理会在bindings-directory中指定的位置上自动创建绑定目录（如果它尚不存在）。默认值为true。
6.1.4. 关于 JMS 日志
JMS 日志存储所有与 JMS 相关的数据，包括 JMS 队列、主题和连接工厂，以及这些资源的任何 JNDI 绑定。通过管理 API 创建的任何 JMS 资源都保留至此日志中，但任何通过配置文件配置的资源都不会被保留。只有在使用 JMS 时，代理才会创建 JMS 日志。
JMS 日志中的文件前缀为 activemq-jms。每个文件的扩展也具有 .jms，默认大小为 1048576 字节。
JMS 日志与绑定日志共享其配置。
其他资源
- 有关绑定日志的详情，请参考 第 6.1.3 节 “关于绑定日志”。
6.1.5. 配置日志保留
您可以将 AMQ Broker 配置为保留每个创建的日志文件的副本。配置日志保留后，您可以重新执行日志文件副本中的消息，以将消息发送到代理。
6.1.5.1. 配置日志保留
您可以将 AMQ Broker 配置为在特定时间段内保留日志文件副本，或直到达到存储限制或两者为止。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 -
在
core元素内，添加journal-retention-directory属性。指定控制日志文件的保留或两者。此外，指定日志文件副本的文件系统位置。以下示例将 AMQ Broker 配置为将日志文件副本保存在期间或存储限制data/retention目录中7天，或直到文件使用10GB存储。
周期- 保存日志文件副本的时间周期。当时间段过期时，AMQ Broker 会删除超过指定时间段的任何文件。
unit-
应用到保留周期的测量单位。默认值为
DAYS。其他有效的值为HOURS、MINUTES和SECONDS。 目录- 日志文件复制的文件系统位置。指定目录相对于 < broker_instance_dir> 目录。
storage-limit- 所有日志文件副本可以使用的最大存储。如果达到存储限制，代理会删除最旧的日志文件，以便为新日志文件复制提供空间。设置存储限制是确保日志文件保留不会导致代理耗尽磁盘空间并关闭的有效方法。
6.1.5.2. 为代理中存在的地址重播日志文件副本中的消息
如果要从日志文件副本重新执行的信息地址存在于 AMQ Broker 上，请使用以下步骤重新显示信息。您可以将消息重新显示到代理上的原始地址或不同地址。
流程
- 登录到 AMQ 管理控制台。如需更多信息，请参阅访问 AMQ 管理控制台。
- 在主菜单中，单击 Artemis。
- 在文件夹树中，单击 addresses 以显示地址列表。
- 点 Addresses 选项卡。
- 在您要重播消息的地址的 Action 列中，单击 operations。
选择重播操作。
- 如果您希望 replay 操作搜索所有日志文件副本中要重播的信息，请点 replay (String,String) 操作。
- 如果您希望重播操作仅在特定时间段内创建的日志文件副本中搜索信息，请选择 replay (String,String, String,String) 操作。在 startScanDate 和 endScanDate 字段中，指定时间段。
指定重播选项。
- 在 target 字段中，指定要发送重播消息的地址。如果将此字段留空，信息将重新显示到代理的原始地址。
-
（可选）在 filter 字段中，指定一个字符串来仅重播与过滤器字符串匹配的消息。例如，如果消息具有 storeID 属性，您可以使用过滤
storeID="1000"来重播存储 ID 值为 1000 的所有消息。如果您没有指定过滤器，扫描的日志文件副本中的所有信息都会重新显示到 AMQ Broker。
- 点 Execute。
其他资源
- 有关使用 AMQ 管理控制台的更多信息，请参阅使用 AMQ 管理控制台。
6.1.5.3. 在日志文件复制中重播从代理中删除的地址
如果要从日志文件副本中重播的消息地址已从 AMQ Broker 中删除，请使用以下步骤将信息重新定向到代理上的不同地址。
流程
- 登录到 AMQ 管理控制台。如需更多信息，请参阅访问 AMQ 管理控制台。
- 在主菜单中，单击 Artemis。
- 在文件夹树中，单击顶级服务器。
- 单击 Operations 选项卡。
选择重播操作。
- 如果您希望 replay 操作搜索所有日志文件副本中要重播的信息，请点 replay (String,String,String) 操作。
- 如果您希望重播操作仅在特定时间段内创建的日志文件副本中搜索信息，请选择 replay (String,String,String,String,String,String) 操作。在 startScanDate 和 endScanDate 字段中，指定时间段。
指定重播选项。
- 在 address 字段中，指定要重播的消息地址。
- 在 target 字段中，指定要发送重播消息的地址。
-
（可选）在 filter 字段中，指定一个字符串来仅重播与过滤器字符串匹配的消息。例如，如果消息具有 storeID 属性，您可以使用过滤
storeID="1000"来重播存储 ID 值为 1000 的所有消息。如果您没有指定过滤器，扫描的日志文件副本中的所有信息都会重新显示到 AMQ Broker。
- 点 Execute。
其他资源
- 有关使用 AMQ 管理控制台的更多信息，请参阅使用 AMQ 管理控制台。
6.1.6. 紧凑日志文件
AMQ Broker 包含一个压缩算法，它从日志中删除死空间并压缩数据，使其占用较少的磁盘空间。
以下子部分演示了如何：
6.1.6.1. 配置日志文件压缩
代理使用以下条件来决定何时开始压缩：
- 为日志创建的文件数。
- 日志文件中实时数据的百分比。
在达到这两个条件的值后，压缩过程会解析日志并删除所有死记录。因此，日志包含较少的文件。
以下流程演示了如何为日志文件压缩配置代理。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，添加journal-compact-min-files和journal-compact-percentage参数并指定值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow journal-compact-min-files-
代理在压缩开始前创建的最小日志文件数。默认值为
10。将值设为0可禁用压缩。禁用压缩时应小心，因为日志的大小可能会无限期增长。 journal-compact-percentage-
日志文件中实时数据的百分比。当这个百分比小于这个百分比时（且达到了
journal-compact-min-files的配置值），则压缩开始。默认值为30。
6.1.6.2. 使用命令行界面运行压缩
以下步骤演示了如何使用命令行界面(CLI)压缩日志文件。
流程
作为 <
broker_instance_dir>目录的所有者，停止代理。以下示例显示了用户amq-broker。su - amq-broker cd <broker_instance_dir>/bin $ ./artemis stop
su - amq-broker cd <broker_instance_dir>/bin $ ./artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow （可选）运行以下 CLI 命令以获取数据工具的完整参数列表。默认情况下，该工具使用 <
broker_instance_dir> /etc/broker.xml 中的设置。./artemis help data compact.
$ ./artemis help data compact.Copy to Clipboard Copied! Toggle word wrap Toggle overflow 运行以下 CLI 命令以压缩数据：
./artemis data compact.
$ ./artemis data compact.Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在工具成功压缩数据后，重启代理。
./artemis run
$ ./artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- AMQ Broker 包括用于管理日志文件的多个 CLI 命令。如需更多信息，请参阅附录中的命令行工具。
6.1.7. 禁用磁盘写入缓存
大多数磁盘都包含硬件写缓存。写缓存可提高磁盘的明显性能，因为写入稍后写入会很好地写入磁盘。默认情况下，许多系统附带启用了磁盘写入缓存。这意味着，即使在从操作系统同步后，也无法保证数据实际将其提供给磁盘。因此，如果发生故障，关键数据可能会丢失。
有些更昂贵的磁盘具有非易失性或电池支持的写缓存，这些缓存不一定会在失败时丢失数据，但您应该测试它们。如果您的磁盘没有这样的功能，您应该确保禁用了写缓存。请注意，禁用磁盘写入缓存可能会对性能造成负面影响。
下面的步骤演示了如何在 Windows 上的 Linux 上禁用磁盘写入缓存。
流程
-
在 Linux 上，要管理磁盘写缓存设置，请使用工具
hdparm（用于 IDE 磁盘）或sdparm或sginfo（用于 SDSI/SATA 磁盘）。 - 在 Windows 上，要管理磁盘写器缓存设置，请右键单击磁盘。选择 属性。
6.2. 在数据库中保留消息数据
当您将消息数据存储在数据库中时，代理使用 Java 数据库连接 (JDBC)连接将消息和绑定数据存储在数据库表中。表中的数据使用 AMQ Broker 日志编码进行编码。有关支持的数据库的详情，请参考红帽客户门户网站中的 Red Hat AMQ 7 支持的配置。
管理员可能会选择根据组织更广泛的 IT 基础架构要求将消息数据存储在数据库中。但是，使用数据库可能会对消息传递系统的性能造成负面影响。具体来说，通过 JDBC 将消息传递数据写入数据库表可为代理造成显著的性能开销。
6.2.1. 配置 JDBC 持久性
以下流程演示了如何配置代理以在数据库表中存储消息和绑定数据。
流程
将适当的 JDBC 客户端库添加到代理运行时。要做到这一点，将相关的
.JAR文件添加到 <broker_instance_dir>/lib目录中。如果要将
.JAR文件添加到其他目录中，您必须将该目录添加到 Java 类路径中。如需更多信息，请参阅 第 1.5 节 “扩展 JAVA 类路径”-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，添加一个包含database-store元素的store元素。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在
database-store元素内，为 JDBC 持久性添加配置参数并指定值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow - jdbc-connection-url
- 您的数据库服务器的完整 JDBC 连接 URL。连接 URL 应包含所有配置参数和数据库名称。
- jdbc-user
- 数据库服务器的加密用户名。有关加密在配置文件中使用的用户名和密码的更多信息，请参阅 第 5.10 节 “在配置文件中加密密码”。
- jdbc-password
- 数据库服务器的加密密码。有关加密在配置文件中使用的用户名和密码的更多信息，请参阅 第 5.10 节 “在配置文件中加密密码”。
- bindings-table-name
- 保存绑定数据的表名称。指定表名称可让您在多个服务器间共享单个数据库，而无需干扰。
- message-table-name
- 保存消息数据的表名称。指定此表名称可让您在多个服务器间共享单个数据库，而无需干扰。
- large-message-table-name
- 在其中保留大型消息和相关数据的表名称。另外，如果客户端以块的形式流出大量消息，则块将存储在此表中。指定此表名称可让您在多个服务器间共享单个数据库，而无需干扰。
- page-store-table-name
- 保存用于存储目录信息的表名称。指定此表名称可让您在多个服务器间共享单个数据库，而无需干扰。
- node-manager-store-table-name
- 主和备份代理的共享存储高可用性(HA)锁定表的名称，以及其他与 HA 相关的数据存储在代理服务器上。指定此表名称可让您在多个服务器间共享单个数据库，而无需干扰。使用共享存储 HA 的每个主备份对都必须使用相同的表名称。您不能在多个（不相关的）主备份对间共享相同的表。
- jdbc-driver-class-name
- JDBC 数据库驱动程序的完全限定域名。有关支持的数据库的详情，请参考红帽客户门户网站中的 Red Hat AMQ 7 支持的配置。
- jdbc-network-timeout
-
JDBC 网络连接超时，以毫秒为单位。默认值为 20000 毫秒。当使用 JDBC 进行共享存储 HA 时，建议将 timeout 设置为小于或等于
jdbc-lock-expiration的值。 - jdbc-lock-renew-period
-
当前 JDBC 锁定的续订周期的长度（以毫秒为单位）。当这个时间过后，代理可以续订锁定。建议设置一个小于
jdbc-lock-expiration的值多次的值。这会给代理有足够的时间扩展租期，并给代理时间来尝试续订连接问题时的锁定。默认值为 2000 毫秒。 - jdbc-lock-expiration
以毫秒为单位，当前的 JDBC 锁定被视为拥有（即获取或续订），即使
jdbc-lock-renew-period值已经过。代理定期尝试根据
jdbc-lock-renew-period值更新它拥有的锁定。如果代理 无法 续订锁定（例如，由于连接问题），代理会持续尝试更新锁定，直到jdbc-lock-expiration的值自上次成功获取或更新后通过。上述续订行为的一个例外是在另一个代理获取锁定时。如果数据库管理系统(DBMS)和代理之间存在时间对齐，或者对垃圾回收有较长的暂停，会出现这种情况。在这种情况下，最初拥有锁定的代理会考虑锁定丢失，且不会尝试更新它。
过期时间后，如果 JDBC 锁定尚未由当前拥有它的代理续订，则另一个代理可以建立 JDBC 锁定。
jdbc-lock-expiration的默认值为 20000 毫秒。- jdbc-journal-sync-period
- 代理日志与 JDBC 同步的时间（以毫秒为单位）。默认值为 5 毫秒。
- jdbc-max-page-size-bytes
-
当 AMQ Broker 将消息保留到 JDBC 数据库时，每个页面文件的最大大小（以字节为单位）。默认值为
102400，即 100KB。您指定的值还支持字节表示法，如 "K" "MB" 和 "GB"。
6.2.2. 配置 JDBC 连接池
如果您为 JDBC 持久性配置了代理，代理使用 JDBC 连接将消息和绑定数据存储在数据库表中。
如果 JDBC 连接失败，并且提供发生失败时没有活动的连接活动（如数据库读取或写入），代理将保持运行，并尝试重新建立数据库连接。为达到此目的，AMQ Broker 使用 JDBC 连接池。
通常，连接池 提供一组对指定数据库的连接，可在多个应用程序间共享。对于代理，如果代理和数据库之间的连接失败，代理会尝试使用与池的不同连接重新连接到数据库。池在代理接收新连接前测试新连接。
以下示例演示了如何配置 JDBC 连接池。
如果您没有明确配置 JDBC 连接池，代理将使用与默认配置的连接池。默认配置使用现有 JDBC 配置中的值。如需更多信息，请参阅 默认连接池配置。
先决条件
- 本例构建在用于配置 JDBC 持久性的示例上。请查看 第 6.2.1 节 “配置 JDBC 持久性”
要启用连接池，AMQ Broker 使用 Apache Commons DBCP 软件包。在为代理配置 JDBC 连接池之前，您应该熟悉此软件包提供的内容。如需更多信息，请参阅：
流程
-
打开 &
lt;broker-instance-dir> /etc/broker.xml配置文件。 在之前为 JDBC 配置添加的
database-store元素中，删除jdbc-driver-class-name、jdbc-connection-url、jdbc-user、jdbc-password、参数。之后，您要将它们替换为对应的 DBCP 配置参数。注意如果您没有显式删除前面的参数，则稍后在此流程中添加的对应 DBCP 参数具有优先权。
在
database-store元素中，添加一个data-source-properties元素。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在新的
data-source-properties元素中，为连接池添加 DBCP 数据源属性。指定键值对。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow driverClassName- JDBC 数据库驱动程序的完全限定域名。
url- 您的数据库服务器的完整 JDBC 连接 URL。
username- 数据库服务器的加密用户名。您还可以将这个值指定为未加密的纯文本。有关加密在配置文件中使用的用户名和密码的更多信息，请参阅 第 5.10 节 “在配置文件中加密密码”。
password- 数据库服务器的加密密码。您还可以将这个值指定为未加密的纯文本。有关加密在配置文件中使用的用户名和密码的更多信息，请参阅 第 5.10 节 “在配置文件中加密密码”。
poolPreparedStatements-
当此参数的值设置为
true时，池可以有无限数量的缓存准备语句。这降低了初始化成本。 maxTotal-
池中的最大连接数。当此参数的值设置为 1 时，没有限制。
如果您没有明确配置 JDBC 连接池，代理将使用与默认配置的连接池。表中描述了默认配置。
| DBCP 配置参数 | 默认值 |
|---|---|
|
|
现有 |
|
|
现有 |
|
|
现有 |
|
|
现有 |
|
|
|
|
|
|
仅在没有 客户端主动向代理发送消息时，重新连接才起作用。如果在重新连接过程中尝试写入数据库表，代理会失败并关闭。
其他资源
- 有关 AMQ Broker 支持的数据库的详情，请参考红帽客户门户网站中的 Red Hat AMQ 7 支持的配置。
- 要了解 Apache Commons DBCP 软件包中所有可用配置选项，请参阅 Apache Commons DBCP 配置参数。
6.3. 禁用持久性
在某些情况下，可能要求消息传递系统 不存储 任何数据。在这些情况下，您可以在代理中禁用持久性。
以下流程演示了如何禁用持久性。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，将persistence-enabled参数的值设置为false。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 没有消息数据、绑定数据、大型消息数据、重复 ID 缓存或分页数据会被保留。
第 7 章 为地址配置内存限值
AMQ Broker 透明地支持包含数百万消息的大队列，即使托管代理的机器使用有限内存运行。
在这些情况下，可能不会一次性将所有队列保存在内存中。为了防止过量内存消耗，您可以限制用于单个地址或代理上的所有地址的内存。另外，您可以将代理配置为在为地址达到配置的限制时执行以下操作之一：
- 页面消息
- 静默丢弃信息
- 丢弃消息并通知发送客户端
- 阻止客户端发送消息
如果您在达到地址的内存限值时将代理配置为页信息，您可以为特定地址配置以下分页限制：
- 限制用于页面传入消息的磁盘空间
- 当客户端准备好使用消息时，限制代理从磁盘传输回内存的内存。
您还可以设置磁盘用量阈值，该阈值会覆盖所有配置的分页限制。如果达到磁盘用量阈值，代理会停止分页并阻止所有传入的信息。
使用事务时，代理可能会分配额外的内存以确保事务的一致性。在这种情况下，代理报告的内存用量可能没有反映内存中使用的字节数。因此，如果您将代理配置为根据指定的最大内存用量将代理配置为页面、丢弃或块消息，您也不应该使用事务。
7.1. 配置消息分页
对于任何配置了内存限制的地址，您还可以指定达到该限制时代理执行的操作。您可以配置的一个选项是 分页。
如果您配置了分页选项，代理将在达到限制时将该地址的消息存储在磁盘上的页面 文件中。每个页面文件都有您可以配置的最大大小。您以这种方式配置的每个地址在文件系统中都有一个专用文件夹来存储页面的消息。
在检查队列中的消息时，队列浏览器和消费者都可以浏览页面文件。但是，使用非常具体的过滤器的消费者可能无法使用存储在页面文件中的消息，直到首先消耗队列中的现有消息。例如，假设 consumer 过滤器包含一个字符串表达式，如 "color='red' "。如果满足此条件的消息遵循一个带有 属性的一百万条消息，则消费者将无法使用消息，直到首先消耗了 "color='blue'"。
"color='blue'"
当客户端就绪使用时，代理传输（即，depages）消息从磁盘变为内存中。当确认该文件中的所有消息时，代理会从磁盘中删除页面文件。
AMQ Broker 根据 JMS 消息优先级在队列中对待处理消息进行排序。但是，页面的消息不会按优先级排序。如果要保留排序，请不要足够配置分页和调整代理的大小，以在内存中保存所有信息。
7.1.1. 指定分页目录
以下流程演示了如何指定分页目录的位置。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，添加 Page-directory元素。在文件系统中指定分页目录的位置。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 对于您随后为分页配置的每个地址，代理会在您指定的分页目录中添加一个专用目录。
7.1.2. 为分页配置地址
您可以为地址配置各种分页参数。配置 max-size-bytes 参数非常重要，以便在代理启动到页面信息前限制地址可以消耗的内存量，如以下步骤所述。
先决条件
- 您应该熟悉如何配置地址和地址设置。更多信息请参阅 第 4 章 配置地址和队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您为匹配地址 或一组 地址配置的
address-setting元素，请添加配置元素来指定最大内存用量并定义分页行为。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow max-size-bytes-
代理执行为
address-full-policy属性指定的操作前地址允许的最大大小（以字节为单位）。默认值为-1，这意味着没有限制。您指定的值还支持字节表示法，如 "K"、"MB" 和 "GB"。
重要强烈建议您将
max-size-bytes的值设置为不大于100MB。这个限制是确保内存中的对象数量不会影响到页面消息前代理的一般操作。max-size-messages-
代理执行
address-full-policy属性指定的操作前地址允许的最大消息数。默认值为 -1，这意味着没有消息限制。 page-size-bytes-
在分页系统上使用的每个页面文件的大小（以字节为单位）。默认值为
10485760（即 10 MiB）。您指定的值还支持字节表示法，如 "K"、"MB" 和 "GB"。 address-full-policy当达到一个地址限制时，代理会采取的操作。默认值为
PAGE。有效值为：PAGE- 代理将任何其他消息页到磁盘。
DROP- 代理静默丢弃任何进一步的信息。
FAIL- 代理丢弃任何进一步的消息，并向客户端消息制作者发出例外问题。
BLOCK- 客户端消息制作者在尝试发送进一步消息时阻止。
如果您为
max-size-bytes和max-size-message属性设置了限制，则代理会在达到任何限制时执行为address-full-policy属性指定的操作。在上例中，当内存中的地址总数超过 20,000 或使用 104857600 字节时，代理将启动到my.paged.address地址的页消息。以下是一个额外的分页参数，没有 在上例中显示：
page-sync-timeout-
定期页面同步之间时间（以纳秒为单位）。如果您使用异步 IO 日志（即，在
broker.xml配置文件中将journal-type设置为ASYNCIO），则默认值为3333333。如果您使用标准的 Java NIO 日志（即journal-type设置为NIO），则默认值是journal-buffer-timeout参数的配置值。
在上例中，当发送到地址
my.paged.address的消息在内存中超过 104857600 字节的消息时，代理将开始进入页消息。注意如果您在
address-setting元素中指定max-size-bytes，则值适用于 每个 匹配地址。指定这个值 并不意味着 所有匹配地址 的总大小 限制为max-size-bytes的值。
7.1.3. 为分页配置全局内存限值
您可以指定一个全局内存限值，这是代理在启动到页消息前可用于所有地址的内存量。您还可以根据内存中的消息总数设置全局限制。
建议您不要设置全局限制。设置全局限制可能会导致内存中的对象数量达到一个级别，该级别会影响代理的常规操作，然后再开始页面信息。为单个地址设置限制，而不是设置全局分页限制。更多信息请参阅 第 7.1.2 节 “为分页配置地址”。
先决条件
- 您应该熟悉如何为分页配置地址。更多信息请参阅 第 7.1.2 节 “为分页配置地址”。
流程
停止代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 如果要根据内存用量指定全局分页限制，您可以指定代理 JVM 或绝对值的最大可用内存百分比。通过指定百分比值，您可以避免在 JVM 内存量更改时更改值。
要将全局分页限制指定为 JVM 可用最大内存的百分比，请在
core元素中添加global-max-size-percent-of-jvm-max-memory元素，并指定一个值。在以下示例中，当内存用量达到 JVM 可用内存的 60% 时，代理将启动到所有地址的页消息：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要将全局分页限制指定为绝对值，请在
core项中添加global-max-size元素并指定一个值。在以下示例中，当内存用量达到 1 GB 时，代理将启动到所有地址的消息。Copy to Clipboard Copied! Toggle word wrap Toggle overflow global-max-size的值以字节为单位，但还支持字节表示法（例如："K", "Mb", "GB"）。
如果要根据消息总数指定全局限制，请在
core元素中添加global-max-messages元素并指定一个值。在以下示例中，当内存中的消息数量达到 900,000 时，代理将启动至页所有地址的消息。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 默认值为 -1，这意味着没有最大消息限制。
如果您为 global-max-size 和 global-max-messages 属性设置了限制，则代理会在达到任何限制时执行为 address-full-policy 属性指定的操作。当上例中的配置时，当内存中的消息数量超过 900,000 或使用 1 GB 可用内存时，代理将开始页面所有地址的消息。
+ 注意：如果使用 max-size-bytes 或 max-size-message 属性为单个地址设置的限制，则会在任何全局限制集前达到，代理会执行为该地址为 address-full-policy 属性指定的操作。
启动代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.1.4. 在分页特定地址时限制磁盘用量
您可以在为单个地址或一组地址停止分页进入信息前限制代理可以使用的磁盘空间量。
流程
停止代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，添加属性以根据磁盘使用情况或消息数量指定分页限制，并在达到任一限制时指定要执行的操作。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow page-limit-bytes-
在代理执行
page-full-policy属性指定的操作前，允许最大大小（以字节为单位）为地址分页传入的信息。您指定的值支持字节表示法，如 "K"、"MB" 和 "GB"。默认值为 -1，这意味着没有限制。 page-limit-messages-
在代理执行
page-full-policy属性指定的操作前，地址可以被分页的最大传入消息数。默认值为 -1，这意味着没有消息限制。 page-full-policy当达到地址的 page-limit-
bytes 或属性中设置的限制时，代理会采取的操作。有效值为：page-limit-messagesDROP The broker 会静默丢弃任何进一步的信息。
FAIL The broker 丢弃任何进一步的消息，并通知发送客户端
在上例中，代理页面会为
my.paged.address地址分页信息，直到使用了 10 GB 的磁盘空间或直到所有 100万条消息都被被分页为止。
启动代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.1.5. 控制将页面消息流到内存中
如果 AMQ Broker 配置为将消息分页到磁盘，代理会读取页面消息，并在客户端准备好使用信息时将消息传送到内存中。要防止消息消耗过量内存，您可以将每个地址使用的内存限制为代理从磁盘传输到内存的消息。
如果客户端应用程序保留太多消息待处理确认，代理不会在确认待处理消息前读取消息，这会导致代理出现消息不足。
例如，如果达到了将页面消息传送到内存（默认为 20 MB）的限制，则代理会在读取更多消息前等待客户端的确认。如果同时，客户端在向代理发送确认前等待收到足够消息（由客户端使用的批处理大小决定），代理会耗尽消息。
为了避免不足，请增加控制页面消息传输的代理限制，或者减少发送消息的数量。当没有从代理收到更多消息时，您可以确保客户端更早地提交消息确认，或使用超时和提交确认来减少发送消息的数量。
您可以在 AMQ 管理控制台中看到在队列的 Delivering Count 和 Delivering Bytes 指标中传递消息的编号和大小。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您为匹配地址或一组地址集配置的
address-settings元素，请指定将页面消息传送到内存的限制。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow max-read-page-messages最大页面数，代理可以从磁盘读取到每个地址的内存。默认值为 -1，这意味着没有应用限制。代理可以从磁盘读取到每个地址的内存消息的 max-read-page-bytesMaximum size （以字节为单位）。默认值为 20 MB。应用这些限制时，代理会计算在内存中准备交付给消费者的消息和当前发送的消息。如果消费者无法确认消息，则传递信息可能会导致达到内存或消息限制，并防止代理将新消息读取到内存中。因此，代理可以耗尽信息。
如果消费者无法确认消息，并且当前提供的消息达到配置的
max-read-page-messages或max-read-page-bytes限制，请为当前交付的消息指定页面消息传输的单独限制。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 预抓取-页字节内存（以字节为单位）可以将页面消息读取到每个队列的内存中。默认值为 20 MB。代理可以从磁盘读取到每个队列的内存，预fetch
-page-messages 数。默认值为 -1，这意味着没有应用限制。如果您为
prefetch-page-bytes或prefetch-page-messages参数指定限值，以限制当前发送的消息量或消息数，请为max-read-page-bytes或max-read-page-message参数设置更高的限值，以提供向内存读取新消息的容量。注意如果在 prefetch-page-bytes 参数的值前达到 max-read-page-bytes 参数的值，代理会停止将进一步页面的信息读取到内存中。
7.1.6. 设置磁盘用量阈值
您可以设置磁盘用量阈值，如果达到，会导致代理停止分页并阻止所有传入的信息。
流程
停止代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，添加max-disk-usage配置元素并指定值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow max-disk-usage代理可以使用的可用磁盘空间的最大百分比。当达到这个限制时，代理会阻止传入的信息。默认值为
90。在上例中，代理限制为使用百分之八十的可用磁盘空间。
启动代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.2. 配置消息丢弃
第 7.1.2 节 “为分页配置地址” 演示了如何为分页配置地址。作为该流程的一部分，您可以将 address-full-policy 的值设置为 PAGE。
当地址达到其指定的最大大小时，要 丢弃 消息（而不是分页信息），请将 address-full-policy 的值设置为以下之一：
DROP- 当达到给定地址的最大大小时，代理会静默丢弃任何进一步的信息。
FAIL- 当达到给定地址的最大大小时，代理会丢弃任何进一步的消息，并给生成者发出例外问题。
7.3. 配置消息阻塞
以下流程演示了如何在给定地址达到您指定的最大大小限制时配置消息阻塞。
您只能为 Core、OpenWire 和 AMQP 协议配置消息阻塞。
7.3.1. 阻塞 Core 和 OpenWire producers
以下流程演示了如何在给定地址达到您指定的最大大小限制时为 Core 和 OpenWire 消息生成者配置消息阻塞。
先决条件
- 您应该熟悉如何配置地址和地址设置。更多信息请参阅 第 4 章 配置地址和队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您为匹配地址 或一组 地址配置的
address-setting元素，请添加配置元素来定义消息阻塞行为。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow max-size-bytes代理执行为
address-full-policy指定的策略前地址允许的最大大小（以字节为单位）。您指定的值还支持字节表示法，如 "K"、"MB" 和 "GB"。注意如果您在
address-setting元素中指定max-size-bytes，则值适用于 每个 匹配地址。指定这个值 并不意味着 所有匹配地址 的总大小 限制为max-size-bytes的值。address-full-policy- 当代理达到最大大小时，代理会采取的操作。
在上例中，当发送到地址
my.blocking.address在内存中超过 300000 字节的消息时，代理开始阻止来自 Core 或 OpenWire 消息制作者的进一步消息。
7.3.2. 阻塞 AMQP 生成者
Core 和 OpenWire 等协议使用窗口大小的流控制系统。在这个系统中，分数代表字节，并分配给生成者。如果生成者希望发送消息，则生成者必须等待直到消息大小有足够的学分。
相反，AMQP 流控制分数不代表字节。相反，AMQP 信用代表生成者允许发送的消息数量，无论消息大小如何。因此，在某些情况下，AMQP 生成者可能会显著超过地址的 max-size-bytes 值。
因此，要阻止 AMQP 生成者，您必须使用不同的配置元素 max-size-bytes-reject-threshold。对于匹配地址或一组地址，此元素指定了内存中所有 AMQP 消息的最大大小（以字节为单位）。当内存中所有消息的总大小达到指定的限制时，代理会阻止 AMQP 生成者发送进一步消息。
以下流程演示了如何为 AMQP 消息生成者配置消息阻塞。
先决条件
- 您应该熟悉如何配置地址和地址设置。更多信息请参阅 第 4 章 配置地址和队列。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 对于您为匹配地址 或一组 地址集配置的
address-setting元素，请指定内存中所有 AMQP 消息的最大大小。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow max-size-bytes-reject-threshold代理阻止进一步 AMQP 消息前地址允许的最大大小（以字节为单位）。您指定的值还支持字节表示法，如 "K"、"MB" 和 "GB"。默认情况下，
max-size-bytes-reject-threshold设置为-1，这意味着没有最大大小。注意如果您在
address-setting元素中指定max-size-bytes-reject-threshold，则该值将应用到 每个 匹配地址。指定这个值 并不意味着 所有匹配地址 的总大小 仅限于max-size-bytes-reject-threshold的值。
在前面的示例中，当发送到地址 my.amqp.blocking.address 的消息超过 300000 字节时，代理开始阻止来自 AMQP 生成者的进一步消息。
7.4. 了解多播地址上的内存用量
当消息路由到绑定了多播队列的地址时，内存中只有一个消息副本。每个队列仅具有对邮件的引用。因此，只有在引用该消息 的所有队列都 发送相关内存后，相关的内存才会发布。
在这种情况下，如果您拥有较慢的消费者，则整个地址可能会遇到负面影响。
例如，请考虑以下情况：
- 地址有十个队列，它使用 multicast 路由类型。
- 由于消费者速度较慢，其中一个队列不会发送其消息。其他 9 个队列继续传递消息并为空。
- 消息继续到达地址。较慢的使用者队列继续累积对消息的引用，从而导致代理在内存中保存消息。
- 当达到地址的最大大小时，代理将开始页消息。
在这种情况下，因为一个较慢的消费者，所有 队列中的消费者都被强制使用来自页面系统的消息，需要额外的 IO。
其他资源
- 要了解如何配置流控制以规范代理和生产者和用户之间的数据流，请参阅 AMQ Core Protocol JMS 文档中的 流控制。
第 8 章 处理大型消息
客户端可能会发送可能会超过代理内部缓冲区大小的大量消息，从而导致意外错误。要防止这种情况，您可以将代理配置为在消息大于指定最小值时将消息存储为文件。以这种方式处理大型消息意味着代理不会在内存中保存消息。相反，您可以在磁盘上或代理存储大型消息文件的数据库表中指定目录。
当代理将消息存储为大消息时，队列会在大型消息目录或数据库表中保留对文件的引用。
大型消息处理可用于核心协议 AMQP、OpenWire 和 STOMP 协议。
对于核心协议和 OpenWire 协议，客户端在其连接配置中指定最小大型消息大小。对于 AMQP 和 STOMP 协议，您可以在代理配置中为每个协议指定 acceptor 定义的最小大消息大小。
建议您不要使用不同的协议 来生成和使用大型消息。要做到这一点，代理可能需要执行多个消息的转换。例如，假设您要使用 AMQP 协议发送一条消息，并使用 OpenWire 接收消息。在这种情况下，代理必须首先读取大型消息的整个正文，并将其转换为使用 Core 协议。然后，代理必须执行另一个转换，这一次到 OpenWire 协议。比如这些信息转换，比如在代理中造成大量处理开销。
您为上述任何协议指定的最小大消息大小会受到系统资源（如可用磁盘空间）以及消息的大小的影响。建议您使用多个值运行性能测试来确定适当的大小。
本节中的步骤演示了如何：
- 配置代理以存储大型消息
- 为大型消息处理配置 AMQP 和 STOMP 协议的接收器
本节还链接到有关配置 AMQ Core Protocol 和 AMQ OpenWire JMS 客户端以使用大型消息的其他资源。
8.1. 为大型消息处理配置代理
以下流程演示了如何在磁盘中指定目录或代理存储大型消息文件的数据库表。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 指定您希望代理存储大型消息文件的位置。
如果要在磁盘上存储大型消息，请在
core元素中添加large-messages-directory参数，并指定文件系统位置。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果没有为
large-messages-directory明确指定值，代理会使用默认值 <broker_instance_dir> /data/largemessages如果您在数据库表中存储大型消息，请将
large-message-table参数添加到database-store元素中，并指定一个值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果您没有为
large-message-table明确指定值，代理将使用默认值LARGE_MESSAGE_TABLE。
其他资源
- 有关配置数据库存储的更多信息，请参阅 第 6.2 节 “在数据库中保留消息数据”。
8.2. 为大型消息处理配置 AMQP 接受器
以下步骤演示了如何配置 AMQP 接收器来处理大于指定大小的 AMQP 消息作为大消息。
流程
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。代理配置文件中的默认 AMQP 接受器如下所示：
<acceptors> ... <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> ... </acceptors><acceptors> ... <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在默认的 AMQP acceptor （或者您配置的另一个 AMQP 接收器）中，添加
amqpMinLargeMessageSize属性并指定一个值。例如：<acceptors> ... <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpMinLargeMessageSize=204800</acceptor> ... </acceptors><acceptors> ... <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpMinLargeMessageSize=204800</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，代理配置为接受端口 5672 上的 AMQP 消息。根据
amqpMinLargeMessageSize的值，如果接收器收到一个 AMQP 消息，其正文大于或等于 204800 字节（即 200 KB），代理会将消息存储为大消息。如果没有为此属性显式指定值，代理会使用默认值 102400 （即 100 KB）。
-
如果将
amqpMinLargeMessageSize设置为 -1，则禁用 AMQP 消息的大型消息处理。 -
如果代理收到一个持久性 AMQP 消息，它没有超过
amqpMinLargeMessageSize的值，但超出消息传递日志缓冲区的大小（使用journal-buffer-size配置参数指定），代理会将消息转换为大型核心协议消息，然后再将其存储在日志中。
8.3. 配置 STOMP acceptor 用于处理大量信息
以下步骤演示了如何配置 STOMP 接收器来处理大于指定大小的 STOMP 消息。
流程
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。代理配置文件中的默认 AMQP 接受器如下所示：
<acceptors> ... <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor> ... </acceptors><acceptors> ... <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在默认的 STOMP acceptor （或其他您配置的 STOMP 接收器），添加
stompMinLargeMessageSize属性并指定值。例如：<acceptors> ... <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true;stompMinLargeMessageSize=204800</acceptor> ... </acceptors><acceptors> ... <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true;stompMinLargeMessageSize=204800</acceptor> ... </acceptors>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
在前面的示例中，代理配置为接受端口 61613 上的 STOMP 消息。根据 stompMinLargeMessageSize 的值，如果接收器接收了一个大于 204800 字节的 STOMP 消息（即 200 KB），代理会将消息存储为大消息。如果没有为此属性显式指定值，代理会使用默认值 102400 （即 100 KB）。
要向 STOMP 消费者发送大型消息，代理会在将消息发送到客户端之前自动将消息从大型消息转换为正常消息。如果压缩了大型消息，代理会先解压缩，然后再将其发送到 STOMP 客户端。
8.4. 大型消息和 Java 客户端
Java 开发人员可通过两种选项编写使用大型消息的客户端。
一个选项是使用 InputStream 和 OutputStream 的实例。例如，FileInputStream 可用于发送从物理磁盘中大型文件获取的消息。然后，接收器可以使用 FileOutputStream 将消息流传输到其本地文件系统中的位置。
另一个选项是直接流传输 JMS BytesMessage 或 StreamMessage。例如：
其他资源
要了解在 AMQ 核心协议 JMS 客户端中使用大型消息的信息，请参阅：
- 有关使用大型消息的示例，请参阅 大型消息示例。要了解更多有关运行示例程序的信息，请参阅 运行 AMQ Broker 示例。
第 9 章 检测死连接
有时，客户端会意外停止，且没有机会清理其资源。如果发生了这种情况，它可能会让资源处于故障状态，并导致代理内存不足或其他系统资源。代理检测到客户端的连接没有在垃圾回收时正确关闭。然后，连接会关闭，并将类似以下的消息写入到日志中。日志捕获客户端会话实例化的代码的确切行。这可让您识别错误并更正它。
- 1
- 连接实例化的客户端代码中的行。
9.1. Connection Time-To-Live
由于客户端和服务器之间的网络连接可能会失败，然后恢复在线，因此 AMQ Broker 会等待清理不活跃的服务器端资源。这个等待周期被称为生存时间(TTL)。基于网络的连接的默认 TTL 为 60000 毫秒(1 分钟)。in-VM 连接上的默认 TTL 是 -1，这意味着代理永远不会超时到代理端的连接。
在代理中配置 Time-To-Live
如果您不希望客户端指定自己的连接 TTL，您可以在代理端设置全局值。这可以通过在代理配置中指定 connection-ttl-override 元素来实现。
检查 TTL 违反连接的逻辑在代理上定期运行，具体由 connection-ttl-check-interval 元素决定。
9.2. 禁用同步连接执行
在代理端收到的大多数数据包都在 remoting thread 上执行。这些数据包代表短暂运行的操作，并且始终在远程线程上执行，以提高性能。但是，有些数据包类型使用线程池执行，而不是使用远程线程，这会增加较少的网络延迟。
使用线程池的数据包类型在下面列出的 Java 类中实施。类都在软件包 org.apache.actiinvemq.artemis.core.protocol.core.impl.wireformat 中找到。
- RollbackMessage
- SessionCloseMessage
- SessionCommitMessage
- SessionXACommitMessage
- SessionXAPrepareMessage
- SessionXARollbackMessage
流程
要禁用异步连接执行，请将
async-connection-execution-enabled配置元素添加到<broker_instance_dir> /etc/broker.xml并将其设置为false，如下例所示。默认值为true。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 要了解如何配置 AMQ Core Protocol JMS 客户端来检测死连接，请参阅 AMQ Core Protocol JMS 文档中的 检测死连接。
- 要了解如何在 AMQ 核心协议 JMS 客户端中 配置连接时间到实时，请参阅 AMQ 核心协议 JMS 文档中的配置生时间。
第 10 章 检测重复消息
您可以将代理配置为自动检测和过滤重复的消息。这意味着您不必实施自己的重复检测逻辑。
如果没有重复的检测，在出现意外连接失败时，客户端无法确定是否收到它发送到代理的消息。在这种情况下，客户端可能会假定代理没有接收消息，并重新发送它。这会产生重复的消息。
例如，假设客户端向代理发送一条消息。如果在代理接收和处理消息 前 代理或连接失败，消息永远不会到达其地址。由于失败，客户端不会收到来自代理的响应。如果在代理接收和处理消息 后 代理或连接失败，则消息会被正确路由，但客户端仍然不会收到响应。
此外，在这些情况下，使用事务来确定成功并不一定有帮助。如果在处理事务提交时代理或连接失败，客户端仍然无法确定它是否成功发送消息。
在这些情况下，为了更正假定的失败，客户端会重新发送最新的消息。结果可能是对您的系统有负面影响的重复消息。例如，如果您在有序系统中使用代理，重复消息可能意味着处理购买顺序两次。
以下流程演示了如何配置重复消息检测以防止这些类型的情况。
10.1. 配置重复的 ID 缓存
要让代理检测重复消息，生产者必须在发送每个消息时为消息属性 _AMQ_DUPL_ID 提供唯一的值。代理维护 _AMQ_DUPL_ID 属性接收的值的缓存。当代理在地址上收到新消息时，它会检查该地址的缓存，以确保它之前没有为此属性处理具有相同值的消息。
每个地址都有自己的缓存。每个缓存都是循环的，并以大小为单位。这意味着新条目会替换最旧的条目，因为缓存空间需求。
以下流程演示了如何全局配置代理中的每个地址使用的 ID 缓存。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，添加id-cache-size和persist-id-cache属性并指定值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow id-cache-sizeID 缓存的最大大小，指定为缓存中单个条目的数量。默认值为 20,000 条目。在本例中，缓存大小被设置为 5,000 个条目。
注意当达到缓存的最大大小时，代理可以开始处理重复的信息。例如，假设您将缓存的大小设置为
3000。如果以前的消息在出现与_AMQ_DUPL_ID值相同的新消息之前到达 3,000 多个 消息，则代理无法检测到重复。这会导致代理处理这两个信息。persist-id-cache-
当此属性值设为
true时，代理会在收到磁盘时将其保留 ID。默认值为true。在上例中，您可以通过将值设置为false来禁用持久性。
其他资源
- 要了解如何使用 AMQ Core Protocol JMS 客户端设置重复的 ID 消息属性，请参阅 AMQ Core Protocol JMS 客户端 文档中的使用重复消息检测。
10.2. 为集群连接配置重复检测
您可以配置集群连接，以为每个在集群中移动的消息插入重复的 ID 标头。
先决条件
- 您应该已经配置了代理集群。如需更多信息，请参阅 第 14.2 节 “创建代理集群”。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在
core元素中，对于给定的集群连接，添加use-duplicate-detection属性并指定一个值。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow use-duplicate-detection-
当此属性的值设为
true时，集群连接会为它处理的每个消息插入一个重复的 ID 标头。
第 11 章 截获消息
使用 AMQ Broker，您可以截获进入或退出代理的数据包，允许您审核数据包或过滤信息。拦截器可以更改它们拦截器的数据包，这使得它们强大，但也可能会有危险。
您可以开发拦截器来满足您的业务需求。拦截器是特定于协议的，必须实现适当的接口。
拦截器必须实施 intercept （） 方法，该方法返回布尔值。如果值为 true，则消息数据包将继续。如果为 false，则进程将中止，则不会调用其他拦截器，且不会进一步处理消息数据包。
11.1. 创建拦截器
您可以创建自己的传入和传出的拦截器。所有拦截器都特定于协议，并为进入或分别退出服务器的任何数据包调用。这可让您创建拦截器来满足审计数据包等业务要求。拦截器可能会更改它们拦截器的数据包。这使得它们的功能强大以及潜在的危险性，因此请务必谨慎使用它们。
拦截器及其依赖项必须放在代理的 Java 类路径中。您可以使用 < ;broker_instance_dir> /lib 目录，因为它是 classpath 的一部分。
流程
以下示例演示了如何创建一个拦截器来检查传递给它的每个数据包的大小。请注意，这些示例为每个协议实施一个特定的接口。
实施适当的接口并覆盖其
intercept （）方法。如果您使用 AMQP 协议，请实施
org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor接口。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果使用核心协议，您的拦截器必须实现
org.apache.artemis.activemq.api.core.Interceptor接口。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果您使用 MQTT 协议，请实施
org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor接口。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果您使用 STOMP 协议，请实施
org.apache.activemq.artemis.core.protocol.stomp.StompFrameInterceptor接口。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
11.2. 将 Broker 配置为使用 Interceptors
创建拦截器后，您必须将代理配置为使用它。
先决条件
您必须创建一个拦截器类，并将其添加到代理的 Java 类路径中，然后才能将其配置为代理使用。您可以使用 < ;broker_instance_dir> /lib 目录，因为它是 classpath 的一部分。
流程
通过将配置添加到 <broker
_instance_dir> /etc/broker.xml，将代理配置为使用拦截器如果您的拦截器用于传入的信息，请将其
class-name添加到remoting-incoming-interceptors列表中。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果您的拦截器用于传出消息，请将其
class-name添加到remoting-outgoing-interceptors列表中。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
- 要了解如何在 AMQ Core Protocol JMS 客户端中配置 拦截器，请参阅 AMQ Core Protocol JMS 文档中的使用消息拦截器。
第 12 章 分离消息和分割消息流
在 AMQ Broker 中，您可以配置名为 diverts 的对象，供您透明地将消息从一个地址分离到另一个地址，而无需更改任何客户端应用程序逻辑。您还可以配置 divert，将消息 副本 转发到指定的转发地址，从而有效地分割消息流。
12.1. 消息 diverts 的工作原理
diverts 可让您在不更改任何客户端应用程序逻辑的情况下，以透明的方式将路由到一个地址的消息。考虑将代理服务器上的一组 diverts 作为消息的路由表类型。
divert 可以 专用，这意味着消息被定向到指定的转发地址，而无需转至原始地址。
divert 也可以是 非独占 的，这意味着消息将继续进入其原始地址，而代理会将消息副本发送到指定的转发地址。因此，您可以使用非独占性分支来分割消息流。例如，如果要单独监控发送到订单队列的每个订单，您可以分割消息流。
可以为单个地址配置多个不同因素。当地址同时配置了 exclusive 和 non-exclusive diverts 时，代理会首先处理 exclusiverts。如果一个特定消息已被一个专用的 divert 分离，代理不会处理该消息的任何非独占性分析。在这种情况下，消息永远不会发送到原始地址。
当代理分离消息时，代理会分配一个新的消息 ID，并将消息地址设置为新的转发地址。您可以通过 _AMQ_ORIG_ADDRESS （字符串类型）和 _AMQ_ORIG_MESSAGE_ID （长类型）消息属性来检索原始消息 ID 和地址值。如果您使用 Core API，请使用 Message.HDR_ORIGINAL_ADDRESS 和 Message.HDR_ORIG_MESSAGE_ID 属性。
您只能将消息转发到同一代理服务器上的地址。如果您要将地址代理到其他服务器上的地址，则常见的解决方案是首先将消息分解到本地存储和转发队列。然后，设置一个从该队列消耗并转发消息到不同代理上的地址的网桥。通过将 diverts 与网桥相结合，您可以在地理分布式代理服务器之间创建分布式路由连接网络。这样，您可以创建一个全局消息传递网格。
12.2. 配置消息 diverts
要在代理实例中配置一个 divert，在 broker.xml 配置文件的 core 元素中添加一个 divert 元素。
- divert
-
名为 divert 的指定实例。您可以在
broker.xml配置文件中添加多个divert元素，只要每个 divert 都有唯一的名称。 - address
- 要从中分离 消息的地址
- forwarding-address
- 信息转发到的地址
- filter
- 可选消息过滤器。如果您配置了过滤器，则只会分离与过滤器字符串匹配的消息。如果没有指定过滤器，则所有消息都会被 divert 视为匹配项。
- routing-type
交换消息的路由类型。您可以将 divert 配置为：
-
将
anycast或multicast路由类型应用到一个信息 - 剥离 （即删除）现有路由类型
- 传递 （即，保留）现有路由类型
-
将
当消息设置了路由类型时，路由类型的控制很有用，但您想要将消息转发到使用不同的路由类型的地址。例如，代理无法将 anycast 路由类型的消息路由到一个使用 multicast 的队列，除非您将 divert 的 routing-type 参数设置为 MULTICAST。divert 的 routing-type 参数的有效值为 ANYCAST、MULTICAST、PASS 和 STRIP。默认值为 STRIP。
- exclusive
-
指定 divert 是 exclusive （将属性设置为
true）或非专用（将属性设置为false）。
以下小节显示了 exclusive 和 non-exusive diverts 的配置示例。
12.2.1. 排除 divert 示例
下面是一个排除 divert 的示例配置。排除 divert 将原始配置的地址的所有匹配消息复制到新地址。匹配消息不会路由到原始地址。
在前面的示例中，您定义了一个名为 price-divert 的 divert，它将发送到 priceUpdates 地址的任何消息转到另外一个本地地址 priceForwarding。您还指定消息过滤器字符串。只有带有 office 属性以及值为 New York 的消息才会被 divert。所有其他消息都路由到其原始地址。最后，您可以指定 divert 为 exclusive。
12.2.2. Non-exclusive divert 示例
以下是非独占性 divert 的示例配置。在非独占的 divert 中，消息将继续进入其原始地址，而代理也会将消息副本发送到指定的转发地址。因此，非独占的 divert 是分割消息流的方法。
<divert name="order-divert"> <address>orders</address> <forwarding-address>spyTopic</forwarding-address> <exclusive>false</exclusive> </divert>
<divert name="order-divert">
<address>orders</address>
<forwarding-address>spyTopic</forwarding-address>
<exclusive>false</exclusive>
</divert>
在上例中，您定义了一个名为 order-divert 的 divert，它会获取发送到地址 orders 的每个消息的副本，并将其发送到名为 spyTopic 的本地地址。您还可以指定 divert 不是排他的。
其他资源
有关使用 exclusive 和 non-exclusive diverts 以及桥接将消息转发到另一个代理的详细示例，请参阅 divert 示例 （外部）。
第 13 章 过滤消息
AMQ Broker 根据 SQL 92 表达式语法的子集提供强大的过滤器语言。过滤器语言使用与 JMS 选择器相同的语法，但预定义的标识符有所不同。下表列出了应用到 AMQ Broker 消息的标识符。
| identifier | 属性 |
|---|---|
| AMQPriority |
消息的优先级。消息优先级是带有从 |
| AMQExpiration | 消息的过期时间。该值是一个长整数。 |
| AMQDurable |
消息是持久化的。该值是一个字符串。有效值为 |
| AMQTimestamp | 创建消息的时间戳。该值是一个长整数。 |
| AMQSize |
消息的 |
在核心过滤器表达式中使用的任何其他标识符都被假定为消息的属性。有关 JMS 消息选择器语法的文档，请参见 Java EE API。
13.1. 将队列配置为使用过滤器
您可以在 < broker_instance_dir> /etc/broker.xml 中配置的队列中添加过滤器。仅匹配过滤器表达式的消息才会进入队列。
流程
将
filter元素添加到所需的队列中，并包含您要应用的过滤器作为元素的值。在以下示例中，过滤器NEWS=' Technical'被添加到队列技术Queue中。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
13.2. 过滤 JMS 消息属性
JMS 规范指出在选择器中使用的 String 属性不能转换为数字类型。例如，如果消息将 age 属性设置为 String 值 21，则选择器 年龄 > 18 不得与它匹配。这个限制限制了 STOMP 客户端，因为它们只能使用 String 属性发送消息。
配置过滤器以将字符串转换为一个数字
要将 String 属性转换为数字类型，请将前缀 convert_string_expressions: 添加到 过滤器 的值。
流程
编辑
<broker_instance_dir>/etc/broker.xml，为相关的filter应用前缀convert_string_expressions:。以下示例编辑age > 18toconvert_string_expressions:age > 18的过滤器值。Copy to Clipboard Copied! Toggle word wrap Toggle overflow
13.3. 根据注解上的属性过滤 AMQP 消息
在代理将过期或未发送 AMQP 消息移至您配置的过期或死信队列之前，代理会将注解和属性应用到消息。客户端可以根据属性或注解创建过滤器，以选择特定消息以从到期或死信队列使用。
代理应用的属性是 内部 属性。这些属性不会公开给客户端供常规使用，但 可以被 过滤器中的客户端指定。
以下是基于消息属性和注解的过滤器示例。根据属性进行过滤是尽可能推荐的方法，因为此方法需要较少的处理。
根据消息属性过滤
根据消息注解过滤
基于注解消耗 AMQP 消息时，客户端必须包含 m. 前缀到消息注解中，如上例中所示。
其他资源
- 有关代理应用到过期或未发送 AMQP 消息的注解和属性的更多信息，请参阅 第 4.14 节 “过期或未发送 AMQP 消息上的注解和属性”。
13.4. 过滤 XML 消息
AMQ Broker 提供了一种使用 XPath 的 XML 正文过滤文本消息的方法。XPath (XML 路径语言)是从 XML 文档选择节点的查询语言。
仅支持基于文本的消息。不支持过滤大型消息。
要过滤基于文本的消息，您需要创建一个 XPATH '<xpath-expression> 形式的 Message Selector。
Message Body 示例
<root>
<a key='first' num='1'/>
<b key='second' num='2'>b</b>
</root>
<root>
<a key='first' num='1'/>
<b key='second' num='2'>b</b>
</root>根据 XPath 查询过滤
XPATH 'root/a'
XPATH 'root/a'由于 XPath 应用到消息的正文，并且需要解析 XML，因此过滤可能比普通的过滤器要慢得多。
使用以下协议在生成者和消费者之间支持 XPath 过滤器：
- OpenWire JMS
- 核心（和核心 JMS）
- STOMP
- AMQP
配置 XML Parser
默认情况下，Broker 使用的 XML Parser 是 JDK 使用的 Platform 默认 DocumentBuilderFactory 实例。
用于 XPath 默认配置的 XML 解析器包括以下设置：
但是，为了处理任何特定于实施的问题，可以通过在 artemis.profile 配置文件中配置系统属性来自定义功能。
org.apache.activemq.documentBuilderFactory.feature:prefix
功能配置示例
-Dorg.apache.activemq.documentBuilderFactory.feature:http://xml.org/sax/features/external-general-entities=true
-Dorg.apache.activemq.documentBuilderFactory.feature:http://xml.org/sax/features/external-general-entities=true第 14 章 设置代理集群
集群由多个已分组在一起的代理实例组成。代理(broker)集群通过将消息处理负载分布到多个代理来提高性能。另外，代理集群可以通过高可用性来最小化停机时间。
您可以在许多不同的集群拓扑中连接代理。在集群中，每个活跃代理管理自己的信息并处理自己的连接。
您还可以在集群中平衡客户端连接，并重新分发信息以避免代理不足。
14.1. 了解代理集群
在创建代理集群前，您应该了解一些重要的集群概念。
14.1.1. 代理集群如何平衡消息负载
当代理连接到组成集群时，AMQ Broker 会自动平衡代理之间的消息负载。这样可确保集群可以维护高消息吞吐量。
考虑四个代理的对称集群。每个代理都配置有一个名为 OrderQueue 的队列。OrderProducer 客户端连接到 Broker1，并将消息发送到 OrderQueue。Broker1 以轮循方式将消息转发到其他代理。连接到每个代理的 OrderConsumer 客户端会使用消息。
图 14.1. 集群中的消息负载均衡
如果没有消息负载均衡，发送到 Broker1 的消息将保留在 Broker1 上，只有 OrderConsumer1 才可以使用它们。
AMQ Broker 默认自动负载平衡信息，将第一个消息组分发到第一个代理，并将第二条消息组分发到第二个代理。启动代理的顺序决定了哪个代理是第一个，第二个，以此类推。
您可以配置：
- 集群在具有匹配队列的代理中负载均衡消息。
- 集群在具有活跃消费者匹配的队列的代理中负载均衡消息。
- 集群不会进行负载平衡，但要执行从没有任何使用者没有消费者队列的队列重新分发消息。
- 一个地址，用于自动将消息从没有任何消费者的队列重新分发到具有消费者的队列。
其他资源
-
消息负载均衡策略配置有每个代理的以太网连接中的
message-load-balancing属性。更多信息请参阅 附录 C, 集群连接配置元素。 - 有关消息重新发布的更多信息，请参阅 第 14.4.2 节 “配置消息重新发布”。
14.1.2. 代理集群如何提高可靠性
代理集群实现高可用性和故障切换功能，这使得它们比独立代理更可靠。通过配置高可用性，您可以确保客户端应用程序可以继续发送和接收信息，即使代理遇到失败事件。
通过高可用性，集群中的代理被分组到主备份组中。primary-backup 组包含一个提供客户端请求的活跃代理，以及等待被动替换活跃代理（如果失败）的一个或多个备份代理。如果发生失败，被动代理会替换其 primary-backup 组中的活跃代理，客户端会重新连接并继续其工作。
14.1.3. 集群限制
在集群环境中使用 AMQ 代理时，会有以下限制。
- 临时队列
- 在故障转移期间，如果客户端有使用临时队列的用户，则会自动重新创建这些队列。重新创建的队列名称与原始队列名称不匹配，这会导致消息重新发布失败，并可能让消息在现有临时队列中保留。红帽建议您避免在集群中使用临时队列。例如，使用请求/回复模式的应用程序应该将固定队列用于 JMSReplyTo 地址。
14.1.4. 了解节点 ID
当代理实例的日志首次创建和初始化时，代理 节点 ID 是以编程方式生成的全局唯一标识符(GUID)。节点 ID 存储在 server.lock 文件中。节点 ID 用于唯一标识代理实例，无论代理是独立实例还是集群的一部分。主备份代理对共享相同的节点 ID，因为它们共享相同的日志。
在代理集群中，代理实例（节点）相互连接，并创建网桥和内部的 "store-and-forward" 队列。这些内部队列的名称基于其他代理实例的节点 ID。代理实例还监控集群广播，以获取与其自身匹配的节点 ID。如果代理标识重复的 ID，则代理会在日志中生成警告信息。
当您使用复制高可用性(HA)策略时，启动的主代理，并将 check-for-active-server 设置为 true 搜索使用其节点 ID 的代理。如果主代理使用同一节点 ID 找到另一个代理，则它不会根据 HA 配置启动或启动故障恢复。
节点 ID 是持久的，这意味着它在代理重启后保留。但是，如果您删除代理实例（包括其日志），则节点 ID 也会永久删除。
其他资源
- 有关配置复制 HA 策略的更多信息，请参阅配置复制高可用性。
14.1.5. 常见代理集群拓扑
您可以连接代理来形成 对称 或 链 集群拓扑。您实现的拓扑取决于您的环境和消息传递要求。
对称集群
在对称集群中，每个代理都连接到所有其他代理。这意味着每个代理都没有多于其它代理的跃点。
图 14.2. 对称集群拓扑
对称集群中的每个代理都知道集群中其他代理上存在的所有队列，以及侦听这些队列的用户。因此，对称集群可以比链集群更最佳地对消息进行负载均衡和重新分发。
对称集群比链集群更容易设置，但很难在网络限制阻止代理被直接连接的环境中使用。
链集群
在链集群中，集群中的每个代理都不直接连接到集群中的每个代理。相反，代理在每个链的末尾使用代理形成一个链，所有其他代理只是连接到链中之前的和下一个代理。
图 14.3. 链集群拓扑
链集群设置比对称集群更困难，但当代理位于单独的网络上，且无法直接连接时很有用。通过使用链集群，中间代理可以间接连接两个代理，以便在它们之间流动信息，即使两个代理没有直接连接。
14.1.6. 代理发现方法
发现是集群中的代理将其连接详情传播到不同的机制。AMQ Broker 支持 动态发现 和静态发现 。
动态发现
集群中的每个代理通过 UDP 多播或 JGroups 将其连接设置广播到其他成员。在这个方法中，每个代理都使用：
- 一个 广播组，将有关其集群连接的信息推送到集群的其他潜在成员。
- 一个 发现组，用于接收并存储集群中其他代理的集群连接信息。
静态发现
如果您无法在网络中使用 UDP 或 JGroups，或者要手动指定集群的每个成员，您可以使用静态发现。在这个方法中，代理"加入"集群通过连接到第二个代理并发送其连接详情。然后，第二个代理会将这些详情传播到集群中的其他代理。
14.1.7. 集群大小注意事项
在创建代理集群前，请考虑您的消息传递吞吐量、拓扑和高可用性要求。这些因素会影响集群中要包含的代理数量。
创建集群后，您可以通过添加和删除代理来调整大小。您可以在不丢失任何信息的情况下添加和删除代理。
消息传递吞吐量
集群应包含足够的代理来提供您需要的消息传递吞吐量。集群中的代理越多，吞吐量越好。但是，大型集群管理可能比较复杂。
Topology
您可以创建对称集群或链集群。您选择的拓扑类型会影响您可能需要的代理数量。
更多信息请参阅 第 14.1.5 节 “常见代理集群拓扑”。
高可用性
如果您需要高可用性(HA)，请在创建集群前考虑选择 HA 策略。HA 策略会影响集群的大小，因为每个主代理应至少有一个备份代理。
如需更多信息，请参阅 第 14.3 节 “实施高可用性”。
14.2. 创建代理集群
您可以通过在应参与集群的每个代理上配置集群连接来创建代理集群。集群连接定义代理应如何连接到其他代理。
您可以创建一个使用静态发现或动态发现(UDP 多播或 JGroups)的代理集群。
先决条件
您应该已确定代理集群的大小。
更多信息请参阅 第 14.1.7 节 “集群大小注意事项”。
14.2.1. 使用静态发现创建代理集群
您可以通过指定静态代理列表来创建代理集群。如果您无法在网络上使用 UDP 多播或 JGroups，请使用这个静态发现方法。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在 <
;core> 元素中，添加以下连接器：- 定义其他代理如何连接这个连接器
- 定义此代理如何连接到集群中的其他代理的一个或多个连接器
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 有关连接器的更多信息，请参阅 第 2.3 节 “关于连接器”。
添加集群连接并将其配置为使用静态发现。
默认情况下，集群连接将对对称拓扑中所有地址进行负载平衡。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow cluster-connection-
使用
name属性指定集群连接的名称。 connector-ref- 定义其他代理如何连接这个连接器的连接器。
static-connectors- 此代理可用于进行初始连接到集群中的另一个代理的一个或多个连接器。在进行初始连接后，代理会发现集群中的其他代理。只有集群使用静态发现时，才需要配置此属性。
配置集群连接的任何其他属性。
这些额外的集群连接属性具有适合大多数常见用例的默认值。因此，如果您不希望默认行为，您只需要配置这些属性。更多信息请参阅 附录 C, 集群连接配置元素。
创建集群用户和密码。
AMQ Broker 附带默认集群凭证，但您应该更改它们以防止未经授权的远程客户端使用这些默认凭证来连接到代理。
重要在集群的每个代理上集群密码必须相同。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在每个额外代理上重复此步骤。
您可以将集群配置复制到每个额外代理中。但是，不要复制任何其他 AMQ Broker 数据文件（如绑定、日志和大型消息目录）。这些文件必须在集群中的节点之间唯一，否则集群不会正确组成。
其他资源
-
有关使用静态发现的代理集群示例，请参阅 cluster
-static-discovery示例。
14.2.2. 使用基于 UDP 的动态发现创建代理集群
您可以创建一个代理集群，代理通过 UDP 多播动态发现它们。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在 <
;core> 元素中，添加一个连接器。此连接器定义其他代理可用于连接到这个连接的连接信息。在发现过程中，此信息将发送到集群中的其他代理。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 添加 UDP 广播组。
broadcast 组可让代理将集群连接的信息推送到集群中的其他代理。这个广播组使用 UDP 广播连接设置：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 除非另有说明，否则需要以下参数：
broadcast-group-
使用
name属性为广播组指定唯一名称。 local-bind-address- UDP 套接字绑定到的地址。如果您在代理中有多个网络接口，您应该指定要用来广播的接口。如果没有指定此属性，套接字将绑定到操作系统所选的 IP 地址。这是特定于 UDP 的属性。
local-bind-port-
数据报套接字绑定到的端口。在大多数情况下，使用默认值
-1，它指定一个匿名端口。这个参数用于与local-bind-address的连接。这是特定于 UDP 的属性。 group-address-
数据要广播的多播地址。它是
224.0.0.0-239.255.255.255.255.255.255范围中的类 D IP 地址。地址224.0.0.0保留且不可用。这是特定于 UDP 的属性。 group-port- 用于广播的 UDP 端口号。这是特定于 UDP 的属性。
broadcast-period（可选）- 连续广播之间的间隔（毫秒）。默认值为 2000 毫秒。
connector-ref- 之前配置的集群连接器应该广播。
添加 UDP 发现组。
发现组定义此代理如何从其他代理接收连接器信息。代理维护一个连接器列表（每个代理一个条目）。当它从代理接收广播时，它会更新其条目。如果它没有从代理接收广播时间，它会删除该条目。
这个发现组使用 UDP 来发现集群中的代理：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 除非另有说明，否则需要以下参数：
discovery-group-
使用
name属性为发现组指定唯一名称。 local-bind-address（可选）- 如果运行代理的机器使用多个网络接口，您可以指定发现组应该侦听的网络接口。这是特定于 UDP 的属性。
group-address-
要侦听的组的多播地址。它应匹配您要侦听的广播组中的
group-address。这是特定于 UDP 的属性。 group-port-
多播组的 UDP 端口号。它应匹配您要侦听的广播组中的
group-port。这是特定于 UDP 的属性。 refresh-timeout（可选）发现组从特定代理接收最后一次广播后等待的时间（以毫秒为单位），然后再从其列表中删除该代理的连接器对条目。默认值为 10000 毫秒(10 秒)。
把它设置为比 broadcast 组中的
broadcast-period高的值。否则，代理可能会定期从列表中消失，即使它们仍然被广播（因为时间上的差别）。
创建群集连接并将其配置为使用动态发现。
默认情况下，集群连接将对对称拓扑中所有地址进行负载平衡。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow cluster-connection-
使用
name属性指定集群连接的名称。 connector-ref- 定义其他代理如何连接这个连接器的连接器。
discovery-group-ref- 此代理应该用来查找集群的其他成员的发现组。只有集群使用动态发现功能时才需要配置此属性。
配置集群连接的任何其他属性。
这些额外的集群连接属性具有适合大多数常见用例的默认值。因此，如果您不希望默认行为，您只需要配置这些属性。更多信息请参阅 附录 C, 集群连接配置元素。
创建集群用户和密码。
AMQ Broker 附带默认集群凭证，但您应该更改它们以防止未经授权的远程客户端使用这些默认凭证来连接到代理。
重要在集群的每个代理上集群密码必须相同。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在每个额外代理上重复此步骤。
您可以将集群配置复制到每个额外代理中。但是，不要复制任何其他 AMQ Broker 数据文件（如绑定、日志和大型消息目录）。这些文件必须在集群中的节点之间唯一，否则集群不会正确组成。
其他资源
-
有关在 UDP 中使用动态发现的代理集群配置示例，请参阅 cluster
-queue示例。
14.2.3. 使用基于 JGroups 的动态发现创建代理集群
如果您已在您的环境中使用 JGroups，可以使用它来创建一个代理集群，代理会互相动态发现。
先决条件
必须安装并配置 JGroups。
有关 JGroups 配置文件的示例，请参见 cluster
-jgroups示例。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在 <
;core> 元素中，添加一个连接器。此连接器定义其他代理可用于连接到这个连接的连接信息。在发现过程中，此信息将发送到集群中的其他代理。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 <
;core> 元素中，添加 JGroups 广播组。broadcast 组可让代理将集群连接的信息推送到集群中的其他代理。这个广播组使用 JGroups 来广播连接设置：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 除非另有说明，否则需要以下参数：
broadcast-group-
使用
name属性为广播组指定唯一名称。 JGroups-file- 用于初始化 JGroups 通道的 JGroups 配置文件的名称。该文件必须位于 Java 资源路径中，以便代理可以加载它。
jgroups-channel- 要连接到的 JGroups 通道的名称，以进行广播。
broadcast-period（可选）- 连续广播之间的间隔（以毫秒为单位）。默认值为 2000 毫秒。
connector-ref- 之前配置的集群连接器应该广播。
添加 JGroups 发现组。
发现组定义如何接收连接器信息。代理维护一个连接器列表（每个代理一个条目）。当它从代理接收广播时，它会更新其条目。如果它没有从代理接收广播时间，它会删除该条目。
此发现组使用 JGroups 来发现集群中的代理：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 除非另有说明，否则需要以下参数：
discovery-group-
使用
name属性为发现组指定唯一名称。 JGroups-file- 用于初始化 JGroups 通道的 JGroups 配置文件的名称。该文件必须位于 Java 资源路径中，以便代理可以加载它。
jgroups-channel- 要连接到的 JGroups 频道的名称，以接收广播。
refresh-timeout（可选）发现组从特定代理接收最后一次广播后等待的时间（以毫秒为单位），然后再从其列表中删除该代理的连接器对条目。默认值为 10000 毫秒(10 秒)。
把它设置为比 broadcast 组中的
broadcast-period高的值。否则，代理可能会定期从列表中消失，即使它们仍然被广播（因为时间上的差别）。
创建群集连接并将其配置为使用动态发现。
默认情况下，集群连接将对对称拓扑中所有地址进行负载平衡。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow cluster-connection-
使用
name属性指定集群连接的名称。 connector-ref- 定义其他代理如何连接这个连接器的连接器。
discovery-group-ref- 此代理应该用来查找集群的其他成员的发现组。只有集群使用动态发现功能时才需要配置此属性。
配置集群连接的任何其他属性。
这些额外的集群连接属性具有适合大多数常见用例的默认值。因此，如果您不希望默认行为，您只需要配置这些属性。更多信息请参阅 附录 C, 集群连接配置元素。
创建集群用户和密码。
AMQ Broker 附带默认集群凭证，但您应该更改它们以防止未经授权的远程客户端使用这些默认凭证来连接到代理。
重要在集群的每个代理上集群密码必须相同。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在每个额外代理上重复此步骤。
您可以将集群配置复制到每个额外代理中。但是，不要复制任何其他 AMQ Broker 数据文件（如绑定、日志和大型消息目录）。这些文件必须在集群中的节点之间唯一，否则集群不会正确组成。
其他资源
- 有关在 JGroups 中使用动态发现的代理集群的示例，请参阅 cluster -jgroups 示例。
14.3. 实施高可用性
您可以通过实施高可用性(HA)来提高可靠性，即使一个或多个代理离线，代理集群也会继续正常工作。
实现 HA 涉及几个步骤：
- 为您的 HA 实现配置代理集群，如 第 14.2 节 “创建代理集群” 所述。
- 您应该了解什么是主备份组，然后选择最适合您的要求的 HA 策略。请参阅了解 HA 在 AMQ Broker 中的工作方式。
当您选择合适的 HA 策略时，在集群的每个代理上配置 HA 策略。请参阅：
- 将您的客户端应用程序配置为使用故障转移。
之后，如果您需要对配置为高可用性的代理集群进行故障排除，建议您为在集群中运行代理的每个 Java 虚拟机(JVM)实例启用 Garbage Collection (GC)日志记录。要了解如何在 JVM 上启用 GC 日志，请查阅 JVM 使用的 Java Development Kit (JDK)版本的官方文档。有关 AMQ Broker 支持的 JVM 版本的更多信息，请参阅 Red Hat AMQ 7 支持的配置。
14.3.1. 了解高可用性
在 AMQ Broker 中，您可以通过将集群中的代理分组到 primary-backup 组 来实现高可用性(HA)。在 primary-backup 组中，主代理链接到备份代理，如果失败，可以接管主代理。AMQ Broker 还为 primary-backup 组中的故障转移（称为 HA 策略）提供多个不同的策略。
14.3.1.1. 主备份组如何提供高可用性
在 AMQ Broker 中，您可以通过将集群中的代理链接到 主备份组 来实现高可用性(HA)。主备份组提供 故障转移，这意味着如果一个代理失败，另一个代理可以接管其消息处理。
primary-backup 组由一个连接到一个或多个备份代理的主代理组成。主代理服务客户端请求，而备份代理在被动模式下等待。如果主代理失败，备份代理会替换主代理作为活跃代理，启用客户端重新连接并继续其工作。
14.3.1.2. 高可用性策略
高可用性(HA)策略定义了在主备份组中如何发生故障转移。AMQ Broker 提供几个不同的 HA 策略：
- 共享存储（推荐）
主代理将消息传递数据存储在共享文件系统上的通用目录中；通常是存储区域网络(SAN)或网络文件系统(NFS)服务器。如果您配置了基于 JDBC 的持久性，您还可以将代理数据存储在指定的数据库中。使用共享存储时，如果主代理失败，备份代理会从共享存储中加载消息数据，并接管作为活跃代理。
在大多数情况下，您应该使用共享存储而不是复制。由于共享存储不会通过网络复制数据，因此通常比复制提供更好的性能。共享存储还避免了网络隔离（也称为"脑裂"）问题，其中主代理及其备份同时处于活动状态。
图 14.4. 共享存储高可用性
- 复制
主代理和备份代理持续通过网络同步其消息传递数据。如果主代理失败，备份代理会加载同步的数据，并作为活跃代理。
主代理和备份代理之间的数据同步可确保主代理失败时不会丢失消息传递数据。当主和备份代理最初加入在一起时，主代理会通过网络将其所有现有数据复制到备份代理中。此初始阶段完成后，主代理会将持久数据复制到备份代理中，因为主代理接收它。这意味着，如果主代理丢弃了网络，备份代理会具有主代理收到的所有持久数据。
因为复制通过网络同步数据，所以网络失败可能会导致主代理及其备份同时处于活跃状态。
图 14.5. 复制高可用性
- 仅主要（有限 HA）
当主代理安全停止时，它会将消息和事务状态复制到另一个活跃代理中，然后关闭。然后，客户端可以重新连接到其他代理以继续发送和接收信息。
图 14.6. 仅主高可用性
其他资源
- 有关主备份组中代理之间共享的持久性消息数据的更多信息，请参阅 第 6.1 节 “在日志中保留消息数据”。
14.3.1.3. 复制策略限制
当您使用复制提供高可用性时，主代理和备份代理可以同时变为活动状态（称为"脑裂"。
如果主代理及其备份丢失连接，则脑裂可能会出现。在这种情况下，主代理及其备份可以同时变为活动状态。由于在这种情况下没有代理间没有消息复制，因此它们各自为客户端和处理消息提供服务，而不会进行其他了解。在这种情况下，每个代理都有完全不同的日志。从这种情况中恢复可能非常困难，在某些情况下无法进行。
- 要 消除 脑裂的可能性，请使用 共享存储 HA 策略。
如果使用复制 HA 策略，请执行以下步骤来减少发生脑裂的风险。
如果您希望代理使用 ZooKeeper Coordination 服务协调代理，请在至少三个节点上部署 ZooKeeper。如果代理丢失到一个 ZooKeeper 节点的连接，使用至少三个节点可确保当主备份代理对复制中断时，大多数节点都可用来协调代理。
如果要使用嵌入式代理协调，它使用集群中的其他可用代理提供仲裁投票，您可以减少（但不消除）遇到脑裂的可能性( 至少使用三个主备份对 )。至少使用三个主备份对可确保当主备份代理对复制中断发生时，任何仲裁票数都可实现大多数结果。
使用复制 HA 策略时的一些额外注意事项如下所述：
- 当主代理失败且备份代理处于活跃状态时，在新的备份代理附加到活跃代理前，不会进行进一步的复制，或者恢复到原始主代理发生。
- 如果 primary-backup 组中的备份代理失败，则主代理将继续提供信息。但是，在将另一个代理添加为备份或原始备份代理重启前，消息不会被复制。在此期间，消息只会保留在主代理中。
- 如果代理使用嵌入式代理协调，且主备份对中的两个代理都已关闭，为了避免消息丢失，您必须首先重启最近活跃的代理。如果最近活跃的代理是备份代理，则需要手动将此代理重新配置为主代理，以便首先重启它。
14.3.3. 配置复制高可用性
您可以使用复制高可用性(HA)策略在代理集群中实施 HA。通过复制，持久数据会在主代理和备份代理之间同步。如果主代理遇到失败，消息数据会同步到备份代理，它会接管失败的主代理。
如果您没有共享文件系统，您应该使用复制作为共享存储的替代选择。但是，复制可能会导致主代理及其备份同时变为活跃的情况。
由于主和备份代理必须通过网络同步其消息传递数据，因此复制会增加性能开销。此同步进程会阻止日志操作，但它不会阻止客户端。您可以配置日志操作对于数据同步的最大时间。
如果 primary-backup 代理对之间的复制连接中断，代理需要一种协调方法来确定主代理是否仍然活跃，或者是否需要到备份代理的故障转移。为了提供此协调，您可以将代理配置为使用以下一种协调方法。
- Apache ZooKeeper 协调服务。
- 嵌入式代理协调，它使用集群中的其他代理来提供仲裁投票。
14.3.3.1. 选择协调方法
红帽建议您使用 Apache ZooKeeper 协调服务协调代理激活。在选择协调方法时，了解基础架构要求和两个协调方法之间数据一致性的差异会很有用。
基础架构要求
- 如果使用 ZooKeeper 协调服务，您可以使用单个主备份代理对操作。但是，您必须将代理连接到至少 3 个 Apache ZooKeeper 节点，以确保代理在连接到一个节点时可以继续正常工作。要为代理提供协调服务，您可以共享其他应用程序使用的现有 ZooKeeper 节点。有关设置 Apache ZooKeeper 的更多信息，请参阅 Apache ZooKeeper 文档。
- 如果要使用嵌入式代理协调，它使用集群中的其他可用代理提供仲裁投票，则必须至少有三个主备份代理对。至少使用三个主备份对，确保在主备份代理对复制中断发生的任何仲裁投票中都可以实现大多数结果。
数据一致性
- 如果您使用 Apache ZooKeeper 协调服务，ZooKeeper 会跟踪每个代理上的数据版本，因此只有具有最新日志数据的代理才可以变为 active，无论代理是否配置为复制目的。版本跟踪消除了代理通过过时的日志和开始服务客户端可以激活的可能性。
- 如果您使用嵌入的代理协调，则不会有机制来跟踪每个代理上的数据版本，以确保只有具有最新日志的代理才会变为活动状态。因此，一个具有没有最新日志的代理可以变为活跃并开始服务客户端，这会导致日志有不同性。
14.3.3.2. 在复制中断后代理如何协调
本节介绍在复制连接中断后两个协调方法的工作方式。
使用 ZooKeeper 协调服务
如果使用 ZooKeeper 协调服务来管理复制中断，则两个代理都必须连接到多个 Apache ZooKeeper 节点。
- 如果任何时候，活跃代理会丢失到大多数 ZooKeeper 节点的连接，它会关闭，以避免出现"脑裂"的风险。
- 如果随时，备份代理会丢失到大多数 ZooKeeper 节点的连接，它会停止接收复制数据并等待它连接到大多数 ZooKeeper 节点，然后再重新充当备份代理。当连接恢复到大多数 ZooKeeper 节点时，备份代理使用 ZooKeeper 来确定是否需要丢弃其数据并搜索要从中复制的活动代理，或者它是否可以成为带有其当前数据的活跃代理。
ZooKeeper 使用以下控制机制来管理故障切换过程：
- 可以随时由单个活跃代理拥有的共享租期锁定。
- 跟踪代理数据的最新版本的激活序列计数器。每个代理将其日志数据的版本跟踪在其服务器锁定文件中的本地计数器中，及其 NodeID。活跃代理还在 ZooKeeper 上的协调激活序列中共享其版本。
如果活跃代理和备份代理之间的复制连接丢失，活跃代理会同时增加其本地激活序列计数器值，并在 ZooKeeper 上增加协调激活序列计数器值，以公告它具有最新数据。备份代理的数据现在被视为过时，代理将无法变为活跃代理，直到恢复复制连接并同步最新的数据。
在复制连接丢失后，备份代理会检查 ZooKeeper 锁定是否归活跃代理所有，以及 ZooKeeper 上的协调激活序列是否与其本地计数器值匹配。
- 如果锁定由活跃代理所有，则备份代理检测到 ZooKeeper 上的激活序列计数器会在复制连接丢失时由活跃代理更新。这表示活跃代理正在运行，因此备份代理不会尝试故障转移。
- 如果锁定不归活跃代理所有，则活跃代理将无法激活。如果备份代理上的激活序列的值与 ZooKeeper 上的协调激活序列计数器值相同，这表示备份代理具有最新数据，备份代理会失败。
- 如果锁定不归活跃代理所有，但备份代理上的激活序列计数器的值小于 ZooKeeper 上的计数器值，备份代理中的数据不会处于最新状态，备份代理无法故障转移。
使用嵌入式代理协调
如果 primary-backup 代理对使用嵌入式代理协调来协调复制中断，则可以启动以下两种类型的仲裁投票。
| vote 类型 | 描述 | initiator | 所需的配置 | 参与者 | 基于投票结果的操作 |
|---|---|---|---|---|---|
| 被动投票 | 如果被动代理丢失了与活跃代理的复制连接，则被动代理会根据这个投票的结果来决定是否启动。 | 被动代理 | 无。当被动代理丢失与其复制合作伙伴的连接时，被动投票会自动发生。 但是，您可以通过为这些参数指定自定义值来控制被动投票的属性：
| 集群中的其他活跃代理 | 如果被动代理从集群中的其他活跃代理接收大多数（即 仲裁）投票，这表示其复制合作伙伴不再可用。 |
| 活跃投票 | 如果活跃代理丢失了与其复制合作伙伴的连接，活跃代理会决定根据此票继续运行。 | 活跃代理 |
当一个活跃代理（可能配置为已故障转移的备份）时发生投票，丢失与复制合作伙伴的连接， | 集群中的其他活跃代理 | 如果没有 从集群中的其他活跃代理接收大多数投票，则活跃代理会关闭，表示其集群连接仍然活跃。 |
下面列出了一些重要的事项，以记录您的代理集群的配置如何影响制裁行为。
- 要使仲裁投票成功，集群的大小必须允许达到大多数结果。因此，您的集群应该 至少有三个 主备份代理对。
- 您添加到集群中的 primary-backup 代理对越多，您可以提高集群的整体容错能力。例如，假设您有三个主备份对。如果您丢失了完整的主备份对，则其余两个主备份对无法达到任何后续的仲裁投票。这种情况意味着集群中出现进一步的复制中断可能会导致主代理关闭，并防止其备份代理启动。通过使用五个代理对配置集群，集群至少可能会出现两个故障，同时仍然保证任何仲裁票的大部分结果。
- 如果您有意 减少 集群中的主备份代理对数量，则之前为大多数投票建立的阈值不会自动减少。在此期间，丢失的复制连接触发的任何仲裁票数都无法成功，使集群更易受脑裂的影响。要使集群重新计算仲裁投票的最大阈值，请首先关闭您要从集群中删除的主要备份对。然后，重启集群中剩余的主备份对。当所有剩余的代理都已重启时，集群会重新计算仲裁投票阈值。
14.3.3.3. 使用 ZooKeeper 协调服务为代理集群配置复制
您必须在使用 Apache ZooKeeper 协调服务的对中同时指定相同的复制配置。然后，代理会协调以确定哪个代理是活跃代理，这是被动备份代理。
先决条件
- 至少 3 个 Apache ZooKeeper 节点，确保在代理丢失到一个节点时可以继续运行。
- 代理机器有类似的硬件规格，即，您不希望运行活跃代理，并在任何时间点上运行被动备份代理。
- ZooKeeper 必须有足够的资源来确保暂停时间显著低于 ZooKeeper 服务器空循环时间。根据代理的预期负载，请考虑代理和 ZooKeeper 节点是否可以共享同一节点。如需更多信息，请参阅 https://zookeeper.apache.org/。
流程
-
为对
中的两个代理打开 <broker_instance_dir> /etc/broker.xml配置文件。 为对中的两个代理配置相同的复制配置。例如：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow primary- 将复制类型配置为 primary，表示代理可以是主代理，具体取决于代理协调的结果。
coordination-id-
为两个代理指定一个通用字符串值。具有相同
Coordination-id字符串的代理将激活协调在一起。在协调过程中，两个代理都使用Coordination-id字符串作为节点 Id，并尝试在 ZooKeeper 中获取锁定。获取锁定并具有最新数据的第一个代理将作为活跃代理启动，其他代理会成为被动备份。 属性指定
property元素，您可以指定一组键值对来提供 ZooKeeper 节点的连接详情：Expand 表 14.2. ZooKeeper 连接详情 键 值 connect-string
指定以逗号分隔的 IP 地址和 ZooKeeper 节点的端口号列表。例如，
value="192.168.1.10:6666,192.168.2.10:6667,192.168.3.10:6668"。session-ms
代理在丢失到大多数 ZooKeeper 节点的连接后等待的持续时间。默认值为
18000ms。有效值是 ZooKeeper 服务器空循环时间的 2 次和 20 次。注意垃圾回收值的 ZooKeeper 暂停时间必须小于
session-ms属性的值 0.33，以便 ZooKeeper heartbeat 能够可靠地正常工作。如果无法确保暂停时间小于这个限制，请增加每个代理的session-ms属性的值，并接受较慢的故障转移。重要代理复制合作伙伴每 2 秒自动交换"ping"数据包，以确认合作伙伴代理可用。当备份代理没有从活跃代理接收响应时，备份会等待响应，直到代理的连接生存时间(ttl)过期。默认 connection-ttl 为
60000ms，这意味着备份代理尝试在 60 秒后尝试故障转移。建议您将 connection-ttl 值设置为与session-ms属性值类似的值，以便更快地进行故障转移。要设置新的 connection-ttl，请配置connection-ttl-override属性。namespace （可选）
如果代理与其他应用程序共享 ZooKeeper 节点，您可以创建一个 ZooKeeper 命名空间来存储为代理提供协调服务的文件。您必须为这两个代理指定相同的命名空间。
为代理配置任何其他 HA 属性。
这些额外的 HA 属性具有适合大多数常见用例的默认值。因此，如果您不希望默认行为，您只需要配置这些属性。更多信息请参阅 附录 F, 其他复制高可用性配置元素。
- 重复步骤 1 到 3，以配置集群中的每个额外代理对。
其他资源
- 有关将复制用于 HA 的代理集群示例，请参阅 HA 示例。
- 有关节点 ID 的更多信息，请参阅了解节点 ID。
14.3.3.4. 使用嵌入式代理协调配置代理集群以复制高可用性
使用嵌入式代理协调进行复制至少需要三个主备份对，以减少（但不消除）"脑裂"的风险。
以下流程描述了如何为 6-broker 集群配置复制高可用性(HA)。在这个拓扑中，6 个代理被分成三个主备份对：三个主代理都使用专用的备份代理对。
先决条件
您必须有一个至少 6 个代理的代理集群。
6 个代理配置为三个主备份对。有关在集群中添加代理的详情，请参考 第 14 章 设置代理集群。
流程
将集群中的代理分组到主备份组中。
在大多数情况下，primary-backup 组应该由两个代理组成：一个主代理和一个备份代理。如果您在集群中有六个代理，则需要三个主备份组。
创建由一个主代理和一个备份代理组成的第一个 primary-backup 组。
-
打开主代理的 <
broker_instance_dir> /etc/broker.xml配置文件。 配置主代理，以将复制用于其 HA 策略。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow check-for-active-server如果主代理失败，此属性控制客户端重启时是否应该返回它。
如果将此属性设置为
true，则当主代理在之前的故障转移后重启时，它会搜索具有相同节点 ID 的集群中的另一个代理。如果主代理找到具有相同节点 ID 的另一个代理，这表示在主代理失败后成功启动了备份代理。在这种情况下，主代理将其数据与备份代理同步。然后，主代理请求备份代理关闭。如果为故障恢复配置了备份代理，它会被关闭。然后，主代理会恢复其活跃角色，客户端会重新连接。警告如果您没有在主代理上将
check-for-active-server设置为true，则可能会在之前的故障转移后重启主代理时遇到重复的消息传递处理。具体来说，如果您重启一个主代理，其此属性设置为false，则主代理不会将数据与其备份代理同步。在这种情况下，主代理可能会处理备份代理已处理的相同消息，从而导致重复。group-name- 此 primary-backup 组的名称（可选）。要形成 primary-backup 组，必须使用相同的组名称配置主和备份代理。如果没有指定 group-name，备份代理可以使用任何主代理复制。
vote-on-replication-failure此属性控制主代理是否在中断复制连接时启动一个名为 primary vote 的仲裁投票。
主要投票是主代理用来确定它还是其合作伙伴是中断复制连接的原因的方法。根据 vote 的结果，主代理可以保持运行或关闭。
重要要使仲裁投票成功，集群的大小必须允许达到大多数结果。因此，在使用复制 HA 策略时，您的集群应该 至少有三个 主备份代理对。
在集群中配置更多代理对，您可以提高集群的整体容错能力。例如，假设您有三个主备份代理对。如果您丢失了与完整的主备份对的连接，则剩余的两个主备份对不再达到仲裁投票。这意味着，任何后续复制中断都可能会导致主代理关闭，并阻止备份代理启动。通过使用五个代理对配置集群，集群至少可能会出现两个故障，同时仍然保证任何仲裁票的大部分结果。
为主代理配置任何其他 HA 属性。
这些额外的 HA 属性具有适合大多数常见用例的默认值。因此，如果您不希望默认行为，您只需要配置这些属性。更多信息请参阅 附录 F, 其他复制高可用性配置元素。
-
打开备份代理的 <
broker_instance_dir> /etc/broker.xml配置文件。 配置备份代理，以将复制用于其 HA 策略。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow allow-failback如果发生故障转移并且为主代理接管备份代理，此属性控制备份代理是否应该在重启并重新连接到集群时返回到原始主代理。
注意failback 用于主备份对（一个主代理与单个备份代理配对）。如果主代理配置了多个备份，则不会进行故障恢复。相反，如果发生故障转移事件，备份代理将活跃，下一个备份将变为备份。当主代理恢复在线时，将无法启动故障恢复，因为现在活跃的代理已有备份。
group-name- 此 primary-backup 组的名称（可选）。要形成 primary-backup 组，必须使用相同的组名称配置主和备份代理。如果没有指定 group-name，备份代理可以使用任何主代理复制。
vote-on-replication-failure此属性控制已激活的备份代理是否可以在中断复制连接时启动称为 主票的仲裁投票。
主要投票是主代理用来确定它还是其合作伙伴是中断复制连接的原因的方法。根据 vote 的结果，主代理可以保持运行或关闭。
（可选）配置备份代理启动的仲裁票的属性。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow vote-retries- 此属性控制备份代理重试仲裁投票的次数，以便接收允许备份代理启动最多的结果。
vote-retry-wait- 此属性控制每次重试仲裁票之间等待的备份代理的时间（以毫秒为单位）。
为备份代理配置任何其他 HA 属性。
这些额外的 HA 属性具有适合大多数常见用例的默认值。因此，如果您不希望默认行为，您只需要配置这些属性。更多信息请参阅 附录 F, 其他复制高可用性配置元素。
-
打开主代理的 <
对集群中的每个额外的 primary-backup 组重复步骤 2。
如果集群中有六个代理，请多次重复这个过程 ; 为每个剩余的 primary-backup 组重复一次。
其他资源
- 有关将复制用于 HA 的代理集群示例，请参阅 HA 示例。
- 有关节点 ID 的更多信息，请参阅了解节点 ID。
14.3.4. 使用仅主配置有限高可用性
唯一的 HA 策略允许您在不丢失任何信息的情况下在集群中关闭代理。使用 primary-only 时，当活跃代理安全停止时，它会将消息和事务状态复制到另一个活跃代理中，然后关闭。然后，客户端可以重新连接到其他代理以继续发送和接收信息。
仅主 HA 策略仅在安全停止代理时处理问题单。它不会处理意外的代理失败。
虽然仅主 HA 会阻止消息丢失，但可能无法保留消息顺序。如果停止配置了主 HA 的代理，其消息将附加到另一个代理队列的末尾。
当代理准备缩减时，它会将消息发送到其客户端，然后再断开连接，通知这些新代理已准备好处理其消息。但是，只有在初始代理完成缩减后，客户端才应重新连接到新代理。这样可确保当客户端重新连接时，其他代理上都可以有任何状态（如队列或事务）。在客户端重新连接时，会应用正常重新连接设置，因此您应该设置默认值，以处理缩减所需的时间。
此流程描述了如何配置集群中的每个代理来缩减。完成此步骤后，每当代理安全停止后，它将将其消息和事务状态复制到集群中的另一个代理。
流程
-
打开第一个代理的 <
broker_instance_dir> /etc/broker.xml配置文件。 将代理配置为使用只读 HA 策略。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 配置缩减代理集群的方法。
指定此代理应缩减到的代理或代理组。
Expand 表 14.3. 缩减代理集群的方法 要缩减到… 这些以下操作 集群中的特定代理
指定要缩减的代理连接器。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 集群中的任何代理
指定代理的发现组。
<primary-only> <scale-down> <discovery-group-ref discovery-group-name="my-discovery-group"/> </scale-down> </primary-only><primary-only> <scale-down> <discovery-group-ref discovery-group-name="my-discovery-group"/> </scale-down> </primary-only>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 特定代理组中的代理
指定代理组。
<primary-only> <scale-down> <group-name>my-group-name</group-name> </scale-down> </primary-only><primary-only> <scale-down> <group-name>my-group-name</group-name> </scale-down> </primary-only>Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 对集群中的每个剩余的代理重复此步骤。
其他资源
-
有关使用 primary-only 缩减集群的代理集群示例，请参阅
缩减示例。
14.3.5. 使用并置备份配置高可用性
您可以在与另一个主代理相同的 JVM 中并置备份代理，而不是配置 primary-backup 组。在这个配置中，每个主代理配置为请求另一个主代理在 JVM 中创建和启动备份代理。
图 14.7. colocated 主和备份代理
您可以将 colocation 与共享存储一起使用，或复制作为高可用性(HA)策略。新的备份代理从创建它的主代理中继承其配置。备份的名称设置为 colocated_backup_n，其中 n 是主代理创建的备份数量。
另外，备份代理会继承其连接器的配置，以及创建它的主代理中的 acceptors。默认情况下，为每个应用端口偏移 100。例如，如果主代理具有端口 61616 的接收器，则创建的第一个备份代理将使用端口 61716，第二个备份将使用 61816，以此类推。
根据您选择的 HA 策略设置日志、大消息和分页的目录。如果选择共享存储，请求代理会通知目标代理要使用哪个目录。如果选择了复制，目录将从创建代理继承，并将新备份的名称附加到它们。
此流程将集群中的每个代理配置为使用共享存储 HA，并请求创建备份并与集群中的另一个代理在一起。
流程
-
打开第一个代理的 <
broker_instance_dir> /etc/broker.xml配置文件。 将代理配置为使用 HA 策略和 colocation。
在本例中，代理配置了共享存储 HA 和 colocation。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow request-backup-
通过将此属性设置为
true，此代理将请求一个备份代理由集群中的另一个主代理创建。 max-backups-
此代理可以创建的备份代理数量。如果将此属性设置为
0，则此代理不接受来自集群中其他代理的备份请求。 backup-request-retries-
此代理应尝试请求创建备份代理的次数。默认值为
-1，即无限尝试。 backup-request-retry-interval-
代理在重试请求以创建备份代理前应等待的时间（毫秒）。默认值为
5000或 5 秒。 backup-port-offset-
用于接受器和新备份代理的端口偏移。如果此代理收到一个请求来为集群中的另一个代理创建备份，它将创建带有这个数量的端口偏移的备份代理。默认值为
100。 excludes（可选）-
从备份端口偏移中排除连接器。如果您已经为应该排除在备份端口偏移中的外部代理配置了任何连接器，请为每个连接器添加一个 <
;connector-ref>。 primary- 此代理的共享存储或复制故障转移配置。
backup- 此代理的备份的共享存储或复制故障转移配置。
- 对集群中的每个剩余的代理重复此步骤。
其他资源
- 有关使用 colocated 备份的代理集群示例，请参阅 HA 示例。
14.3.6. 将客户端配置为故障切换
在代理集群中配置高可用性后，您可以将客户端配置为故障切换。客户端故障转移可确保如果代理失败，连接到它的客户端可以在最少的停机时间的情况下重新连接到集群中的另一个代理。
如果出现临时网络问题，AMQ Broker 会自动重新附加连接到同一代理。这与故障转移类似，但客户端重新连接到同一代理。
您可以配置两种不同类型的客户端故障转移：
- 自动客户端故障转移
- 客户端在第一次连接时接收代理集群的信息。如果连接了它的代理失败，客户端会自动重新连接到代理的备份，备份代理会在故障转移前重新创建每个连接上存在的任何会话和用户。
- 应用程序级别的客户端故障转移
- 作为自动客户端故障转移的替代选择，您可以在故障处理程序中使用自己的自定义重新连接逻辑来编写客户端应用程序。
流程
使用 AMQ 核心协议 JMS 配置带有自动或应用程序级别的故障转移的客户端应用程序。
如需更多信息，请参阅使用 AMQ 核心协议 JMS 客户端。
14.4. 启用消息重新发布
如果您的代理集群配置了 message-load-balancing 设置为 ON_DEMAND 或 OFF_WITH_REDISTRIBUTION，您可以配置消息 重新发布 以防止消息在没有消费者使用的队列中"stuck"。
本节包含有关以下内容的信息：
14.4.1. 了解消息再发布
代理集群使用负载均衡来在集群中分发消息负载。在集群连接中配置负载均衡时，您可以使用以下 message-load-balancing 设置启用重新发布：
-
ON_DEMAND- 启用负载平衡并允许重新发布 -
OFF_WITH_REDISTRIBUTION- 禁用负载均衡，但允许重新发布
在这两种情况下，代理只会将消息转发到具有匹配消费者的其他代理。此行为可确保消息不会移到没有用户使用消息的队列。但是，如果用户在消息转发到代理后附加到队列关闭，则这些消息将变为队列中的"stuck"，且不会被使用。此问题有时被称为 不足状态。
消息重新发布通过自动重新分发消息从没有消费者为具有匹配消费者的集群中的代理队列进行分发。
使用 OFF_WITH_REDISTRIBUTION 时，代理只会将消息转发到具有匹配消费者的其他代理（如果没有活跃消费者），允许您在消费者不可用时提供替代方案。
消息重新发布支持使用过滤器（也称为 选择器），也就是说，当消息与可用本地消费者的选择器不匹配时，会重新分发消息。
其他资源
- 有关集群负载均衡的更多信息，请参阅 第 14.1.1 节 “代理集群如何平衡消息负载”。
14.4.2. 配置消息重新发布
此流程演示了如何通过负载平衡配置消息重新发布。如果您希望在没有负载均衡的情况下重新发布消息，请将 < ;message-load-balancing& gt; 设置为 OFF_WITH_REDISTRIBUTION。
流程
-
打开 &
lt;broker_instance_dir> /etc/broker.xml配置文件。 在 &
lt;cluster-connection> 元素中，验证<message-load-balancing> 是否已设置为ON_DEMAND。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 <
;address-settings> 元素中，为队列或一组队列设置 redistribution delay。在本例中，在最后一个消费者关闭后，对
my.queue的消息负载均衡将重新分发 5000 毫秒。Copy to Clipboard Copied! Toggle word wrap Toggle overflow address-setting-
将
match属性设置为您要重新分发消息的队列的名称。您可以使用代理通配符语法来指定队列的范围。更多信息请参阅 第 4.2 节 “将地址设置应用到一组地址”。 redistribution-delay-
代理应在此队列的最终消费者关闭后等待的时间（以毫秒为单位），然后再将消息重新分发到集群中的其他代理。如果将其设置为
0，则会立即重新分发消息。但是，您应该在 redistributing 之前设置延迟 - 通常与消费者关闭，但需要在同一队列中快速创建另一个延迟。
- 对集群中的每个额外代理重复此步骤。
其他资源
-
有关重新分发消息的代理集群配置示例，请参阅
queue-message-redistribution示例。
14.5. 配置集群消息分组
消息分组可让客户端发送特定类型的消息组，以便由同一消费者按顺序处理。通过向集群中的每个代理添加分组处理程序，您可以确保客户端可以将分组的消息发送到集群中的任何代理，并且仍然以正确顺序使用这些消息。
分组和集群技术总结如下：
- 消息分组会对消息消耗施加一个顺序。在组中，必须在继续下一消息之前完全使用并确认每个消息。这个方法会导致串行消息处理，其中 concurrency 不是一个选项。
- 集群旨在水平扩展代理，以提高消息吞吐量。通过添加额外的用户可以同时处理消息的消费者来实现水平扩展。
由于这些技术相互冲突，因此请避免将集群和分组一起使用。
有两种分组处理程序：local handlers 和 remote handlers。它们可让代理集群将特定组中的所有消息路由到适当的队列，以便预期的消费者可以以正确顺序消耗它们。
先决条件
集群中每个代理上应至少有一个使用者。
当消息固定到队列中的消费者时，具有相同组 ID 的所有消息都将路由到该队列。如果删除了消费者，则队列将继续接收消息，即使没有消费者也是如此。
流程
在集群中的一个代理上配置本地处理器。
如果您使用高可用性，这应该是主代理。
-
打开代理的 <
broker_instance_dir> /etc/broker.xml配置文件。 在 <
;core> 元素中添加本地处理器：本地处理程序充当远程处理程序的仲裁程序。它存储路由信息并将其与其他代理通信。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow grouping-handler-
使用
name属性为分组处理程序指定唯一名称。 type-
把它设置为
LOCAL。 timeout决定在路由消息的位置等待的时间（以毫秒为单位）。默认值为 5000 毫秒。如果在做出路由决策前达到超时，则会抛出异常，这样可保证严格的消息排序。
当代理收到带有组 ID 的消息时，它会将路由到消费者所连接的队列的路由。如果路由被集群中的其他代理上的分组处理程序接受，则路由会被建立：集群中的所有代理都将使用此组 ID 的消息转发到该队列。如果代理的路由提议被拒绝，则提议一个备用路由，重复这个过程，直到接受路由为止。
-
打开代理的 <
如果您使用高可用性，请将本地处理器配置复制到主代理的备份代理中。
将本地处理器配置复制到备份代理可防止本地处理程序出现单点故障。
在集群的每个剩余的代理中，配置远程处理器。
-
打开代理的 <
broker_instance_dir> /etc/broker.xml配置文件。 在 <
;core> 元素中添加远程处理器：Copy to Clipboard Copied! Toggle word wrap Toggle overflow grouping-handler-
使用
name属性为分组处理程序指定唯一名称。 type-
把它设置为
REMOTE。 timeout- 决定在路由消息的位置等待的时间（以毫秒为单位）。默认值为 5000 毫秒。将此值设置为本地处理程序值的至少一半。
-
打开代理的 <
其他资源
- 有关为消息分组配置的代理集群的示例，请参阅 JMS 集群分组示例。
14.6. 将客户端连接到代理集群
您可以使用红帽构建的 Apache Qpid JMS 客户端连接到集群。通过使用 JMS，您可以将消息传递客户端配置为动态或静态发现代理列表。您还可以配置客户端负载均衡，以分发从集群中的连接中创建的客户端会话。
流程
使用 AMQ 核心协议 JMS 将客户端应用程序配置为连接到代理集群。
如需更多信息，请参阅使用 AMQ 核心协议 JMS 客户端。
14.7. 客户端连接分区
分区客户端连接涉及在每次客户端发起连接时将各个客户端路由到同一代理的路由连接。
客户端连接的两种用例是：
- 对持久订阅进行分区客户端，以确保订阅者始终连接到 durable 订阅者队列所在的代理。
- 通过吸引客户到源自数据的数据（也称为数据 gravity），最大限度地减少对移动数据的需要。
持久化订阅
持久化订阅以代理上的队列表示，并在持久订阅者首先连接到代理时创建。这个队列保留在代理中，并接收信息，直到客户端取消订阅为止。因此，您希望客户端重复连接到同一代理，以使用订阅者队列中的消息。
要对客户端进行持久订阅队列分区，您可以在客户端连接中过滤客户端 ID。
Data gravity
如果您在环境中扩展代理数量而不考虑数据 gravity，则一些性能优势会因为需要在代理间移动消息而丢失。要支持日期变化，您应该对客户端连接进行分区，以便客户端用户连接到生成所需消息的代理。
要分区客户端连接来支持 data gravity，您可以过滤客户端连接的任何属性：
- 分配给连接用户的角色(ROLE_NAME)
- 用户的用户名(USER_NAME)
- 客户端的主机名(SNI_HOST)
- 客户端的 IP 地址(SOURCE_IP)
14.7.1. 对客户端连接进行分区以支持持久化订阅
要对客户端进行持久订阅分区，您可以使用一致的哈希算法或正则表达式在传入连接中过滤客户端 ID。
先决条件
客户端会被配置，以便它们可以连接到集群中的所有代理，例如，使用负载均衡器或让所有代理实例在连接 URL 中配置。如果代理拒绝连接，因为客户端详情与那个代理的分区配置不匹配，客户端必须能够连接到集群中的其他代理，以查找接受来自它的连接的代理。
14.7.1.1. 使用一致的哈希算法过滤客户端 ID
您可以将集群中的每个代理配置为使用一致的哈希算法来对每个客户端连接中的客户端 ID 进行哈希处理。代理哈希客户端 ID 后，它会在散列值上执行 modulo 操作，以返回一个整数值，用于标识客户端连接的目标代理。代理将整数值与代理上配置的唯一值进行比较。如果存在匹配项，代理会接受连接。如果值不匹配，代理会拒绝连接。此过程会在集群中的每个代理上重复，直到找到匹配项并接受连接。
流程
-
为第一个代理打开 <
broker_instance_dir> /etc/broker.xml配置文件。 创建
connection-routers元素，并创建一个connection-route来使用一致的哈希算法过滤客户端 ID。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow connection-route-
对于
connection-route 名称，请为此连接路由配置指定一个识别字符串。您必须将此名称添加到要应用一致的散列过滤器的每个代理接受者。 key-
将过滤器应用到的密钥类型。要过滤客户端 ID，请在
key字段中指定CLIENT_ID。 local-target-filter-
代理与 modulo 操作返回的整数值进行比较，以确定是否存在匹配项，代理是否可以接受连接。示例中的
NULL|0值为没有客户端 ID(NULL)的连接提供了匹配的连接，其中 modulo 操作返回的数量为0。 policy接受
modulo属性键，它对哈希客户端 ID 执行 modulo 操作，以识别目标代理。modulo属性键的值必须等于集群中的代理数量。重要策略名称必须是CONSISTENT_HASH_MODULO。
-
为第二个代理打开 <
broker_instance_dir> /etc/broker.xml配置文件。 创建
connection-routers元素，并使用一致的哈希算法创建一个连接路由来过滤客户端 ID。在以下示例中，
NULL|1的local-target-filter值为没有客户端 ID (NULL)的连接提供了匹配，其中 modulo 操作返回的值为1。Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 重复此步骤，为集群中的每个额外代理创建一个一致的哈希过滤器。
14.7.1.2. 使用正则表达式过滤客户端 ID
您可以通过将代理配置为对客户端连接中的客户端 ID 的一部分应用正则表达式过滤器来对客户端连接进行客户端连接分区。只有在正则表达式过滤器的结果与为代理配置的本地目标过滤器匹配时，代理才会接受连接。如果没有找到匹配项，代理会拒绝连接。此过程会在集群中的每个代理上重复，直到找到匹配项并接受连接。
先决条件
- 每个客户端 ID 中的常用字符串，可以通过正则表达式过滤。
流程
-
为第一个代理打开 <
broker_instance_dir> /etc/broker.xml配置文件。 创建
connection-routers元素，并创建一个connection-route来过滤客户端 ID 的一部分。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow connection-route-
对于
connection-route 名称，请为此路由配置指定一个识别字符串。您必须将此名称添加到要应用正则表达式过滤器的每个代理接受者。 key-
将过滤器应用到的密钥。要过滤客户端 ID，请在
key字段中指定CLIENT_ID。 key-filter应用正则表达式的客户端 ID 字符串的一部分来提取键值。在上面的第一个代理示例中，代理提取一个 key 值，它是客户端 ID 的前 3 个字符。例如，客户端 ID 字符串是
CL100.consumer，代理会提取CL1的键值。代理提取 key 值后，它会将它与local-target-filter的值进行比较。如果传入连接没有客户端 ID，或者代理无法使用为
key-filter指定的正则表达式提取键值，则 key 值设为 NULL。local-target-filter-
代理与 key 值进行比较的值，以确定是否存在匹配项，代理是否可以接受连接。
NULL|CL1值（如上例中所示），与没有客户端 ID (NULL)的连接匹配，或者在客户端 ID 中具有 3 个字符前缀CL1。
-
为第二个代理打开 <
broker_instance_dir> /etc/broker.xml配置文件。 创建
connection-routers元素，并根据客户端 ID 的一部分创建连接路由来过滤连接。在以下过滤器示例中，代理使用正则表达式来提取一个 key 值，它是客户端 ID 的前 3 个字符。代理将
NULL和CL2的值与 key 值进行比较，以确定是否存在匹配项，代理是否可以接受连接。Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 重复此步骤，并为集群中的每个附加代理创建适当的连接路由过滤器。
14.7.2. 对客户端连接进行分区，以支持数据 gravity
要支持日期变化，您可以对客户端连接进行分区，以便客户端用户连接到生成需要消耗的消息的代理。例如，如果您有一组由生成者和消费者应用程序使用的地址，您可以在特定代理上配置地址。然后，您可以为生成者和使用这些地址的用户对客户端连接进行分区，以便他们只能连接到该代理。
您可以根据分配给连接用户、用户的用户名或客户端的主机名或 IP 地址等属性对客户端连接进行分区。本节介绍如何通过过滤分配给客户端用户的用户角色来对客户端连接进行分区。如果需要客户端进行身份验证以连接到代理，您可以将角色分配给客户端用户并过滤连接，以便只有与角色条件匹配的用户才能连接到代理。
先决条件
- 客户端会被配置，以便它们可以连接到集群中的所有代理，例如，使用负载均衡器或让所有代理实例在连接 URL 中配置。如果代理拒绝连接，因为客户端与为该代理配置的分区过滤器标准不匹配，客户端必须能够连接到集群中的其他代理，以查找接受来自它的连接的代理。
流程
-
为第一个代理打开 <
broker_instance_dir> /etc/artemis-roles.properties文件。添加broker1users角色，并将用户添加到角色中。 -
为第一个代理打开 <
broker_instance_dir> /etc/broker.xml配置文件。 创建
connection-routers元素，并创建一个connection-route来根据分配给用户的角色过滤连接。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow connection-route-
对于
connection-route 名称，请为此路由配置指定一个识别字符串。您必须将此名称添加到要应用角色过滤器的每个代理 acceptor 中。 key-
将过滤器应用到的密钥。要配置基于角色的过滤，在
key字段中指定ROLE_NAME。 key-filter-
代理用来过滤用户角色和提取键值的字符串或正则表达式。如果代理找到匹配的角色，它会将 key 值设置为该角色。如果没有找到匹配的角色，代理会将 key 值设置为 NULL。在上例中，代理将
broker1users过滤器应用到客户端用户的角色。代理提取 key 值后，它会将它与local-target-filter的值进行比较。 local-target-filter-
代理与 key 值进行比较的值，以确定是否存在匹配项，代理是否可以接受连接。在示例中，代理将
broker1users值与 key 值进行比较。存在一个匹配项，这意味着用户具有broker1users角色，代理接受连接。
- 重复此步骤，并在过滤器中指定适当的角色到集群中的其他代理客户端。
14.7.3. 在 acceptors 中添加连接路由
在代理中配置连接路由后，您必须将路由添加到一个或多个代理的 acceptors 中，以对客户端连接进行分区。将连接路由添加到接收器后，代理会将连接路由中配置的过滤器应用到接受者接收的连接。
流程
-
为第一个代理打开 <
broker_instance_dir> /etc/broker.xml配置文件。 对于您要启用分区的每个接收器，附加
router密钥并指定connection-route 名称。在以下示例中，将具有consistent-hash-routing的connection-route name添加到artemisacceptor 中。Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 重复此步骤，为集群中的每个代理指定适当的连接路由过滤器。
第 15 章 使用 Ceph 配置多站点容错消息传递系统
大规模企业消息传递系统通常具有位于地理分布式数据中心的离散代理集群。如果数据中心中断，系统管理员可能需要保留现有的消息传递数据，并确保客户端应用程序可以继续生成和使用消息。您可以使用特定代理拓扑和 Red Hat Ceph Storage （软件定义的存储平台）来确保数据中心中断期间消息传递系统的连续性。这种类型的解决方案称为 多站点、容错架构。
如果您只需要 AMQP 协议支持，请考虑 第 16 章 使用代理连接配置多站点容错消息传递系统。
以下小节解释了如何使用 Red Hat Ceph Storage 保护消息传递系统不受数据中心中断的影响：
多站点容错不是 数据中心内 高可用性(HA)代理冗余的替代。基于主备份组的代理冗余功能为单个集群内的单个代理故障提供自动保护。相反，多站点容错可防止大规模数据中心中断。
要使用 Red Hat Ceph Storage 来确保消息传递系统的连续性，您必须将代理配置为使用共享存储高可用性(HA)策略。您不能将代理配置为使用复制 HA 策略。有关这些策略的更多信息，请参阅 实施高可用性。
15.1. Red Hat Ceph Storage 集群如何工作
Red Hat Ceph Storage 是一个集群的对象存储系统。Red Hat Ceph Storage 使用对象和基于策略的复制数据分片来确保数据完整性和系统可用性。
Red Hat Ceph Storage 使用名为 CRUSH （可扩展哈希下的受控复制）的算法来确定如何通过自动计算数据存储位置来存储和检索数据。您可以配置 Ceph 项目，称为 CRUSH map，它详细介绍了集群拓扑，并指定如何在存储集群之间复制数据。
CRUSH 映射包含对象存储设备(OSD)列表、用于将设备聚合到故障域层次结构中的 'buckets 列表，以及告知 CRUSH 在 Ceph 集群池中复制数据的规则。
通过反映安装的底层物理组织，CRUSH 映射可以建模，从而解决相关的设备故障的潜在源，如物理感应、共享电源源和共享网络。通过将此信息编码到集群映射中，CRUSH 可以在不同的故障域（如数据中心）之间分隔对象副本，同时仍然在存储集群中维护数据的伪随机分布。这有助于防止数据丢失，并允许集群以降级状态运行。
Red Hat Ceph Storage 集群需要多个节点（物理或虚拟）才能运行。集群必须包括以下类型的节点：
监控节点
每个 monitor (MON)节点运行 monitor 守护进程(ceph-mon)，后者维护 cluster map 的主要副本。集群映射包含集群拓扑。连接到 Ceph 集群的客户端从 monitor 检索 cluster map 的当前副本，这使得客户端能够从集群读取和写入数据。
Red Hat Ceph Storage 集群可以使用一个 monitor 节点运行，但为了确保生产环境中的高可用性，红帽只支持至少具有三个 monitor 节点的部署。最少三个 monitor 节点意味着，如果一个 monitor 出现故障或不可用，则代表集群中的剩余的 monitor 节点有一个仲裁来选择新的领导。
Manager 节点
每个管理器(MGR)节点运行 Ceph 管理器守护进程(ceph-mgr)，它负责跟踪运行时指标和 Ceph 集群的当前状态，包括存储利用率、当前的性能指标和系统负载。通常，管理器节点与 monitor 节点在一起（即，在同一个主机上）。
对象存储设备节点
每个对象存储设备(OSD)节点运行 Ceph OSD 守护进程(ceph-osd)，它与附加到节点的逻辑卷交互。Ceph 在 OSD 节点上存储数据。Ceph 可以在很少有 OSD 节点的情况下运行（默认为 3），但生产环境中的集群在扩展方面实现了更好的性能，例如，存储集群中有 50 个 OSD。在存储集群中拥有多个 OSD 可让系统管理员在 CRUSH map 中定义隔离的故障域。
元数据服务器节点
每个元数据服务器(MDS)节点运行 MDS 守护进程(ceph-mds)，后者管理与 Ceph 文件系统(CephFS)中存储的文件相关的元数据。MDS 守护进程也协调对共享集群的访问。
其他资源
有关 Red Hat Ceph Storage 的更多信息，请参阅 什么是 Red Hat Ceph Storage？
15.2. 安装 Red Hat Ceph Storage
AMQ Broker 多站点、容错架构使用 Red Hat Ceph Storage 3。通过跨数据中心复制数据，Red Hat Ceph Storage 集群可以有效地创建一个供独立数据中心的代理使用的共享存储。您可以将代理配置为使用共享存储高可用性(HA)策略，并将消息传递数据存储在 Red Hat Ceph Storage 集群中。
用于生产环境的 Red Hat Ceph Storage 集群应至少有：
- 三个 monitor (MON)节点
- 三个管理器(MGR)节点
- 包含多个 OSD 守护进程的三个对象存储设备(OSD)节点
- 三个元数据服务器(MDS)节点
您可以在相同或单独的物理或虚拟上运行 OSD、MON、MGR 和 MDS 节点。但是，为了确保 Red Hat Ceph Storage 集群中的容错功能，最好在不同的数据中心之间分发这些类型的节点。特别是，您必须确保在单个数据中心停机时，您的存储集群仍具有两个可用的 MON 节点。因此，如果您集群中有三个 MON 节点，则每个节点都必须在单独的数据中心独立的主机上运行。不要在单个数据中心中运行两个 MON 节点，因为此数据中心故障会使存储集群仅具有剩余的 MON 节点。在这种情况下，存储集群无法再操作。
本节中的链接过程演示了如何安装包含 MON、MGR、OSD 和 MDS 节点的 Red Hat Ceph Storage 3 集群。
先决条件
有关准备 Red Hat Ceph Storage 安装的详情，请参考：
流程
有关如何安装包含 MON、MGR、OSD 和 MDS 节点的 Red Hat Ceph 3 存储集群的步骤，请参阅：
15.3. 配置 Red Hat Ceph Storage 集群
本例流程演示了如何为容错配置 Red Hat Ceph 存储集群。您可以创建 CRUSH bucket，将对象存储设备(OSD)节点聚合到反映您现实的物理安装的数据中心。此外，您还可创建一个规则，告知 CRUSH 如何在存储池中复制数据。这些步骤将更新由 Ceph 安装创建的默认 CRUSH map。
先决条件
- 已安装 Red Hat Ceph Storage 集群。有关更多信息，请参阅安装 Red Hat Ceph Storage。
- 您应该了解 Red Hat Ceph Storage 如何使用放置组(PG)在池中组织大量数据对象，以及如何计算池中要使用的 PG 数量。如需更多信息，请参阅 放置组(PG)。
- 您应该了解如何在池中设置对象副本数量。如需更多信息，请参阅设置对象副本的数量。
流程
创建 CRUSH 存储桶以组织 OSD 节点。bucket 是 OSD 列表，基于数据中心等物理位置。在 Ceph 中，这些物理位置称为 故障域。
ceph osd crush add-bucket dc1 datacenter ceph osd crush add-bucket dc2 datacenter
ceph osd crush add-bucket dc1 datacenter ceph osd crush add-bucket dc2 datacenterCopy to Clipboard Copied! Toggle word wrap Toggle overflow 将 OSD 节点的主机移到您创建的数据中心 CRUSH bucket 中。将主机名
host1-host4替换为主机机器的名称。ceph osd crush move host1 datacenter=dc1 ceph osd crush move host2 datacenter=dc1 ceph osd crush move host3 datacenter=dc2 ceph osd crush move host4 datacenter=dc2
ceph osd crush move host1 datacenter=dc1 ceph osd crush move host2 datacenter=dc1 ceph osd crush move host3 datacenter=dc2 ceph osd crush move host4 datacenter=dc2Copy to Clipboard Copied! Toggle word wrap Toggle overflow 确保您创建的 CRUSH bucket
是默认CRUSH 树的一部分。ceph osd crush move dc1 root=default ceph osd crush move dc2 root=default
ceph osd crush move dc1 root=default ceph osd crush move dc2 root=defaultCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建一条规则来映射数据中心中的存储对象副本。这有助于防止数据丢失，并使集群在单一数据中心中断时保持运行。
创建规则的命令使用以下语法：
ceph osd crush rule create-replicated <rule-name> <root> <failure-domain> <class>。下面是一个示例。ceph osd crush rule create-replicated multi-dc default datacenter hdd
ceph osd crush rule create-replicated multi-dc default datacenter hddCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意在前面的命令中，如果您的存储集群使用固态驱动器(SSD)，请指定
ssd而不是hdd（硬磁盘驱动器）。配置 Ceph 数据和元数据池，以使用您创建的规则。最初，这可能会导致数据回填到由 CRUSH 算法决定的存储目的地。
ceph osd pool set cephfs_data crush_rule multi-dc ceph osd pool set cephfs_metadata crush_rule multi-dc
ceph osd pool set cephfs_data crush_rule multi-dc ceph osd pool set cephfs_metadata crush_rule multi-dcCopy to Clipboard Copied! Toggle word wrap Toggle overflow 为您的元数据和数据池指定放置组(PG)和放置组的数量。PGP 值应当等于 PG 值。
ceph osd pool set cephfs_metadata pg_num 128 ceph osd pool set cephfs_metadata pgp_num 128 ceph osd pool set cephfs_data pg_num 128 ceph osd pool set cephfs_data pgp_num 128
ceph osd pool set cephfs_metadata pg_num 128 ceph osd pool set cephfs_metadata pgp_num 128 ceph osd pool set cephfs_data pg_num 128 ceph osd pool set cephfs_data pgp_num 128Copy to Clipboard Copied! Toggle word wrap Toggle overflow 指定您的数据和元数据池使用的副本数。
ceph osd pool set cephfs_data min_size 1 ceph osd pool set cephfs_metadata min_size 1 ceph osd pool set cephfs_data size 2 ceph osd pool set cephfs_metadata size 2
ceph osd pool set cephfs_data min_size 1 ceph osd pool set cephfs_metadata min_size 1 ceph osd pool set cephfs_data size 2 ceph osd pool set cephfs_metadata size 2Copy to Clipboard Copied! Toggle word wrap Toggle overflow
下图显示了前面示例步骤创建的 Red Hat Ceph Storage 集群。存储集群已将 OSD 整理到与数据中心对应的 CRUSH bucket 中。
图 15.1. Red Hat Ceph Storage Custer 示例
下图显示了第一个数据中心（包括您的代理服务器）的可能布局。具体来说，数据中心主机：
- 两个主备份代理对的服务器
- 在前面的步骤中分配给第一个数据中心的 OSD 节点
- 单一元数据服务器、监控和管理器节点.monitor 和 Manager 节点通常位于同一个机器上。
图 15.2. 使用 Ceph Storage 集群和两个主备份代理对的单一数据中心
您可以在相同或单独的物理或虚拟上运行 OSD、MON、MGR 和 MDS 节点。但是，为了确保 Red Hat Ceph Storage 集群中的容错功能，最好在不同的数据中心之间分发这些类型的节点。特别是，您必须确保在单个数据中心停机时，存储集群仍具有两个可用的 MON 节点。因此，如果您集群中有三个 MON 节点，则每个节点都必须在单独的数据中心独立的主机上运行。
下图显示了一个完整的示例拓扑。为确保存储集群中的容错性，MON、MGR 和 MDS 节点分布在三个单独的数据中心。
图 15.3. 带有 Ceph 存储集群的多个数据中心，以及两个主备份代理对
在与代理服务器相同的数据中心中，为某些 OSD 节点查找主机机器并不意味着将消息传递数据存储在这些特定的 OSD 节点上。您可以配置代理，将消息传递数据存储在 Ceph 文件系统中的指定目录中。然后，元数据服务器节点决定了如何在数据中心的所有可用 OSD 之间分发存储的数据，并处理跨数据中心的此数据的复制。以下章节演示了如何配置代理以在 Ceph 文件系统上存储消息传递数据。
下图展示了在具有代理服务器的两个数据中心之间复制数据。
图 15.4. Ceph 在具有代理服务器的两个数据中心之间代表
其他资源
有关以下内容的更多信息：
- 为您的 Red Hat Ceph Storage 集群管理 CRUSH，请参阅 CRUSH 管理。
- 您可以在存储池上设置的完整属性集合，请参阅池 值。
15.4. 在代理服务器上挂载 Ceph 文件系统
在消息传递系统中配置代理以将消息传递数据存储在 Red Hat Ceph Storage 集群中，您首先需要挂载 Ceph 文件系统(CephFS)。
本节中的链接过程演示了如何在代理服务器上挂载 CephFS。
先决条件
您有：
- 安装和配置 Red Hat Ceph Storage 集群。有关更多信息，请参阅安装 Red Hat Ceph Storage 和 配置 Red Hat Ceph Storage 集群。
-
安装和配置三个或更多 Ceph 元数据服务器守护进程(
ceph-mds)。如需更多信息，请参阅安装元数据服务器和配置元数据服务器守护进程。 - 从 monitor 节点创建 Ceph 文件系统。有关更多信息，请参阅创建 Ceph 文件系统。
- 创建 Ceph 文件系统客户端用户，其中包含您的代理服务器可用于授权访问的密钥。有关更多信息，请参阅创建 Ceph 文件系统客户端用户。
流程
有关在代理服务器上挂载 Ceph 文件系统的说明，请参阅 将 Ceph 文件系统挂载为内核客户端。
15.5. 在多站点容错消息传递系统中配置代理
要将代理配置为多站点容错消息传递系统的一部分，您需要：
15.5.1. 添加备份代理
在每个数据中心中，您需要在数据中心中断时添加空闲的备份代理，这些代理可以从 primary-backup 组中的代理接管。您应该在空闲备份代理中复制活跃主代理的配置。您还需要配置备份代理，以便使用与现有代理相同的方式接受客户端连接。
在后续步骤中，您会看到如何配置闲置备份代理来加入现有的 primary-backup 代理组。您必须在单独的数据中心中找到空闲的备份代理，到活跃的 primary-backup 代理组。另外，建议您仅在数据中心失败时手动启动闲置备份代理。
下图显示了一个示例拓扑。
图 15.5. 在多站点、容错消息传递系统中闲置备份代理
其他资源
- 要了解如何创建额外的代理实例，请参阅创建独立代理。
- 有关配置代理网络连接的详情，请参考 第 2 章 在网络连接中配置接收器和连接器。
15.5.2. 将代理配置为 Ceph 客户端
当您添加了容错系统所需的备份代理时，您必须使用 Ceph 客户端角色配置所有代理服务器。客户端角色启用代理将数据存储在 Red Hat Ceph Storage 集群中。
要了解如何配置 Ceph 客户端，请参阅安装 Ceph 客户端角色。
15.6. 在多站点、容错消息传递系统中配置客户端
内部客户端应用程序是在与代理服务器位于同一数据中心的计算机上运行。下图显示了此拓扑。
图 15.6. 多站点容错消息传递系统中的内部客户端
外部客户端应用程序是在代理数据中心外部的计算机上运行。下图显示了此拓扑。
图 15.7. 多站点、容错消息传递系统中的外部客户端
以下子部分描述了在数据中心中断时配置内部和外部客户端应用程序以在另一个数据中心中连接到备份代理的示例。
15.6.1. 配置内部客户端
如果您遇到数据中心中断，内部客户端应用程序将与您的代理一起关闭。要缓解这种情况，您必须在单独的数据中心中有另一个客户端应用程序实例。如果数据中心中断，您可以手动启动备份客户端来连接到已手动启动的备份代理。
要启用备份客户端连接到备份代理，您需要配置与主数据中心中客户端类似的客户端连接。
Example
AMQ 核心协议 JMS 客户端的基本连接配置到 primary-backup 代理组，如下所示。在本例中，host1 和 host2 是 primary 和 backup 代理的主机服务器。
<ConnectionFactory connectionFactory = new ActiveMQConnectionFactory(“(tcp://host1:port,tcp://host2:port)?ha=true&retryInterval=100&retryIntervalMultiplier=1.0&reconnectAttempts=-1”);
<ConnectionFactory connectionFactory = new ActiveMQConnectionFactory(“(tcp://host1:port,tcp://host2:port)?ha=true&retryInterval=100&retryIntervalMultiplier=1.0&reconnectAttempts=-1”);
要在数据中心中断时将备份客户端配置为连接到备份代理，请使用类似的连接配置，但只指定备份代理服务器的主机名。在本例中，备份代理服务器是 host3。
<ConnectionFactory connectionFactory = new ActiveMQConnectionFactory(“(tcp://host3:port)?ha=true&retryInterval=100&retryIntervalMultiplier=1.0&reconnectAttempts=-1”);
<ConnectionFactory connectionFactory = new ActiveMQConnectionFactory(“(tcp://host3:port)?ha=true&retryInterval=100&retryIntervalMultiplier=1.0&reconnectAttempts=-1”);其他资源
- 有关配置代理网络连接的更多信息，请参阅 第 2 章 在网络连接中配置接收器和连接器。
15.6.2. 配置外部客户端
要让外部代理客户端在数据中心中断时继续生成或消耗消息传递数据，您必须将客户端配置为切换到另一个数据中心的代理。如果是多站点容错系统，您可以将客户端配置为故障转移到您在停机时手动启动的备份代理。
例子
以下是在 primary-backup 组不可用的情况下，将 AMQ 核心协议 JMS 和红帽构建的 Apache Qpid JMS 客户端故障转移到备份代理的示例。在这些示例中，host1 和 host2 是 primary 和 backup 代理的主机服务器，而 host3 则是您在数据中心停机时手动启动的备份代理的主机服务器。
要配置 AMQ 核心协议 JMS 客户端，请将备份代理包含在客户端尝试连接的代理列表中。
<ConnectionFactory connectionFactory = new ActiveMQConnectionFactory(“(tcp://host1:port,tcp://host2:port,tcp://host3:port)?ha=true&retryInterval=100&retryIntervalMultiplier=1.0&reconnectAttempts=-1”);
<ConnectionFactory connectionFactory = new ActiveMQConnectionFactory(“(tcp://host1:port,tcp://host2:port,tcp://host3:port)?ha=true&retryInterval=100&retryIntervalMultiplier=1.0&reconnectAttempts=-1”);Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要配置红帽构建的 Apache Qpid JMS 客户端，请将备份代理包含在您在客户端上配置的故障转移 URI 中。
failover:(amqp://host1:port,amqp://host2:port,amqp://host3:port)?jms.clientID=myclient&failover.maxReconnectAttempts=20
failover:(amqp://host1:port,amqp://host2:port,amqp://host3:port)?jms.clientID=myclient&failover.maxReconnectAttempts=20Copy to Clipboard Copied! Toggle word wrap Toggle overflow
其他资源
有关配置故障切换的更多信息：
- AMQ 核心协议 JMS 客户端，请参阅 Failover 选项。
- 红帽构建的 Apache Qpid JMS 客户端，请参阅 故障切换选项。
- 其他支持的客户端，请参阅产品文档 Red Hat AMQ Clients 中的特定于客户端的文档。
15.7. 在数据中心中断过程中验证存储集群健康状况
当您为容错配置了 Red Hat Ceph Storage 集群时，集群将继续以降级状态运行，而不会丢失数据，即使其中一个数据中心失败。
此流程演示了如何在以降级状态运行时验证集群的状态。
流程
要验证 Ceph 存储集群的状态，请使用
health或status命令：ceph health ceph status
# ceph health # ceph statusCopy to Clipboard Copied! Toggle word wrap Toggle overflow 要在命令行中观察集群的持续事件，请打开一个新的终端。然后，输入：
ceph -w
# ceph -wCopy to Clipboard Copied! Toggle word wrap Toggle overflow
运行上述任何命令时，您会看到指示存储集群仍在运行的输出，但处于降级状态。特别是，您应该看到类似如下的警告：
health: HEALTH_WARN
2 osds down
Degraded data redundancy: 42/84 objects degraded (50.0%), 16 pgs unclean, 16 pgs degraded
health: HEALTH_WARN
2 osds down
Degraded data redundancy: 42/84 objects degraded (50.0%), 16 pgs unclean, 16 pgs degraded其他资源
- 有关监控 Red Hat Ceph Storage 集群健康状况的更多信息，请参阅监控。
15.8. 在数据中心中断期间保持消息传递连续性
以下流程演示了如何在数据中心中断期间保持代理和相关消息传递数据可供客户端使用。具体来说，当数据中心失败时，您需要：
- 手动启动您创建的任何空闲备份代理，以便接管失败的数据中心的代理。
- 将内部或外部客户端连接到新的活跃代理。
先决条件
您必须：
- 安装和配置 Red Hat Ceph Storage 集群。有关更多信息，请参阅安装 Red Hat Ceph Storage 和 配置 Red Hat Ceph Storage 集群。
- 挂载 Ceph 文件系统。有关更多信息，请参阅在 代理服务器上挂载 Ceph 文件系统。
- 添加了闲置备份代理，以便在数据中心出现故障时接管 primary-backup 组中的代理。如需更多信息，请参阅 添加备份代理。
- 配置有 Ceph 客户端角色的代理服务器。有关更多信息，请参阅将代理配置为 Ceph 客户端。
- 将每个代理配置为使用共享存储高可用性(HA)策略，指定 Ceph 文件系统中的每个代理存储其消息传递数据的位置。如需更多信息，请参阅配置共享存储高可用性。
- 配置客户端，以便在数据中心停机时连接到备份代理。如需更多信息，请参阅 在多站点、容错消息传递系统中配置客户端。
流程
对于失败的数据中心中的每个主备份代理对，请手动启动您添加的空闲备份代理。
图 15.8. 在数据中心中断后启动备份代理
重新建立客户端连接。
如果您在失败的数据中心中使用内部客户端，请手动启动您创建的备份客户端。如 在多站点、容错消息传递系统中配置客户端 中所述，您必须配置客户端以连接到您手动启动的备份代理。
下图显示了新的拓扑。
图 15.9. 数据中心中断后连接到备份代理的内部客户端
如果您有外部客户端，请手动将外部客户端连接到新的活跃代理，或者观察客户端根据其配置自动切换到新的活跃代理。如需更多信息，请参阅配置外部客户端。
下图显示了新的拓扑。
图 15.10. 数据中心中断后连接到备份代理的外部客户端
15.9. 重启之前失败的数据中心
当之前失败的数据中心恢复在线时，请按照以下步骤恢复消息传递系统的原始状态：
- 重启托管 Red Hat Ceph Storage 集群的节点的服务器
- 重启消息传递系统中的代理
- 从客户端应用程序重新建立到恢复的代理的连接
以下子部分显示执行这些步骤。
15.9.1. 重启存储集群服务器
当您在之前失败的数据中心中重启 monitor、元数据服务器、管理器和对象存储设备(OSD)节点时，您的 Red Hat Ceph Storage 集群自我修复以恢复完整的数据冗余。在此过程中，Red Hat Ceph Storage 会根据需要自动回填数据到恢复的 OSD 节点。
要验证您的存储集群是否自动自我修复和恢复完整的数据冗余，请使用之前 在数据中心中断期间验证存储集群健康状况 中显示的命令。当您重新执行这些命令时，您会看到之前 HEALTH_WARN 消息指示的百分比降级开始改进，直到它返回到 100%。
15.9.2. 重启代理服务器
以下流程演示了如何在存储集群不再以降级状态运行时重启代理服务器。
流程
- 停止连接到备份代理的任何客户端应用程序，在您数据中心中断时手动启动。
停止您手动启动的备份代理。
对于 Linux：
<broker_instance_dir>/bin/artemis stop
<broker_instance_dir>/bin/artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe stop
<broker_instance_dir>\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
在之前失败的数据中心中，重启原始主和备份代理。
对于 Linux：
<broker_instance_dir>/bin/artemis run
<broker_instance_dir>/bin/artemis runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Windows 上：
<broker_instance_dir>\bin\artemis-service.exe start
<broker_instance_dir>\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow
原始主代理会在重启时自动将其角色恢复为主。
15.9.3. 重新建立客户端连接
重启代理服务器后，将客户端应用程序重新连接到这些代理。以下小节介绍了如何重新连接内部和外部客户端应用程序。
15.9.3.1. 重新连接内部客户端
内部客户端是那些在以前与恢复的代理相同的运行失败的数据中心。要重新连接内部客户端，请重新启动它们。每个客户端应用程序都重新连接到连接配置中指定的恢复的主代理。
有关配置代理网络连接的更多信息，请参阅 第 2 章 在网络连接中配置接收器和连接器。
15.9.3.2. 重新重新连接外部客户端
外部客户端是那些在之前出现故障的数据中心外运行的。根据客户端类型以及 配置外部代理客户端 中的信息，您可以将客户端配置为自动切换到备份代理，或者您手动建立此连接。当您恢复之前失败的数据中心时，您可以以类似的方式重新建立从客户端到恢复的主代理的连接，如下所述。
- 如果您将外部客户端配置为自动故障转移到备份代理，客户端会在关闭备份代理并重启原始主代理时自动返回到原始主代理。
- 如果在发生数据中心中断时手动将外部客户端连接到备份代理，您必须手动将客户端重新连接到您重启的原始主代理。
第 16 章 使用代理连接配置多站点容错消息传递系统
大规模企业消息传递系统通常具有位于地理分布式数据中心的离散代理集群。如果数据中心中断，系统管理员可能需要保留现有的消息传递数据，并确保客户端应用程序可以继续生成和使用消息。您可以使用代理连接来确保数据中心中断期间消息传递系统的连续性。这种类型的解决方案称为 多站点、容错架构。
仅支持 AMQP 协议用于代理连接之间的通信。客户端可以使用任何支持的协议。目前，消息通过镜像过程转换为 AMQP。
以下小节解释了如何使用代理连接保护消息传递系统不受数据中心中断的影响：
多站点容错不是 数据中心内 高可用性(HA)代理冗余的替代。基于主备份组的代理冗余功能为单个集群内的单个代理故障提供自动保护。相反，多站点容错可防止大规模数据中心中断。
16.1. 关于代理连接
使用代理连接时，代理可以建立到另一个代理的连接，并将信息镜像到该代理。
- AMQP 服务器连接
- 代理可以使用 AMQP 协议启动与其他端点的连接。例如，例如，代理可以连接到其他 AMQP 服务器，并在这些连接上创建元素。
AMQP 服务器连接支持以下类型的操作：
- mirrors - 代理使用 AMQP 连接到另一个代理，重复消息，并通过线路发送确认。
- senders - 在特定队列上收到的消息传输到另一个代理。
- Receivers - 代理从另一个代理拉取信息。
- peers - 代理在 AMQ Interconnect 端点上创建发送者和接收器。
本章论述了如何使用代理连接来创建容错系统。有关发送者、接收器和对等选项的信息，请参阅 第 17 章 桥接代理。
以下事件通过镜像发送：
- Message sending - 发送到一个代理的消息将"复制"到目标代理。
- 消息确认 - 将使用一个代理中删除信息的功能将发送到目标代理。
- 队列和地址创建。
- 队列和地址删除。
如果消息在目标镜像上的消费者处于 pending 状态，则确认信息将无法成功，且消息可能由两个代理发送。
镜像不会阻止任何操作，不会影响代理的性能。
代理只镜像从配置镜像的时间点相关的消息。以前，现有信息不会转发到其他代理。
确保您没有实现创建循环的镜像拓扑，这会导致消息重复。例如，如果您有一个 3-broker 部署，其中代理 1 将数据镜像到代理 2，代理 2 会将数据镜像到代理 3，请通过将数据从代理 3 镜像到代理 1 来避免创建循环。同样，不要创建 3 个或更多代理的拓扑，每个代理将数据镜像到所有其他代理。但是，您可以实施双镜像拓扑，其中两个代理会相互镜像。
16.2. 配置代理镜像
您可以使用代理连接在一对代理间镜像信息。任何时候只能有一个代理处于活跃状态。
先决条件
- 您有两个工作代理。
流程
在
broker.xml文件中为第一个代理创建一个broker-connections元素，例如：<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC1"> <mirror/> </amqp-connection> </broker-connections><broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC1"> <mirror/> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow <hostname>- 其他代理实例的主机名。
<port>- 代理在其他主机上使用的端口。
第一个代理上的所有消息都镜像到第二个代理，但在创建镜像前存在的消息不会被镜像(mirror)。
如果您希望第一个代理同步镜像消息，以确保镜像代理为 OK-to-date 用于灾难恢复，请在代理的
amqp-connection元素中设置sync=true属性，如下例所示。同步镜像要求代理发送到镜像代理的消息同时写入两个代理的卷。在两个代理上完成写入操作后，源代理会确认写入请求已完成，并且控制返回给客户端。
<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true"/> </amqp-connection> </broker-connections><broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true"/> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果无法在镜像代理上完成写入请求，例如，如果代理不可用，则客户端连接将被阻止，直到镜像可用于完成最新的写入请求。
注意示例
DC1中的代理连接名称用于创建名为$ACTIVEMQ_ARTEMIS_MIRROR_mirror的队列。确保对应的代理配置为接受这些消息，即使队列在该代理中不可见。在
broker.xml文件中为第二个代理创建一个broker-connections元素，例如：<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror/> </amqp-connection> </broker-connections><broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror/> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果您希望第二个代理同步镜像消息，请在代理的
amqp-connection项中设置sync=true属性。例如：<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true"/> </amqp-connection> </broker-connections><broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true"/> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow （可选）根据需要为镜像配置以下参数。
queue-removal-
指定是否发送队列或地址删除事件。默认值为
true。 message-acknowledgments-
指定是否发送消息确认。默认值为
true。 queue-creation-
指定是否发送队列或地址创建事件。默认值为
true。
例如：
<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true" queue-removal="false" message-acknowledgments ="false" queue-creation="false"/> </amqp-connection> </broker-connections><broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true" queue-removal="false" message-acknowledgments ="false" queue-creation="false"/> </amqp-connection> </broker-connections>Copy to Clipboard Copied! Toggle word wrap Toggle overflow （可选）自定义代理重试尝试确认目标镜像上的信息。
对于不在队列内存的消息，可能在目标镜像上收到确认信息。要给代理有足够的时间重试在目标镜像上的信息，您可以为您的环境自定义以下参数：
- mirrorAckManagerQueueAttempts
-
代理发出在内存中查找消息的尝试次数。默认值为
5。如果代理在指定次数后没有在内存中找到信息，代理会在页文件中搜索消息。 - mirrorAckManagerPageAttempts
-
如果内存中找不到消息，代理在页面文件中查找消息的尝试次数。默认值为
2。 - mirrorAckManagerRetryDelay
- 代理在尝试代理之间的间隔（以毫秒为单位）查找信息以确认在内存中，然后在页文件中。
指定
broker-connections元素之外的任何这些参数。例如：Copy to Clipboard Copied! Toggle word wrap Toggle overflow （可选）如果消息在目标镜像上进行分页，如果您希望代理协调将重复检测信息写入页面文件，请将
mirrorPageTransaction设置为true。如果
mirrorPageTransaction属性设置为false（默认值），且代理之间发生通信失败，则可能会在个别情况下，重复的信息会被写入目标镜像。将此参数设置为
true可增加代理的内存用量。- 使用 第 15.6 节 “在多站点、容错消息传递系统中配置客户端” 中记录的说明配置客户端，请注意使用代理连接，没有共享存储。
红帽不支持在镜像配置中消耗来自两个代理的客户端应用程序。要防止客户端在两个代理中使用消息，请在其中一个代理中禁用客户端接受器。
第 17 章 桥接代理
网桥提供了一种连接两个代理的方法，将消息从一个代理转发到另一个代理。
可用的网桥如下：
- Core
-
core-bridge示例演示了 在一个代理上部署的核心网桥，该代理消耗来自本地队列的消息并将其转发到第二个代理上的地址。 - mirror
- 请查看 第 16 章 使用代理连接配置多站点容错消息传递系统
- sender 和 receiver
- 请查看 第 17.1 节 “代理连接的发送者和接收器配置”
- peer
- 请查看 第 17.2 节 “代理连接的对等配置”
Core 网桥的 broker.xml 元素是 bridge。其他桥接技术使用 < broker-connection> 元素。
17.1. 代理连接的发送者和接收器配置
通过在 broker.xml 的 < broker-connections > 部分中创建发送者或接收器代理连接元素，可以将代理连接到另一个代理。
对于 发送者，代理会在队列上创建消息使用者，用于将消息发送到另一个代理。
对于 接收器，代理会在从另一个代理接收消息的地址上创建一个消息制作者。
这两个元素充当消息网桥。但是，处理消息不需要额外的开销。发件人和接收器的行为与代理中的任何其他消费者或生成者一样。
特定队列可由发送者或接收器配置。通配符表达式可用于将发送者和接收器与特定地址 或一组 地址匹配。在配置发送者或接收方时，可以设置以下属性：
-
address-match: 使用通配符表达式将发件人或接收器附加到特定地址 或一组 地址。 -
queue-name：为特定队列配置发送者或接收器。 使用地址表达式：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用队列名称：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Receivers 只能与已存在的本地队列匹配。因此，如果使用接收器，请确保在本地预先创建队列。否则，代理无法与远程队列和地址匹配。
不要创建具有相同目的地的发送者和接收器，因为这会产生一个无限的发送和接收循环。
17.2. 代理连接的对等配置
代理可以配置为连接到 AMQ Interconnect 实例的对等点，并指示代理充当该路由器上配置的 AMQP 方式点地址的 storage-and-forward 队列。在这种情况下，客户端连接到路由器，以使用 waypoint 地址发送和接收消息，路由器将这些消息路由到代理中的队列或来自代理的队列。
此对等配置为每个目的地创建一个与代理上的代理连接配置匹配的发件人和接收器对。这些对包括可让路由器与代理协作的配置。此功能避免了路由器启动连接并创建自动链接的要求。
使用对等配置时，存在与发送者和接收器相同的属性。例如，带有名称开始队列 的队列 为。作为匹配的路由器方法点地址的存储是：
路由器上必须有一个匹配的地址方式配置。这指示它将代理附加到的特定路由器地址视为 waypoint。例如，请查看以下基于前缀的路由器地址配置：
address {
prefix: queue
waypoint: yes
}
address {
prefix: queue
waypoint: yes
}
不要使用 peer 选项直接连接到另一个代理。如果您使用这个选项连接到另一个代理，则所有消息都会立即可用的使用，从而创建一个无限回发送和接收。
第 18 章 日志记录
AMQ Broker 使用 Apache Log4j 2 logging 工具提供消息日志记录。安装代理时，它在 < broker_instance_dir> /etc/log4j2.properties 文件中有默认的 Log4j 2 配置。使用默认配置，日志记录器同时写入到控制台和文件中。
下表中显示了 AMQ Broker 中提供的日志记录器。
| logger | 描述 |
|---|---|
| org.apache.activemq.artemis.core.server | 日志代理内核 |
| org.apache.activemq.artemis.journal | 日志日志调用 |
| org.apache.activemq.artemis.utils | 日志工具调用 |
| org.apache.activemq.artemis.jms | 日志 JMS 调用 |
| org.apache.activemq.artemis.integration.bootstrap | 日志 bootstrap 调用 |
| org.apache.activemq.audit.base | 记录对所有 JMX 对象方法的访问 |
| org.apache.activemq.audit.message | 记录消息操作，如生产、消耗和浏览消息 |
| org.apache.activemq.audit.resource | 记录身份验证事件，从 JMX 或 AMQ Broker 管理控制台创建和删除代理资源，并在管理控制台中浏览信息 |
18.1. 更改日志记录级别
您可以为每个日志程序配置日志级别，在 <logger name>.level 行的日志程序名称后，如以下 apache.activemq.artemis.core.server 日志程序：
logger.artemis_server.name=org.apache.activemq.artemis.core.server logger.artemis_server.level=INFO
logger.artemis_server.name=org.apache.activemq.artemis.core.server
logger.artemis_server.level=INFO
审计日志记录器的默认日志记录级别为 OFF，这意味着禁用日志记录。AMQ Broker 中其他日志记录器的默认日志记录级别为 INFO。有关 Log4j 2 中可用的日志记录级别的详情，请查看 Log4j 2 文档。
18.2. 更改日志记录布局格式
默认情况下，log4j 2 实用程序使用 PatternLayout 格式：
appender.log_file.layout.type = PatternLayout appender.log_file.layout.pattern = %d %-5level [%logger] %msg%n
appender.log_file.layout.type = PatternLayout
appender.log_file.layout.pattern = %d %-5level [%logger] %msg%n
您可以将日志输出的布局格式更改为 JsonTemplateLayout，以创建 JSON 格式的日志消息。例如：
appender.log_file.layout.type = JsonTemplateLayout
appender.log_file.layout.type = JsonTemplateLayout18.3. 启用审计日志记录
您可以启用三个审计日志记录器，即基础审计日志记录器、消息审计日志记录器和资源审计日志记录器。
- 基本审计日志记录器(org.apache.activemq.audit.base)
- 记录到所有 JMX 对象方法的访问，如创建和删除地址和队列。日志 不 指示这些操作是成功还是失败。
- 消息审计日志记录器(org.apache.activemq.audit.message)
- 记录与消息相关的代理操作，如生产、消耗或浏览消息。
- 资源审计日志记录器(org.apache.activemq.audit.resource)
- 记录来自客户端、路由和 AMQ Broker 管理控制台的身份验证成功或失败。另外，从 JMX 或管理控制台中记录创建、更新或删除队列，并在管理控制台中浏览消息。
您可以独立于其他程序启用每个审计日志记录程序。默认情况下，日志级别设置为 OFF，这意味着为每个审计日志禁用日志记录。若要启用其中一个审计日志记录器，请将日志记录级别从 OFF 更改为 INFO。例如：
logger.audit_base = INFO, audit_log_file
logger.audit_base = INFO, audit_log_file
INFO 是 logger.org.apache.activemq.audit.base,logger.org.apache.activemq.audit.message, 和 logger.org.apache.activemq.audit.resource 审计日志记录器的唯一可用日志记录级别。
消息审计日志记录程序在代理上的性能密集型路径上运行。启用日志记录器可能会对代理的性能造成负面影响，特别是当代理在高消息传递负载下运行时。红帽建议不要在需要高吞吐量的消息传递系统中启用审计日志记录。
18.4. 客户端或嵌入式服务器日志记录
如果要在客户端上启用日志记录，您需要在支持 SLF4J facade 的应用程序中包含日志实施。如果使用 Maven，请为 Log4j 2 添加以下依赖项：
您可以在 classpath 中的 log4j2.properties 文件中提供 Log4j 2 配置。或者，您可以使用 log4j2.configurationFile 系统属性指定自定义配置文件。例如：
-Dlog4j2.configurationFile=file:///path/to/custom-log4j2-config.properties
-Dlog4j2.configurationFile=file:///path/to/custom-log4j2-config.properties
以下是客户端的 log4j2.properties 文件示例：
18.5. AMQ Broker 插件支持
AMQ 支持自定义插件。您可以使用插件记录关于许多不同类型的事件的信息，否则这些事件只能通过调试日志可用。可以一起注册、绑定和执行多个插件。插件是根据注册顺序执行的，即，首先注册的第一个插件。
您可以创建自定义插件并使用 ActiveMQServerPlugin 接口来实施它们。此接口可确保插件位于 classpath 上，并注册到代理。由于所有接口方法都是默认实施的，您必须仅添加需要实施的必要行为。
18.5.1. 在类路径中添加插件
通过将相关的 .jar 文件添加到 < broker_instance_dir> /lib 目录中，将自定义创建的代理插件添加到代理运行时。
如果您使用嵌入式系统，请将 .jar 文件放在嵌入式应用程序的常规类路径下。
18.5.2. 注册插件
您必须在 broker.xml 配置文件中添加 broker-plugins 元素来注册插件。您可以使用 property 子元素指定插件配置值。这些属性会在插件实例化后读取并传递给插件的 init (Map<String, String>)操作。
18.5.3. 以编程方式注册插件
要以编程方式注册插件，请使用 registerBrokerPlugin （） 方法并传递插件的新实例。以下示例显示了 UserPlugin 插件的注册：
Configuration config = new ConfigurationImpl(); config.registerBrokerPlugin(new UserPlugin());
Configuration config = new ConfigurationImpl();
config.registerBrokerPlugin(new UserPlugin());18.5.4. 记录特定事件
默认情况下，AMQ 代理提供 LoggingActiveMQServerPlugin 插件来记录特定的代理事件。LoggingActiveMQServerplugin 插件默认是注释的，不会记录任何信息。
下表描述了每个插件属性。将配置属性值设置为 true 以记录事件。
| 属性 | 描述 |
|
| 创建或销毁连接时记录信息。 |
|
| 创建或关闭会话时记录信息。 |
|
| 创建或关闭消费者时记录信息。 |
|
| 当消息传送给消费者以及消息被消费者确认时，记录信息。 |
|
| 当消息发送到地址以及消息在代理中路由时，会记录信息。 |
|
| 当队列创建或销毁时，当消息过期、部署网桥时以及关键故障发生时，会记录信息。 |
|
| 所有上述所有事件的日志信息。 |
要配置 LoggingActiveMQServerPlugin 插件来记录连接事件，在 broker.xml 配置文件中取消注释 <broker-plugins> 部分。在注释的默认示例中，所有事件的值都设为 true。
当您更改 < broker-plugins> 部分中的配置参数时，您必须重启代理以重新载入配置更新。这些配置更改不会基于 configuration-file-refresh-period 设置重新载入。
当日志级别设置为 INFO 时，事件发生后会记录一个条目。如果日志级别设为 DEBUG，则会在事件之前和之后生成日志条目，例如 beforeCreateConsumer （） 和 afterCreateConsumer （）。如果日志级别设为 DEBUG，则日志记录器会在可用时记录更多通知信息。
第 19 章 调优指南
查看以下调整 AMQ Broker 的准则。
19.1. 调优持久性
参阅以下信息来获取有关提高持久性性能的提示。
将消息持久化到基于文件的日志中。
使用基于文件的日志实现消息持久性。AMQ Broker 也可以将消息持久化到 Java 数据库连接(JDBC)数据库，但与使用基于文件的日志相比，这具有性能成本。
将消息日志放在其自身的物理卷上。
仅附加日志的一个优点是，磁盘头移动最小化。如果磁盘共享，这个优点会丢失。当多个进程（如事务协调器、数据库和其他日志）的多个进程时，从同一磁盘读取和写入时，性能会受到影响，因为磁盘头必须在不同的文件之间跳过。如果您使用分页或大型消息，请确保它们也放在单独的卷中。
调优
journal-min-files参数值。将
journal-min-files参数设置为适合您的平均可持续速率的文件数。如果在日志数据目录中经常创建新文件，这意味着要保留大量数据，您需要增加日志维护的最小文件数。这允许日志重复使用，而不是创建新的数据文件。优化日志文件大小。
将
journal-file-size参数的值与磁盘上的 cylinder 的容量一致。大多数系统上应该具有 10 MB 的默认值。使用异步 IO (AIO)日志类型。
对于 Linux 操作系统，请将您的日志类型保留为 AIO。AIO 扩展比 Java 新 I/O (NIO)更好地扩展。
调优
journal-buffer-timeout参数值。增加
journal-buffer-timeout参数的值会导致以牺牲延迟而增加吞吐量。调优
journal-max-io参数值。如果使用 AIO，可以通过增加
journal-max-io参数值来提高性能。如果使用 NIO，请不要更改这个值。调优
journal-pool-files参数。将
journal-pool-files参数（即日志文件池的上限阈值）设置为与您预期负载接近的数字。如果需要，日志会超过上限，但尽可能缩小到阈值。这允许重复使用文件，而不需要消耗更多磁盘空间。如果您在日志数据目录中经常看到新文件创建太频繁，请增加journal-pool-size参数。增加此参数可让日志重复使用更多现有文件，而不是创建新文件，从而提高性能。如果您不需要对日志写入进行持久性保证，请禁用
journal-data-sync参数。如果发生电源失败，则不需要在日志写入时具有保证持久性，请禁用
journal-data-sync参数，并使用日志类型NIO或MAPPED来提高性能。
19.2. 调优 Java 消息服务(JMS)
如果使用 JMS API，请查看以下信息以获取有关如何提高性能的提示。
禁用消息 ID。
如果您不需要消息 ID，请在
MessageProducer类中使用setDisableMessageID （）方法来禁用它们。将值设为true可消除创建唯一 ID 并缩小消息大小的需求。禁用消息时间戳。
如果您不需要消息时间戳，请在
MessageProducer类中使用setDisableMessageTimeStamp （）方法来禁用它们。将值设为true可消除创建时间戳的开销，并减少消息的大小。避免使用
ObjectMessage。ObjectMessage用于发送具有序列化对象的消息，即消息或有效负载的正文作为字节数发送。Java 序列化形式甚至小对象非常大，并在有线上占用大量空间。与自定义捆绑技术相比，它也很慢。只有在无法使用其它消息类型时才使用ObjectMessage，例如，如果您不知道有效负载的类型，直到运行时为止。避免
AUTO_ACKNOWLEDGE.选择消费者的确认模式会影响性能，因为通过网络发送确认消息导致了额外的开销和流量。
AUTO_ACKNOWLEDGE会导致这个开销，因为它需要为客户端收到的每个消息从服务器发送确认。如果可能，请使用DUPS_OK_ACKNOWLEDGE，它以 lazy 方法或CLIENT_ACKNOWLEDGE确认消息，这意味着客户端代码将调用一个方法来确认消息。或者，通过转换的会话中确认或提交许多确认。避免持久消息。
默认情况下，JMS 消息是持久的。如果不需要持久消息，请将其设置为非持久。持久化消息会产生额外的开销，因为它们被保留到存储中。
使用
TRANSACTED_SESSION模式在单个事务中发送和接收消息。通过在单个事务中批处理消息，AMQ Broker 只需要提交中的一个网络往返，而不是每次发送或接收。
19.3. 调优传输设置
有关调优传输设置的提示，请查看以下信息。
- 如果您的操作系统支持 TCP 自动调整，就像较晚版本的 Linux 一样，请不要增加 TCP 发送和接收缓冲区大小来尝试提高性能。在具有自动调整的系统中手动设置缓冲区大小可防止自动工作，并真正降低代理性能。如果您的操作系统不支持 TCP 自动调整，且代理在快速机器和网络中运行，您可以通过增加 TCP 发送和接收缓冲大小来提高代理性能。如需更多信息，请参阅 附录 A, acceptor 和 Connector 配置参数。
如果您希望代理上的许多并发连接，或者如果客户端快速打开和关闭连接，请确保运行代理的用户有创建足够文件句柄的权限。您执行此操作的方式因操作系统而异。在 Linux 系统上，您可以在
/etc/security/limits.conf文件中增加允许打开的文件句柄的数量。例如，添加行：serveruser soft nofile 20000 serveruser hard nofile 20000
serveruser soft nofile 20000 serveruser hard nofile 20000Copy to Clipboard Copied! Toggle word wrap Toggle overflow 这个示例允许
serveruser用户打开最多 20000 文件句柄。-
为
batchDelaynetty TCP 参数设置值，并将directDelivernetty TCP 参数设置为false，以最大化非常小消息吞吐量。
19.4. 调整代理虚拟机
请查看以下信息，了解有关如何调整各种虚拟机设置的提示。
- 使用最新的 Java 虚拟机获得最佳性能。
为服务器分配尽可能多的内存。
AMQ Broker 可使用分页，使用低内存运行。但是，如果 AMQ Broker 可以在内存中保存所有队列，您会收到更高的性能。您需要的内存量取决于您的队列的大小以及消息的大小和数量。使用 -Xms 和 -Xmx JVM 参数设置可用内存。
调优堆大小。
在高负载时，AMQ Broker 可能会生成并销毁大量对象，这可能会导致构建过时的对象。这会增加代理内存不足的风险，并导致完整的垃圾回收，这可能会引入暂停和不必要行为。要降低这一风险，请确保 JVM 的最大堆大小(-Xmx)至少设置为
global-max-size参数的值的五倍。例如，如果代理在高负载下，并使用global-max-size为 1 GB 运行，则将最大堆大小设置为 5 GB。
19.5. 调整其他设置
参阅以下信息来获取有关改进性能的其他提示。
使用异步发送确认。
如果您需要发送非事务性，持久化消息，且不需要保证在调用 send （）时已达到服务器，请不要将它们设置为发送阻塞。反之，使用异步发送确认来获得在单独的流中返回的发送确认。但是，如果服务器崩溃，一些消息可能会丢失。
使用 pre-acknowledge 模式。
使用 pre-acknowledge 模式时，会在发送给客户端之前确认消息。这可减少有线上确认流量的数量。但是，如果客户端崩溃，如果客户端重新连接，则不会恢复消息。
禁用安全性。
通过将
security-enabled参数设置为false来禁用安全性，会改进较小的性能。禁用持久性。
您可以通过将
persistence-enabled参数设置为false来关闭消息持久性。同步事务。
将
journal-sync-transactional参数设置为false在保留事务时提供更好的性能，但会牺牲一些失败事务丢失的情况。同步非事务处理。
将
journal-sync-non-transactional参数设置为false会在保留非事务时提供更好的性能，但会牺牲在失败时丢失持久消息的可能性。发送消息非阻塞。
为避免在发送的每个消息中等待网络往返，如果您正在使用 Java 消息传递服务(JMS)和 Java 命名与目录接口(JNDI)，请将
block-on-durable-sendfalse。或者，通过调用setBlockOnDurableSend （）和setBlockOnNonDurableSend （）方法直接在服务器查找器上设置它们。优化
consumer-window-size。如果您有非常快的用户，您可以增加
consumer-window-size参数的值，以有效地禁用消费者流控制。使用核心 API 而不是 JMS API。
JMS 操作必须转换为核心操作，然后服务器可以处理它们，从而降低使用核心 API 的性能。使用核心 API 时，请尝试尽可能使用
SimpleString的方法。SimpleString与 java.lang.String 不同，在写入线前不需要复制。因此，如果您在调用之间重复使用SimpleString实例，您可以避免一些不必要的复制。请注意，核心 API 无法可移植到其他代理。
19.6. 避免反模式
尽可能重复使用连接、会话、消费者和制作者。
最常见的消息传递反模式是为发送或消耗的每条消息创建新连接、会话和制作者。这些对象需要时间创建，并可能需要多次网络往返，这对资源的使用不佳。
注意Spring JMS 模板等一些流行的库使用这些反模式。如果您使用 Spring JMS 模板，您可能会看到性能不佳。Spring JMS 模板只能安全地在缓存 JMS 会话的应用服务器中使用，例如使用 Java Connector 架构，然后仅用于发送消息。即使在应用服务器中，它也无法安全地使用消息。
避免 fat 消息。
详细格式（如 XML）会占用线线上的大量空间，因此性能会受到影响。如果需要，请避免消息正文中的 XML。
不要为每个请求创建临时队列。
这种常见的反模式涉及临时队列请求响应模式。使用临时队列请求响应模式时，会将消息发送到目标，并使用本地临时队列的地址设置回复标头。当接收者收到消息时，它们处理它，然后发回一个响应到 reply-to 标头中指定的地址。使用这个模式的常见错误是在每个发送的消息上创建新的临时队列，这大大降低了性能。相反，应该对许多请求重复使用临时队列。
除非必要，否则不要使用消息驱动的 Bean。
使用消息驱动的 Bean 使用简单的 JMS 消息使用者来消耗消息的速度比消耗消息要慢。
附录 A. acceptor 和 Connector 配置参数
下表详细介绍了用于配置 Netty 网络连接的一些可用参数。参数及其值附加到连接字符串的 URI 中。如需更多信息，请参阅在 网络连接中配置接收器和连接器。每个表按名称列出参数，并记录它们是否与接收器或连接器一起使用。您可以使用一些参数，例如只使用 acceptors。
所有 Netty 参数都在类 org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants 中定义。可在客户门户网站上下载源代码 http://access.redhat.com/downloads。
| 参数 | 使用 with… | 描述 |
|---|---|---|
| batchDelay | 两者 |
在将数据包写入 acceptor 或 connector 之前，代理可以被配置为批量写入最多 |
| connectionsAllowed | acceptors |
限制接受者允许的连接数量。达到这个限制时，会向日志发出 DEBUG 级别的消息，并且拒绝连接。使用中的客户端类型决定了连接被拒绝时发生的情况。默认值为 |
| directDeliver | 两者 |
当消息到达服务器并传送到等待消费者时，默认会在与消息到达的线程相同的线程上进行交付。这在相对较小的消息和少量消费者的环境中提供了良好的延迟，但代价是总体吞吐量和可扩展性，特别是在多核机器上。如果您希望最低延迟和吞吐量可能降低，那么您可以将默认值用于 |
| handshake-timeout | acceptors | 防止未授权客户端打开大量连接并保持打开状态。由于每个连接都需要文件句柄，所以它会消耗给其他客户端不可用的资源。 此超时限制连接可在不通过身份验证的情况下消耗资源的时间。在连接被身份验证后，您可以使用资源限值设置来限制资源消耗。
默认值为 编辑超时值后，您必须重启代理。 |
| localAddress | 连接器 | 指定在连接到远程地址时客户端要使用的本地地址。这通常用于应用服务器，或者在运行 Embedded 时使用，以控制用于出站连接的地址。如果没有设置本地地址，则连接器将使用任何可用的本地地址。 |
| localPort | 连接器 | 指定客户端在连接到远程地址时将使用哪个本地端口。这通常在应用服务器中使用，或者在运行 Embedded 时使用，以控制用于出站连接的端口。如果使用默认值，则为 0，则连接器可让系统获取临时端口。有效端口为 0 到 65535 |
| nioRemotingThreads | 两者 |
当配置为使用 NIO 时，代理默认使用多个线程等于 |
| tcpNoDelay | 两者 |
如果为 |
| tcpReceiveBufferSize | 两者 |
以字节为单位决定 TCP 接收缓冲区的大小。默认值为 |
| tcpSendBufferSize | 两者 |
以字节为单位决定 TCP 发送缓冲区的大小。默认值为 TCP 缓冲区大小应根据您的网络带宽和延迟进行调优。 在摘要 TCP 发送/接收缓冲区大小中，应计算为： buffer_size = bandwidth * RTT.
其中带宽（以字节/秒为单位），网络往返用时(RTT)以秒为单位。可以使用 对于快速网络，您可能需要从默认值中增加缓冲区大小。 |
| 参数 | 使用 with… | 描述 |
|---|---|---|
| httpClientIdleTime | acceptors | 在发送空 HTTP 请求以保持连接处于活动状态前，客户端可以闲置多久。 |
| httpClientIdleScanPeriod | acceptors | 扫描空闲客户端的频率（以毫秒为单位）。 |
| httpEnabled | acceptors | 不再需要。现在，通过单一端口支持，代理会自动检测是否使用 HTTP 并配置其自身。 |
| httpRequiresSessionId | 两者 |
如果为 |
| httpResponseTime | acceptors | 服务器在发送空 HTTP 响应前可以等待多久，以保持连接处于活动状态。 |
| httpServerScanPeriod | acceptors | 扫描需要响应的客户端的频率（以毫秒为单位）。 |
| 参数 | 使用 with… | 描述 |
|---|---|---|
| enabledCipherSuites | 两者 | 用于 SSL 通信的密码套件的逗号分隔列表。
指定客户端应用程序支持的最安全密码套件。如果您指定了代理和客户端通用的、以逗号分隔的密码套件列表，或者您没有指定任何密码套件，则代理和客户端会相互协商要使用的密码套件。如果您不知道要指定的密码套件，您可以首先与以 debug 模式运行的客户端建立 broker-client 连接，以验证代理和客户端通用的密码套件。然后，在代理上配置
可用的密码套件取决于代理和客户端使用的 TLS 协议版本。如果在升级代理后默认 TLS 协议版本有变化，您可能需要选择较早的 TLS 协议版本，以确保代理和客户端可以使用通用密码套件。如需更多信息，请参阅 |
| enabledProtocols | 两者 | 用于 SSL 通信的 TLS 协议版本的逗号分隔列表。如果没有指定 TLS 协议版本，代理将使用 JVM 的默认版本。
如果代理使用 JVM 的默认 TLS 协议版本，且该版本在升级代理后发生了变化，则代理和客户端使用的 TLS 协议版本可能会不兼容。虽然建议您使用更新的 TLS 协议版本，但您可以在 |
| forceSSLParameters | 连接器 |
控制是否在连接器上设置的任何 SSL 设置，而不是使用 JVM 系统属性（包括
有效值为 |
| keyStorePassword | 两者 | 在 acceptor 上使用时，这是服务器端密钥存储的密码。
在连接器上使用时，这是客户端密钥存储的密码。只有在您使用双向 SSL （即 mutual 身份验证）时，这才与连接器相关。虽然此值可以在服务器上配置，但客户端会下载并使用该值。如果客户端需要使用与服务器上该设置不同的密码，那么它可以使用 customary |
| keyStorePath | 两者 | 当在接受者中使用时，这是包含服务器证书的服务器上的 SSL 密钥存储的路径（无论是自签名还是由颁发机构签名）。
当在连接器中使用时，这是包含客户端证书的客户端 SSL 密钥存储的路径。只有在您使用双向 SSL （即 mutual 身份验证）时，这才与连接器相关。虽然这个值在服务器上配置，但客户端会下载并使用该值。如果客户端需要使用与服务器上该设置不同的路径，那么它可以使用 customary |
| keyStoreAlias | 两者 | 在 acceptor 上使用时，这是密钥存储中密钥的别名，以便在客户端连接时呈现给客户端。当在连接器中使用时，这是密钥存储中密钥的别名，在客户端连接到时出现在服务器。这只适用于使用双向 SSL 时的连接器，即 mutual 身份验证。 |
| needClientAuth | acceptors |
告知客户端连接到此接收器，需要双向 SSL。有效值为 |
| sslEnabled | 两者 |
必须为 |
| sslAutoReload | acceptors |
如果设置为 |
| trustManagerFactoryPlugin | 两者 |
定义实施
这是一个简单的接口，具有返回
您需要将任何指定的插件放在代理的 Java 类路径上。您可以使用 < |
| trustStorePassword | 两者 | 当在接收器中使用时，这是服务器端信任存储的密码。只有在您使用双向 SSL （即 mutual 身份验证）时，这才与接受者相关。
当在连接器中使用时，这是客户端信任存储的密码。虽然此值可以在服务器上配置，但客户端会下载并使用该值。如果客户端需要使用与服务器上该设置不同的密码，那么它可以使用 customary |
| sniHost | 两者 |
在 acceptor 中使用时，
如果传入连接不包含
在连接器中使用时， |
| sslProvider | 两者 |
用于更改
如果设置为 如果要使用通过 OpenSSL 支持的特殊 ciphersuite-elliptic curve 组合，而不是通过 JDK 供应商，这个选项很有用。 |
| trustStorePath | 两者 | 当在接收器中使用时，这是服务器端 SSL 密钥存储的路径，该存储包含服务器信任的所有客户端的密钥。只有在您使用双向 SSL （即 mutual 身份验证）时，这才与接受者相关。
当在连接器中使用时，这是客户端 SSL 密钥存储的路径，其中包含客户端信任的所有服务器的公钥。虽然此值可以在服务器上配置，但客户端会下载并使用该值。如果客户端需要使用与服务器上该设置不同的路径，那么它可以使用 customary |
| useDefaultSslContext | 连接器 |
允许连接器使用"默认"SSL 上下文（通过
如果此参数设为 |
| verifyHost | 两者 | 当在连接器中使用时，服务器的 SSL 证书的 CN 或 Subject Alternative Name 值会与要连接到的主机名进行比较，以验证它们是否匹配。这对单向和双向 SSL 都很有用。 当在接受者中使用时，连接的客户端的 SSL 证书的 CN 或 Subject Alternative Name 值会与其主机名进行比较，以验证它们是否匹配。这仅适用于双向 SSL。
有效值为 |
| wantClientAuth | acceptors |
告知客户端连接到此接收器，但请求双向 SSL，但并不需要。有效值为
如果属性 |
附录 B. 地址设置配置元素
下表列出了 address-setting 的所有配置元素。请注意，一些元素被标记为 DEPRECATED。使用建议的替换以避免潜在的问题。
| Name | 描述 |
|---|---|
| address-full-policy |
确定使用
注意 BLOCK 策略仅适用于 AMQP、OpenWire 和核心协议协议，因为它们功能流控制。 |
| auto-create-addresses |
当客户端向其发送消息时，是否自动创建地址，还是尝试使用映射到不存在的地址的队列中的消息。默认值为 |
| auto-create-dead-letter-resources |
指定代理是否自动创建死信地址和队列来接收未发送的消息。默认值为
如果参数设为 |
| auto-create-jms-queues |
DEPRECATED: 使用 |
| auto-create-jms-topics |
DEPRECATED: 使用 |
| auto-create-queues |
当客户端向队列发送消息或尝试使用队列的消息时，是否自动创建队列。默认值为 |
| auto-delete-addresses |
当代理不再有任何队列时，是否删除自动创建的地址。默认值为 |
| auto-delete-jms-queues |
DEPRECATED: 使用 |
| auto-delete-jms-topics |
DEPRECATED: 使用 |
| auto-delete-queues |
当队列没有消费者且没有消息时，是否删除自动创建的队列。默认值为 |
| config-delete-addresses | 重新加载配置文件时，此设置指定了如何处理从配置文件中删除的地址（及其队列）。您可以指定以下值：
|
| config-delete-queues | 重新加载配置文件时，此设置指定了如何处理从配置文件中删除的队列。您可以指定以下值：
|
| dead-letter-address | 代理向其中发送死消息的地址。 |
| dead-letter-queue-prefix |
代理应用到自动创建的死信队列的名称的前缀。默认值为 |
| dead-letter-queue-suffix | 代理应用到自动创建的死信队列的后缀。默认值没有定义（即，代理没有应用后缀）。 |
| default-address-routing-type |
自动创建的地址上使用的路由类型。默认值为 |
| default-max-consumers |
此队列中允许的最大消费者数量。默认值为 |
| default-purge-on-no-consumers |
在没有消费者后清除队列的内容。默认值为 |
| default-queue-routing-type |
自动创建队列中使用的 route-type。默认值为 |
| enable-metrics |
指定配置的指标插件（如 Prometheus 插件）是否收集匹配地址 或一组 地址的指标。默认值为 |
| expiry-address | 接收过期消息的地址。 |
| expiry-delay |
定义用于使用默认过期时间的消息的过期时间（以毫秒为单位）。默认值为 |
| last-value-queue |
队列是否只使用最后一个值。默认值为 |
| management-browse-page-size |
管理资源可以浏览的消息数量。默认值为 |
| max-delivery-attempts |
在发送到死信地址之前尝试发送邮件的次数。默认值为 |
| max-redelivery-delay | redelivery-delay 的最大值，以毫秒为单位。 |
| max-size-bytes |
此地址的最大内存大小，以字节为单位指定。当 |
| max-size-bytes-reject-threshold |
|
| message-counter-history-day-limit |
为这个地址保留消息计数器历史记录的天数。默认值为 |
| page-size-bytes |
分页大小（以字节为单位）。还支持字节表示法，如 |
| redelivery-delay |
在取消的消息前等待的时间（以毫秒为单位）。默认值为 |
| redelivery-delay-multiplier |
应用到 redelivery-delay 参数的倍数。默认值为 |
| redistribution-delay |
定义在队列上关闭最后一个消费者后等待的时间（以毫秒为单位），然后再重新分发任何消息。默认值为 |
| send-to-dla-on-no-route |
当设置为 |
| slow-consumer-check-period |
速度较慢的用户检查的频率（以秒为单位）。默认值为 |
| slow-consumer-policy |
决定在识别较慢的消费者时会发生什么。有效选项为 |
| slow-consumer-threshold |
在消费者被视为较慢前允许的最小消息消耗率。以 message-per-second 测量。默认值为 |
附录 C. 集群连接配置元素
下表列出了 cluster-connection 的所有配置元素。
| Name | 描述 |
|---|---|
| address |
每个集群连接只适用于与
注意 您不应该有多个带有重叠地址的集群连接（如 "europe" 和 "europe.news"），因为同一消息可以在多个集群连接之间分发，从而导致重复发送。 |
| call-failover-timeout |
在故障转移尝试过程中发出调用时使用。默认值为 |
| call-timeout |
当数据包通过集群连接发送，且它是一个阻塞调用时， |
| check-period |
检查集群连接是否无法从另一个代理接收 ping 的时间间隔（以毫秒为单位）。默认值为 |
| confirmation-window-size |
用于向连接的代理发送确认的窗口的大小（以字节为单位）。当代理收到 |
| connector-ref |
标识将传送到集群中的其他代理的 |
| connection-ttl |
如果集群连接停止从集群中的特定代理接收信息，则集群连接应保持多久。默认值为 |
| discovery-group-ref |
指向一个 |
| initial-connect-attempts |
设置系统初始尝试连接代理的次数。如果实现 max-retry，则此代理将永久被视为永久关闭，系统不会将消息路由到此代理。默认值为 |
| max-hops |
将代理配置为仅将消息与代理进行负载平衡，这些代理可能只作为链中的中间部分连接到其他代理。这可实现更复杂的拓扑，同时仍然提供消息负载平衡。默认值为 |
| max-retry-interval |
重试的最大延迟，以毫秒为单位。默认值为 |
| message-load-balancing |
决定是否在集群中的其他代理间分发信息。包含
|
| min-large-message-size |
如果消息大小（以字节为单位）大于 |
| notification-attempts |
设置集群连接连接到集群时应广播的次数。默认值为 |
| notification-interval |
设置连接到集群时集群连接应广播的频率（以毫秒为单位）。默认值为 |
| producer-window-size |
生成者流控制集群连接的大小（以字节为单位）。默认情况下，它被禁用，但如果您在集群中使用非常大的消息，您可能需要设置值。值 |
| reconnect-attempts |
设置系统尝试重新连接到集群中的代理的次数。如果实现 max-retry，则此代理将永久考虑，系统将停止将消息路由到此代理。默认值为 |
| retry-interval | 决定重试尝试之间间隔（以毫秒为单位）。如果创建了集群连接，且目标代理尚未启动或启动，则来自其他代理的集群连接将重试连接到目标，直到备份为止。这个参数是可选的。默认值为 500 毫秒。 |
| retry-interval-multiplier |
在每次重新连接尝试后增加 |
| use-duplicate-detection |
集群连接使用网桥来链接代理，并且网桥可以配置为在转发的每个消息中添加重复的 ID 属性。如果桥接的目标代理崩溃，然后恢复，则可能会从源代理中重新显示信息。通过将 |
附录 D. 命令行工具
AMQ Broker 包括一组命令行界面(CLI)工具，以便您可以管理消息传递日志。下表列出了每个工具的名称及其描述。
| 工具 | 描述 |
|---|---|
| exp | 使用特殊的独立 XML 格式导出消息数据。 |
| imp |
使用 |
| data | 输出有关日志记录的报告并压缩其数据。 |
| 编码 | 显示编码为 String 的日志的内部格式。 |
| 解码 | 从编码导入内部日志格式。 |
要获得每个工具可用的命令列表，请使用 help 参数，后跟工具的名称。在以下示例中，CLI 输出列出了用户在输入命令 ./artemis help data 后对 data 工具使用的所有命令。
您可以使用工具中的帮助来了解更多有关如何执行每个工具的命令的信息。例如，CLI 在用户输入 ./artemis help data print 后列出了 data print 命令的更多信息。
附录 E. 消息传递日志配置元素
下表列出了与 AMQ Broker 消息传递日志相关的所有配置元素。
| Name | 描述 |
|---|---|
| journal-directory |
消息日志所在的目录。默认值为 < 为了获得最佳性能，日志应位于自己的物理卷上，以便最大程度降低磁盘头移动。如果日志位于与其他进程共享的卷，这些进程可能会编写其他文件（例如，绑定日志、数据库或事务协调器），那么磁盘头在这些文件之间快速移动，从而大大降低性能。 使用 SAN 时，应为每个日志实例提供自己的 LUN （逻辑单元）。 |
| create-journal-dir |
如果设置为 |
| journal-type |
有效值为
如果设置为 |
| journal-sync-transactional |
如果设置为 |
| journal-sync-non-transactional |
如果设置为 |
| journal-file-size |
每个日志文件的大小（以字节为单位）。默认值为 |
| journal-min-files | 在启动时，代理预先创建的最小文件数。只有不存在消息数据时，才会预先创建文件。 根据您期望队列包含 steady 状态的数据量，您应该调整此文件数量以匹配预期的数据总量。 |
| journal-pool-files |
系统将根据需要创建任意数量的文件；但是，当回收文件时，它将缩小回
默认值为 |
| journal-max-io | 控制 IO 队列中可以一次可以的最大写入请求数。如果队列已满，则写入将阻止直到空间被释放为止。
使用 NIO 时，该值应始终为 |
| journal-buffer-timeout | 控制缓冲区将刷新的时间。AIO 通常可以具有高于 NIO 的清空率，因此系统可为 NIO 和 AIO 维护不同的默认值。
NIO 的默认值为 注意 通过增加超时值，您可能会以牺牲延迟增加系统吞吐量，因为默认值是选择在吞吐量和延迟之间合理平衡。 |
| journal-buffer-size |
AIO 上时间缓冲区的大小。默认值为 |
| journal-compact-min-files |
代理压缩日志前所需的最少文件数。在至少为 注意
将值设为 |
| journal-compact-percentage |
开始紧凑的阈值。如果小于 |
附录 F. 其他复制高可用性配置元素
下表列出了 配置复制高可用性 部分没有描述的额外 ha-policy 配置元素。这些元素具有足以满足大多数常见用例的默认设置。
| Name | 使用于 | 描述 |
|---|---|---|
| check-for-active-server | 嵌入式代理协调 |
只适用于配置为主代理的代理。指定原始主代理是否在启动后使用自己的服务器 ID 检查集群是否有另一个活跃代理。设置为 |
| cluster-name | 嵌入式代理和 ZooKeeper 协调 | 用于复制的集群配置的名称。只有在配置多个集群连接时，才需要此设置。如果配置，则连接到集群时将使用此名称进行集群配置。如果未设置，则使用配置中定义的第一个集群连接。 |
| initial-replication-sync-timeout | 嵌入式代理和 ZooKeeper 协调 |
复制代理在完成副本的初始复制过程后等待的时间，以确认它已收到了所有必要的数据。此属性的默认值为 注意：在此时间段内，任何其他与日志相关的操作都会被阻断。 |
| max-saved-replicated-journals-size | 嵌入式代理和 ZooKeeper 协调 |
仅适用于备份代理。指定备份代理保留的备份日志文件数量。达到这个值后，代理通过删除最旧的日志文件来为每个新的备份日志文件产生空间。此属性的默认值为 |
附录 G. 代理属性
以下是 AMQ Broker 属性列表，它可以直接应用到内部 java 配置 bean，而不使用 XML 配置。
criticalAnalyzerCheckPeriod
Type: long
Default: 0
XML name: critical-analyzer-check-period
Description: The period 默认为 critical-analyzer-timeout，并在运行时计算。
pageMaxConcurrentIO
type: int
Default: 5
XML name: page-max-concurrent-io
Description: 在分页期间允许的最大并发读取数。
messageCounterSamplePeriod
type: long
Default: 10000
XML name: message-counter-sample-period
Description: 用于消息计数器的示例周期（单位为 ms）。
networkCheckNIC
Type: String
Default:
XML name: network-check-nic
Description: 用于验证地址的网络接口卡名称。
globalMaxSize
Type: long
Default: -1
XML name: global-max-size
Description: Size (in bytes) before all addresses will enter into their Full Policy configured upon messages being produced.支持字节表示法，如"K"、"Mb"、"MiB"、"GB"等。
journalFileSize
type: int
Default: 10485760
XML name: journal-file-size
Description: 每个日志文件的大小（以字节为单位）。支持字节表示法，例如："K", "Mb", "MiB", "GB"。
configurationFileRefreshPeriod
27 MinLength: long
Default: 5000
XML name: configuration-file-refresh-period
Description:
diskScanPeriod
Type: int
Default: 5000
XML name: disk-scan-period
Description: 频率（毫秒）来扫描磁盘以了解完整磁盘。
journalRetentionDirectory
Type: String
Default:
XML name: journal-retention-directory
Description: 用于存储 journal-retention 消息和保留配置的目录。
networkCheckPeriod
Type: long
Default: 10000
XML name: network-check-period
Description: the frequency, in milliseconds, to check the network is up.
journalBufferSize_AIO
type: int
Default: 501760
XML name: journal-buffer-size
Description: 日志内部缓冲区的大小（以字节为单位）。支持字节表示法，例如 "K", "Mb", "MiB", "GB"。
networkCheckURLList
Type: string
Default:
XML name: network-check-URL-list
Description: 用来验证代理是否应保持在线的 URL 列表。
networkCheckTimeout
Type: int
Default: 1000
XML name: network-check-timeout
Description:
pageSyncTimeout
type: int
Default:
XML name: page-sync-timeout
Description: timeout, in nanoseconds, 用于同步页面。确切的默认值取决于日志是 ASYNCIO 还是 NIO。
journalPoolFiles
Type: int
Default: -1
XML name: journal-pool-files
Description: The number of journal files to pre-create.
criticalAnalyzer
Type: boolean
Default: true
XML name: critical-analyzer
Description: Should analyze response time on critical paths, decide for broker log, shutdown 或 halt。
readWholePage
type: boolean
Default: false
XML name: read-whole-page
Description: 指定在页面缓存被驱除后是否读取整个页面。
maxDiskUsage
type: int
Default: 90
XML name: max-disk-usage
Description: 系统块或失败的客户端前磁盘用量最大百分比。
globalMaxMessages
Type: long
Default: -1
XML name: global-max-messages
Description: Number of messages before all addresses will enter into their address full policy configured.它与 global-max-size 结合使用，当达到其中任一限制时，它就会执行配置的地址完全策略。
internalNamingPrefix
Type: string
Default:
XML name: internal-naming-prefix
Description: Artemis 使用内部队列和地址来实施某些行为。这些队列和地址默认带有 "$.activemq.internal" 前缀，以避免使用用户名命名冲突。这可以通过将此值设置为有效的 Artemis 地址来覆盖。
journalFileOpenTimeout
Type: int
Default: 5
XML name: journal-file-open-timeout
Description: 在打开新 Journal 文件前等待的时间（以秒为单位）。
journalCompactPercentage
Type: int
Default: 30
XML name: journal-compact-percentage
Description: 要考虑压缩日志的实时数据的百分比。
createBindingsDir
type: boolean
Default: true
XML name: create-bindings-dir
Description: true 的值会导致服务器在启动时创建绑定目录。
suppressSessionNotifications
Type: boolean
Default: false
XML name: suppress-session-notifications
Description: Whether or not suppress SESSION_CREATED 和 SESSION_CLOSED 通知。设置为 true 以减少通知开销。但是，需要为 MQTT 客户端在集群中强制实施唯一的客户端 ID 利用率。
journalBufferTimeout_AIO
type: int
Default:
XML name: journal-buffer-timeout
Description: the timeout,in nanoseconds, 用于清除日志上的内部缓冲区。确切的默认值取决于日志是 ASYNCIO 还是 NIO。
journalType
Type: JournalType
Default: ASYNCIO
XML name: journal-type
Description: 要使用的日志类型。
名称
Type: String
Default:
XML name: name
Description: Node name.如果设置，它将在拓扑通知中使用。
networkCheckPingCommand
Type: String
Default:
XML name: network-check-ping-command
Description: The ping command used to ping IPV4 addresses.
temporaryQueueNamespace
Type: string
Default:
XML name: temporary-queue-namespace
Description: 用于查找临时队列的地址设置的命名空间。
pagingDirectory
Type: String
Default: data/paging
XML name: Page-directory
Description: 存储页面消息的目录。
journalDirectory
Type: String
Default: data/journal
XML name: journal-directory
Description: 存储日志文件的目录。
journalBufferSize_NIO
type: int
Default: 501760
XML name: journal-buffer-size
Description: 日志内部缓冲区的大小（以字节为单位）。支持字节表示法，例如："K", "Mb", "MiB", "GB"。
journalDeviceBlockSize
Type: Integer
Default:
XML name: journal-device-block-size
Description: 大小为，以字节为单位，供设备使用。这通常转换为 fstat/st_blksize，这是绕过 st_blksize 返回的值的方法。
nodeManagerLockDirectory
Type: String
Default:
XML name: node-manager-lock-directory
Description: 存储节点管理器锁定文件的目录。
messageCounterMaxDayHistory
Description: int
Default: 10
XML name: message-counter-max-day-history
Description: 用于保留消息计数器历史记录的天数。
largeMessagesDirectory
Type: String
Default: data/largemessages
XML name: large-messages-directory
Description: 要存储大型消息的目录。
networkCheckPing6Command
Type: String
Default:
XML name: network-check-ping6-command
Description: The ping command used to ping IPV6 addresses.
memoryWarningThreshold
Type: int
Default: 25
XML name: memory-warning-threshold
Description: Percentage of available memory that a warning is generated.
mqttSessionScanInterval
Type: long
Default: 5000
XML name: mqtt-session-scan-interval
Description: 频率，以毫秒为单位扫描过期的 MQTT 会话。
journalMaxAtticFiles
type: int
Default:
XML name: journal-max-attic-files
Description:
journalSyncTransactional
Type: boolean
Default: true
XML name: journal-sync-transactional
Description: 如果设为 true，请等待事务数据同步到日志，然后再返回到客户端。
logJournalWriteRate
type: boolean
Default: false
XML name: log-journal-write-rate
Description: 指定与日志 write-rate 相关的消息。
journalMaxIO_AIO
type: int
Default:
XML name: journal-max-io
Description: 最多可在 AIO 队列中的写入请求数。AIO 的默认为 500，NIO 为 1。
messageExpiryScanPeriod
Type: long
Default: 30000
XML name: message-expiry-scan-period
Description: frequency, in milliseconds, to scan for expired 信息。
criticalAnalyzerTimeout
type: long
Default: 120000
XML name: critical-analyzer-timeout
Description: 用于分析关键路径上的超时的默认超时。
messageCounterEnabled
type: boolean
Default: false
XML name: message-counter-enabled
Description: true 表示启用了消息计数器。
journalCompactMinFiles
type: int
Default: 10
XML name: journal-compact-min-files
Description: 代理开始紧凑文件前的最小数据文件数量。
createJournalDir
type: boolean
Default: true
XML name: create-journal-dir
Description: true 表示日志目录已创建。
addressQueueScanPeriod
Type: long
Default: 30000
XML name: address-queue-scan-period
Description: 用于扫描需要删除的地址和队列的频率（以毫秒为单位）。
memoryMeasureInterval
Type: long
Default: -1
XML name: memory-measure-interval
Description: The frequency, in milliseconds, to sample JVM memory.值 -1 禁用内存抽样。
journalSyncNonTransactional
Type: boolean
Default: true
XML name: journal-sync-non-transactional
Description: 如果为 true，请等待非事务数据同步到日志，然后再返回到客户端。
connectionTtlCheckInterval
type: long
Default: 2000
XML name: connection-ttl-check-interval
Description: frequency, in milliseconds, to check connections for ttl violations。
rejectEmptyValidatedUser
Type: boolean
Default: false
XML name: reject-empty-validated-user
Description: 如果为 true，服务器不允许任何没有经过验证的用户的消息。在 JMS 中，这是 JMSXUserID。
journalMaxIO_NIO
type: int
Default:
XML name: journal-max-io
Description: 最多可在 AIO 队列中的写入请求数。AIO 的默认为 500，NIO 为 1。目前，代理属性只支持使用整数和测量（以字节为单位）。
transactionTimeoutScanPeriod
Type: long
Default: 1000
XML name: transaction-timeout-scan-period
Description: 用于扫描超时事务的频率（以毫秒为单位）。
systemPropertyPrefix
Type: String
Default:
XML name: system-property-prefix
Description: The prefix used to parse system properties for the configuration.
transactionTimeout
type: long
Default: 300000
XML name: transaction-timeout
Description: the duration, in milliseconds, before a transaction after the after the resource manager after the creation time.
journalLockAcquisitionTimeout
Type: long
Default: -1
XML name: journal-lock-acquisition-timeout
Description: The frequency, in milliseconds, to wait to acquire a file lock on the journal.
journalBufferTimeout_NIO
type: int
Default:
XML name: journal-buffer-timeout
Description: the timeout, in nanoseconds, 用于清除日志上的内部缓冲区。确切的默认值取决于日志是 ASYNCIO 还是 NIO。
journalMinFiles
type: int
Default: 2
XML name: journal-min-files
Description: 要预先创建的日志文件数量。
G.1. bridgeConfigurations
bridgeConfigurations.<name>.retryIntervalMultiplier
Type: double
Default: 1
XML name: retry-interval-multiplier
Description: 应用于连续重试间隔的倍数。
bridgeConfigurations.<name>.maxRetryInterval
Type: long
Default: 2000
XML name: max-retry-interval
Description: 限制 retry-interval 增长，因为 retry-interval-multiplier。
bridgeConfigurations.<name>.filterString
Type: String
Default:
XML name: filter-string
Description:
bridgeConfigurations.<name>.connectionTTL
type: long
Default: 60000
XML name: connection-ttl
Description: 如果客户端没有收到数据，则保持连接在线的时间。持续时间应大于 ping 周期。
bridgeConfigurations.<name>.confirmationWindowSize
type: int
Default: 1048576
XML name: confirmation-window-size
Description: 网桥发送确认的字节数。支持字节表示法，例如 "K", "Mb", "MiB", "GB"。
bridgeConfigurations.<name>.staticConnectors
type: List
Default:
XML name: static-connectors
Description:
bridgeConfigurations.<name>.reconnectAttemptsOnSameNode
type: int
Default:
XML name: reconnect-attempts-on-same-node
Description:
bridgeConfigurations.<name>.concurrency
type: int
Default: 1
XML name: concurrency
Description: concurrent worker 的数量。更多 worker 可帮助提高高延迟网络上的吞吐量。默认值为 1。
bridgeConfigurations.<name>.transformerConfiguration
type: TransformerConfiguration
Default:
XML name: transformer-configuration
Description:
bridgeConfigurations.<name>.transformerConfiguration.className
Type: String
Default:
XML name: class-name
Description:
bridgeConfigurations.<name>.transformerConfiguration.properties
type: Map
Default:
XML name: property
Description: A KEY/VALUE 对在转换器上设置，如 properties.MY_PROPERTY=MY_VALUE
bridgeConfigurations.<name>.password
Type: String
Default:
XML name: password
Description: if unspecified, cluster-password.
bridgeConfigurations.<name>.queueName
Type: String
Default:
XML name: queue-name
Description: 此网桥使用的队列的名称。
bridgeConfigurations.<name>.forwardingAddress
Type: String
Default:
XML name: forward-address
Description: Address to forward to。如果省略，则使用原始地址。
bridgeConfigurations.<name>.routingType
Type: ComponentConfigurationRoutingType
Default: PASS
XML name: routing-type
Description: 如何设置桥接消息上的 routing-type。
bridgeConfigurations.<name>.name
Type: string
Default:
XML name: name
Description: this bridge 的唯一名称。
bridgeConfigurations.<name>.ha
type: boolean
Default: false
XML name: ha
Description: 指定此网桥是否支持故障切换。
bridgeConfigurations.<name>.initialConnectAttempts
Type: int
Default: -1
XML name: initial-connect-attempts
Description: The maximum number of initial connection attempts.默认值 -1 表示没有限制。
bridgeConfigurations.<name>.retryInterval
Type: long
Default: 2000
XML name: retry-interval
Description: 间隔（以毫秒为单位）在连续重试之间。
bridgeConfigurations.<name>.producerWindowSize
Description: int
Default: 1048576
XML name: producer-window-size
Description: Producer flow control。支持字节表示法，例如："K", "Mb", "MiB", "GB"。
bridgeConfigurations.<name>.clientFailureCheckPeriod
Type: long
Default: 30000
XML name: check-period
Description: the interval, in milliseconds, in the bridge's client check it failed to receive a ping from server。指定 -1 来禁用此检查。
bridgeConfigurations.<name>.discoveryGroupName
Type: String
Default:
XML name: discovery-group-ref
Description:
bridgeConfigurations.<name>.user
Type: String
Default:
XML name: user
Description: Username.如果未指定，则使用 cluster-user。
bridgeConfigurations.<name>.useDuplicateDetection
type: boolean
Default: true
XML name: use-duplicate-detection
Description: 指定是否在转发的消息中插入重复的检测标头。
bridgeConfigurations.<name>.minLargeMessageSize
type: int
Default: 102400
XML name: min-large-message-size
Description: size, in bytes, above，消息被视为大型消息。大型消息通过网络在多个片段中发送。支持字节表示法，例如 "K", "Mb", "MiB", "GB"。
G.2. AMQPConnections
AMQPConnections.<name>.reconnectAttempts
Type: int
Default: -1
XML name: reconnect-attempts
Description: The number of reconnection attempts after a failure.
AMQPConnections.<name>.password
Type: string
Default:
XML name: password
Description: used to connect password。如果没有指定，则会尝试匿名连接。
AMQPConnections.<name>.retryInterval
Type: int
Default: 5000
XML name: retry-interval
Description: 间隔（以毫秒为单位）在连续重试之间。
AMQPConnections.<name>.connectionElements
Description: AMQPMirrorBrokerConnectionElement
Default:
XML name: amqp-connection
Description: 一个 AMQP Broker 连接支持 4 类型：1。mirrors - 代理使用 AMQP 连接到另一个代理，重复消息，并通过线路发送确认。2.senders - 在特定队列上收到的消息传输到另一个端点。3.receivers - 代理从另一个端点拉取信息。4.peers - 代理在另一个端点上创建发送者和接收器，它们知道如何处理它们。目前由 Apache Qpid Dispatch 实施。目前，只支持镜像类型。
AMQPConnections.<name>.connectionElements.<name>.messageAcknowledgments
Type: boolean
Default:
XML name: message-acknowledgments
Description: If true, message confirmations are mirroreds are mirrored.
AMQPConnections.<name>.connectionElements.<name>.queueRemoval
type: boolean
Default:
XML name: queue-removal
Description: 指定镜像队列是否删除地址和队列的事件。
AMQPConnections.<name>.connectionElements.<name>.addressFilter
Type: String
Default:
XML name: address-filter
Description: 指定镜像用来根据源地址将哪些事件转发到目标服务器的过滤器。
AMQPConnections.<name>.connectionElements.<name>.queueCreation
type: boolean
Default:
XML name: queue-creation
Description: 指定镜像队列是否为地址和队列创建事件。
AMQPConnections.<name>.autostart
type: boolean
Default: true
XML name: auto-start
Description: 指定在服务器启动时是否启动代理连接。
AMQPConnections.<name>.user
Type: string
Default:
XML name: user
Description: 用于连接的用户名。如果没有指定，则会尝试匿名连接。
AMQPConnections.<name>.uri
Type: String
Default:
XML name: uri
Description:
G.3. divertConfiguration
divertConfigurations.<name>.transformerConfiguration
type: TransformerConfiguration
Default:
XML name: transformer-configuration
Description:
divertConfigurations.<name>.transformerConfiguration.className
Type: String
Default:
XML name: class-name
Description:
divertConfigurations.<name>.transformerConfiguration.properties
type: Map
Default:
XML name: property
Description: A KEY/VALUE 对在转换器上设置，例如 …properties.MY_PROPERTY=MY_VALUE。
divertConfigurations.<name>.filterString
Type: String
Default:
XML name: filter-string
Description:
divertConfigurations.<name>.routingName
Type: String
Default:
XML name: routing-name
Description: the divert.
divertConfigurations.<name>.address
Type: String
Default:
XML name: address
Description: The address this divert will divert from.
divertConfigurations.<name>.forwardingAddress
Type: String
Default:
XML name: forward-address
Description: The forwarding address for the divert.
divertConfigurations.<name>.routingType
Type: ComponentConfigurationRoutingType (MULTICAST ANYCAST STRIP PASS)
Default:
XML name: routing-type
Description: How the routing-type on the diverted messages is set.
divertConfigurations.<name>.exclusive
type: boolean
Default: false
XML name: exclusive
Description: 指定这是否为 exclusive divert。
G.4. addressSettings
addressSettings.<address>.configDeleteDiverts
Type: DeletionPolicy (OFF FORCE)
Default:
XML name: config-delete-addresses
Description:
addressSettings.<address>.expiryQueuePrefix
type: SimpleString
Default:
XML name: expiry-queue-prefix
Description:
addressSettings.<address>.defaultConsumerWindowSize
type: int
Default:
XML name: default-consumer-window-size
Description:
addressSettings.<address>.maxReadPageBytes
type: int
Default:
XML name: max-read-page-bytes
Description:
addressSettings.<address>.deadLetterQueuePrefix
type: SimpleString
Default:
XML name: dead-letter-queue-prefix
Description:
addressSettings.<address>.defaultGroupRebalancePauseDispatch
type: boolean
Default:
XML name: default-group-rebalance-pause-dispatch
Description:
addressSettings.<address>.autoCreateAddresses
type: Boolean
Default:
XML name: auto-create-addresses
Description:
addressSettings.<address>.slowConsumerThreshold
type: long
Default:
XML name: slow-consumer-threshold
Description:
addressSettings.<address>.managementMessageAttributeSizeLimit
type: int
Default:
XML name: management-message-attribute-size-limit
Description:
addressSettings.<address>.autoCreateExpiryResources
type: boolean
Default:
XML name: auto-create-expiry-resources
Description:
addressSettings.<address>.pageSizeBytes
type: int
Default:
XML name: page-size-bytes
Description:
addressSettings.<address>.minExpiryDelay
type: Long
Default:
XML name: min-expiry-delay
Description:
addressSettings.<address>.defaultConsumersBeforeDispatch
type: Integer
Default:
XML name: default-consumers-before-dispatch
Description:
addressSettings.<address>.expiryQueueSuffix
type: SimpleString
Default:
XML name: expiry-queue-suffix
Description:
addressSettings.<address>.configDeleteQueues
Type: DeletionPolicy (OFF FORCE)
Default:
XML name: config-delete-queues
Description:
addressSettings.<address>.enableIngressTimestamp
type: boolean
Default:
XML name: enable-ingress-timestamp
Description:
addressSettings.<address>.autoDeleteCreatedQueues
type: Boolean
Default:
XML name: auto-delete-created-queues
Description:
addressSettings.<address>.expiryAddress
type: SimpleString
Default:
XML name: expiry-address
Description:
addressSettings.<address>.managementBrowsePageSize
type: int
Default:
XML name: management-browse-page-size
Description:
addressSettings.<address>.autoDeleteQueues
type: Boolean
Default:
XML name: auto-delete-queues
Description:
addressSettings.<address>.retroactiveMessageCount
type: long
Default:
XML name: retroactive-message-count
Description:
addressSettings.<address>.maxExpiryDelay
type: Long
Default:
XML name: max-expiry-delay
Description:
addressSettings.<address>.maxDeliveryAttempts
type: int
Default:
XML name: max-delivery-attempts
Description:
addressSettings.<address>.defaultGroupFirstKey
type: SimpleString
Default:
XML name: default-group-first-key
Description:
addressSettings.<address>.slowConsumerCheckPeriod
type: long
Default:
XML name: slow-consumer-check-period
Description:
addressSettings.<address>.defaultPurgeOnNoConsumers
type: Boolean
Default:
XML name: default-purge-on-no-consumers
Description:
addressSettings.<address>.defaultLastValueKey
type: SimpleString
Default:
XML name: default-last-value-key
Description:
addressSettings.<address>.autoCreateQueues
type: Boolean
Default:
XML name: auto-create-queues
Description:
addressSettings.<address>.defaultExclusiveQueue
type: Boolean
Default:
XML name: default-exclusive-queue
Description:
addressSettings.<address>.defaultMaxConsumers
type: Integer
Default:
XML name: default-max-consumers
Description:
addressSettings.<address>.defaultQueueRoutingType
Type: RoutingType (MULTICAST ANYCAST)
Default:
XML name: default-queue-routing-type
Description:
addressSettings.<address>.messageCounterHistoryDayLimit
type: int
Default:
XML name: message-counter-history-day-limit
Description:
addressSettings.<address>.defaultGroupRebalance
type: boolean
Default:
XML name: default-group-rebalance
Description:
addressSettings.<address>.defaultAddressRoutingType
Type: RoutingType (MULTICAST ANYCAST)
Default:
XML name: default-address-routing-type
Description:
addressSettings.<address>.maxSizeBytesRejectThreshold
type: long
Default:
XML name: max-size-bytes-reject-threshold
Description:
addressSettings.<address>.pageCacheMaxSize
type: int
Default:
XML name: page-cache-max-size
Description:
addressSettings.<address>.autoCreateDeadLetterResources
type: boolean
Default:
XML name: auto-create-dead-letter-resources
Description:
addressSettings.<address>.maxRedeliveryDelay
type: long
Default:
XML name: max-redelivery-delay
Description:
addressSettings.<address>.configDeleteAddresses
type: DeletionPolicy
Default:
XML name: config-delete-addresses
Description:
addressSettings.<address>.deadLetterAddress
type: SimpleString
Default:
XML name: dead-letter-address
Description:
addressSettings.<address>.autoDeleteQueuesMessageCount
type: long
Default:
XML name: auto-delete-queues-message-count
Description:
addressSettings.<address>.autoDeleteAddresses
type: Boolean
Default:
XML name: auto-delete-addresses
Description:
addressSettings.<address>.addressFullMessagePolicy
type: AddressFullMessagePolicy
Default:
XML name: address-full-policy
Description:
addressSettings.<address>.maxSizeBytes
type: long
Default:
XML name: max-size-bytes
Description:
addressSettings.<address>.defaultDelayBeforeDispatch
type: Long
Default:
XML name: default-delay-before-dispatch
Description:
addressSettings.<address>.redistributionDelay
type: long
Default:
XML name: redistribution-delay
Description:
addressSettings.<address>.maxSizeMessages
type: long
Default:
XML name: max-size-messages
Description:
addressSettings.<address>.redeliveryMultiplier
type: double
Default:
XML name: redelivery-delay-multiplier
Description:
addressSettings.<address>.defaultRingSize
Type: long
Default:
XML name: default-ring-size
Description:
addressSettings.<address>.defaultLastValueQueue
type: boolean
Default:
XML name: default-last-value-queue
Description:
addressSettings.<address>.slowConsumerPolicy
type: SlowConsumerPolicy (KILL NOTIFY)
Default:
XML name: slow-consumer-policy
Description:
addressSettings.<address>.redeliveryCollisionAvoidanceFactor
type: double
Default:
XML name: redelivery-collision-avoidance-factor
Description:
addressSettings.<address>.autoDeleteQueuesDelay
type: long
Default:
XML name: auto-delete-queues-delay
Description:
addressSettings.<address>.autoDeleteAddressesDelay
type: long
Default:
XML name: auto-delete-addresses-delay
Description:
addressSettings.<address>.expiryDelay
type: Long
Default:
XML name: expiry-delay
Description:
addressSettings.<address>.enableMetrics
type: boolean
Default:
XML name: enable-metrics
Description:
addressSettings.<address>.sendToDLAOnNoRoute
type: boolean
Default:
XML name: send-to-d-l-a-on-no-route
Description:
addressSettings.<address>.slowConsumerThresholdMeasurementUnit
Type: SlowConsumerThresholdMeasurementUnit (MESSAGES_PER_SECOND MESSAGES_PER_MINUTE MESSAGES_PER_HOUR MESSAGES_PER_DAY)
Default:
XML name: slow-consumer-threshold-measurement-unit
Description:
addressSettings.<address>.redeliveryDelay
type: long
Default:
XML name: redelivery-delay
Description:
addressSettings.<address>.deadLetterQueueSuffix
type: SimpleString
Default:
XML name: dead-letter-queue-suffix
Description:
addressSettings.<address>.defaultNonDestructive
type: boolean
Default:
XML name: default-non-destructive
Description:
G.5. federationConfigurations
federationConfigurations.<name>.transformerConfigurations
type: FederationTransformerConfiguration
Default:
XML name: transformer
Description: Optional transformer configuration。
federationConfigurations.<name>.transformerConfigurations.<name>.transformerConfiguration
type: TransformerConfiguration
Default:
XML name: transformer
Description: 允许添加自定义转换器来修改消息。
federationConfigurations.<name>.transformerConfigurations.<name>.transformerConfiguration.<name>.className
Type: String
Default:
XML name: class-name
Description: the class name of the Transformer 实现。
federationConfigurations.<name>.transformerConfigurations.<name>.transformerConfiguration.<name>.properties
type: Map
Default:
XML name: property
Description: A KEY/VALUE 对在转换器上设置，例如 …properties.MY_PROPERTY=MY_VALUE。
federationConfigurations.<name>.queuePolicies
type: FederationQueuePolicyConfiguration
Default:
XML name: queue-policy
Description:
federationConfigurations.<name>.queuePolicies.<name>.priorityAdjustment
Type: Integer
Default:
XML name: priority-adjustment
Description: 当消费者附加时，会使用其优先级来创建上游消费者，但调整了调整，以便本地用户在远程消费者之前平衡负载。
federationConfigurations.<name>.queuePolicies.<name>.excludes
type: Matcher
Default:
XML name: exclude
Description: 一个队列与要排除的队列列表。
federationConfigurations.<name>.queuePolicies.<name>.excludes.<name>.queueMatch
Type: String
Default:
XML name: queue-match
Description: 一个要应用的队列匹配模式。如果没有，则所有队列都会匹配。
federationConfigurations.<name>.queuePolicies.<name>.transformerRef
Type: String
Default:
XML name: transformer-ref
Description: 您要配置的转换器的 ref 名称，以在联邦传输时转换消息。
federationConfigurations.<name>.queuePolicies.<name>.includes
Type: Matcher
Default:
XML name: queue-match
Description:
federationConfigurations.<name>.queuePolicies.<name>.excludes.<name>.queueMatch
Type: String
Default:
XML name: queue-match
Description: 一个要应用的队列匹配模式。如果没有，则所有队列都会匹配。
federationConfigurations.<name>.queuePolicies.<name>.includeFederated
Type: boolean
Default:
XML name: include-federated
Description: 当值设置为 false 时，配置不会重新联邦已经联邦的消费者，即联邦队列中的消费者。这可避免发生在对称或闭环拓扑中，没有非联邦消费者和系统间的消息流。
federationConfigurations.<name>.upstreamConfigurations
type: FederationUpstreamConfiguration
Default:
XML name: upstream
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration
type: FederationConnectionConfiguration
Default:
XML name: connection-configuration
Description: the stream connection configuration。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.priorityAdjustment
type: int
Default:
XML name: priority-adjustment
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.retryIntervalMultiplier
Type: double
Default: 1
XML name: retry-interval-multiplier
Description: to the retry-interval 的倍数。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.shareConnection
type: boolean
Default: false
XML name: share-connection
Description: 如果设为 true，如果为同一代理配置了下游和上游连接，则会共享同一连接。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.maxRetryInterval
type: long
Default: 2000
XML name: max-retry-interval
Description: retry-interval 的最大值。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.connectionTTL
type: long
Default:
XML name: connection-t-t-l
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.circuitBreakerTimeout
type: long
Default: 30000
XML name: circuit-breaker-timeout
Description: 指定此连接是否支持 fail-over。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.callTimeout
type: long
Default: 30000
XML name: call-timeout
Description: 等待回复的持续时间。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.staticConnectors
Type: List
Default:
XML name: static-connectors
Description: 通过连接器配置的连接器引用列表。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.reconnectAttempts
Type: int
Default: -1
XML name: reconnect-attempts
Description: The number of reconnection attempts after a failure.
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.password
Type: String
Default:
XML name: password
Description: a password.如果没有指定，则使用联邦密码。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.callFailoverTimeout
Type: long
Default: -1
XML name: call-failover-timeout
Description: The duration to wait for a reply during a fail-over.值 -1 表示没有限制。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.hA
type: boolean
Default:
XML name: h-a
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.initialConnectAttempts
Type: int
Default: -1
XML name: initial-connect-attempts
Description: The number of initial attempts to connect.
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.retryInterval
Type: long
Default: 500
XML name: retry-interval
Description: 间隔（以毫秒为单位）在连续重试之间。
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.clientFailureCheckPeriod
type: long
Default:
XML name: client-failure-check-period
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.connectionConfiguration.username
Type: string
Default:
XML name: username
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.policyRefs
type: Collection
Default:
XML name: policy-refs
Description:
federationConfigurations.<name>.upstreamConfigurations.<name>.staticConnectors
Type: List
Default:
XML name: static-connectors
Description: 通过连接器配置的连接器引用列表。
federationConfigurations.<name>.downstreamConfigurations
type: FederationDownstreamConfiguration
Default:
XML name: downstream
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration
type: FederationConnectionConfiguration
Default:
XML name: connection-configuration
Description: the stream connection configuration。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.priorityAdjustment
type: int
Default:
XML name: priority-adjustment
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.retryIntervalMultiplier
Type: double
Default: 1
XML name: retry-interval-multiplier
Description: to the retry-interval 的倍数。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.shareConnection
type: boolean
Default: false
XML name: share-connection
Description: 如果设为 true，如果为同一代理配置了下游和上游连接，则会共享同一连接。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.maxRetryInterval
type: long
Default: 2000
XML name: max-retry-interval
Description: retry-interval 的最大值。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.connectionTTL
type: long
Default:
XML name: connection-t-t-l
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.circuitBreakerTimeout
type: long
Default: 30000
XML name: circuit-breaker-timeout
Description: 指定此连接是否支持 fail-over。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.callTimeout
type: long
Default: 30000
XML name: call-timeout
Description: 等待回复的持续时间。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.staticConnectors
Type: List
Default:
XML name: static-connectors
Description: 通过连接器配置的连接器引用列表。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.reconnectAttempts
Type: int
Default: -1
XML name: reconnect-attempts
Description: The number of reconnection attempts after a failure.
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.password
Type: String
Default:
XML name: password
Description: a password.如果没有指定，则使用联邦密码。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.callFailoverTimeout
Type: long
Default: -1
XML name: call-failover-timeout
Description: The duration to wait for a reply during a fail-over.值 -1 表示没有限制。
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.hA
type: boolean
Default:
XML name: h-a
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.initialConnectAttempts
Type: int
Default: -1
XML name: initial-connect-attempts
Description: The number of initial attempts to connect.
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.retryInterval
Type: long
Default: 500
XML name: retry-interval
Description: The period, in milliseconds, between successive retries.
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.clientFailureCheckPeriod
type: long
Default:
XML name: client-failure-check-period
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.connectionConfiguration.username
Type: string
Default:
XML name: username
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.policyRefs
type: Collection
Default:
XML name: policy-refs
Description:
federationConfigurations.<name>.downstreamConfigurations.<name>.staticConnectors
Type: List
Default:
XML name: static-connectors
Description: 通过连接器配置的连接器引用列表。
federationConfigurations.<name>.federationPolicys
type: FederationPolicy
Default:
XML name: policy-set
Description:
federationConfigurations.<name>.addressPolicies
type: FederationAddressPolicyConfiguration
Default:
XML name: address-policy
Description:
federationConfigurations.<name>.addressPolicies.<name>.autoDeleteMessageCount
Type: Long
Default:
XML name: auto-delete-message-count
Description: 在该队列有资格自动删除前，仍然可在动态创建的远程队列中的最大消息数。
federationConfigurations.<name>.addressPolicies.<name>.enableDivertBindings
type: Boolean
Default:
XML name: enable-divert-bindings
Description: Setting to true 可让 divert 绑定进行侦听。如果存在与地址策略包含地址匹配的地址的 divert 绑定，则与 divert 的转发地址匹配的队列绑定都将创建需求。默认值为 false。
federationConfigurations.<name>.addressPolicies.<name>.includes.{NAME}.addressMatch
Type: Matcher
Default:
XML name: include
Description:
federationConfigurations.<name>.addressPolicies.<name>.maxHops
type: int
Default:
XML name: max-hops
Description: 消息可以进行联邦的跃点数。
federationConfigurations.<name>.addressPolicies.<name>.transformerRef
Type: String
Default:
XML name: transformer-ref
Description: 您要配置的转换器的 ref 名称，以在联邦传输时转换消息。
federationConfigurations.<name>.addressPolicies.<name>.autoDeleteDelay
Type: Long
Default:
XML name: auto-delete-delay
Description: The duration, in milliseconds, after the upstream broker disconnects before the upstream queue can be delete.
federationConfigurations.<name>.addressPolicies.<name>.autoDelete
Type: Boolean
Default:
XML name: auto-delete
Description: 用于地址联邦，下游会在上游地址上动态创建一个持久队列。指定在下游断开连接并且满足延迟和消息计数参数后，是否删除上游队列。
federationConfigurations.<name>.addressPolicies.<name>.excludes.{NAME}.addressMatch
Type: Matcher
Default:
XML name: include
Description:
G.6. clusterConfigurations
clusterConfigurations.<name>.retryIntervalMultiplier
Type: double
Default: 1
XML name: retry-interval-multiplier
Description: to the retry-interval 的倍数。
clusterConfigurations.<name>.maxRetryInterval
type: long
Default: 2000
XML name: max-retry-interval
Description: retry-interval 的最大值。
clusterConfigurations.<name>.address
Type: String
Default:
XML name: address
Description: this cluster connection to address 的名称。
clusterConfigurations.<name>.maxHops
type: int
Default: 1
XML name: max-hops
Description: 集群拓扑传播到的最大跃点数。
clusterConfigurations.<name>.connectionTTL
type: long
Default: 60000
XML name: connection-ttl
Description: 如果客户端没有收到数据，则保持连接在线的时间。
clusterConfigurations.<name>.clusterNotificationInterval
Type: long
Default: 1000
XML name: notification-interval
Description: 集群连接通知其存在集群的间隔。
clusterConfigurations.<name>.confirmationWindowSize
type: int
Default: 1048576
XML name: confirmation-window-size
Description: 用于确认服务器数据的窗口的大小（以字节为单位）。支持字节表示法，例如 "K", "Mb", "MiB", "GB"。
clusterConfigurations.<name>.callTimeout
type: long
Default: 30000
XML name: call-timeout
Description: 等待回复的持续时间。
clusterConfigurations.<name>.staticConnectors
type: List
Default:
XML name: static-connectors
Description: 连接器引用名称列表。
clusterConfigurations.<name>.clusterNotificationAttempts
type: int
Default: 2
XML name: notification-attempts
Description: 此集群连接尝试通知集群的存在次数。
clusterConfigurations.<name>.allowDirectConnectionsOnly
type: boolean
Default: false
XML name: allow-direct-connections-only
Description: Restricts cluster connection to the listed connector-refs。
clusterConfigurations.<name>.reconnectAttempts
Type: int
Default: -1
XML name: reconnect-attempts
Description: The number of reconnection attempts after a failure.
clusterConfigurations.<name>.duplicateDetection
type: boolean
Default: true
XML name: use-duplicate-detection
Description: 指定是否在转发的消息中插入重复的检测标头。
clusterConfigurations.<name>.callFailoverTimeout
Type: long
Default: -1
XML name: call-failover-timeout
Description: The duration to wait for a reply during a fail-over.值 -1 表示没有限制。
clusterConfigurations.<name>.messageLoadBalancingType
Type: MessageLoadBalancingType (OFF STRICT ON_DEMAND OFF_WITH_REDISTRIBUTION)
Default:
XML name: message-load-balancing-type
Description:
clusterConfigurations.<name>.initialConnectAttempts
Type: int
Default: -1
XML name: initial-connect-attempts
Description: The number of initial attempts to connect.
clusterConfigurations.<name>.connectorName
Type: String
Default:
XML name: connector-ref
Description: 要使用的连接器引用的名称。
clusterConfigurations.<name>.retryInterval
Type: long
Default: 500
XML name: retry-interval
Description: 间隔（以毫秒为单位）在连续重试之间。
clusterConfigurations.<name>.producerWindowSize
Description: int
Default: 1048576
XML name: producer-window-size
Description: Producer flow control。支持字节表示法，例如 "K", "Mb", "MiB", "GB"。
clusterConfigurations.<name>.clientFailureCheckPeriod
type: long
Default:
XML name: client-failure-check-period
Description:
clusterConfigurations.<name>.discoveryGroupName
Type: String
Default:
XML name: discovery-group-name
Description: 此 cluster-connection 使用的发现组的名称。
clusterConfigurations.<name>.minLargeMessageSize
type: int
Default:
XML name: min-large-message-size
Description: size, bytes, above, a message is considered a large message。大型消息通过网络在多个片段中发送。支持字节表示法，例如 "K", "Mb", "MiB", "GB"。
G.7. connectionRouters
connectionRouters.<name>.cacheConfiguration
Type: CacheConfiguration
Default:
XML name: cache
Description: 控制如果缓存条目持久，以及缓存删除其条目的频率。
connectionRouters.<name>.cacheConfiguration.persisted
Type: boolean
Default: false
XML name: persistent
Description: true 表示缓存条目具有持久性。
connectionRouters.<name>.cacheConfiguration.timeout
Type: int
Default: -1
XML name: timeout
Description: The timeout, in milliseconds, before cache entries are removed.
connectionRouters.<name>.keyFilter
Type: String
Default:
XML name: key-filter
Description: target 键的过滤器。
connectionRouters.<name>.keyType
Type: KeyType (CLIENT_ID SNI_HOST SOURCE_IP USER_NAME ROLE_NAME)
Default:
XML name: key-type
Description: The optional target key.
connectionRouters.<name>.localTargetFilter
Type: String
Default:
XML name: local-target-filter
Description: a filter to find the local target。
connectionRouters.<name>.poolConfiguration
type: PoolConfiguration
Default:
XML name: pool
Description: the pool configuration.
connectionRouters.<name>.poolConfiguration.quorumTimeout
type: int
Default: 3000
XML name: quorum-timeout
Description: 用于获取最小就绪目标的超时时间（以毫秒为单位）。
connectionRouters.<name>.poolConfiguration.password
Type: string
Default:
XML name: password
Description: to access the target。
connectionRouters.<name>.poolConfiguration.localTargetEnabled
type: boolean
Default: false
XML name: local-target-enabled
Description: true 表示本地目标已启用。
connectionRouters.<name>.poolConfiguration.checkPeriod
Type: int
Default: 5000
XML name: check-period
Description: 用于检查目标是否已就绪的时间（以毫秒为单位）。
connectionRouters.<name>.poolConfiguration.quorumSize
type: int
Default: 1
XML name: quorum-size
Description: 最小就绪目标数。
connectionRouters.<name>.poolConfiguration.staticConnectors
Type: List
Default:
XML name: static-connectors
Description: 通过连接器配置的连接器引用列表。
connectionRouters.<name>.poolConfiguration.discoveryGroupName
Type: String
Default:
XML name: discovery-group-name
Description: 此网桥使用的发现组的名称。
connectionRouters.<name>.poolConfiguration.clusterConnection
Type: String
Default:
XML name: cluster-connection
Description: 集群连接的名称。
connectionRouters.<name>.poolConfiguration.username
Type: String
Default:
XML name: username
Description:
connectionRouters.<name>.policyConfiguration
type: NamedPropertyConfiguration
Default:
XML name: policy-configuration
Description:
connectionRouters.<name>.properties.{PROPERTY}
type: Properties
Default:
XML name: property
Description: 特定于每个命名属性的键值对集合。
更新于 2025-05-14
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}