# RocketMQ 使用与接入
## 是什么
### 阿里开源,后捐给 Apache,Java 编写
### NameServer 注册中心 + Broker 存储转发
### 强项:事务消息、延时/定时消息、消息回溯
### 典型场景:订单、支付、削峰、异步解耦
## 两代架构
### 4.x:Remoting 私有协议
- 客户端连 NameServer:9876
- 再直连 Broker:10911
- Java 客户端 rocketmq-client
### 5.x:Proxy + gRPC
- 客户端只连 Proxy:8081
- Proxy 代理 NameServer 与 Broker
- 官方多语言客户端统一走 gRPC
- 服务端仍兼容 4.x 老客户端
## 部署
### 4.x 二进制:mqnamesrv + mqbroker
### 5.x 容器:namesrv + broker + proxy
### 控制台:rocketmq-dashboard
## 四种接入方式
### Java 4.x remoting
### Java 5.x gRPC
### Spring Boot(rocketmq-spring-boot-starter)
### Go / Python / C++ / Node.js 客户端
## 消息类型
- 普通消息
- 顺序消息(队列级有序)
- 延时/定时消息
- 事务消息
- 批量消息
- Tag / SQL92 过滤
## 可靠性与运维
- 主从复制、flushDiskType
- 消费重试 %RETRY%group
- 死信队列 %DLQ%group
- 消费端幂等
- mqadmin 常用命令
## 常见坑
- brokerIP1 要配对外 IP
- No route info of this topic
- 发送超时多为 10911 不通
- 内存不足导致启动失败

RocketMQ 最早由阿里内部研发(前身 MetaQ),2016 年捐给 Apache 基金会,现为 Apache 顶级项目。纯 Java 实现,特点是高吞吐 + 低延迟 + 功能丰富:事务消息、延时/定时消息、消息回溯、Tag/SQL92 过滤都是原生能力。

组件 作用
NameServer 无状态注册中心,Broker 向它注册、客户端向它拉路由;生产环境一般部署 2~3 台
Broker 真正存消息、转发消息的节点,启动时向所有 NameServer 注册
Topic 逻辑上的消息分类,内部再切成多个 Queue(默认 4 个)
Producer / Consumer Group 生产者组 / 消费者组;组内负载均衡,组间各得一份

四个招牌能力(也是它相对 Kafka 的差异点):

  • 事务消息:半消息 + 本地事务回查,解决「发消息」和「写数据库」的一致性问题。
  • 延时 / 定时消息:4.x 支持 18 个固定延时级别,5.x 支持任意时间戳。
  • 消息回溯:按时间戳重置消费位点(resetOffsetByTime),可重新消费历史消息,业务侧比改 offset 友好。
  • 丰富的过滤:Tag 过滤、SQL92 属性过滤,在 Broker 端就把不需要的消息筛掉。

一句话:5.x = 4.x 的存储内核 + 新增 Proxy 统一入口 + gRPC 协议。服务端换了架构,老客户端不改代码也能用。

对比项 4.x 5.x
通信协议 Remoting(自定义 TCP 协议) gRPC(新客户端)+ Remoting(兼容老客户端)
客户端连接目标 先连 NameServer:9876 拿路由,再直连 Broker:10911 只连 Proxy 的 8081,由 Proxy 转发
官方 Java 客户端 org.apache.rocketmq:rocketmq-client rocketmq-client-java(gRPC);rocketmq-client 5.x 仍可用
多语言客户端 C++ / Go / Python,各基于 remoting 或 C++ 内核 官方统一 gRPC 客户端:Java / C++ / Go / Rust / Python
延时消息 固定 18 级(1s 5s 10s 30s 1m … 2h) 任意时间戳,精度秒级
消费模式 Push(DefaultMQPushConsumer)/ Pull PushConsumer / SimpleConsumer(显式 ack)/ POP 模式
扩缩容表现 消费者按队列重平衡,扩容时可能短暂重复消费 POP 模式把重平衡放到 Broker 侧,扩缩容更平滑
运维入口 mqadmin 命令行 + rocketmq-console mqadmin + Proxy 管理接口 + rocketmq-dashboard
兼容性 — 5.x 服务端同时开 remoting(10911)与 gRPC(8081),4.x 客户端可继续接

