环境准备：

项 要求
操作系统 Linux（CentOS 7+ / Ubuntu 16+），开发环境也可用 Windows/Mac
JDK 1.8+，推荐 1.8
内存 开发环境最低 2C4G
磁盘 50GB+
部署步骤：

1. 下载并解压

wget https://archive.apache.org/dist/rocketmq/5.0.0/rocketmq-all-5.0.0-bin-release.zip
unzip rocketmq-all-5.0.0-bin-release.zip
cd rocketmq-all-5.0.0-bin-release

2. 启动 NameServer（默认端口 9876）

nohup sh bin/mqnamesrv &

3. 启动 Broker（连接到 NameServer）

nohup sh bin/mqbroker -n localhost:9876 &

4. 验证是否启动成功

sh bin/mqadmin clusterList -n localhost:9876
JVM 参数调整（bin/runserver.sh 和 bin/runbroker.sh）：

NameServer 轻量级，2GB 堆内存足够；Broker 建议根据机器配置调整：

runbroker.sh 中的 JVM 配置示例（8GB 堆内存）

JAVA_OPT=“${JAVA_OPT} -server -Xms8g -Xmx8g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m”
单机部署架构

发消息

拉消息

获取路由

获取路由

注册

NameServer
端口 9876

Producer

Broker
端口 10911

Consumer

⚠️ 仅适用于开发/测试环境
存在单点故障风险

💡 小贴士：NameServer 和 Broker 默认的 JVM 参数（-Xms4g -Xmx4g）在低配机器上可能启动失败，需要根据实际内存调小。

多 NameServer 部署
NameServer 是 RocketMQ 的“注册中心”，它的高可用直接决定了集群的可用性。

为什么 NameServer 要部署多个？

NameServer 的设计非常巧妙——节点之间完全无状态、不需要数据同步。所有的路由信息都是由 Broker 主动上报构建的。

这就意味着：你只要多启动几个 NameServer 实例，客户端配置上所有地址，任何一个 NameServer 挂掉都不影响服务。

部署方式：

在 3 台机器上分别启动 NameServer

机器 A: 192.168.1.10

nohup sh bin/mqnamesrv &

机器 B: 192.168.1.11

nohup sh bin/mqnamesrv &

机器 C: 192.168.1.12

nohup sh bin/mqnamesrv &
客户端配置：

// Producer 和 Consumer 配置多个 NameServer 地址
producer.setNamesrvAddr(“192.168.1.10:9876;192.168.1.11:9876;192.168.1.12:9876”);
Broker 集群

客户端

NameServer 集群 - 无状态

连接任意一个

连接任意一个

注册到所有

注册到所有

注册到所有

NameServer 1
192.168.1.10

NameServer 2
192.168.1.11

NameServer 3
192.168.1.12

Producer

Consumer

Broker Master A

✅ 任意一个 NameServer 宕机
其他节点仍可正常服务

NameServer 资源配置建议：

配置项 建议值
CPU 2 核（x86_64），主频 ≥ 2.4GHz
内存 4GB（实际使用约 500MB）
磁盘 50GB SSD（存储日志，日志轮转周期建议 7 天）
JVM 堆内存 2GB
Broker 主从集群部署（Master-Slave）
生产环境的标配是 多 Master 多 Slave 架构。

集群规划示例（双主双从）：

节点 角色 IP 端口
Broker-A-M Master 192.168.1.20 10911
Broker-A-S Slave 192.168.1.21 10911
Broker-B-M Master 192.168.1.22 10911
Broker-B-S Slave 192.168.1.23 10911
配置文件示例（broker-a-m.conf）：

集群名称

brokerClusterName = rocketmq-cluster

Broker 名称（主从配对使用相同名称）

brokerName = broker-a

Broker ID：0 表示 Master，>0 表示 Slave

brokerId = 0

NameServer 地址

namesrvAddr = 192.168.1.10:9876;192.168.1.11:9876;192.168.1.12:9876

存储路径

storePathRootDir = /data/rocketmq/store

消息保留时间（72 小时）

fileReservedTime = 72

刷盘策略：SYNC_FLUSH / ASYNC_FLUSH

flushDiskType = ASYNC_FLUSH

复制策略：SYNC_MASTER / ASYNC_MASTER

brokerRole = ASYNC_MASTER
Slave 配置（broker-a-s.conf）只需修改 brokerId = 1 和存储路径。

客户端

写入

写入

拉取

