RocketMQNotes

第 02 章：环境搭建

zjc 于 2026-01-02 发布

这是《RocketMQ 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 本章从单机、Docker 到生产集群逐步搭建 RocketMQ 环境。学习环境可以简化部署，生产环境必须考虑多副本、磁盘、监控、安全和管理工具。

2.1 版本选择

常见版本：

版本 定位
RocketMQ 4.x 传统 NameServer + Broker 架构，生产使用广泛
RocketMQ 5.x 引入 Proxy、Controller、新客户端与云原生能力

新项目建议选择当前稳定 5.x 版本，同时评估：

  1. 客户端版本兼容性；
  2. 是否使用 Proxy；
  3. Controller 或 DLedger 高可用模式；
  4. 运维平台支持；
  5. 社区文档和问题修复情况。

不要在生产中直接使用最新快照版本。

2.2 下载与目录

wget https://archive.apache.org/dist/rocketmq/5.3.1/rocketmq-all-5.3.1-bin-release.zip
unzip rocketmq-all-5.3.1-bin-release.zip
cd rocketmq-all-5.3.1-bin-release

目录结构：

bin/       启动脚本
conf/      配置文件
lib/       依赖 jar
logs/      日志目录

如果下载地址失效，以 Apache RocketMQ 官方下载页为准。

2.3 启动 NameServer

Linux：

nohup sh bin/mqnamesrv > logs/namesrv.log 2>&1 &

验证：

jps -l
netstat -lntp | grep 9876

NameServer 默认监听 9876。学习环境可单节点，生产至少部署多个节点。

2.4 启动 Broker

nohup sh bin/mqbroker -n localhost:9876 \
  -c conf/broker.conf \
  > logs/broker.log 2>&1 &

关键配置：

brokerClusterName=DefaultCluster
brokerName=broker-a
brokerId=0
namesrvAddr=localhost:9876
brokerIP1=192.168.1.10
listenPort=10911
storePathRootDir=/data/rocketmq/store
autoCreateTopicEnable=false

验证进程：

jps -l
tail -f logs/broker.log

2.5 命令行验证

创建 Topic：

sh bin/mqadmin updateTopic -n localhost:9876 \
  -c DefaultCluster \
  -t OrderTopic \
  -r 8 \
  -w 8

查看 Topic：

sh bin/mqadmin topicList -n localhost:9876
sh bin/mqadmin topicStatus -n localhost:9876 -t OrderTopic

生产消息：

sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer

消费消息：

sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer

官方示例包中的默认 Topic 和地址可能随版本变化，使用时按当前源码修改。

2.6 关闭服务

sh bin/mqshutdown broker
sh bin/mqshutdown namesrv

顺序说明：

  1. 先停应用流量；
  2. 再停 Broker；
  3. 最后停 NameServer；
  4. 生产环境按节点逐个操作；
  5. 停止前确认副本同步状态。

2.7 Docker Compose

示例 docker-compose.yml：

services:
  namesrv:
    image: apache/rocketmq:5.3.1
    command: sh mqnamesrv
    ports:
      - "9876:9876"

  broker:
    image: apache/rocketmq:5.3.1
    command: sh mqbroker -n namesrv:9876
    depends_on:
      - namesrv
    ports:
      - "10911:10911"
    volumes:
      - ./broker.conf:/home/rocketmq/conf/broker.conf

注意：

  1. brokerIP1 必须是客户端可访问 IP；
  2. 数据目录要挂载；
  3. 容器内存要足够；
  4. 生产不建议单容器单副本；
  5. 网络要固定，避免路由漂移。

2.8 Dashboard

RocketMQ Dashboard 常用于查看 Topic、消费组、消息和位点。

git clone https://github.com/apache/rocketmq-dashboard.git
cd rocketmq-dashboard
mvn spring-boot:run

配置：

rocketmq.config.namesrvAddr=localhost:9876

Dashboard 功能：

  1. Topic 管理；
  2. 消费组状态；
  3. 消息查询；
  4. 位点重置；
  5. Broker 状态；
  6. 死信查看。

生产必须开启认证和权限控制，避免误操作重置位点。

2.9 生产环境部署清单

1. 至少多个 NameServer
2. Broker 主从或多副本
3. 独立数据盘和监控盘
4. RAID 或云盘性能验证
5. 时钟同步
6. JVM 参数固定
7. 日志滚动
8. 监控 exporter
9. 控制台权限
10. 备份和恢复演练

建议 Linux 参数：

ulimit -n 102400

磁盘目录：

/data/rocketmq/store
/data/rocketmq/commitlog
/data/rocketmq/consumequeue
/data/rocketmq/index

2.10 常见启动问题

问题 排查
Broker 注册失败 namesrvAddr、网络、防火墙
客户端连接失败 brokerIP1 配置错误
启动内存不足 JVM 堆配置过大
Topic 不存在 autoCreateTopicEnable 或手动创建
磁盘满 保留策略和监控
进程消失 OOM、磁盘、systemd 限制
权限不足 数据目录属主

查看日志：

tail -200 logs/broker.log
tail -200 logs/store.log
tail -200 logs/rocketmqlogs/broker.log

不同发行包日志目录可能不同，以实际文件为准。

本章小结

学习环境可以用二进制包或 Docker 快速启动 NameServer 和 Broker，并用 mqadmin 创建 Topic 验证收发。生产环境必须关闭自动创建 Topic、配置客户端可访问的 brokerIP1、部署多副本、规划磁盘和日志，并提前部署监控与管理工具。

思考题

  1. 为什么生产不建议开启 autoCreateTopicEnable？
  2. brokerIP1 配错会造成什么问题？
  3. 单机环境和生产环境的核心差异有哪些？
  4. RocketMQ Dashboard 需要重点控制哪些权限？
  5. 如何设计一个最小三节点测试集群？