企业官网建设流程全解析

RabbitMQ 集群部署，说起来不算难，网上教程一搜一大把，但真正从零搭一套能扛业务、能平滑扩缩容、出问题了还能快速定位的集群，我踩过的坑真不少。尤其是最近不少人用 Docker 镜像拉一个 RabbitMQ 起来，Web 管理界面也能打开，结果 admin 账号连虚拟主机都建不了，或者节点之间始终无法通信，这些都是非常典型的问题。

这篇文章我就按实际运维的视角，从集群规划、节点部署、权限配置、MQTT 接入，到故障排查，完整过一遍 RabbitMQ 集群部署方案。全程用的都是我在生产环境验证过的操作和参数，尽量把每个“为什么这样做”都讲透，希望能帮你少走弯路。

1. 集群部署前，先把这几个概念搞清楚

1.1 RabbitMQ 集群到底解决了什么问题

先说个最基础的问题：为什么要组集群？

很多团队的 RabbitMQ 一开始就是单节点，业务量小的时候完全没问题。但一旦流量上来，或者你希望消息中间件具备高可用能力，单节点的瓶颈就很明显：进程挂了服务就断，磁盘满了消息写不进去，重启还要等一堆队列恢复。集群的价值，说白了就是三件事——高可用、横向扩展、故障转移。

高可用好理解，一个节点挂了，其他节点还能继续收发消息；横向扩展是指通过增加节点提升整体吞吐和存储能力，毕竟单机的内存和磁盘终归有限；故障转移则是客户端连接断开后，能自动重连到其他存活节点，尽量让业务无感知。

这里也顺带回答一个经常被问到的问题：和 Kafka 比，什么时候该选 RabbitMQ？我个人看法是，如果你的场景是高性能日志管道、海量流式数据、分区顺序保证，优先考虑 Kafka；而如果业务上是复杂的路由规则、延时消息、RPC 回调、需要精细确认机制的任务分发，RabbitMQ 的灵活性和生态更合适。集群方案没有绝对优劣，匹配业务才是关键。

1.2 磁盘节点与内存节点，你怎么选

RabbitMQ 的节点分为磁盘节点和内存节点两种。很多初次搭建集群的人根本不看这个，所有节点都默认启动成磁盘节点，其实也没毛病。但如果你的集群规模超过三节点，或者你希望某些节点承担更高吞吐，就需要理解这两者的区别。

磁盘节点会把队列元数据、交换机、绑定关系、用户权限等信息持久化到磁盘，内存节点则只把元数据保存在内存里，性能上确实有优势，但一重启，内存节点上的元数据就会丢失。注意，内存节点只会丢弃元数据，不会丢消息本身，但节点重启后会尝试从磁盘节点同步元数据。问题是：如果整个集群里所有的磁盘节点都挂了，内存节点也活不下去。

所以我的建议很直接：生产环境所有节点都用磁盘节点，不要为了那点性能去用内存节点。理由很简单，元数据在 RabbitMQ 里本质上量很小，哪怕是几千个交换机、队列、绑定关系，也就是几 MB 到几十 MB 的规模，内存节点的性能优势微乎其微。你省下的那点性能，远不够赔偿一次元数据丢失带来的运维成本。

队列层面的选型也要注意。RabbitMQ 的经典队列如果要做高可用，需要配置镜像队列（Mirrored Queue），主从节点之间同步全量消息，性能损耗明显。而新版本的 Quorum Queue（基于 Raft 协议）在一致性、数据安全上更好，是官方推荐的替代方案。如果你们用的 RabbitMQ 版本在 3.8 以上，新项目建议直接用 Quorum Queue，别再用镜像队列了。

提示：集群节点自身的角色（磁盘/内存）与队列类型（经典/Quorum）是两套概念，不要混淆。节点角色管的是元数据存储方式，队列类型管的是消息数据的复制策略。

2. 集群前置准备与部署方案选型

2.1 直接用二进制包部署，还是上 Docker

这是很多人纠结的第一个问题。先给结论：没有绝对答案，看你的环境和管理习惯。