拉取

主从复制架构

Broker 组 B

Broker 组 A

同步/异步复制

同步/异步复制

Master B
brokerId=0
可读写

Master A
brokerId=0
可读写

Slave A
brokerId=1
只读

Slave B
brokerId=1
只读

Producer

Consumer

启动命令：

先启动所有 NameServer，再启动 Broker

nohup sh bin/mqbroker -c conf/broker-a-m.conf &
nohup sh bin/mqbroker -c conf/broker-a-s.conf &
nohup sh bin/mqbroker -c conf/broker-b-m.conf &
nohup sh bin/mqbroker -c conf/broker-b-s.conf &
Dledger 高可用集群部署与自动切换
传统主从架构有一个痛点：Master 宕机后需要人工切换。Dledger 解决了这个问题——基于 Raft 协议实现自动故障切换。

Dledger 的核心机制：

一个 Dledger Group 至少需要 3 个节点（遵循 2n+1 原则，容忍 1 个节点宕机）
通过 Raft 协议自动选举出一个 Leader，其余为 Follower
Leader 和 Follower 之间复制数据，保证高可用
RocketMQ 5.x 的 Dledger Controller 模式：

RocketMQ 5.0 引入了 Controller 组件来增强自动切换能力。Controller 可以独立部署，也可以嵌入 NameServer 部署。

Broker 副本组 - 三节点

Controller 集群 - 三副本

复制

复制

选主/心跳

选主/心跳

选主/心跳

Controller 1

Controller 2

Controller 3

Leader
处理读写

Follower 1
数据备份

Follower 2
数据备份

✅ Leader 宕机后
Controller 协调选举新 Leader
自动切换，无需人工干预

Controller 嵌入 NameServer 的配置：

namesrv.conf

enableControllerInNamesrv = true
controllerDLegerGroup = group1
controllerDLegerPeers = n0-127.0.0.1:9877;n1-127.0.0.1:9878;n2-127.0.0.1:9879
controllerDLegerSelfId = n0
controllerStorePath = /home/admin/DledgerController
enableElectUncleanMaster = false
Broker 开启 Controller 模式：

broker.conf

enableControllerMode = true
controllerAddr = 127.0.0.1:9877;127.0.0.1:9878;127.0.0.1:9879
💡 小贴士：Dledger Group 至少需要 3 个节点才能实现容灾切换。2 节点部署会丧失自动切换能力。

多机房多活部署方案
对于需要异地容灾或单元化架构的场景，多机房多活是必备能力。

方案一：单集群跨机房部署：

同一个 RocketMQ 集群的 Broker 分布在多个机房
每一对主从 Broker 分别部署在不同机房
尽量让两个机房的 Master 数量均衡（如 1:2 或 2:2）
客户端

机房 B

机房 A

同步复制

同步复制

就近写入

就近写入

Master A

Slave B

Master B

Slave A

Producer

✅ 单个机房故障
另一个机房的 Master 仍可提供服务
⚠️ 跨机房网络延迟是瓶颈

方案二：双集群异地双活：

两个独立的 RocketMQ 集群分别部署在两个机房
通过 Global Replicator 实现跨集群数据同步
平时业务写入各自机房的集群，一个机房故障时切换流量
支持双向同步，实现真正的“双活”
方案 优点 缺点 适用场景
单集群跨机房 部署简单，数据一致 跨机房延迟高 同城双机房
双集群双活 延迟低，可用性高 部署复杂，可能有数据冲突 异地容灾、单元化
NameServer 与 Broker 的资源配置建议
硬件配置核心原则：

垂直扩展优先：单节点性能不足时优先升级硬件，而非盲目增加节点
资源隔离：Broker、NameServer、监控组件部署在不同机器或容器中
弹性预留：生产环境预留 20%-30% 的硬件资源应对突发流量
各组件配置建议：

组件 场景 CPU 内存 磁盘
NameServer 通用 2 核 4GB（堆 2GB） 50GB SSD
Broker 普通消息 8 核 16GB（堆 8GB） NVMe SSD，IOPS≥50K
Broker 高吞吐（10 万+/s） 16 核 32GB（堆 12GB） RAID10 阵列（4 块 NVMe SSD）
Broker Slave 同步复制 12 核 16GB 不低于 Master
内存分配的关键原则：