怎么选:

  • 老项目、已有 4.x 客户端、Spring Boot 老版本 starter —— 继续走 remoting,服务端升到 5.x 也能跑。
  • 新项目、多语言团队(Go / Rust / Python)、需要任意时刻定时消息 —— 直接上 5.x Proxy + gRPC 客户端。
  • 4.x 客户端要连 5.x 集群时,Proxy 需要保留 remoting 兼容(配置项在 conf/rmq-proxy.json 里,例如 enableRemotingAccess,键名以所用版本为准),否则老客户端连不上。
端口速记
端口 用途
9876 NameServer(4.x 客户端连这个)
10911 Broker 主服务端口(客户端收发消息)
10909 Broker VIP / fast-remoting 通道
8080 5.x Proxy 的 HTTP 接口 / 管理端口
8081 5.x Proxy 的 gRPC 端口(新客户端连这个)
8082 rocketmq-dashboard 示例端口
3.1 老版本:4.x 二进制包(最经典)
wget https://archive.apache.org/dist/rocketmq/4.9.7/rocketmq-all-4.9.7-bin-release.zip
unzip rocketmq-all-4.9.7-bin-release.zip && cd rocketmq-all-4.9.7-bin-release
 
# 1) 改内存:默认要 4G/8G,小机器必须调小,否则起不来
vi bin/runserver.sh     # -Xms512m -Xmx512m -Xmn256m
vi bin/runbroker.sh     # -Xms1g -Xmx1g
# 2) Broker 配置 conf/broker.conf
brokerClusterName = DefaultCluster
brokerName = broker-a
brokerId = 0
namesrvAddr = 127.0.0.1:9876
brokerIP1 = 192.168.1.10       # 关键:客户端最终连这个 IP,容器/云主机必须显式指定
listenPort = 10911
deleteWhen = 04
fileReservedTime = 48
brokerRole = ASYNC_MASTER
flushDiskType = ASYNC_FLUSH
autoCreateTopicEnable = true   # 生产环境建议 false,改为手工建 Topic
# 3) 启动
nohup sh bin/mqnamesrv &                       # NameServer
nohup sh bin/mqbroker -c conf/broker.conf &    # Broker
 
# 4) 验证
sh bin/mqadmin clusterList -n 127.0.0.1:9876

控制台(可选):

docker run -d --name rocketmq-dashboard -p 8082:8080 \
  -e "JAVA_OPTS=-Drocketmq.namesrv.addr=127.0.0.1:9876" \
  apacherocketmq/rocketmq-dashboard:latest
3.2 新版本:5.x(namesrv + broker + proxy 三角色)

生产建议三个角色分开部署;开发环境可以让 Broker 内嵌 Proxy(Local 模式)。

# NameServer
docker run -d --name rmqnamesrv -p 9876:9876 \
  -e "JAVA_OPT_EXT=-Xms512m -Xmx512m" \
  apache/rocketmq:5.3.1 sh mqnamesrv
 
# Broker(指向 NameServer)
docker run -d --name rmqbroker --link rmqnamesrv:namesrv \
  -p 10911:10911 -p 10909:10909 \
  -e "NAMESRV_ADDR=namesrv:9876" \
  -e "JAVA_OPT_EXT=-Xms1g -Xmx1g" \
  apache/rocketmq:5.3.1 sh mqbroker -c /home/rocketmq/conf/broker.conf
 
# Proxy(客户端连它的 8081)
docker run -d --name rmqproxy --link rmqnamesrv:namesrv \
  -p 8080:8080 -p 8081:8081 \
  -e "NAMESRV_ADDR=namesrv:9876" \
  apache/rocketmq:5.3.1 sh mqproxy

要点:

  • 新客户端连的是 Proxy 的 8081,不是 NameServer 的 9876,这是新老接入最大的差别。
  • brokerIP1 依然要填对外真实 IP,否则 Proxy 会把内网地址回给客户端,报连接超时。
  • Proxy 的配置在 conf/rmq-proxy.json(namesrvAddr、grpcServerPort 等)。
  • 用云上托管版时,控制台给出的「接入点」就是 Proxy 的 endpoints,直接交给第 5 节的 gRPC 客户端。

