RocketMQ 5.1.0 + Dashboard Docker 生产部署方案

RocketMQ 5.1.0 + Dashboard Docker 生产部署方案

部署日期：2026-07-09
组件：apache/rocketmq:5.1.0 · apacherocketmq/rocketmq-dashboard:2.0.0
架构：单 NameServer + 单 Broker（已知单点风险，资源受限下的生产取舍）
鉴权：Broker ACL (plain_acl.yml) + Dashboard 凭证

---

架构概览

[客户端] → NameServer(:9876) → Broker(:10911) ← Dashboard(:8080) ↓ rmq-exporter(:5557) ← Prometheus 容器网络：rocketmq-net (bridge)

---

Step 0 — 宿主机 OS 调参（必做）

cat>>/etc/sysctl.conf<<'EOF' vm.max_map_count=262144 vm.overcommit_memory=1 net.core.somaxconn=32768 net.ipv4.tcp_max_syn_backlog=16384 EOFsysctl-pcat>>/etc/security/limits.conf<<'EOF' * soft nofile 655350 * hard nofile 655350 EOF

---

Step 1 — 创建 Docker 网络并获取子网段

必须先建网络，再查子网，再写配置文件，顺序不能乱。

dockernetwork create rocketmq-net

查询子网（用于后续 plain_acl.yml 白名单配置）：

dockernetwork inspect rocketmq-net--format'{{range .IPAM.Config}}{{.Subnet}}{{end}}'# 示例输出：172.23.0.0/16

将子网转换为 ACL 白名单格式：取前三段加.*

Docker 子网	ACL 白名单格式
172.23.0.0/16	172.23.0.*
172.18.0.0/16	172.18.0.*
192.168.100.0/24	192.168.100.*

⚠️ RocketMQ ACL只支持单通配符（172.23.0.*），不支持双通配符（172.23.*.*）。
双通配符会被内部转成 CIDR 格式（172.23.0.0/16），而 ACL 又不支持 CIDR，导致启动崩溃。

---

Step 2 — 准备目录与配置文件

mkdir-p/data/rocketmq/namesrv/logs/rocketmqlogsmkdir-p/data/rocketmq/broker/{conf,logs,store}mkdir-p/data/rocketmq/console/conf# 设置目录权限（rocketmq 用户 UID=3000）chown-R3000:3000 /data/rocketmq/namesrv/logschown-R3000:3000 /data/rocketmq/broker/logschown-R3000:3000 /data/rocketmq/broker/store

broker.conf

路径：/data/rocketmq/broker/conf/broker.conf

brokerClusterName=DefaultCluster brokerName=broker-a brokerId=0 brokerRole=ASYNC_MASTER flushDiskType=ASYNC_FLUSH namesrvAddr=namesrv:9876 # ⚠️ 填宿主机真实 IP，否则客户端从 NameServer 拿到容器内网 IP 无法连接 brokerIP1=172.27.191.15 # 生产必须关闭，防止业务代码写错 Topic 名乱建 autoCreateTopicEnable=false autoCreateSubscriptionGroup=false # ACL 鉴权 aclEnable=true # 消息保留 deleteWhen=04 fileReservedTime=72 # CommitLog 单文件 1GB mapedFileSizeCommitLog=1073741824 # 存储路径 storePathRootDir=/home/rocketmq/store storePathCommitLog=/home/rocketmq/store/commitlog

plain_acl.yml

路径：/data/rocketmq/broker/conf/plain_acl.yml

使用 python3 写入，避免 heredoc 换行丢失问题（将172.23.0.*替换为 Step 1 查到的实际子网）：

