RocketMQ：超详细部署与使用教程

Apache RocketMQ 是一款低延迟、高性能、高可靠、万亿级容量、灵活可扩展的分布式消息与流平台，支持发布/订阅、请求/回复、流处理、金融级事务消息、顺序消息、消息回溯等能力，是阿里巴巴开源并捐献给 Apache 的顶级项目。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Apache RocketMQ 源自阿里巴巴在双十一等超大规模场景下的消息中间件实践，2016 年开源后捐献给 Apache，现为 Apache 顶级项目。它在金融、电商、支付等对消息可靠性、顺序性、事务一致性要求极高的场景被广泛使用，单队列支持百万级消息堆积，天然具备消息回溯、重试、死信、事务消息等企业级能力。

1.2 核心功能

• 多种消息模型：发布/订阅（Pub/Sub）、点对点、请求/回复、流式（Streaming）。
• 金融级事务消息：支持本地事务与消息发送的最终一致性，解决「先写库还是先发消息」的分布式一致性问题。
• 顺序消息：在同一队列内保证严格 FIFO 顺序消费。
• 消息回溯：支持按时间或 offset 重新消费历史消息。
• 消息堆积与重试：单队列百万级堆积能力；消费失败自动重试，最终进入死信队列。
• 多种协议：gRPC、MQTT、JMS、OpenMessaging；5.x 引入轻量级队列（LiteTopic）等新模型。
• 内置容错与高可用：基于 DLedger Controller 的主从复制与自动选主。
• 消息轨迹（Trace）：内置消息轨迹能力，也支持 OpenTracing。
• 丰富生态：Dashboard 控制台、Exporter（Prometheus）、Connect（数据集成）、MQTT（IoT）、RocketMQ Streams（轻量流计算）、Operator（K8s）。
• 认证与授权：支持 ACL 访问控制。

1.3 技术架构

RocketMQ 由四个核心角色组成：

• NameServer：轻量级路由注册中心，无状态、可多节点部署，各节点互不通信；负责维护 Broker 路由信息。
• Broker：实际存储与投递消息的节点，负责消息的持久化、投递、查询、主从同步。
• Producer：消息生产者，向 Broker 发送消息。
• Consumer：消息消费者，从 Broker 拉取/推送消息。

官方基本模型图（Topic → MessageQueue → ConsumerGroup 的关系）：

官方部署架构图（NameServer 集群 + Broker 主从集群 + Producer/Consumer 集群）：

二、环境要求

注意：RocketMQ 默认 JVM 堆参数较大（如 Broker 8g/8g），小内存机器启动前务必修改 bin/runbroker.sh、bin/runserver.sh 中的 -Xms/-Xmx，否则会因内存不足直接退出。

三、部署方式

下面给出：二进制包单机部署（NameServer + Broker，官方推荐上手）→ Docker 部署 → Dashboard 控制台 → 源码编译，并附验证命令。

3.1 方式一：二进制包单机部署（最快上手）

步骤 1：下载并解压

从 Apache 官方镜像下载 5.5.1 二进制包（以实际最新版本为准，可到 rocketmq.apache.org/download 选择）：

# macOS / Linux
wget https://dist.apache.org/repos/dist/release/rocketmq/5.5.1/rocketmq-all-5.5.1-bin-release.zip
unzip rocketmq-all-5.5.1-bin-release.zip
cd rocketmq-all-5.5.1-bin-release/bin

Windows 用户直接下载 zip 解压到如 D:\rocketmq。

步骤 2：（小内存机器必做）调整 JVM 堆内存

编辑 bin/runserver.sh（NameServer）与 bin/runbroker.sh（Broker），把默认较大的堆改小，例如：

# runserver.sh 中
JAVA_OPT="${JAVA_OPT} -server -Xms512m -Xmx512m -Xmn256m"

# runbroker.sh 中
JAVA_OPT="${JAVA_OPT} -server -Xms1g -Xmx1g"

步骤 3：启动 NameServer

# Linux / macOS：后台启动
nohup sh mqnamesrv &

# 查看日志，出现以下内容即成功
tail -f ~/logs/rocketmqlogs/namesrv.log
# The Name Server boot success...

NameServer 默认监听 0.0.0.0:9876，确认 9876 端口未被占用。

Windows：先设置环境变量 ROCKETMQ_HOME=D:\rocketmq，再执行：

mqnamesrv.cmd

步骤 4：启动 Broker

# 后台启动，连接本地 NameServer
nohup sh mqbroker -n localhost:9876 &

# 查看日志，出现以下内容即成功
tail -f ~/logs/rocketmqlogs/broker.log
# The broker[broker-a, 192.168.1.2:10911] boot success...

Windows：

mqbroker.cmd -n localhost:9876

多机/外网部署时，-n 后面填 NameServer 地址（如 192.168.1.10:9876），并在 conf/broker.conf 中设置 brokerIP1 为 Broker 真实 IP，否则 Producer/Consumer 可能拿到内网 127.0.0.1 地址导致连不上。