如果你们公司是有专门运维团队的，服务器上跑了一堆 Java、Tomcat，那用官方二进制包部署最干净，可控性最强。如果你想快速拉起一套环境做测试，或者你们本身就已经全面容器化了，那用 Docker 部署会省心很多。

不过要注意，Docker 部署 RabbitMQ 集群最大的坑就是.erlang.cookie和节点名的解析。容器默认的 hostname 每次创建都可能变，节点间的通信会受影响。所以用 Docker 部署集群时，一定要显式指定 hostname，并挂载或手动指定 cookie 文件。

这里我不做“谁好谁坏”的结论，下面两章我会分别给出原生部署和 Docker Compose 部署两套完整流程，你按自己的场景选一套就行。

2.2 主机规划、端口清单与文件目录

假设你准备搭建一个三节点集群，我先给一份比较标准的主机规划，后续所有操作都以这三台为例：

RabbitMQ 涉及的端口不少，规划时记得在防火墙和安全组里提前放行：

• 4369：Erlang 端口映射守护进程（epmd）使用
• 5672：AMQP 主端口，客户端连接用
• 15672：Web 管理界面端口
• 25672：集群节点间通信端口
• 1883：MQTT 插件开启后的默认端口
• 15675：Web MQTT 端口（如果启用）

提示：实际生产环境最好做一个端口用途清单，避免后期排查时自己都分不清哪个端口是干嘛的。特别是 25672 容易被忽略，节点间通信不通大多数时候就是它没放行。

文件层面，二进制部署时会用到几个关键路径：

• /etc/rabbitmq/rabbitmq.conf：主配置文件
• /etc/rabbitmq/enabled_plugins：启用的插件列表
• /etc/rabbitmq/.erlang.cookie：集群通信的共享密钥
• /var/log/rabbitmq/：日志目录

2.3 .erlang.cookie 与节点名，决定集群能不能拉起的关键

RabbitMQ 节点间的通信依赖 Erlang 分布式架构，而 Erlang 分布式节点要互相认证，靠的就是.erlang.cookie。这个文件里面就是一行字符串，相当于集群节点间的“共享密码”。集群里所有节点的 cookie 必须完全一致，哪怕差一个字符，节点都无法加入集群。

还有一个容易被忽略的细节：节点的 hostname 解析。RabbitMQ 启动时会将主机名解析成完整的 Erlang 节点名，比如rabbit@node1。如果/etc/hosts里没有把node1映射到对应 IP，或者 DNS 解析有问题，节点之间互相找不到，集群就拉不起来。

所以搭建集群前，我建议三台机器都配置好/etc/hosts，比如：

192.168.1.11 node1 192.168.1.12 node2 192.168.1.13 node3

这两件事看起来基础，但实际排查中发现，cookie 不一致和hosts 配置错误占到了集群拉起失败原因的七八成。

3. 三节点集群原生部署实操（CentOS / Ubuntu 通用）

3.1 安装 Erlang 与 RabbitMQ Server

RabbitMQ 依赖于 Erlang 环境，版本必须匹配。官方有一个兼容性列表，比如 RabbitMQ 3.13.x 对应 Erlang 26.x。这里以 Ubuntu 22.04 / CentOS 7 为例，最简单的方式是添加官方仓库：

# Ubuntu / Debian curl -fsSL https://github.com/rabbitmq/signing-keys/releases/download/2.0/rabbitmq-release-signing-key.asc | sudo apt-key add - echo "deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/rabbitmq.list sudo apt update sudo apt install -y erlang rabbitmq-server

CentOS 用 rpm 包安装时，我建议提前把socat、logrotate等依赖装好，不然启动时会报错。装完先不急着启动，先把集群要用的 cookie 和 hosts 配好。

3.2 配置 cookie、hosts 与 rabbitmq.conf

三台节点都执行以下操作：

