4.22. 定位地址和队列

联合支持在代理间传输信息，而无需在通用集群中使用代理。代理可以是独立的，也可以在单独的集群中。另外，源和目标代理可以在不同的管理域中，这意味着代理可能有不同的配置、用户和安全设置。代理甚至可能使用不同的 AMQ Broker 版本。

例如，联合适合将信息从一个集群可靠地发送到另一个集群。这种传输可能会跨越广域网(WAN)、云基础架构的区域或互联网。如果源代理到目标代理的连接丢失（例如，因为网络故障），源代理会尝试重新建立连接，直到目标代理恢复在线为止。当目标代理恢复在线时，邮件传输会恢复。

管理员可以使用地址和队列策略来管理联合。策略配置可以匹配到特定的地址或队列，或者策略可以包含与一组地址或队列匹配的通配符表达式。因此，联邦可以动态应用，作为队列或地址被添加到匹配集合中，或从匹配的集合中删除。策略 可以包含多个 表达式，其中包括和/或排除特定地址和队列。另外，多个策略也可以应用到代理或代理集群。

在 AMQ Broker 中，两个主要的联邦选项是 address federation 和 queue federation。这些选项在后面的部分中描述。

注意

代理可以包括联合和仅限本地组件的配置。也就是说，如果您在代理上配置联合，则不需要联合该代理的所有内容。

4.22.1. 关于地址联合

地址联合(address federation)类似于连接的代理之间的全多播分布模式。例如，发送到 BrokerA 上地址的每个消息都传送到该代理上的每个队列。另外，每个消息都传送到 BrokerB 以及所有附加的队列。

地址联合会动态将代理链接到远程代理中的地址。例如，如果本地代理想要从远程代理上的地址获取信息，则远程地址上会自动创建队列。然后，远程代理上的消息会被消耗到这个队列。最后，消息会复制到本地代理上的对应地址，尽管它们最初直接发布到本地地址。

远程代理不需要重新配置，以允许联合在其上创建地址。但是，本地代理需要被授予远程地址的权限。

4.22.2. 地址联合的通用拓扑

下面介绍了一些使用地址联邦的拓扑。

对称拓扑

在对称拓扑中，生产者和使用者连接到每个代理。队列及其使用者可接收由任一制作者发布的消息。下面是一个对称拓扑的示例。

图 4.1. 在对称拓扑中的地址联合

为对称拓扑配置地址联合时，务必要将地址策略的 max-hops 属性值设置为 1。这样可保证 仅复制一次 消息，从而避免复制。如果此属性设置为较大的值，则使用者将接收相同消息的多个副本。

全网格拓扑

全网格拓扑与对称设置类似。三个或更多对称的代理相互联合，从而创建一个完整的网格。在这个设置中，生产者和使用者连接到每个代理。队列及其使用者可接收任何生产者发布的消息。此拓扑示例如下所示。

图 4.2. 在完整网格拓扑中联合地址

与对称设置一样，在为全网格拓扑配置地址联合时，务必要将地址策略的 max-hops 属性的值设置为 1。这样可保证 仅复制一次 消息，从而避免复制。

Ring topology

在代理环中，每个联合地址都被上游用于环中另一个地址。此拓扑示例如下所示。

图 4.3. 在环拓扑中联合地址

当您为环拓扑配置联合时，为了避免cyclic 复制，务必要将地址策略的 max-hops 属性设置为 n-1 的值，其中 n 是环中节点的数量。例如，在上面的环拓扑中，max-hops 的值设置为 5。这可确保环中的每个地址都只看到消息一次。

环形拓扑的一个优点是，根据您需要进行的物理连接数量，设置价格较低。但是，这种类型的拓扑的一个缺陷是，如果单个代理失败，整个环都会失败。

fan-out 拓扑

在流畅的拓扑中，单个 master 地址通过联合地址树链接到。发布到 master 地址的任何消息都可以被连接到树中的任何代理都接收。树可以被配置为任何深度。也可以通过在树内重新配置现有代理的情况下扩展树。此拓扑示例如下所示。

图 4.4. 在 fan-out 拓扑中进行地址联合

