单机部署（开发/测试环境）

环境准备：

项要求

操作系统 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="JAVAOPT−server−Xms8g−Xmx8g−XX:MetaspaceSize=256m−XX:MaxMetaspaceSize=512m"JAVAOPT="{JAVA_OPT} -server -Xms8g -Xmx8g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m" JAVA_OPT="JAVAOPT−server−Xms8g−Xmx8g−XX:MetaspaceSize=256m−XX:MaxMetaspaceSize=512m"JAVAOPT="{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