依赖:

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client</artifactId>
    <version>4.9.7</version>   <!-- 5.x 服务端也可用同一坐标的 5.x 版本 -->
</dependency>
生产者
DefaultMQProducer producer = new DefaultMQProducer("pg_order");   // 生产者组
producer.setNamesrvAddr("192.168.1.10:9876");
producer.setSendMsgTimeout(3000);
producer.setRetryTimesWhenSendFailed(2);
producer.start();                                                 // 只启动一次,务必全应用复用
 
Message msg = new Message(
        "topic_order",                                  // topic
        "PAID",                                         // tag
        "orderId=A1001",                                // keys,便于控制台按消息查询
        "{\"orderId\":\"A1001\",\"amount\":99.5}".getBytes(StandardCharsets.UTF_8));
 
SendResult sr = producer.send(msg);                         // 同步发送
System.out.println(sr.getSendStatus() + " / " + sr.getMsgId());
 
// 异步:producer.send(msg, new SendCallback(){ onSuccess / onException });
// 单向:producer.sendOneway(msg);          (不关心结果,吞吐最高)
// 批量:producer.send(Collection<Message>) (同 topic,总大小不超过 4MB)
// 指定队列:producer.send(msg, new MessageQueueSelector(){...}, arg)  → 顺序消息用
 
producer.shutdown();
消费者(Push 模式,最常用)
DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("cg_order");
consumer.setNamesrvAddr("192.168.1.10:9876");
consumer.subscribe("topic_order", "PAID || REFUND");              // Tag 过滤;"*" 表示全部
consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
consumer.setConsumeThreadMin(10);
consumer.setConsumeThreadMax(20);
consumer.setMaxReconsumeTimes(16);                               // 超过次数进死信队列
 
consumer.registerMessageListener((MessageListenerConcurrently) (msgs, ctx) -> {
    for (MessageExt m : msgs) {
        try {
            handle(new String(m.getBody(), StandardCharsets.UTF_8));
        } catch (Exception e) {
            return ConsumeConcurrentlyStatus.RECONSUME_LATER;    // 稍后重试
        }
    }
    return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;            // 成功才提交位点
});
consumer.start();
顺序消息

同一订单的消息必须落进同一个队列,消费端用 MessageListenerOrderly:

// 生产端:按业务主键选队列
producer.send(msg, (mqs, m, arg) ->
        mqs.get(Math.abs(arg.hashCode()) % mqs.size()), "A1001");
 
// 消费端:顺序监听器
consumer.registerMessageListener((MessageListenerOrderly) (msgs, ctx) -> {
    // 暂时无法处理时返回这个状态,而不是无限阻塞
    // return ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT;
    return ConsumeOrderlyStatus.SUCCESS;
});
延时消息(4.x 固定 18 级)
msg.setDelayTimeLevel(5);   // 级别:1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h
                            // level=5 → 1m,level=17 → 2h
事务消息
TransactionMQProducer producer = new TransactionMQProducer("pg_tx");
producer.setNamesrvAddr("192.168.1.10:9876");
producer.setExecutorService(Executors.newFixedThreadPool(8));   // 回查线程池
producer.setTransactionListener(new TransactionListener() {
    @Override
    public LocalTransactionState executeLocalTransaction(Message msg, Object arg) {
        try {
            orderService.create((String) arg);        // 本地事务:写库
            return LocalTransactionState.COMMIT_MESSAGE;
        } catch (Exception e) {
            return LocalTransactionState.ROLLBACK_MESSAGE;
        }
    }
 
    @Override
    public LocalTransactionState checkLocalTransaction(MessageExt msg) {
        // Broker 回查本地事务状态,必须能查到真实结果
        return orderService.exists(msg.getKeys())
                ? LocalTransactionState.COMMIT_MESSAGE
                : LocalTransactionState.ROLLBACK_MESSAGE;
    }
});
producer.start();
 
producer.sendMessageInTransaction(msg, "A1001");   // 先发半消息,再回调本地事务