当您为 fan-out 拓扑配置联合时，请确保将地址策略的 max-hops 属性设置为 n-1 的值，其中 n 是树中的级别数。例如，在上方显示的 fan-out 拓扑中，max-hops 的值设置为 2。这样可保证树中的每个地址都只看到消息一次。

4.22.3. 支持在地址联合配置中区分绑定

配置地址联合时，您可以在地址策略配置中添加对竞争绑定的支持。添加这个支持可让联合响应分离绑定，为远程代理上的给定地址创建一个联合消费者。

例如，假设地址策略中包含一个名为 test.federation.source 的地址，并且包含另一个名为 test.federation.target 的地址。通常，当一个队列在 test.federation.target 上创建，不会导致创建联邦消费者，因为地址不是地址策略的一部分。但是，如果您创建 divert 绑定，使得 test.federation.source 是源地址，test.federation.target 是转发地址的转发地址，则会在转发地址中创建 durable consumer。源地址仍然必须使用 multicast 路由类型，但目标地址可以使用 multicast 或 anycast。

示例用例是将 JMS 主题（多播地址 ）重定向到 JMS 队列（任何广播地址 ）。这可为不支持 JMS 2.0 和共享订阅的传统消费者上启用对消息的负载平衡。

4.22.4. 为代理集群配置联合

以下部分示例演示了如何配置独立本地和远程代理之间的地址和队列联合。对于独立代理（联合配置）的名称以及任何地址和队列策略的名称，在本地和远程代理之间必须是唯一的。

但是，如果您要在 集群中 为代理配置联合，则还有额外的要求。对于集群代理（联合配置）的名称以及该配置中的任何地址和队列策略 的名称必须与该集群中的每个代理都相同。

确保同一集群中的代理使用相同的联合配置和地址和队列策略名称，避免消息重复。例如，如果同一集群中的代理 有不同的 联合配置名称，这可能会导致出现多个不同命名的转发队列用于同一地址，从而导致下游用户的消息重复。相反，如果同一集群中的代理 使用相同的 联合配置名称，这实质上会创建复制，集群转发队列与下游用户进行负载平衡。这可避免消息重复。

4.22.5. 配置上游地址联合

以下示例演示了如何配置独立代理之间的上游地址联合。在本例中，您要将一个本地（即下游）代理联合配置为一些远程（即上游）代理。

先决条件

以下示例演示了如何配置独立代理间的地址联邦。但是，您还应熟悉为代理 集群配置 联合的要求。更多信息请参阅第 4.22.4 节 “为代理集群配置联合”。

流程

