消息队列 / 系统课时
Federation 联邦连接
Federation 联邦连接
Federation 用于通过异步 AMQP 链路连接彼此独立的 RabbitMQ 集群,而不是合并为一个集群。本课用最小交换机联邦示例完成插件、Upstream、Policy 和链路验证,并说明何时使用队列联邦。
学习目标
- 区分 Exchange Federation 与 Queue Federation 的消息语义
- 配置一个远端 Upstream,并用 Policy 选择需要联邦的资源
- 通过 Federation Link 状态验证跨集群连接并定位常见故障
先选交换机联邦还是队列联邦
Federation 的方向从下游连接到上游:下游主动建立 Federation Link,从上游获取消息。两个集群仍保留独立的用户、虚拟主机、拓扑和生命周期,因此远端链路中断不会把两个集群的本地可用性绑在一起。

| 方式 | 核心行为 | 常见用途 |
|---|---|---|
| Exchange Federation | 将上游交换机的消息流异步复制到下游交换机 | 跨区域事件分发、数据汇聚、灾备侧订阅 |
| Queue Federation | 当本地消费者需要消息时,从上游队列按需移动消息 | 多站点共享工作队列、按消费能力调节消息位置 |
Exchange Federation 更像“把事件流带到另一个站点”,Queue Federation 更像“把待消费消息搬到有消费需求的位置”。队列联邦不是 Quorum Queue 的跨集群副本机制,也不提供 Raft 一致性语义。
启用 Federation 插件
在需要建立 Federation Link 的下游集群所有节点启用 rabbitmq_federation。如果还要通过 Management UI 查看和管理联邦状态,再启用 rabbitmq_federation_management;若两个集群需要双向联邦,则双方都要按各自的下游角色配置。
rabbitmq-plugins enable rabbitmq_federation
rabbitmq-plugins enable rabbitmq_federation_management预期输出
rabbitmq_federation 处于 enabled 状态;
rabbitmq_federation_management 处于 enabled 状态。
已启用插件时命令会保持现有状态。生产环境应为 Federation 使用独立账号、最小权限和 TLS。Upstream URI 中的凭据不要长期明文保存在 Shell 历史或自动化日志里。
定义 Upstream 和匹配策略
下面在下游集群的默认虚拟主机 / 中定义名为 east 的 Upstream,再让本地交换机 orders.events 使用它。示例假设上游可以通过 east-rmq.example.com 访问,并且上下游已经声明了需要的交换机与本地绑定。
rabbitmqctl -p "/" set_parameter federation-upstream east '{"uri":"amqps://federation:<PASSWORD>@east-rmq.example.com/%2f"}'
rabbitmqctl -p "/" set_policy federate-orders '^orders\.events$' '{"federation-upstream":"east"}' --apply-to exchanges预期结果
默认虚拟主机中出现名为 east 的 federation-upstream 参数;
名为 federate-orders 的策略匹配 orders.events,并应用到 exchanges;
匹配资源建立 Federation Link 后才会开始跨集群传输。Upstream 负责“去哪里、怎样连接”,Policy 负责“哪些本地交换机或队列要使用这个 Upstream”。同一个虚拟主机可以定义多个 Upstream,也可以用 Upstream Set 将多个远端组合起来,但一个 Policy 不应同时设置 federation-upstream 与 federation-upstream-set。
如果改做 Queue Federation,Upstream 定义方式相同,但 Policy 应匹配队列并使用 --apply-to queues。不要为了“更可靠”同时对同一业务链路叠加 Exchange Federation 与 Queue Federation,否则消息复制和移动的组合可能产生难以预期的重复与路径。
验证 Federation Link
只有 Upstream 存在、Policy 确实匹配资源,并且下游能够认证并连接上游时,Federation Link 才会进入运行状态。先在下游节点查看链路状态。
rabbitmqctl federation_status预期输出
状态中可看到对应 link 的 type、name、vhost、upstream_name 和 status;
本例应出现 orders.events、east,并且 status 为 running。
具体 Erlang 格式、连接名和时间戳会因环境不同。Exchange Federation 会根据下游绑定需求在上游侧维护内部队列并异步转发消息。因此新增或删除绑定不是跨 WAN 的强同步操作,变化需要时间传播。链路短暂中断后可以重连并继续处理仍在上游缓冲范围内的消息,但跨区域延迟与积压恢复速度仍受网络和磁盘吞吐影响。
链路不起来时按层排查
排障时不要先删除 Policy 重配一遍。按“参数是否存在 → Policy 是否命中 → 网络与认证 → Federation 状态与节点日志”的顺序定位,能快速区分配置错误和远端不可达。
rabbitmq-diagnostics list_parameters --formatter=pretty_table
rabbitmqctl list_policies
rabbitmqctl federation_status --only-down预期结果
参数列表中能找到目标 federation-upstream;
策略列表中能找到匹配目标 exchange 或 queue 的 Federation Policy;
如果存在异常链路,--only-down 只列出未运行的 Federation Link。最常见的失败包括虚拟主机路径不一致、账号无权限、TLS 证书校验失败、Policy 正则没有命中资源,以及多个 Policy 竞争导致 Federation Policy 没有成为有效策略。把这些层次逐一排除后,再考虑重启单条 Federation Link,而不是直接重启整个集群。
Federation 适合跨 WAN、跨管理域的松耦合消息传输;如果目标是同一局域网内的统一元数据与 Raft 副本一致性,应使用 RabbitMQ Cluster;如果目标是无条件、明确方向地搬运消息,则通常应评估 Shovel。