python3-c" content = ''' globalWhiteRemoteAddresses: - 172.18.0.* accounts: - accessKey: rocketmqAdmin secretKey: Admin@Rmq2024! admin: true defaultTopicPerm: PUB|SUB defaultGroupPerm: SUB topicPerms: [] groupPerms: [] - accessKey: appUser secretKey: App@Rmq2024! admin: false defaultTopicPerm: PUB|SUB defaultGroupPerm: SUB topicPerms: [] groupPerms: [] ''' open('/data/rocketmq/broker/conf/plain_acl.yml', 'w').write(content) print('written') "

验证文件格式（两个账号之间必须有空行）：

cat/data/rocketmq/broker/conf/plain_acl.yml

---

Step 3 — 启动容器

⚠️ 关键约束：

• -e "KEY=value"内部不能用\换行，所有 JVM 参数必须写在一行
• !字符在 bash 双引号中触发 history expansion，用\!转义，或执行前set +H
• 健康检查用bash -c '</dev/tcp/localhost/PORT>'，容器内无ss/netstat

① NameServer

dockerrun-d\--namenamesrv\--networkrocketmq-net\--restartunless-stopped\--ulimitnofile=655350\--memory=512m --memory-swap=512m\--cpus=0.5\-p9876:9876\-v/data/rocketmq/namesrv/logs:/home/rocketmq/logs\-e"JAVA_OPT_EXT=-server -Xms256m -Xmx256m"\--health-cmd="bash -c '</dev/tcp/localhost/9876'"\--health-interval=15s --health-timeout=5s --health-retries=3\apache/rocketmq:5.1.0shmqnamesrv

② Broker

dockerrun-d\--namebroker\--networkrocketmq-net\--restartunless-stopped\--ulimitnofile=655350\--memory=2g --memory-swap=2g\--cpus=4\-p10909:10909\-p10911:10911\-p10912:10912\-v/data/rocketmq/broker/conf/broker.conf:/home/rocketmq/rocketmq-5.1.0/conf/broker.conf\-v/data/rocketmq/broker/conf/plain_acl.yml:/home/rocketmq/rocketmq-5.1.0/conf/plain_acl.yml\-v/data/rocketmq/broker/logs:/home/rocketmq/logs\-v/data/rocketmq/broker/store:/home/rocketmq/store\-e"JAVA_OPT_EXT=-server -Xms1g -Xmx1g -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/home/rocketmq/logs/heapdump.hprof"\--health-cmd="bash -c '</dev/tcp/localhost/10911'"\--health-interval=30s --health-timeout=10s --health-retries=3\apache/rocketmq:5.1.0\shmqbroker-c/home/rocketmq/rocketmq-5.1.0/conf/broker.conf

③ Dashboard

styletang/rocketmq-console-ng不支持 ACL，必须用apacherocketmq/rocketmq-dashboard:2.0.0。
2.0.0内部端口 8080。JAVA_OPTS对该镜像无效（entrypoint 不展开此变量），必须用SPRING_APPLICATION_JSON传配置。

dockerrun-d\--namerocketmq-dashboard\--networkrocketmq-net\--restartunless-stopped\--memory=512m --memory-swap=512m\--cpus=0.5\-p8080:8080\-e'SPRING_APPLICATION_JSON={"rocketmq":{"config":{"namesrvAddr":"namesrv:9876","isVIPChannel":false,"accessKey":"rocketmqAdmin","secretKey":"Admin@Rmq2024!"}}}'\apacherocketmq/rocketmq-dashboard:2.0.0

④ Prometheus Exporter（监控）

dockerrun-d\--namermq-exporter\--networkrocketmq-net\--restartunless-stopped\--memory=256m\-p5557:5557\-e"ROCKETMQ_CONFIG_NAMESRVADDR=namesrv:9876"\-e"ROCKETMQ_CONFIG_WEBTELEMETRYPATH=/metrics"\-e"rocketmq.config.accessKey=rocketmqAdmin"\-e"rocketmq.config.secretKey=Admin@Rmq2024!"\apache/rocketmq-exporter:0.0.2

Prometheusscrape_configs加入http://YOUR_HOST:5557/metrics，Grafana 导入 Dashboard ID10477。