打开 & lt;broker_instance_dir> /etc/broker.xml 配置文件。
添加新的 < federations> 元素，其中包含 &lt ;federation> 元素。例如：
```
<federations>
  <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
  </federation>
</federations>
```
name
联合配置的名称。在本例中，名称与本地代理的名称对应。
user
连接到上游代理的共享用户名。
password
连接到上游代理的共享密码。
注意
如果远程代理的用户和密码凭证不同，您可以在将代理添加到配置中单独指定凭证。此流程稍后会描述。
在 federation 元素中添加 < address-policy> 元素。例如：
```
<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
        </address-policy>

    </federation>
</federations>
```
name
地址策略的名称。在代理中配置的所有地址策略都必须有唯一的名称。
auto-delete
在地址联合过程中，本地代理会在远程地址动态创建持久队列。auto-delete 属性的值指定在本地代理断开连接后队列是否应该被删除， auto-delete-delay 和 auto-delete-message-count 属性的值也已达到。如果要自动清理动态创建的队列，这是非常有用的选项。如果要防止本地代理长时间在远程代理上构建消息，它也是一个有用的选项。但是，如果您希望消息在连接断开连接时总是为本地代理保留排队，则可以将此选项设置为 false，从而避免在本地代理上丢失消息。
auto-delete-delay
本地代理断开连接后，此属性的值指定了在动态创建的远程队列有资格删除前的时间长度（以毫秒为单位）。
auto-delete-message-count
断开本地代理后，此属性的值指定在符合该队列条件自动删除前，仍可处于动态创建的远程队列中的最大信息数。
enable-divert-bindings
将此属性设置为 true 可按需侦听绑定。如果存在与地址策略所包含地址相匹配的地址的分制绑定，那么任何与分组转发地址匹配的队列绑定将根据需要创建。默认值为 false。
max-hops
在联合过程中可以进行消息的最大跃点数。特定拓扑需要此属性的特定值。如需了解更多有关这些要求的信息，请参阅第 4.22.2 节 “地址联合的通用拓扑”。
transformer-ref
转换器配置的名称。如果要在联合消息传输过程中转换消息，可以添加一个转换器配置。此流程稍后会描述转换器配置。
在 & lt;address-policy > 元素中，添加 address-matching 模式，以便从地址策略中包含和排除地址。例如：
```
<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">

            <include address-match="queue.bbc.new" />
            <include address-match="queue.usatoday" />
            <include address-match="queue.news.#" />

            <exclude address-match="queue.news.sport.#" />
        </address-policy>

    </federation>
</federations>
```
Include
此元素的 address-match 属性的值指定要包含在地址策略中的地址。您可以指定具体地址，如 queue.bbc.new 或 queue.usatoday。或者，您可以使用通配符表达式来指定一组匹配的地址。在前面的示例中，地址策略还包括以字符串 queue.news 开头的所有 地址名称。
exclude
此元素的 address-match 属性的值指定要从地址策略中排除的地址。您可以指定准确的地址名，或使用通配符表达式来指定匹配的地址集。在前面的示例中，地址策略排除以字符串 queue.news.sport 开头的所有 地址名称。

（可选）使用 federation 元素，添加一个 transformer 元素来引用自定义转换器实现。例如：

<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">

            <include address-match="queue.bbc.new" />
            <include address-match="queue.usatoday" />
            <include address-match="queue.news.#" />

            <exclude address-match="queue.news.sport.#" />
        </address-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
</federations>

name

转换器配置的名称。这个名称必须在本地代理中唯一。这是您指定为地址策略的 transformer-ref 属性的值的名称。

class-name

实施 org.apache. office.artemis.core.server.transformer.Transformer 接口的用户定义的类名称。

在传输消息之前，使用消息调用 transformer 的 transform（） 方法。这可让您在整合消息标题或正文前转换它。

属性

用于保存用于特定转换器配置的键值对。