3.2 方式二：Docker 部署

官方镜像 apache/rocketmq（使用 host 网络暴露端口）：

# 1) 启动 NameServer
docker run -d --name rmqnamesrv --net=host apache/rocketmq ./mqnamesrv

# 2) 启动 Broker，挂载存储目录，连接本地 NameServer
docker run -d --name rmqbroker --net=host \
  --mount type=bind,source=/tmp/store,target=/home/rocketmq/store \
  apache/rocketmq ./mqbroker -n localhost:9876

生产环境不建议用 --net=host 单机跑，应使用 docker-compose 或官方 rocketmq-docker 项目编排多容器集群。

3.3 方式三：Dashboard 可视化控制台

# 官方控制台仓库：github.com/apache/rocketmq-dashboard
# Docker 一键运行，连接到 NameServer
docker run -d --name rmq-dashboard -p 8080:8080 \
  -e rocketmq.namesrv.addr=127.0.0.1:9876 \
  apacherocketmq/rocketmq-dashboard:latest

浏览器访问 http://127.0.0.1:8080，可查看 Topic、消息、消费情况、集群状态。

3.4 方式四：源码编译

需要 JDK 8 与 Maven 3.2.x+：

git clone https://github.com/apache/rocketmq.git
cd rocketmq
mvn -Dmaven.test.skip=true clean install -U
# 编译产物在 distribution/target 下，解压后按 3.1 方式启动

3.5 验证部署成功（关键）

使用官方 tools 工具做一次「发送 → 消费」闭环验证：

cd rocketmq-all-5.5.1-bin-release

# 1) 启动消费者（监听 BP 测试 Topic）
sh tools.sh org.apache.rocketmq.example.quickstart.Consumer

# 2) 另开终端，启动生产者发送 1000 条消息
sh tools.sh org.apache.rocketmq.example.quickstart.Producer

预期输出：

# Producer 端
SendResult [sendStatus=SEND_OK, msgId= ...]

# Consumer 端
ConsumeMessageThread_1 Receive Tags: [TagA] NewMsg ...

出现 SEND_OK 且 Consumer 收到消息，说明 NameServer → Broker → Producer → Consumer 全链路打通。

也可用命令行查看 Topic 路由：

sh tools.sh org.apache.rocketmq.tools.command.topic.TopicListSubCommand -n localhost:9876

四、使用方法

4.1 基础用法

RocketMQ 的消息模型：一个 Topic 下有多个 MessageQueue，Producer 发消息到 Topic，Consumer 以 ConsumerGroup 为单位订阅并负载均衡消费。

4.2 Java 客户端示例（Maven）

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client-java</artifactId>
    <version>5.0.x</version>
</dependency>

5.x 推荐使用 gRPC 协议的 rocketmq-client-java（新一代客户端）；传统 4.x Remoting 客户端坐标为 org.apache.rocketmq:rocketmq-client，具体以官方客户端文档为准。

发送同步消息（Producer）

import org.apache.rocketmq.client.producer.DefaultMQProducer;
import org.apache.rocketmq.common.message.Message;

public class ProducerDemo {
    public static void main(String[] args) throws Exception {
        DefaultMQProducer producer = new DefaultMQProducer("demo_producer_group");
        producer.setNamesrvAddr("127.0.0.1:9876");
        producer.start();

        Message msg = new Message("TopicTest", "TagA",
            "Hello RocketMQ".getBytes());
        SendResult result = producer.send(msg);
        System.out.println("发送结果：" + result.getSendStatus());

        producer.shutdown();
    }
}

订阅消费（Consumer）

import org.apache.rocketmq.client.consumer.DefaultMQPushConsumer;
import org.apache.rocketmq.client.consumer.listener.ConsumeConcurrentlyStatus;
import org.apache.rocketmq.client.consumer.listener.MessageListenerConcurrently;

public class ConsumerDemo {
    public static void main(String[] args) throws Exception {
        DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("demo_consumer_group");
        consumer.setNamesrvAddr("127.0.0.1:9876");
        consumer.subscribe("TopicTest", "TagA");

        consumer.registerMessageListener((MessageListenerConcurrently) (msgs, context) -> {
            msgs.forEach(m -> System.out.println("收到：" + new String(m.getBody())));
            return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
        });

        consumer.start();
    }
}

4.3 进阶功能

• 顺序消息：Producer 用 MessageQueueSelector 把同一业务 key 发到同一队列，Consumer 用 MessageListenerOrderly。
• 事务消息：实现 TransactionListener，half 消息 + 本地事务 + 回查，保证「发消息与写库」最终一致。
• 延迟消息：msg.setDelayTimeLevel(3) 按等级延时（1s/5s/.../2h 等，具体等级以官方文档为准）。
• 消息过滤：按 Tag 或 SQL92 表达式过滤。
• 消息轨迹：Broker/Consumer 开启 trace 后，可在 Dashboard 追踪每条消息。
• ACL 权限：在 conf/plain_acl.yml 配置用户名/密码与 Topic 权限。
• K8s 部署：使用官方 rocketmq-operator 声明式部署集群。