依赖(JDK 8+):

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client-java</artifactId>
    <version>5.0.7</version>   <!-- 请以 Maven Central 上最新的 5.0.x 为准 -->
</dependency>
客户端配置与生产者
ClientServiceProvider provider = ClientServiceProvider.loadService();
 
ClientConfiguration cfg = ClientConfiguration.newBuilder()
        .setEndpoints("192.168.1.10:8081")     // Proxy 的 gRPC 端口,多个用分号隔开
        // 开启 ACL 时:
        // .setCredentialProvider(SessionCredentialsProvider.newBuilder()
        //         .setAccessKey("ak").setAccessSecret("sk").build())
        .build();
 
Producer producer = provider.newProducerBuilder()
        .setClientConfiguration(cfg)
        .setTopics("topic_order")               // 前置声明用到的 topic
        .build();
 
Message msg = provider.newMessageBuilder()
        .setTopic("topic_order")
        .setTag("PAID")
        .setKeys("A1001")
        .setBody("{\"orderId\":\"A1001\"}".getBytes(StandardCharsets.UTF_8))
        // 定时消息(5.x 新能力,任意时刻,精度秒级)
        // .setDeliveryTimestamp(System.currentTimeMillis() + 60_000L)
        .build();
 
SendReceipt receipt = producer.send(msg);
System.out.println(receipt.getMessageId());
 
// 异步:producer.sendAsync(msg) → CompletableFuture<SendReceipt>
producer.close();     // 实现 Closeable
PushConsumer(推荐,框架自动 ack)
PushConsumer consumer = provider.newPushConsumerBuilder()
        .setClientConfiguration(cfg)
        .setConsumerGroup("cg_order")
        .setSubscriptionExpressions(Collections.singletonMap("topic_order", "*"))
        .setMessageListener(messageView -> {
            try {
                handle(messageView.getBody().toString(StandardCharsets.UTF_8));
                return ConsumeResult.SUCCESS;
            } catch (Exception e) {
                return ConsumeResult.FAILURE;    // 触发重试,超限进死信
            }
        })
        .build();
SimpleConsumer(拉模式,显式 ack,适合批量与自定义流控)
SimpleConsumer consumer = provider.newSimpleConsumerBuilder()
        .setClientConfiguration(cfg)
        .setConsumerGroup("cg_order_pull")
        .setAwaitDuration(java.time.Duration.ofSeconds(15))
        .setSubscriptionExpressions(Collections.singletonMap("topic_order", "*"))
        .build();
 
List<MessageView> msgs = consumer.receive(32, java.time.Duration.ofSeconds(15));
for (MessageView m : msgs) {
    process(m);
    consumer.ack(m);     // 处理成功才 ack;也可 changeInvisibleDuration 延长不可见时间
}
事务消息(5.x 写法更简洁)
Producer producer = provider.newProducerBuilder()
        .setClientConfiguration(cfg)
        .setTopics("topic_order")
        .setTransactionChecker(messageView -> TransactionResolution.COMMIT)   // 回查逻辑
        .build();
 
Transaction transaction = producer.beginTransaction();
producer.send(transaction, msg);
transaction.commit();      // 本地事务成功则 commit,失败则 transaction.rollback()
4.x → 5.x API 映射速查
能力 4.x remoting 5.x gRPC
入口配置 setNamesrvAddr(“ip:9876”) ClientConfiguration#setEndpoints(“ip:8081”)
生产者 DefaultMQProducer ClientServiceProvider#newProducerBuilder
推消费 DefaultMQPushConsumer + Listener newPushConsumerBuilder + MessageListener
拉消费 DefaultMQPullConsumer(API 繁琐) newSimpleConsumerBuilder + receive / ack
发送结果 SendResult SendReceipt
延时消息 setDelayTimeLevel(int) setDeliveryTimestamp(long)
事务消息 TransactionMQProducer + TransactionListener beginTransaction / commit / rollback + TransactionChecker
日志 自带 logback 配置 需自行引入 slf4j 实现,否则启动报错
资源释放 shutdown() close()
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.3.1</version>
    <!-- 2.2.x 面向 4.x;2.3.x 基于 5.x 客户端 jar(仍是 remoting 协议连 9876),4.x/5.x 服务端都能连 -->