在 联合 元素内，添加一个或多个 上游 元素。每个 上游 元素都定义了与远程代理的连接，以及应用到该连接的策略。例如：
```
<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <upstream name="eu-east-1">
            <static-connectors>
                <connector-ref>eu-east-connector1</connector-ref>
            </static-connectors>
            <policy ref="news-address-federation"/>
        </upstream>

        <upstream name="eu-west-1" >
            <static-connectors>
                <connector-ref>eu-west-connector1</connector-ref>
            </static-connectors>
            <policy ref="news-address-federation"/>
        </upstream>

        <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">

            <include address-match="queue.bbc.new" />
            <include address-match="queue.usatoday" />
            <include address-match="queue.news.#" />

            <exclude address-match="queue.news.sport.#" />
        </address-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
</federations>
```
static-connectors
包含一个 连接器 元素列表，它引用本地代理的 broker.xml 配置文件其他位置中定义的 连接器 元素。连接器定义了用于出站连接的传输（TCP、SSL、HTTP 等）和服务器连接参数（主机、端口等）。此流程的下一步演示了如何添加在 static-connectors 元素中引用的连接器。
policy-ref
在应用到上游代理的下游代理上配置的地址策略的名称。
您可以为 上游 元素指定的附加选项如下所述：
name
上游代理配置的名称。在本例中，名称与名为 eu-east-1 和 eu-west-1 的上游代理对应。
user
创建到上游代理的连接时使用的用户名。如果没有指定，则使用在 联合 元素配置中指定的共享用户名。
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
下游和上游代理之间的单个连接可能由许多联合队列和地址消费者共享。如果代理间的连接丢失，每个联合消费者可能会尝试同时重新连接。为避免这种情况，称为 断路器 的机制将阻止消费者。当指定的超时值 elapses 时，断路器重新尝试连接。如果成功，则使用者将被取消阻塞。否则，再次应用断路器。
connection-ttl
如果联合连接停止从远程代理接收信息，则以毫秒为单位的连接会保持活跃时间。默认值为 60000。
discovery-group-ref
作为为到上游代理定义静态连接器的替代选择，此元素可用于指定已在 broker.xml 配置文件中其他位置配置的发现组。具体来说，您可以将一个现有的 discovery 组指定为此元素的 discovery-group-name 属性的值。有关发现组的更多信息，请参阅第 14.1.6 节 “代理发现方法”。
ha
指定是否为连接到上游代理启用高可用性。如果此参数的值被设置为 true，则本地代理可以连接到上游集群中的任何可用代理，并在实时上游代理关闭时自动故障切换到备份代理。默认值为 false。
initial-connect-attempts
下游代理要连接到上游代理的初始尝试次数。如果在没有建立连接的情况下达到这个值，则上游代理被视为永久离线。下游代理不再将消息路由到上游代理。默认值为 -1，这表示没有限制。
max-retry-interval
当连接到远程代理失败时，后续重新连接尝试之间的最长时间（以毫秒为单位）。默认值为 2000。
reconnect-attempts
如果连接失败，下游代理会尝试重新连接到上游代理的次数。如果在没有重新建立连接的情况下达到这个值，则上游代理被视为永久离线。下游代理不再将消息路由到上游代理。默认值为 -1，这表示没有限制。
retry-interval
如果连接到远程代理失败，则在后续的重新连接尝试之间以毫秒为单位为单位。默认值为 500。
retry-interval-multiplier
应用于 retry-interval 参数的值的倍数。默认值为：1。
share-connection
如果为同一代理同时配置了下游和上游连接，那么只要下游和上游配置都将把这个参数的值设置为 true，就可以共享同一连接。默认值为 false。

在本地代理上，将连接器添加到远程代理中。这些是在联合地址配置 的静态连接器 元素中引用的连接器。例如：

<connectors>
   <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
   <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
</connectors>

4.22.6. 配置下游地址联合

以下示例演示了如何为独立代理配置下游地址联合。

借助下游地址联合，您可以在本地代理中添加一个或多个远程代理用来连接到本地代理的本地代理。这种方法的优势在于，您可以在单个代理中保留所有联合配置。这可能是 hub 和spoke 拓扑的一个实用方法，例如：

注意

下游地址联合会反转连接与上游地址配置的方向。因此，当您在配置中添加远程代理时，这些代理被视为下游代理。下游代理使用配置中的连接信息重新连接到本地代理，该代理现在被视为上游。当您为远程代理添加配置时，本例中会对此进行说明。

先决条件

您应该熟悉上游地址联合的配置。请参阅第 4.22.5 节 “配置上游地址联合”。
以下示例演示了如何配置独立代理间的地址联邦。但是，您还应熟悉为代理 集群配置 联合的要求。更多信息请参阅第 4.22.4 节 “为代理集群配置联合”。

流程

在本地代理中，打开 &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">

        <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">

            <include address-match="queue.bbc.new" />
            <include address-match="queue.usatoday" />
            <include address-match="queue.news.#" />

            <exclude address-match="queue.news.sport.#" />
        </address-policy>

    </federation>
  ...
</federations>

如果要在传输前转换消息，请添加转换器配置。例如：

<federations>
    ...
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">

            <include address-match="queue.bbc.new" />
            <include address-match="queue.usatoday" />
            <include address-match="queue.news.#" />

            <exclude address-match="queue.news.sport.#" />
        </address-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
  ...
</federations>

为每个远程代理添加 downstream 项。例如：

