007|RocketMQ 快速上手:核心概念与第一条消息

罗兴波发布于
文章摘要

用 Python 5.x 客户端跑通 RocketMQ 一发一收,认识 Topic、Queue、消费组与 Proxy,明确发送确认、业务落库和消费 ACK 的边界。

**先给结论:**接入 RocketMQ,先建立 Topic 和消费组,再让生产者发送消息、消费者完成业务并确认。本篇用 Python 的 5.x 客户端跑通这条链路,后两篇分别解释存储与消费并发。

**适用场景与前提:**本机学习普通业务消息。示例基线为 RocketMQ 5.5.0、Python 3.12、rocketmq-python-client==5.1.2,需要可运行 Linux 容器的 Docker。只部署一个 Broker,没有副本高可用;不开鉴权的学习端口只绑定本机。部署命令和示例依据固定版本源码核对,尚未完成本机 Broker 收发联调;下文输出均为预期现象。

系列位置:消息队列第 7/10 篇,RocketMQ 第 1/3 篇。

先认识六个必要对象

假设订单创建以后,要异步登记一条事件:

  • Producer:创建并发送这条事件的程序。
  • Topic:按业务组织消息,例如 journal_order_events。
  • Queue:Topic 内的逻辑消息队列,同一个 Topic 可以包含多条 Queue。
  • Broker:实际接收、保存消息并维护消费状态的服务。
  • Consumer Group:一个处理业务的订阅身份,例如订单事件登记服务。同一组的多个实例共同处理消息,不同组有各自的消费状态。
  • NameServer 与 Proxy:前者供服务发现使用,后者为本文 5.x Python 客户端提供 gRPC 入口。

本文不需要先记住全部组件细节,先看这张路径图:

Python Producer ----发送----> Proxy ----> Broker ----> 磁盘存储
                                 ^           |
Python SimpleConsumer --获取-----+-----------+
          |
          +-- 业务事务提交 -- ACK --> Proxy/Broker

NameServer:供 Broker/Proxy 获取服务和路由信息

生产者返回发送结果,和消费者返回业务处理结果,是两个不同时间点。订单服务看到发送确认时,下游可能尚未开始处理。官方领域模型

Python 包名要先选对

本篇安装的是 rocketmq-python-client,来自 Apache 的 5.x 客户端集合,使用 from rocketmq import ...。旧包 rocketmq-client-python 依赖 C++ 动态库,常见导入方式为 from rocketmq.client import ...,并通过 NameServer 使用旧客户端模型。两者不是名字顺序可以互换的同一个包。

请新建独立虚拟环境,避免已有旧包占用相同的顶层模块。这里的 SimpleConsumer 显式获取消息并 ACK;不要把旧 PushConsumer 的回调代码粘过来混用。5.x 客户端项目、固定 Python 发行版、旧客户端说明

第一步:启动学习用服务

服务端源码发行版与 Docker 镜像标签要分别核对。核对时官方发行列表已有 5.5.1,但官方镜像标签可用的是 5.5.0;本文固定采用 apache/rocketmq:5.5.0 作为学习基线,不使用 latest,也不把源码下载版本号直接当作可拉取的镜像号。官方镜像标签、镜像发布跟踪

新建一个空目录操作,预留数 GiB 磁盘和约 4 GiB 的 Docker 可用内存。下面缩小 JVM 堆,只用于低流量实验。所有 journal-rmq-demo-* 名称都专供本文;如果已存在同名资源,先检查原资源,不要直接删掉重建。

写入 broker.conf:

brokerClusterName=DefaultCluster
brokerName=journal-demo-broker
brokerId=0
brokerRole=ASYNC_MASTER
flushDiskType=SYNC_FLUSH
brokerIP1=127.0.0.1
listenPort=10911
storePathRootDir=/home/rocketmq/store
storePathCommitLog=/home/rocketmq/store/commitlog
autoCreateTopicEnable=false
autoCreateSubscriptionGroup=false

写入 proxy.json:

{
  "rocketMQClusterName": "DefaultCluster",
  "localServeAddr": "127.0.0.1",
  "grpcServerPort": 18081,
  "remotingListenPort": 18080
}

启动 NameServer,再启动包含本地 Broker 的 Proxy:

# 本文两个示例配置不含密钥,让镜像运行用户能够读取。
chmod 644 broker.conf proxy.json

docker network create journal-rmq-demo-net
docker volume create journal-rmq-demo-store

# 仅初始化本文新专用卷的根目录属主,匹配官方镜像 UID/GID。
docker run --rm --user 0:0 \
  --mount type=volume,src=journal-rmq-demo-store,dst=/data \
  --entrypoint sh apache/rocketmq:5.5.0 \
  -c 'chown 3000:3000 /data'

docker run -d --name journal-rmq-demo-namesrv \
  --network journal-rmq-demo-net \
  -e 'JAVA_OPT_EXT=-Xms256m -Xmx256m -Xmn128m' \
  apache/rocketmq:5.5.0 sh mqnamesrv

docker logs journal-rmq-demo-namesrv

