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、容器启动与收发仍需在目标机器复验。本文不包含集群容灾或真实生产性能承诺。
记录过程,也留下判断。
← 继续阅读其他文章