<federations>
    ...
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <downstream name="eu-east-1">
                <static-connectors>
                    <connector-ref>eu-east-connector1</connector-ref>
                </static-connectors>
                <transport-connector-ref>netty-connector</transport-connector-ref>
                <policy ref="news-address-federation"/>
        </downstream>

        <downstream name="eu-west-1" >
                <static-connectors>
                    <connector-ref>eu-west-connector1</connector-ref>
                </static-connectors>
                <transport-connector-ref>netty-connector</transport-connector-ref>
                <policy ref="news-address-federation"/>
        </downstream>

        <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
            <include address-match="queue.bbc.new" />
            <include address-match="queue.usatoday" />
            <include address-match="queue.news.#" />

            <exclude address-match="queue.news.sport.#" />
        </address-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
  ...
</federations>

如前面的配置所示，远程代理现在被视为本地代理的下游。下游代理使用配置中的连接信息来回连接本地（即上游）代理。

在本地代理上，添加供本地和远程代理使用的连接器和接收器来建立联合连接。例如：
```
<connectors>
   <connector name="netty-connector">tcp://localhost:61616</connector>
   <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
   <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
</connectors>

<acceptors>
   <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
</acceptors>
```
连接器名称="netty-connector"
本地代理发送到远程代理的连接器配置。远程代理使用此配置连接回本地代理。
连接器名称="eu-west-1-connector", connector name="eu-east-1-connector"
远程代理的连接器。本地代理使用这些连接器连接到远程代理，并共享远程代理所需的配置来回连接本地代理。
acceptor name="netty-acceptor"
与远程代理使用的连接器对应的本地代理中的接受者，以连接至本地代理。

4.22.7. 关于队列联合

队列联合提供了一种方式，可以在其它远程代理的本地代理中平衡单一队列负载。

为实现负载平衡，本地代理从远程队列检索信息，以满足本地消费者对消息的要求。下面是一个示例。

图 4.5. 对称队列联合

远程队列不需要重新配置，且不必位于同一代理或同一集群中。建立远程链接且联合队列需要的所有配置都在本地代理中。

4.22.7.1. 队列联合的优点

以下是您可能选择配置队列联邦的一些原因。

增加容量

队列联合可以创建在多个代理上分发的"逻辑"队列。这个逻辑分布式队列的容量比单个代理中的一个队列要高。在这个设置中，尽可能多的信息会从最初发布到的代理中消耗。仅当需要负载平衡时，系统才会在联合中移动消息。

部署多区域设置

在多区域设置中，您可能在一个地区或场地处有一个消息制作者，并在另一个地区和消费者中有一个消息制作者。但是，您最好保留本地在特定地区的制作者和消费者连接。在这种情况下，您可以在生产者和消费者所处的每个区域中部署代理，并使用队列联合在区域间移动消息(WAN)。下面是一个示例。

图 4.6. 多区域队列联合

安全企业 LAN 和 DMZ 之间的通信

在网络安全中，demilitarized 区域 (DMZ)是一个物理或逻辑子网，其中包含一个企业级的、面向企业的外部服务，通常更大、网络（如互联网）。企业级本地区域网络(LAN)的其余部分在防火墙后保留与这个外部网络隔离。

在 DMZ 中，很多消息制作者位于 DMZ 中，而且安全企业 LAN 中的许多消费者可能并不适合使生产者连接到安全企业 LAN 中的代理。在这种情况下，您可以在 DMZ 中部署一个代理，制作者可以向其中发布消息。然后，企业 LAN 中的代理可以连接到 DMZ 中的代理，并使用联合队列从 DMZ 中的代理接收信息。

4.22.8. 配置上游队列联合

以下示例演示了如何为独立代理配置上游队列联合。在本例中，您要将一个本地（即下游）代理联合配置为一些远程（即上游）代理。

先决条件

以下示例演示了如何配置独立代理间的队列联邦。但是，您还应熟悉为代理 集群配置 联合的要求。更多信息请参阅第 4.22.4 节 “为代理集群配置联合”。

流程