---

Step 4 — 验证

# 查看所有容器状态dockerps--format"table {{.Names}}\t{{.Status}}\t{{.Ports}}"# Broker 日志确认 ACL 加载（无 AclException 即正常）dockerlogs broker2>&1|grep-i"acl\|boot success\|exception"|tail-10# NameServer 验证 Broker 注册dockerexecnamesrvshmqadmin clusterList-nlocalhost:9876# 访问 Dashboard# http://YOUR_HOST_IP:8080

---

修改 plain_acl.yml 后的正确流程

⚠️docker restart会保留容器 overlay 层，导致仍读旧文件。必须重建容器。

# 1. 修改宿主机文件（用 python3 写，避免 heredoc 换行问题）python3-c"...">/data/rocketmq/broker/conf/plain_acl.yml# 2. 验证宿主机文件正确cat/data/rocketmq/broker/conf/plain_acl.yml# 3. 删容器重建（不要用 restart）dockerrm-fbrokerdockerrun-d...# 完整启动命令

---

关键注意事项汇总

项目	说明
brokerIP1	必须填宿主机真实 IP，否则客户端无法连接
ACL 白名单格式	只支持单通配符172.23.0.*，不支持172.23.*.*（会崩）也不支持 CIDR
修改 ACL 文件后	必须docker rm -f+docker run重建，不能restart
-e中的 JVM 参数	不能用\换行，所有参数写一行
!字符	bash 双引号内需转义\!，或先执行set +H
日志目录权限	chown -R 3000:3000设置 rocketmq UID
健康检查命令	容器无ss/netstat，用bash -c '</dev/tcp/localhost/PORT>'
Console 选型	styletang/rocketmq-console-ng不支持 ACL，必须用rocketmq-dashboard:2.0.0
autoCreateTopicEnable=false	生产必须关闭，Topic 通过 Dashboard 或 mqadmin 预先创建
plain_acl.yml热更新	修改后60 秒内自动生效（但 overlay 问题需重建容器）

---

资源分配参考（8核16G宿主机）

容器	--memory	--cpus	堆内存
namesrv	512m	0.5	256m
broker	2g	4	1g
dashboard	512m	0.5	256m
rmq-exporter	256m	0.25	—

---

客户端 ACL 配置参考（Java）

方案 A：rocketmq-spring-boot-starter（推荐）

# application-test.ymlrocketmq:name-server:localhost:9876producer:group:your-group# 不写 access-key / secret-key = 不启用 ACL# application-prod.ymlrocketmq:name-server:172.16.0.6:9876producer:group:your-groupaccess-key:appUsersecret-key:App@Rmq2024!

方案 B：手动构建 Producer

# application-test.ymlrocketmq:acl.enabled:false# application-prod.ymlrocketmq:acl.enabled:trueacl.access-key:appUseracl.secret-key:App@Rmq2024!

@ConfigurationpublicclassRocketMQConfig{@Value("${rocketmq.acl.enabled:false}")privatebooleanaclEnabled;@Value("${rocketmq.acl.access-key:}")privateStringaccessKey;@Value("${rocketmq.acl.secret-key:}")privateStringsecretKey;@Bean(destroyMethod="shutdown")publicDefaultMQProducerproducer()throwsMQClientException{RPCHookhook=aclEnabled?newAclClientRPCHook(newSessionCredentials(accessKey,secretKey)):null;DefaultMQProducerproducer=newDefaultMQProducer("your-group",hook);producer.setNamesrvAddr("172.16.0.6:9876");producer.start();returnproducer;}}

---

端口汇总

端口	组件	用途
9876	NameServer	客户端注册/查询
10909	Broker	fastRemoting
10911	Broker	remoting（主通信端口）
10912	Broker	HA 同步（预留）
8080	Dashboard	Web UI
5557	rmq-exporter	Prometheus 指标