# 1. 设置 hostname sudo hostnamectl set-hostname node1 # node2、node3 分别是 node2、node3 # 2. 配置 hosts cat >> /etc/hosts <<EOF 192.168.1.11 node1 192.168.1.12 node2 192.168.1.13 node3 EOF # 3. 生成一致的 cookie（先在 node1 生成，再复制到 node2/node3） sudo mkdir -p /etc/rabbitmq echo "MY-SECURE-COOKIE-STRING-2024" | sudo tee /etc/rabbitmq/.erlang.cookie sudo chown rabbitmq:rabbitmq /etc/rabbitmq/.erlang.cookie sudo chmod 400 /etc/rabbitmq/.erlang.cookie

注意，.erlang.cookie权限必须设置成 400 或 600，属主必须是运行 RabbitMQ 的用户（一般是rabbitmq）。如果权限不对，Erlang 会直接拒绝使用这个文件，表现为节点无法启动。

主配置文件写这些内容（三台节点都一样）：

cat > /etc/rabbitmq/rabbitmq.conf <<EOF listeners.tcp.default = 5672 management.tcp.port = 15672 cluster_formation.peer_discovery_backend = classic_config cluster_formation.classic_config.nodes.1 = rabbit@node1 cluster_formation.classic_config.nodes.2 = rabbit@node2 cluster_formation.classic_config.nodes.3 = rabbit@node3 EOF

cluster_formation这一段是让 RabbitMQ 在启动时自动发现集群节点，填上全部节点名即可。具体原理后续会讲。

3.3 启动第一个节点并初始化集群

第一台节点不要急着加集群，它负责创建最初的集群元数据：

sudo systemctl start rabbitmq-server sudo systemctl enable rabbitmq-server sudo rabbitmqctl cluster_status

看到Disk Nodes里有rabbit@node1，说明第一个节点已经正常以磁盘节点身份运作了。

接着在 node2 上执行：

sudo systemctl start rabbitmq-server sudo rabbitmqctl stop_app sudo rabbitmqctl join_cluster rabbit@node1 sudo rabbitmqctl start_app

stop_app的意思是只停止 RabbitMQ 应用，而不是停掉 Erlang 虚拟机，这样节点才能以空的状态加入集群。join_cluster rabbit@node1指定要加入的现有集群节点。默认加入后就是磁盘节点，如果你希望它以内存节点加入，可以加--ram参数，但我前面说了，生产环境不建议。

node3 重复同样的操作。全部完成后，随便挑一个节点执行：

sudo rabbitmqctl cluster_status

输出里应该能看到三个节点都列出来了，而且每个节点的分区健全。执行rabbitmqctl list_cluster_nodes能看到节点类型。

心得：加入集群时如果卡住不动，99% 是 cookie 或 hosts 配置问题。可以先看/var/log/rabbitmq/下节点的启动日志，里面会明确告诉你哪个节点连接失败。

3.4 配置镜像队列与 Quorum Queue 策略

集群建好之后，默认的经典队列并不会自动做高可用。对经典队列而言，需要手动配置镜像策略，否则消息只会存储在单个节点上。

用管理命令添加策略：

sudo rabbitmqctl set_policy ha-all "^" '{"ha-mode":"all","ha-sync-mode":"automatic"}'

这条命令的意思是对所有名称匹配^（即全部队列）的队列启用镜像模式，副本分布到所有节点，同步方式为自动。

但如果你用的是 Quorum Queue，不需要配置镜像策略，因为它是天然复制到多节点的，你只需要在声明队列时指定类型：

rabbitmqadmin declare queue name=q.queue durable=true arguments='{"x-queue-type":"quorum"}'

从实际生产经验看，Quorum Queue 在节点故障恢复时的表现确实更稳定，我建议新项目优先采用。经典队列 + 镜像策略这种组合，适合老项目里已经被大量使用的场景，迁移成本太大时才保留。

4. Docker Compose 部署集群，以及那个让人头大的 admin 账号权限问题

4.1 用 Docker Compose 拉起三节点集群

如果你更习惯容器化部署，这里给一份可以直接用的docker-compose.yml。需要注意的是，每个容器必须显式设置hostname，并且把.erlang.cookie统一挂载进去，否则集群节点间无法通信。