打开 & lt;broker_instance_dir> /etc/broker.xml 配置文件。
在新的 < federations> 元素中添加 < federation> 元素。例如：
```
<federations>
  <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
  </federation>
</federations>
```
name
联合配置的名称。在本例中，名称与下游代理的名称对应。
user
连接到上游代理的共享用户名。
password
连接到上游代理的共享密码。
注意
- 如果上游代理的用户和密码凭证不同，您可以在将代理添加到配置中单独指定凭证。此流程稍后会描述。
在 federation 元素中添加 < queue-policy> 元素。指定 < queue-policy& gt; 元素的属性值。例如：
```
<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
        </queue-policy>

    </federation>
</federations>
```
name
队列策略的名称。在代理中配置的所有队列策略都必须有唯一的名称。
包含反馈
当此属性的值设置为 false 时，配置不会重新处理一个被破坏的消费者（即联合队列上的使用者）。这可避免在对称或闭环拓扑中出现的情况，没有对消费者造成不必要的影响，且系统无法无害的消息流。
如果您没有 闭环拓扑，可以将此属性的值设置为 true。例如，假设您有以下三个代理、BrokerA、BrokerB 和 BrokerC 链，且由 BrokerA 的制作者以及 BrokerC 的消费者。在这种情况下，您将希望 BrokerB 重新联邦消费者到 BrokerA。
优先级覆盖
当消费者连接到队列时，当创建上游（即联合）消费者时，会使用其优先级。联合消费者的优先级由 priority-adjustment 属性的值调整。这个属性的默认值为 -1，它可确保本地使用者在负载平衡期间得到的优先级高于联合消费者。但是，您可以根据需要更改优先级调整的值。

注意

如果只为本地消费者提供优先权，联邦消费者使用消息的速度导致太多消息被移到联邦消费者，但您可以限制联邦消费者消耗消息的速率。要限制消息消耗率，请在联邦用户的客户端连接 URI 中配置 consumerMaxRate 流控制选项。如需更多信息，请参阅使用 AMQ 核心协议 JMS 客户端 文档中的流控制选项。

transformer-ref

转换器配置的名称。如果要在联合消息传输过程中转换消息，可以添加一个转换器配置。此流程稍后会描述转换器配置。

在 & lt;queue-policy > 元素中，添加 address-matching 模式，以便从队列策略中包含和排除地址。例如：

<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">

            <include queue-match="#" address-match="queue.bbc.new" />
            <include queue-match="#" address-match="queue.usatoday" />
            <include queue-match="#" address-match="queue.news.#" />

            <exclude queue-match="#.local" address-match="#" />

        </queue-policy>

    </federation>
</federations>

Include

此元素的 address-match 属性的值指定要包含在队列策略中的地址。您可以指定具体地址，如 queue.bbc.new 或 queue.usatoday。或者，您可以使用通配符表达式来指定一组匹配的地址。在前面的示例中，队列策略还包括以字符串 queue.news 开头的所有 地址名称。