官方镜像以 UID/GID 3000 的 rocketmq 用户运行,因此先初始化专用新卷的属主,避免 Broker 创建存储目录时权限不足。这一步只处理命名卷根目录,不递归修改宿主文件。已有同名卷且用途不明时,先核对,不直接套用初始化命令。官方镜像用户定义

确认 NameServer 日志出现启动成功信息,再执行:

docker run -d --name journal-rmq-demo-broker \
  --network journal-rmq-demo-net \
  -p 127.0.0.1:18081:18081 \
  -e NAMESRV_ADDR=journal-rmq-demo-namesrv:9876 \
  -e 'JAVA_OPT_EXT=-Xms1g -Xmx1g -Xmn256m' \
  --mount "type=bind,src=$PWD/broker.conf,dst=/tmp/journal-broker.conf,readonly" \
  --mount "type=bind,src=$PWD/proxy.json,dst=/tmp/journal-proxy.json,readonly" \
  --mount type=volume,src=journal-rmq-demo-store,dst=/home/rocketmq/store \
  apache/rocketmq:5.5.0 \
  sh mqproxy -pm local -bc /tmp/journal-broker.conf -pc /tmp/journal-proxy.json

docker logs journal-rmq-demo-broker

local 表示 Proxy 与 Broker 组合运行,不是第二个独立集群。这里把容器内 gRPC 端口和宿主机映射都设成 18081,Python 连接 127.0.0.1:18081。只改宿主机映射、却保留路由返回的另一个端口,是常见的连接误区。brokerIP1=127.0.0.1 适用于本例的本地组合模式及容器内管理命令;拆成独立 Proxy、跨机器访问或旧 Remoting 客户端时,要重新规划地址。官方 Docker 入门、5.5.0 Proxy 配置、本地模式启动参数

第二步:显式创建 Topic 与消费组

确认 Broker 和 Proxy 启动成功以后运行:

docker exec journal-rmq-demo-broker sh mqadmin updateTopic \
  -n journal-rmq-demo-namesrv:9876 -c DefaultCluster \
  -t journal_order_events -r 4 -w 4 -a '+message.type=NORMAL'

docker exec journal-rmq-demo-broker sh mqadmin updateSubGroup \
  -n journal-rmq-demo-namesrv:9876 -c DefaultCluster \
  -g journal_order_worker -r 3

这里建普通消息 Topic,四条读写 Queue;消费组最多重试次数显式设为 3。updateTopic 的 -r 是读队列数,updateSubGroup 的 -r 是重试次数,同名短参数属于不同命令,不要混记。

后续每次启动客户端无需重新创建资源。同一消费组内保持订阅 Topic、过滤条件等业务约定一致。订单积分、通知是两个独立业务时,通常应使用两个组,而不是混在同一组里抢同一条消息。Topic 定义、消费组定义、建组命令源码

第三步:准备 Python 环境与生产者

确认 python3 指向 Python 3.12,再安装固定版本:

python3 --version
python3 -m venv .venv
. .venv/bin/activate
python -m pip install 'rocketmq-python-client==5.1.2'

固定版 SDK 默认把日志写到当前用户的 ~/logs/rocketmq_python/,运行用户需要有相应目录权限。导入阶段报权限错误时,先检查用户目录及现有日志目录的属主;不要通过更改 HOME 来掩盖问题。

将下面代码保存为 producer.py。每次创建新事件生成一个 event_id;如果重新发送同一个业务事件,继续使用原事件编号,而不是每次重试换新编号。

import json
import os
import sys
import uuid

from rocketmq import ClientConfiguration, Credentials, Message, Producer

TOPIC = "journal_order_events"
ENDPOINT = os.getenv("RMQ_ENDPOINT", "127.0.0.1:18081")


def main():
    event_id = sys.argv[1] if len(sys.argv) > 1 else str(uuid.uuid4())
    event = {"event_id": event_id, "order_id": "order-1001", "type": "order.created"}
    config = ClientConfiguration(ENDPOINT, Credentials(), request_timeout=5)
    producer = Producer(config, {TOPIC}, tls_enable=False)
    try:
        producer.startup()
        message = Message()
        message.topic = TOPIC
        message.body = json.dumps(event, ensure_ascii=False).encode("utf-8")
        message.keys = event_id
        # 返回凭据只说明发送结果,不代表下游业务处理成功。
        receipt = producer.send(message)
        print(f"发送已确认 event_id={event_id} message_id={receipt.message_id}")
    finally:
        producer.shutdown()


if __name__ == "__main__":
    main()

异常应让调用方知道此次结果没有确认,不要捕获后仍然返回“业务消息发送成功”。网络超时还可能发生在 Broker 已保存、回包却丢失的窗口,因此重新发送与业务幂等要配套设计。

第四步:运行消费者,业务成功后再 ACK

将下面代码保存为 consumer.py。SQLite 是 Python 自带库,本例用插入事件登记记录模拟一个真实业务动作;主键约束提供同一事件重复投递时的去重效果。

import json
import os
import sqlite3
import time

from rocketmq import ClientConfiguration, Credentials, FilterExpression, SimpleConsumer