version: '3.8' services: rabbit1: image: rabbitmq:3.13-management hostname: rabbit1 container_name: rabbit1 environment: - RABBITMQ_ERLANG_COOKIE=SECRET_COOKIE_VALUE - RABBITMQ_NODENAME=rabbit@rabbit1 ports: - "5672:5672" - "15672:15672" volumes: - rabbit1_data:/var/lib/rabbitmq networks: - rabbitnet rabbit2: image: rabbitmq:3.13-management hostname: rabbit2 container_name: rabbit2 environment: - RABBITMQ_ERLANG_COOKIE=SECRET_COOKIE_VALUE - RABBITMQ_NODENAME=rabbit@rabbit2 ports: - "5673:5672" - "15673:15672" volumes: - rabbit2_data:/var/lib/rabbitmq networks: - rabbitnet depends_on: - rabbit1 rabbit3: image: rabbitmq:3.13-management hostname: rabbit3 container_name: rabbit3 environment: - RABBITMQ_ERLANG_COOKIE=SECRET_COOKIE_VALUE - RABBITMQ_NODENAME=rabbit@rabbit3 ports: - "5674:5672" - "15674:15672" volumes: - rabbit3_data:/var/lib/rabbitmq networks: - rabbitnet depends_on: - rabbit1 volumes: rabbit1_data: rabbit2_data: rabbit3_data: networks: rabbitnet: driver: bridge

启动后，进入 rabbit1 容器，把 rabbit2 和 rabbit3 加入集群：

docker exec -it rabbit2 rabbitmqctl stop_app docker exec -it rabbit2 rabbitmqctl join_cluster rabbit@rabbit1 docker exec -it rabbit2 rabbitmqctl start_app docker exec -it rabbit3 rabbitmqctl stop_app docker exec -it rabbit3 rabbitmqctl join_cluster rabbit@rabbit1 docker exec -it rabbit3 rabbitmqctl start_app

4.2 为什么 Docker 部署后，admin 账号还是不能创建虚拟主机

这是热词里出现频率最高的问题：管理界面打开了，用 admin 用户登进去，点Virtual Hosts那边却无法创建新的虚拟主机。这是为什么？

关键在于 RabbitMQ 的用户权限模型：用户能不能创建虚拟主机，不看你是不是 admin，而是看你有没有administrator标签，并且是否对目标虚拟主机有配置权限。

Docker 官方镜像默认会创建一个用户，这个用户的信息由环境变量决定，例如：

environment: - RABBITMQ_DEFAULT_USER=admin - RABBITMQ_DEFAULT_PASS=admin123 - RABBITMQ_DEFAULT_VHOST=/

如果你只设置了默认用户和密码，没有给用户打administrator标签，那么即使你能登录 Web 管理界面，也只能看到和操作自己有权限的虚拟主机，而没有管理全局的权限。这也是为什么很多人觉得“管理界面能用，但 admin 什么都干不了”。

所以，Docker Compose 的环境变量里，在一开始就要把用户权限打满：

environment: - RABBITMQ_DEFAULT_USER=admin - RABBITMQ_DEFAULT_PASS=admin123 - RABBITMQ_DEFAULT_VHOST=/ - RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS=-rabbitmq_management load_definitions "/etc/rabbitmq/definitions.json"

但这种做法需要在容器启动时加载一份定义文件，对快速验证来说略麻烦。更直接的办法是容器起来之后，用命令手动处理：

# 进入容器 docker exec -it rabbit1 bash # 创建虚拟主机（如果你不想用默认的 /） rabbitmqctl add_vhost myvhost # 设置用户为 administrator 标签 rabbitmqctl set_user_tags admin administrator # 给用户在指定 vhost 上授予全部权限 rabbitmqctl set_permissions -p "/" admin ".*" ".*" ".*" rabbitmqctl set_permissions -p "myvhost" admin ".*" ".*" ".*"

关于权限的三个正则：

• 第一个.*：允许配置（交换机、队列的创建删除）
• 第二个.*：允许写入（发送消息）
• 第三个.*：允许读取（消费消息）

如果你只给了一部分权限，比如只给写不读，那客户端能发消息但收不到消息，排查时会非常困惑。

4.3 通过 Web 管理界面验证权限配置