在与 address-match 属性结合使用，您可以使用 queue-match 属性在队列策略中包含特定队列。与 address-match 属性类似，您可以指定准确的队列名称，也可以使用通配符表达式来指定一组队列。在前面的示例中，数字符号(#)通配符表示在每个地址或一组地址上都 包括所有 队列。

exclude

此元素的 address-match 属性的值指定要从队列策略中排除的地址。您可以指定一个精确的地址或使用通配符表达式来指定一组匹配的地址。在前面的示例中，数字符号(#)通配符表示排除任何匹配跨越所有地址中的 queue-match 属性的队列。在这种情况下，任何以字符串 .local 结尾的队列都会被排除。这表示某些队列保留为本地队列，而不是联合。

在 federation 元素中，添加一个 transformer 元素来引用自定义转换器实现。例如：

<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">

            <include queue-match="#" address-match="queue.bbc.new" />
            <include queue-match="#" address-match="queue.usatoday" />
            <include queue-match="#" address-match="queue.news.#" />

            <exclude queue-match="#.local" address-match="#" />

        </queue-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
</federations>

name

转换器配置的名称。这个名称必须在有问题的代理中唯一。您可以将这个名称指定为地址策略的 transformer-ref 属性的值。

class-name

实施 org.apache. office.artemis.core.server.transformer.Transformer 接口的用户定义的类名称。

在传输消息之前，使用消息调用 transformer 的 transform（） 方法。这可让您在整合消息标题或正文前转换它。

属性

用于保存用于特定转换器配置的键值对。

在 联合 元素内，添加一个或多个 上游 元素。每个 上游 元素都定义了一个上游代理连接，以及应用到该连接的策略。例如：

<federations>
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <upstream name="eu-east-1">
            <static-connectors>
                <connector-ref>eu-east-connector1</connector-ref>
            </static-connectors>
            <policy ref="news-queue-federation"/>
        </upstream>

        <upstream name="eu-west-1" >
            <static-connectors>
                <connector-ref>eu-west-connector1</connector-ref>
            </static-connectors>
            <policy ref="news-queue-federation"/>
        </upstream>

        <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">

            <include queue-match="#" address-match="queue.bbc.new" />
            <include queue-match="#" address-match="queue.usatoday" />
            <include queue-match="#" address-match="queue.news.#" />

            <exclude queue-match="#.local" address-match="#" />

        </queue-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
</federations>

static-connectors: 包含一个 连接器 元素列表，它引用本地代理的 broker.xml 配置文件其他位置中定义的 连接器 元素。连接器定义了用于出站连接的传输（TCP、SSL、HTTP 等）和服务器连接参数（主机、端口等）。以下步骤演示了如何添加联合队列配置的 static-connector 元素引用的连接器。
policy-ref: 在应用到上游代理的下游代理上配置的队列策略的名称。

您可以为 上游 元素指定的附加选项如下所述：

name

上游代理配置的名称。在本例中，名称与名为 eu-east-1 和 eu-west-1 的上游代理对应。

user

创建到上游代理的连接时使用的用户名。如果没有指定，则使用在 联合 元素配置中指定的共享用户名。

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

下游和上游代理之间的单个连接可能由许多联合队列和地址消费者共享。如果代理间的连接丢失，每个联合消费者可能会尝试同时重新连接。为避免这种情况，称为 断路器 的机制将阻止消费者。当指定的超时值 elapses 时，断路器重新尝试连接。如果成功，则使用者将被取消阻塞。否则，再次应用断路器。

connection-ttl

如果联合连接停止从远程代理接收信息，则以毫秒为单位的连接会保持活跃时间。默认值为 60000。

discovery-group-ref

作为为到上游代理定义静态连接器的替代选择，此元素可用于指定已在 broker.xml 配置文件中其他位置配置的发现组。具体来说，您可以将一个现有的 discovery 组指定为此元素的 discovery-group-name 属性的值。有关发现组的更多信息，请参阅第 14.1.6 节 “代理发现方法”。

ha

指定是否为连接到上游代理启用高可用性。如果此参数的值被设置为 true，则本地代理可以连接到上游集群中的任何可用代理，并在实时上游代理关闭时自动故障切换到备份代理。默认值为 false。

initial-connect-attempts

下游代理要连接到上游代理的初始尝试次数。如果在没有建立连接的情况下达到这个值，则上游代理被视为永久离线。下游代理不再将消息路由到上游代理。默认值为 -1，这表示没有限制。

max-retry-interval

当连接到远程代理失败时，后续重新连接尝试之间的最长时间（以毫秒为单位）。默认值为 2000。

reconnect-attempts

如果连接失败，下游代理会尝试重新连接到上游代理的次数。如果在没有重新建立连接的情况下达到这个值，则上游代理被视为永久离线。下游代理不再将消息路由到上游代理。默认值为 -1，这表示没有限制。

retry-interval

如果连接到远程代理失败，则在后续的重新连接尝试之间以毫秒为单位为单位。默认值为 500。

retry-interval-multiplier

应用于 retry-interval 参数的值的倍数。默认值为：1。

share-connection

如果为同一代理同时配置了下游和上游连接，那么只要下游和上游配置都将把这个参数的值设置为 true，就可以共享同一连接。默认值为 false。

在本地代理上，将连接器添加到远程代理中。这些是在联合地址配置 的静态连接器 元素中引用的连接器。例如：

<connectors>
   <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
   <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
</connectors>

4.22.9. 配置下游队列联合

以下示例演示了如何配置下游队列联合。

借助下游队列联合，可以在一个或多个远程代理用来连接到本地代理的本地代理中添加配置。这种方法的优势在于，您可以在单个代理中保留所有联合配置。这可能是 hub 和spoke 拓扑的一个实用方法，例如：

注意

下游队列联合会反转连接与上游队列配置的方向。因此，当您在配置中添加远程代理时，这些代理被视为下游代理。下游代理使用配置中的连接信息重新连接到本地代理，该代理现在被视为上游。当您为远程代理添加配置时，本例中会对此进行说明。

先决条件

您应该熟悉上游队列联合的配置。请参阅第 4.22.8 节 “配置上游队列联合”。
以下示例演示了如何配置独立代理间的队列联邦。但是，您还应熟悉为代理 集群配置 联合的要求。更多信息请参阅第 4.22.4 节 “为代理集群配置联合”。

流程

打开 & 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">

        <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">

            <include queue-match="#" address-match="queue.bbc.new" />
            <include queue-match="#" address-match="queue.usatoday" />
            <include queue-match="#" address-match="queue.news.#" />

            <exclude queue-match="#.local" address-match="#" />

        </queue-policy>

    </federation>
  ...
</federations>

如果要在传输前转换消息，请添加转换器配置。例如：

<federations>
    ...
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="news-transformer">

            <include queue-match="#" address-match="queue.bbc.new" />
            <include queue-match="#" address-match="queue.usatoday" />
            <include queue-match="#" address-match="queue.news.#" />

            <exclude queue-match="#.local" address-match="#" />

        </queue-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
  ...
</federations>

为每个远程代理添加 downstream 项。例如：

<federations>
    ...
    <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">

        <downstream name="eu-east-1">
            <static-connectors>
                <connector-ref>eu-east-connector1</connector-ref>
            </static-connectors>
            <transport-connector-ref>netty-connector</transport-connector-ref>
            <policy ref="news-address-federation"/>
        </downstream>

        <downstream name="eu-west-1" >
            <static-connectors>
                <connector-ref>eu-west-connector1</connector-ref>
            </static-connectors>
            <transport-connector-ref>netty-connector</transport-connector-ref>
            <policy ref="news-address-federation"/>
        </downstream>

        <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">

            <include queue-match="#" address-match="queue.bbc.new" />
            <include queue-match="#" address-match="queue.usatoday" />
            <include queue-match="#" address-match="queue.news.#" />

            <exclude queue-match="#.local" address-match="#" />

        </queue-policy>

        <transformer name="news-transformer">
            <class-name>org.foo.NewsTransformer</class-name>
            <property key="key1" value="value1"/>
            <property key="key2" value="value2"/>
        </transformer>

    </federation>
  ...
</federations>

如前面的配置所示，远程代理现在被视为本地代理的下游。下游代理使用配置中的连接信息来回连接本地（即上游）代理。

在本地代理上，添加供本地和远程代理使用的连接器和接收器来建立联合连接。例如：
```
<connectors>
   <connector name="netty-connector">tcp://localhost:61616</connector>
   <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
   <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
</connectors>

<acceptors>
   <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
</acceptors>
```
连接器名称="netty-connector"
本地代理发送到远程代理的连接器配置。远程代理使用此配置连接回本地代理。
连接器名称="eu-west-1-connector" , connector name="eu-east-1-connector"
远程代理的连接器。本地代理使用这些连接器连接到远程代理，并共享远程代理所需的配置来回连接本地代理。
acceptor name="netty-acceptor"
与远程代理使用的连接器对应的本地代理中的接受者，以连接至本地代理。

4.22. 定位地址和队列

4.22.1. 关于地址联合

4.22.2. 地址联合的通用拓扑

4.22.3. 支持在地址联合配置中区分绑定

4.22.4. 为代理集群配置联合

4.22.5. 配置上游地址联合

4.22.6. 配置下游地址联合

4.22.7. 关于队列联合

4.22.7.1. 队列联合的优点

4.22.8. 配置上游队列联合

4.22.9. 配置下游队列联合

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Red Hat legal and privacy links

Red Hat legal and privacy links