4.4 适用场景

• 电商下单后的异步解耦（订单 → 库存 → 积分）；
• 金融级事务消息（支付结果与下游一致）；
• 订单/物流状态严格顺序消费；
• 秒杀、流量削峰填谷；
• 大数据/流计算的数据管道（配合 RocketMQ Streams / Flink Connector）；
• IoT 设备消息接入（MQTT 协议）。

五、常见问题排查（FAQ）

Q1：Broker 启动后立即退出，日志报 Could not reserve enough space for object heap - 原因：默认 JVM 堆（如 8g）超过机器可用内存。 - 解决：修改 bin/runbroker.sh 与 bin/runserver.sh 的 -Xms/-Xmx 为机器可承受值（见 3.1 步骤 2）。

Q2：Producer 报 No route info of this topic / 连接 10911 超时 - 原因：Broker 未正确注册到 NameServer；或 Broker 注册的是内网 IP（127.0.0.1），Producer 拿不到真实地址。 - 解决：确认 Broker 日志 boot success；在 broker.conf 设置 brokerIP1=外网/内网可达IP；检查 10911 端口放行。

Q3：Consumer 启动报 connect to <broker-ip>:10911 failed - 原因：同 Q2，Consumer 通过 NameServer 拿到的 Broker 地址不可达。 - 解决：同上配置 brokerIP1，并确保客户端所在网络能访问 Broker 10911。

Q4：NameServer 启动正常，但 Broker 连不上 - 原因：-n 地址写错或 9876 被防火墙拦截。 - 解决：确认 mqbroker -n 后填的是 NameServer ip:9876；telnet ip 9876 测试连通性。

Q5：消息堆积严重，Consumer 消费慢 - 原因：消费并发度低、下游处理慢、单队列数有限。 - 解决：增加 Consumer 实例/线程数；提高 Topic 队列数；排查下游慢调用；必要时扩容 Broker。

Q6：消息发出去了但 Consumer 没收到 - 原因：Topic/Tag 订阅不一致、ConsumerGroup 已存在在线实例做了负载均衡、或 Consumer 组名重复。 - 解决：核对 Topic 与 Tag；确保不同服务用不同 ConsumerGroup；看 Dashboard 中该 Topic 的消费进度。

Q7：Windows 下启动报 ROCKETMQ_HOME 未定义 - 解决：设置环境变量 ROCKETMQ_HOME=D:\rocketmq 后再运行 mqnamesrv.cmd / mqbroker.cmd。

Q8：Dashboard 连接不上集群 - 原因：Dashboard 配的 namesrv 地址不对，或容器网络隔离。 - 解决：设置 rocketmq.namesrv.addr=宿主机IP:9876，确认容器能访问该地址。

六、部署注意事项与最佳实践

1. 生产必须主从 + 集群：单机 NameServer/Broker 仅用于开发；生产用多 NameServer 节点 + Broker 主从复制（DLedger Controller）。
2. 磁盘与内存规划：消息存储建议 SSD 并单独挂载；根据堆积量预估磁盘容量；JVM 堆按机器实际内存调优。
3. brokerIP1 必配：跨机/容器/云环境部署，务必显式配置 Broker 对外 IP，否则路由地址错乱。
4. 端口全集：9876（NameServer）、10911（Broker）、10909（fast）、10912（VIP），安全组一次性放行。
5. 合理设置 Topic 队列数：队列数决定 Consumer 最大并发度，提前规划。
6. 死信监控：消费多次失败进入死信队列，需在 Dashboard 配置告警，避免消息静默丢失。
7. 打开 ACL 与认证：生产不要裸奔，用 plain_acl.yml 或 5.x 认证授权。
8. 版本对齐：客户端版本与 Broker 大版本尽量匹配；5.x 用新客户端 gRPC 模型。

七、参考资料

• GitHub 仓库：https://github.com/apache/rocketmq
• 官网：https://rocketmq.apache.org/zh-cn/
• 快速开始：https://rocketmq.apache.org/docs/quickStart/01quickstart/
• 下载页：https://rocketmq.apache.org/zh-cn/download/
• 二进制下载（Apache 镜像）：https://dist.apache.org/repos/dist/release/rocketmq/
• Dashboard 控制台：https://github.com/apache/rocketmq-dashboard
• Exporter（Prometheus）：https://github.com/apache/rocketmq-exporter
• Operator（K8s）：https://github.com/apache/rocketmq-operator
• Spring 集成：https://github.com/apache/rocketmq-spring
• Release 页：https://github.com/apache/rocketmq/releases