配置完成后，重启 RabbitMQ 应用（或者等几秒让权限策略生效），重新登录 Web 管理界面。此时在Admin标签页里能看到用户列表，点击自己的账号，确认Tags中包含administrator。然后在Virtual Hosts标签页里，应该能看到/和myvhost都在列表里，且后面有权限标志。

这里有个经验：不要过度依赖 Web 界面做权限管理。Web 界面适合查看，批量操作和精确配置用rabbitmqctl比在界面上点来点去高效得多，也更容易写进自动化脚本。我自己管理集群时，用户和权限的增改基本都是命令行一把梭，Web 界面只看监控和队列状态。

5. MQTT 插件开启，以及集群的对外负载均衡

5.1 启用 MQTT 插件并用 MqttX 连接

RabbitMQ 不仅可以做 AMQP 消息中间件，还可以直接当 MQTT Broker 用，这对物联网场景特别友好。开启方式：

# 原生部署 sudo rabbitmq-plugins enable rabbitmq_mqtt rabbitmq_web_mqtt # Docker 部署 docker exec -it rabbit1 rabbitmq-plugins enable rabbitmq_mqtt rabbitmq_web_mqtt

开启后，默认监听1883端口，15675端口用于 WebSocket 方式接入。如果你要用 MqttX 测试连接，填这几项就可以：

• Host:192.168.1.11
• Port:1883
• Username:mqtt_user
• Password:mqtt_pass

注意，MQTT 连接同样受权限控制。如果mqtt_user没有在对应 vhost 上的写读权限，连接虽然能建立，但发布或订阅会直接被拒绝。所以创建 MQTT 用户后，一定要执行：

rabbitmqctl add_user mqtt_user mqtt_pass rabbitmqctl set_user_tags mqtt_user management rabbitmqctl set_permissions -p "/" mqtt_user ".*" ".*" ".*"

MqttX 连接成功的前提，就是这三行命令都正确。

5.2 三节点前加一层负载均衡，客户端该连谁

集群搭建好之后，客户端不能写死连某一个节点的 IP，否则这个节点挂了，客户端不会自动切换。生产环境我建议在前面加一层负载均衡，最简单的就是 HAProxy。

HAProxy 配置里，关键是做四层 TCP 代理，并启用对节点端口的健康检查：

frontend rabbitmq_front bind *:5672 mode tcp default_backend rabbitmq_nodes backend rabbitmq_nodes mode tcp balance roundrobin option tcp-check server rabbit1 192.168.1.11:5672 check inter 3s fall 2 rise 2 server rabbit2 192.168.1.12:5672 check inter 3s fall 2 rise 2 server rabbit3 192.168.1.13:5672 check inter 3s fall 2 rise 2

客户端只需要连接 HAProxy 的 5672 端口，后面任何一个 RabbitMQ 节点挂了，HAProxy 的check会发现后端不可用，自动把流量导到其他存活节点。inter 3s表示每 3 秒探测一次，fall 2表示连续失败 2 次标记为下线。

5.3 集群节点的故障转移与脑裂处理

集群节点之间的网络如果出现分区，RabbitMQ 会进入网络分区状态。默认配置下，分区恢复后集群会自动处理，但可能出现某些节点被踢出集群并拒绝重新加入的情况。

处理方式有两种：

• 重启被分区的节点，让它重新加入集群
• 如果节点状态很乱，先rabbitmqctl stop_app，然后rabbitmqctl reset，再重新join_cluster和start_app

关于脑裂的预防，核心是网络质量。RabbitMQ 集群本身对网络抖动比较敏感，建议集群节点都放在同一机房或同一 VPC 内，节点间走内网，不要跨公网组集群。跨地域的场景应该用 Federation 或 Shovel 插件做消息转发，而不是直接一个集群打天下。

6. 高频问题排查与避坑速查

这部分我把热词里那些典型的坑整理成表格，按“现象-原因-解法”的方式写清楚。

这里再单独强调两个细节。

