RocketMQ消息队列集群搭建完整教程：从环境准备到双主双从部署

消息队列是微服务和分布式系统的核心组件之一，RocketMQ 凭借高吞吐、低延迟和强一致性深受开发者喜爱。
但真正到生产环境，单节点远远不够，必须搭建成集群才能保证可靠性和扩展性。
本文将以 双主双从（2m-2s）架构 为例，向你展示从零开始搭建 RocketMQ 集群的完整过程。

搭建前需要准备哪些环境

在动手之前，先确认好以下硬件和软件要求：

• 服务器：至少 4 台 Linux 主机（建议 CentOS 7+/Ubuntu 20.04+），每台 2 核 4GB 以上。
• JDK：RocketMQ 基于 Java 运行，必须安装 Java 8 或更高版本。通过 java -version 检查。
• RocketMQ 版本：从 Apache 官网 下载最新稳定版二进制包（当前推荐 4.9.x 或 5.x 系列）。
• 主机名与 IP 映射：在每台机器的 /etc/hosts 中添加所有节点的 IP 和主机名，避免后续通信因 DNS 解析而中断。

假设我们规划 4 台服务器：

| 角色 | 主机名 | IP 地址 |
|------|--------|---------|
| NameServer1 | ns1 | 192.168.1.10 |
| NameServer2 | ns2 | 192.168.1.11 |
| Broker-a（主） | broker-a | 192.168.1.20 |
| Broker-a（从） | broker-a-s | 192.168.1.21 |
| Broker-b（主） | broker-b | 192.168.1.22 |
| Broker-b（从） | broker-b-s | 192.168.1.23 |

如果机器有限，可以只开两台虚拟机，将 NameServer 和 Broker 混合部署，但生产环境建议分离。

一步步配置双主双从集群

1. 部署 NameServer

在所有需要运行 NameServer 的机器上执行：

# 下载并解压（以 4.9.6 为例）
wget https://dlcdn.apache.org/rocketmq/4.9.6/rocketmq-all-4.9.6-bin-release.zip
unzip rocketmq-all-4.9.6-bin-release.zip
mv rocketmq-all-4.9.6-bin-release /usr/local/rocketmq

直接使用默认配置启动 NameServer：

cd /usr/local/rocketmq/bin
nohup sh mqnamesrv > /dev/null 2>&1 &

用 tail -f ~/logs/rocketmqlogs/namesrv.log 看到 The Name Server boot success 就表示启动成功。

2. 配置 Broker 主从关系

RocketMQ 的集群模式由 broker 配置文件决定。
我们先配置第一个主节点 broker-a（IP: 192.168.1.20）。

进入 /usr/local/rocketmq/conf/2m-2s-async 目录（官方提供示例模板），复制一份配置并修改：

cp -r 2m-2s-async /usr/local/rocketmq/conf/my-cluster
cd /usr/local/rocketmq/conf/my-cluster

编辑 broker-a.properties：

# 所属集群名称
goClusterName=myRocketMQCluster
# broker 名称，主从需相同
brokerName=broker-a
# 0 表示主节点，1 表示从节点
brokerId=0
# namesrv 地址（多个用分号分隔）
namesrvAddr=192.168.1.10:9876;192.168.1.11:9876
# 持久化路径
storePathRootDir=/data/rocketmq/store
storePathCommitLog=/data/rocketmq/store/commitlog
# 绑定 IP（重要：务必将下面地址改为本机内网 IP）
brokerIP1=192.168.1.20
# 监听端口
listenPort=10911
# 异步复制模式
brokerRole=ASYNC_MASTER
# 刷盘方式
flushDiskType=ASYNC_FLUSH

对应的从节点 broker-a-s.properties（部署在 192.168.1.21）只需修改以下项：

brokerId=1
brokerIP1=192.168.1.21
brokerRole=SLAVE
listenPort=10911

同样的方法配置 broker-b 主和从节点，注意修改 brokerName=broker-b 以及 IP 地址。

3. 启动 Broker 主从

在主节点上执行：

cd /usr/local/rocketmq/bin
nohup sh mqbroker -c /usr/local/rocketmq/conf/my-cluster/broker-a.properties > /dev/null 2>&1 &

从节点同样启动，只需换成对应的配置文件路径。

启动后立即检查日志：

tail -f /root/logs/rocketmqlogs/broker.log

看到 boot success 字样即成功。

启动集群并验证是否正常工作

当所有 NameServer 和 Broker 都启动后，使用 RocketMQ 自带的工具验证。

1. 查看集群状态

任意一台机器上执行：

cd /usr/local/rocketmq/bin
sh mqadmin clusterList -n "192.168.1.10:9876;192.168.1.11:9876"

正常会列出所有主从节点及其状态状态、读写权限。

2. 测试生产和消费

编写一个简单的 Java 测试类太麻烦？
可以用官方示例：

在 Bin 目录下执行以下命令发送消息：

export NAMESRV_ADDR=192.168.1.10:9876;192.168.1.11:9876
sh tools.sh org.apache.rocketmq.example.quickstart.Producer

消费消息：

sh tools.sh org.apache.rocketmq.example.quickstart.Consumer

如果终端正常打印消息数据，则集群可用。

常见问题与避坑指南

问题1：Broker 启动时提示 No Space Left on Device

RocketMQ 默认的存储路径 /root/store 可能分区空间不足。一定要在配置前创建并挂载独立数据盘，
比如上面配置中的 /data/rocketmq/store，
并确保运行 RocketMQ 的用户有写权限。

问题2：内存占用过高导致被 OOM Killer 杀掉

默认 runbroker.sh 中的 JVM 参数（如 -Xms8g -Xmx8g）对低配机器很不友好。
修改 bin/runbroker.sh 中的参数，例如改为 -Xms1g -Xmx1g -Xmn512m。

问题3：客户端连接失败或超时

检查防火墙是否放通了 NameServer（9876）、Broker（10911 和 10909）端口。
在服务器上执行：

firewall-cmd --zone=public --add-port=9876/tcp --permanent
firewall-cmd --zone=public --add-port=10911/tcp --permanent
firewall-cmd --reload

问题4：NameServer 无法注册 Broker

t和 Nameserver 日志中频繁出现 registerBroker 失败？
确认所有机器的 /etc/hosts 中配置了正确的主机名和 IP 对应关系，并且主机名在各台机器上能互相 ping 通。

总结

本文从零开始，带大家完成了一个 RocketMQ 双主双从集群 的搭建。
核心步骤包括环境准备、NameServer 启动、Broker 主从配置、启动验证及常见排错。
如果你要正式上线，建议再加上 VIP 虚拟 IP 或负载均衡 来实现自动故障切换。
遇到任何异常时，优先检查日志文件和 clusterList 的输出，八成问题都能定位。
希望这篇教程能帮你快速上手，顺利部署自己的 RocketMQ 消息队列集群。