</dependency>
rocketmq.name-server=192.168.1.10:9876
rocketmq.producer.group=pg_order
rocketmq.producer.send-message-timeout=3000
# 开启 ACL 时再填
# rocketmq.producer.access-key=
# rocketmq.producer.secret-key=

发送(RocketMQTemplate,topic 与 tag 用冒号分隔):

@Resource
private RocketMQTemplate rocketMQTemplate;
 
public void pay(String payload) {
    // 同步
    SendResult r = rocketMQTemplate.syncSend("topic_order:PAID", payload);
 
    // 异步
    rocketMQTemplate.asyncSend("topic_order:PAID", payload, new SendCallback() {
        @Override public void onSuccess(SendResult sendResult) { }
        @Override public void onException(Throwable e) { }
    });
 
    // 单向
    rocketMQTemplate.sendOneWay("topic_order:LOG", "click");
 
    // 顺序消息:第三个参数是 hashKey
    rocketMQTemplate.syncSendOrderly("topic_order:PAID", payload, "A1001");
 
    // 延时消息:最后一个参数是 4.x 的延时级别
    rocketMQTemplate.syncSend("topic_order:PAID",
            MessageBuilder.withPayload(payload).build(), 3000, 5);
}

消费:

@Service
@RocketMQMessageListener(
        topic = "topic_order",
        consumerGroup = "cg_order",
        selectorExpression = "PAID",
        consumeMode = ConsumeMode.ORDERLY)     // 默认 CONCURRENTLY
public class OrderConsumer implements RocketMQListener<String> {
    @Override
    public void onMessage(String body) {
        // 正常返回即消费成功;抛异常会触发重试
    }
}
语言 4.x(remoting) 5.x(gRPC)
Go github.com/apache/rocketmq-client-go/v2 github.com/apache/rocketmq-clients/golang/v5
Python pip install rocketmq-client-python(C++ 内核) apache/rocketmq-clients 的 python 目录(gRPC,需自行装 grpcio 依赖)
C++ rocketmq-client-cpp rocketmq-client-cpp 的 5.x 分支(gRPC)
Rust rocketmq-client-rust(4.x 内核) rocketmq-client-rust 的 5.x 分支(gRPC)
Node.js rocketmq-client-nodejs(C++ 绑定,连 9876,已少维护) 无官方客户端:用 @grpc/grpc-js 自行直连 Proxy,或走 Go/Python sidecar(见下)

Go(4.x 风格):

p, _ := rocketmq.NewProducer(
    producer.WithNameServer([]string{"192.168.1.10:9876"}),
    producer.WithGroupName("pg_order"),
    producer.WithRetry(2))
_ = p.Start()
 
res, err := p.SendSync(context.Background(), &primitive.Message{
    Topic: "topic_order",
    Body:  []byte("hello"),
})
_ = res
_ = err
 
defer p.Shutdown()

Go(5.x gRPC 风格):

producer, _ := golang.NewProducer(&golang.Config{
    Endpoint:    "192.168.1.10:8081",
    Credentials: credentials.NewCredentials("", ""),
}, golang.WithTopics("topic_order"))
_ = producer.Start()
 
resp, err := producer.Send(context.Background(), &golang.Message{
    Topic: "topic_order",
    Body:  []byte("hello"),
})
_ = resp
_ = err
// defer producer.GracefulStop()

Python(4.x 风格):

from rocketmq.client import Producer, Message
 
producer = Producer('pg_order')
producer.set_name_server_address('192.168.1.10:9876')
producer.start()
 
msg = Message('topic_order')
msg.set_keys('A1001')
msg.set_tags('PAID')
msg.set_body('{"orderId":"A1001"}')
producer.send_sync(msg)
 
producer.shutdown()
Node.js 接 5.x gRPC:官方没客户端,两条路

先把现状说清楚:官方 rocketmq-clients 覆盖 Java / C++ / C# / Go / Rust / Python 等语言,Node.js 一直是个空缺;能搜到的 rocketmq-client-nodejs 是 4.x 时代的 C++ 绑定(连 NameServer 9876,走 remoting),早已停止更新,接不了 5.x Proxy。所以 Node 侧只有下面两条路。