TOPIC = "journal_order_events"
ENDPOINT = os.getenv("RMQ_ENDPOINT", "127.0.0.1:18081")
GROUP = os.getenv("RMQ_GROUP", "journal_order_worker")
DB_FILE = os.getenv("RMQ_DEMO_DB", "rocketmq_demo.db")


def apply_event(db, message):
    if message.corrupted:
        raise ValueError("消息校验未通过")
    event = json.loads(message.body.decode("utf-8"))
    for field in ("event_id", "order_id", "type"):
        if not isinstance(event.get(field), str) or not event[field]:
            raise ValueError(f"消息缺少有效字段:{field}")
    if event["event_id"] == os.getenv("RMQ_FAIL_EVENT_ID"):
        raise RuntimeError("演示指定事件处理失败")
    # 此处把插入事件记录本身作为业务动作;唯一键与落库在同一事务中完成。
    with db:
        cursor = db.execute(
            "INSERT OR IGNORE INTO order_events(event_id, order_id, event_type) VALUES(?,?,?)",
            (event["event_id"], event["order_id"], event["type"]),
        )
    print(f"业务落库 event_id={event['event_id']} 新增={cursor.rowcount == 1}", flush=True)
    # 仅用于第三篇观察“提交后、ACK前退出”的窗口,正常运行默认不等待。
    time.sleep(float(os.getenv("RMQ_AFTER_COMMIT_SLEEP", "0")))


def main():
    db = sqlite3.connect(DB_FILE, timeout=10)
    db.execute(
        "CREATE TABLE IF NOT EXISTS order_events("
        "event_id TEXT PRIMARY KEY, order_id TEXT NOT NULL, event_type TEXT NOT NULL)"
    )
    db.commit()
    config = ClientConfiguration(ENDPOINT, Credentials(), request_timeout=5)
    consumer = SimpleConsumer(
        config, GROUP, {TOPIC: FilterExpression()}, await_duration=10, tls_enable=False
    )
    try:
        consumer.startup()
        print(f"开始消费 group={GROUP},按 Ctrl+C 退出", flush=True)
        while True:
            try:
                # 一次最多一条,避免批次后部的消息在等待期间耗尽不可见时间。
                messages = consumer.receive(1, 60)
                for message in messages or []:
                    print(
                        f"收到 message_id={message.message_id} attempt={message.delivery_attempt}",
                        flush=True,
                    )
                    apply_event(db, message)
                    # 业务事务成功之后才确认;确认失败时仍允许后续重投。
                    consumer.ack(message)
                    print(f"消费已确认 message_id={message.message_id}", flush=True)
            except Exception as error:
                print(f"本轮未确认,检查日志并等待重投:{error}", flush=True)
                time.sleep(1)
    except KeyboardInterrupt:
        print("停止接收消息", flush=True)
    finally:
        consumer.shutdown()
        db.close()


if __name__ == "__main__":
    main()

先在一个终端启动消费者;另开终端进入同一目录并激活同一虚拟环境,再发送消息:

# 终端一
python consumer.py
# 终端二
. .venv/bin/activate
python producer.py quickstart-event-001

预期看到三类信息:生产者打印“发送已确认”;消费者打印“业务落库”;随后打印“消费已确认”。再次发送相同的 quickstart-event-001,消息仍可能被接收,但本地事件登记只保留一条。

检查实际落库结果:

python -c "import sqlite3; c=sqlite3.connect('rocketmq_demo.db'); print(c.execute('SELECT event_id,order_id,event_type FROM order_events').fetchall()); c.close()"

receive(1, 60) 表示一次最多获取一条,获取后有一段 60 秒的不可见时间。它不是消息保留时间,也不是业务必须休眠 60 秒。正常处理应尽快提交业务并 ACK;持续失败会受到消费组重试策略影响。消费者类型

跑不通时按路径排查

  • 导入 rocketmq.client 才能工作:很可能装的是旧包;回到新虚拟环境检查 python -m pip show rocketmq-python-client。
  • 连接超时:先检查 Docker 容器状态、Proxy 日志及 18081 是否监听,确认 Python 连的是 gRPC 入口。
  • 找不到 Topic、组或类型不匹配:检查显式建资源命令是否成功、Topic 是否为 NORMAL。
  • 生产者成功但消费者没日志:先启动消费者再新发一个事件,并核对组名、订阅和过滤条件。
  • 一直重复接收:检查业务异常、ACK 异常及处理耗时,不要靠提前 ACK 掩盖问题。

停止实验只需停止本文容器,命名卷保留数据:

docker stop journal-rmq-demo-broker journal-rmq-demo-namesrv

学习完成标准:能解释 Topic、Queue 与消费组的区别,能运行一发一收,并明确“业务事务提交后才确认”的位置。下一篇继续看消息正文与消费索引究竟存在哪里。

参考与版本核对

资料核对日期:2026-10-31。服务端发行列表、可用镜像标签与Python 5.1.2 发行记录分别核对。固定 SDK 已在 Python 3.10 隔离环境完成安装、导入和方法签名检查;本文目标 Python 3.12、容器启动与收发仍需在目标机器复验。本文不包含集群容灾或真实生产性能承诺。

记录过程,也留下判断。

← 继续阅读其他文章