第一个是 Windows 上的 RabbitMQ。很多人在本地开发环境用 Windows 装 RabbitMQ，总在服务启动阶段翻车。踩过几次坑之后，我的经验是两个：一是要去官网查清楚当前 RabbitMQ 版本依赖的 Erlang 版本，不要随便装最新版 Erlang，版本不对服务起不来；二是安装路径和工作目录不要出现中文、空格，最好直接用C:\RabbitMQ这种简单路径。装完之后用管理员权限打开命令行执行rabbitmq-service.bat start，不成功就去看%APPDATA%\RabbitMQ\log\下的启动日志。

第二个是关于管理界面显示“不能连接到服务器”的情况。这个在 Docker 镜像里特别容易出现，因为容器里rabbitmqctl默认会去连名为rabbit@<hostname>的节点，但如果你在环境变量里设置了RABBITMQ_NODENAME，名称不匹配，rabbitmqctl就找不到节点了。解决办法是执行rabbitmqctl时加上-n参数指定节点名，或者直接用容器里默认的节点名，不要随意修改。

7. 集群部署完成后，还需要做这几件事

集群能跑起来只是第一步。按我个人的经验，部署完成后一定要做一轮“验收测试”，确认高可用能力真的有效，而不是纸面上看起来是集群。

第一件事，验证节点故障转移。挑一个节点直接停掉，看客户端是否能在短时间内自动重连到其他节点。你可以用一个简单的生产者消费者脚本压一会儿，观察停节点期间消息是否丢失、消费是否有明显中断。如果中断时间过长，检查一下客户端的重连机制和连接工厂配置，确认automatic recovery已开启，并且连接地址配置了多个节点或负载均衡。

第二件事，确认消息堆积和队列同步情况。向集群发送一批消息，然后执行rabbitmqctl list_queues name messages messages_ready messages_unacknowledged，观察队列在各节点上的分布。对于 Quorum Queue，可以查看rabbitmqctl list_quorum_queue_stats，确认所有队列的leader和online状态都健康。

第三件事，监控要跟上。RabbitMQ 官方提供了rabbitmq-prometheus插件，开启后暴露 15692 端口，Prometheus 可以直接抓取指标。我的建议是至少把以下指标接入告警：

• 节点可用性
• 队列消息堆积数量
• 连接数
• 文件描述符使用率
• 内存使用率
• 磁盘剩余空间

告警阈值没有统一标准，但有一个原则：磁盘快满和高水位内存一定要提前告警，别等到消息写不进去才去处理。

第四件事，做好备份。RabbitMQ 的元数据（用户、虚拟主机、策略、绑定关系）可以通过rabbitmqctl export_definitions导出成 JSON 文件，建议定期备份。消息数据则依赖节点存储，靠队列副本机制保证安全。

心得：很多团队把集群搭起来就以为万事大吉，实际上节点故障、网络抖动、客户端异常重连，每一个环节都可能暴露问题。我见过最惨的事故不是节点全挂，而是磁盘节点先挂、内存节点随后也挂，整个集群元数据全丢。所以磁盘节点的作用再怎么强调也不过分。

8. 最后分享一点个人经验

关于 RabbitMQ 集群部署，我最后再说两个实际操作中得到的经验。

第一个是关于升级策略。RabbitMQ 集群不支持跨大版本热升级，比如 3.12 升 3.13 没问题，但 3.12 跳到 4.0 就很可能不兼容。升级时要采用“滚动升级”的思路：先升级一个节点，确认集群状态正常，再依次升级其他节点。升级前一定要先备份配置和元数据，并且千万不能同时升级 Erlang 和 RabbitMQ 两个东西，否则出了问题你根本不知道是谁导致的。

第二个是关于“能简单就别复杂”。如果你只有两三台机器，业务量也不算大，真没必要把集群方案设计得特别复杂。我曾经见过有人用虚拟机搭了五个 RabbitMQ 节点，还做了跨机房的镜像，结果日常运维成本高得离谱，最后又降配回三节点。集群规模应该从业务需求反推，而不是为了“看起来高可用”盲目堆节点。

希望这篇 RabbitMQ 集群部署方案能帮到你。如果你刚接触集群，建议先在两台机器上完整走一遍原生部署流程，再试 Docker 部署，等把两种方法的差异和坑都摸清了，再去谈生产环境的高可用和自动化运维。