路径 A:用 @grpc/grpc-js 直连 Proxy 的 8081

原理:Proxy 对外暴露的就是标准 gRPC 服务 apache.rocketmq.v2.MessagingService,只要有官方 proto,Node 自己也能当客户端。

npm i @grpc/grpc-js @grpc/proto-loader
 
# 从 apache/rocketmq-clients 仓库把 proto 目录拷到本地,例如:
#   proto/apache/rocketmq/v2/definition.proto
#   proto/apache/rocketmq/v2/service.proto
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
 
const def = protoLoader.loadSync('proto/apache/rocketmq/v2/service.proto', {
  includeDirs: ['proto'],
  keepCase: false,        // 生成驼峰方法名 sendMessage / receiveMessage
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
});
const { apache } = grpc.loadPackageDefinition(def);
 
// 关键:这里填 Proxy 的 8081,不是 NameServer 的 9876
const client = new apache.rocketmq.v2.MessagingService(
  '192.168.1.10:8081',
  grpc.credentials.createInsecure(),       // 托管版 / 开 TLS 时换成 createSsl(...)
  { 'grpc.keepalive_time_ms': 30000, 'grpc.keepalive_timeout_ms': 10000 }
);
 
function send(body, tag, keys) {
  return new Promise((resolve, reject) => {
    client.sendMessage({
      messages: [{
        topic: 'topic_order',                 // 字段名请以你手上的 proto 为准
        systemProperties: { tag, keys },      // tag / keys 属于系统属性
        body: Buffer.from(body, 'utf8'),
      }],
    }, (err, resp) => (err ? reject(err) : resolve(resp.entries)));
  });
}
 
send('{"orderId":"A1001"}', 'PAID', 'A1001')
  .then(entries => console.log(JSON.stringify(entries)))
  .catch(console.error);

动手前必须知道的几点:

  • Message 结构动过:topic / tag / keys 是顶层字段还是塞在 systemProperties 里,5.0 前后调整过,务必对着本地 proto 文件核对字段名,不要照抄旧博客。
  • 心跳不能省:官方 SDK 会周期性发 TelemetryCommand(上报 settings、线程栈)和 Heartbeat。只调 SendMessage 在部分版本上看着能用,但 Proxy 会把没有存活信号的连接当异常客户端清理,表现为随机超时、偶发失败,生产环境务必补齐。
  • 消费端远比发送麻烦:POP 消费要自己维持 ReceiveMessage 长轮询、调 AckMessage、管理不可见时间(invisibleDuration)与重试/死信,还要处理连接重建。手写这一套性价比很低。
  • ACL:开启鉴权后必须在 gRPC metadata 里带签名头(AK/SK 按官方 SDK 的签名算法算),否则 Proxy 直接拒绝请求。
  • 升级代价:官方 proto 不承诺向后兼容,Proxy 升级后自维护的 stub 可能要跟着改 —— 这正是路径 B 存在的理由。

路径 B:Go / Python sidecar(生产推荐)

用官方 Go(github.com/apache/rocketmq-clients/golang/v5)或 Python 客户端跑一个极小的网关进程,对外只暴露 HTTP / gRPC,Node 侧调网关:

Node 业务进程  --HTTP/gRPC-->  sidecar(官方 Go/Python 客户端)  --gRPC 8081-->  Proxy
  • 好处:协议、心跳、重试、ACK、死信全交给官方 SDK,Node 只写业务;SDK 升级只动 sidecar,不用维护 proto stub。
  • 代价:多一个常驻进程,部署、监控、超时与错误透传要一起设计。
  • 什么时候值得:只要这条链路要进生产,就值得。团队里 Go / Java 更熟的话,投入产出比比在 Node 里手写协议高得多。

选型建议:多语言团队优先用 5.x 的 gRPC 客户端,接口在各语言间基本一致;Node.js 没有官方客户端,生产链路建议用 Go/Python sidecar 包住协议细节,而不是长期自己维护 gRPC stub;4.x 时代的 Python/Node 客户端维护活跃度较低,新项目不建议依赖。