堆内存占比不超过 60%（单节点堆内存 ≤ 32GB，避免 GC 停顿过长）
剩余内存用于 PageCache 加速磁盘 IO
启用 transientStorePoolEnable=true 和堆外内存池
JVM 参数调优与内存配置
NameServer JVM 参数：

JAVA_OPT=“${JAVA_OPT} -server -Xms2g -Xmx2g -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=320m”
Broker JVM 参数（16GB 内存机器）：

JAVA_OPT=“$JAV{A}_{O}PT-server-Xms8g-Xmx8g-XX:MetaspaceSize=256m-XX:MaxMetaspaceSize=512m"JAV{A}_{O}PT="${JAVA_OPT} -XX:+UseG1GC -XX:G1HeapRegionSize=16m -XX:G1ReservePercent=25”
JAVA_OPT=“${JAVA_OPT} -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35”
关键 JVM 参数说明：

参数 建议值 说明
-Xms / -Xmx 堆内存的 50%-60% 不超过 32GB，避免 GC 停顿
GC 算法 G1GC 适合大堆内存，停顿可控
-XX:MaxGCPauseMillis 20ms 控制 GC 停顿时间
堆外内存 剩余内存用于 PageCache 加速消息读写
RocketMQ 操作命令大全（mqadmin）
mqadmin 是 RocketMQ 最强大的运维工具。几乎所有命令都需要 -n 指定 NameServer 地址。

常用命令分类：

Topic 管理：

命令 用途 示例
updateTopic 创建/更新 Topic ./mqadmin updateTopic -n 127.0.0.1:9876 -t order_topic -b 192.168.1.20:10911
deleteTopic 删除 Topic ./mqadmin deleteTopic -n 127.0.0.1:9876 -t order_topic
topicList 查看所有 Topic ./mqadmin topicList -n 127.0.0.1:9876
topicStatus 查看 Topic 状态 ./mqadmin topicStatus -n 127.0.0.1:9876 -t order_topic
topicRoute 查看 Topic 路由 ./mqadmin topicRoute -n 127.0.0.1:9876 -t order_topic
集群与 Broker 管理：

命令 用途 示例
clusterList 查看集群状态 ./mqadmin clusterList -n 127.0.0.1:9876
brokerStatus 查看 Broker 状态 ./mqadmin brokerStatus -n 127.0.0.1:9876 -b 192.168.1.20:10911
brokerConsumeStats 查看消费统计 ./mqadmin brokerConsumeStats -n 127.0.0.1:9876 -b 192.168.1.20:10911
消费组管理：

命令 用途 示例
consumerProgress 查看消费进度 ./mqadmin consumerProgress -n 127.0.0.1:9876 -g order_consumer_group
consumerStatus 查看消费者状态 ./mqadmin consumerStatus -n 127.0.0.1:9876 -g order_consumer_group
consumerConnection 查看消费者连接 ./mqadmin consumerConnection -n 127.0.0.1:9876 -g order_consumer_group
消息管理：

命令 用途 示例
queryMsgById 按 ID 查消息 ./mqadmin queryMsgById -n 127.0.0.1:9876 -i msgId
queryMsgByKey 按 Key 查消息 ./mqadmin queryMsgByKey -n 127.0.0.1:9876 -t order_topic -k order_123
queryMsgByOffset 按偏移量查消息 ./mqadmin queryMsgByOffset -n 127.0.0.1:9876 -t order_topic -b 192.168.1.20:10911 -i 0
💡 小贴士：所有命令都可以加 -h 获取详细帮助。如果同时配置了 -b（Broker 地址）和 -c（集群名），优先使用 -b。

RocketMQ 常用运维脚本与工具
启动/停止脚本：

启动 NameServer

nohup sh bin/mqnamesrv &

启动 Broker

nohup sh bin/mqbroker -c conf/broker.conf &

停止 NameServer

sh bin/mqshutdown namesrv

停止 Broker

sh bin/mqshutdown broker
查看日志：

Broker 运行日志

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

NameServer 日志

tail -f ~/logs/rocketmqlogs/namesrv.log

存储错误日志

tail -f ~/logs/rocketmqlogs/store.log
RocketMQ Dashboard：官方提供的 Web 控制台，支持 Topic 管理、消费者管理、消费进度查看、消息查询等功能。

部署 Dashboard

git clone https://github.com/apache/rocketmq-externals
cd rocketmq-console
mvn clean package -Dmaven.test.skip=true
java -jar target/rocketmq-console-ng-*.jar --rocketmq.config.namesrvAddr=192.168.0.1:9