类型 4.x 写法 5.x 写法 注意点
普通消息 send / sendAsync / sendOneway 同样三种 核心链路用同步发送并配重试,别用单向
顺序消息 手动选队列 + Orderly 监听器 PushConsumer 分区顺序消费 只在同一 Queue 内有序,选队列的 key 必须是业务主键
延时消息 setDelayTimeLevel(1~18) setDeliveryTimestamp 5.x 可定时到任意时刻
事务消息 半消息 + 本地事务回查 beginTransaction / commit / rollback 回查有次数上限,回查逻辑必须能查到真实状态
批量消息 send(List) 客户端批量发送接口 同 topic、总大小不超过 4MB;批量不等于事务
过滤 Tag 过滤(多 Tag 用两条竖线连接)、SQL92 同左 过滤表达式写在订阅方法里,注意转义

bin/mqadmin 在 4.x / 5.x 上通用,常用命令:

# 集群与 Topic
sh bin/mqadmin clusterList      -n 127.0.0.1:9876
sh bin/mqadmin topicList        -n 127.0.0.1:9876 -c DefaultCluster
sh bin/mqadmin topicRoute       -n 127.0.0.1:9876 -t topic_order
sh bin/mqadmin updateTopic      -n 127.0.0.1:9876 -c DefaultCluster -t topic_order -r 8 -w 8
sh bin/mqadmin deleteTopic      -n 127.0.0.1:9876 -c DefaultCluster -t topic_order
 
# 消费情况与位点
sh bin/mqadmin consumerProgress  -n 127.0.0.1:9876 -g cg_order
sh bin/mqadmin consumerStatus    -n 127.0.0.1:9876 -g cg_order
sh bin/mqadmin resetOffsetByTime -n 127.0.0.1:9876 -g cg_order -t topic_order -s now
 
# 手工发一条测试消息
sh bin/mqadmin sendMessage       -n 127.0.0.1:9876 -t topic_order -p "hello"

5.x 还可以配合 Proxy 的管理接口和 rocketmq-dashboard 使用。

排查清单(按出现频率排序):

  • sendDefaultImpl call timeout:客户端到 Broker 的 10911 不通,多为安全组/防火墙未放行,或 brokerIP1 填了内网地址。
  • No route info of this topic:NameServer 上没有该 Topic 的路由。生产环境 autoCreateTopicEnable=false 时需先 updateTopic 手工创建。
  • 4.x 客户端连 5.x 连不上:Proxy 未保留 remoting 兼容,或客户端仍指向已关闭的 9876。
  • 5.x 新客户端连不上:endpoints 必须填 Proxy 的 8081,填 9876 一定失败。
  • Broker 启动即 OOM:默认 runbroker.sh 需要大内存,小机器必须调小 -Xmx。
  • 消费堆积:看 consumerProgress 的 diff;先确认消费者是否在线(consumerStatus 里的 notOnline),再考虑加实例(实例数超过队列数没有意义)。
  • 消息重复:默认至少一次语义,别指望 MQ 去重,消费端必须幂等。
  • 刷盘:flushDiskType=ASYNCFLUSH 性能好、断电可能丢少量消息;SYNCFLUSH 更安全但 TPS 下降。
  • 主从:ASYNCMASTER 主挂掉可能有少量未同步消息丢失;SYNCMASTER(同步双写)不丢消息但 RT 上升。5.x 可用 DLedger / Controller 模式做主备自动切换。
  • 消费重试:并发消费失败会重试(默认 16 次),消息进入 %RETRY%消费组名 的 Topic,以递增间隔重投;超过次数后进入 %DLQ%消费组名 死信队列,死信必须有人工处理入口。
  • 幂等:用业务唯一 ID(订单号 + 事件类型)做 Redis 或数据库唯一键去重,这是应对「至少一次」的标准做法。
  • 不丢消息的三道关:生产端同步发送 + 失败重试;Broker 端同步刷盘 / 主从可靠;消费端处理成功才 ack。
  • 顺序:顺序消费要求消息进同一队列且消费端单线程(MessageListenerOrderly);生产端按业务键 hash 选队列,扩容队列会破坏既有顺序。

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • rocketmq.txt
  • 最后更改: 2026/10/16 14:11
  • 由 张叶安