文档版本V1.0 编写日期2026‑09‑05 部署环境Docker Swarm RocketMQ版本5.3.0 Dashboard版本1.0.1 集群架构1×NameServer 3×Broker节点 Dashboard控制台开启ACL权限控制说明本文所有 IP、AccessKey/SecretKey 均为演示示例切勿直接用于生产环境部署时请替换为自己服务器真实 IP并重新设置高强度账号密码。环境Docker Swarm 集群RocketMQ 版本5.3.0Dashboard 版本1.0.1 架构1×NameServer 3×Broker 节点 Dashboard开启 ACL 权限管控。⚠️重要坑点提醒Docker Swarm 的 config 是只读挂载mqadmin updateAclConfig热更新 ACL 不会生效修改 ACL 必须重建 config重新 deploy stack。一、环境概述本次部署采用Docker Swarm Stack方式部署RocketMQ5.3.0集群。部署节点主机名mq‑docker‑node主机IP192.168.10.38私有镜像仓库地址192.168.10.74:7080/library/集群组件清单NameServer1个实例RocketMQ注册中心Broker‑a / broker‑b / broker‑c3个Broker服务节点RocketMQ‑Dashboard可视化管理控制台安全特性开启ACL访问权限控制区分管理员账号、业务账号。⚠️重要提醒Docker Swarm的config配置为只读挂载不支持mqadmin工具热更新ACL配置。修改ACL配置必须重建config重新部署stack才能生效。 ✅提示本文所有IP、账号密码均为示例实际部署请自行修改为自己环境的信息。二、端口规划所有端口均为TCP协议防火墙需要放行宿主机对应端口。组件名称容器内部端口宿主机映射端口说明NameServer98769111MQ注册中心客户端连接地址Broker‑a91109110消息broker节点aBroker‑b91089108消息broker节点bBroker‑c91099109消息broker节点cDashboard控制台80809114web管理页面访问端口三、部署前置条件Docker Swarm集群已经完成初始化mq‑docker‑node节点已经加入swarm集群。部署节点可以正常访问私有镜像仓库192.168.10.74:7080能够拉取镜像。服务器防火墙/安全组开放端口9111、9110、9108、9109、9114。服务器时间同步容器挂载/etc/localtime保证容器与宿主机时间一致。四、前期准备工作4.1 创建Docker外部存储卷本方案全部使用external外部存储卷数据独立于容器删除服务不会丢失业务数据。执行下面命令创建存储卷docker volume create rmqnamesrv_logs docker volume create rmqbroker_a_store docker volume create rmqbroker_a_logs docker volume create rmqbroker_b_store docker volume create rmqbroker_b_logs docker volume create rmqbroker_c_store docker volume create rmqbroker_c_logs docker volume create dashboard_data4.2 准备配置文件在宿主机新建工作目录将下面5个文件保存到此目录文件名严格保持一致。4.2.1 plain_acl.yml ACL权限配置文件文件名plain_acl.ymlglobalWhiteRemoteAddresses: - 127.0.0.1 - 192.168.10.* accounts: #管理帐号 - accessKey: mq_admin secretKey: Admin123456 admin: true whiteRemoteAddress: # 业务帐号 mq_biz - accessKey: mq_biz secretKey: Biz654321 whiteRemoteAddress: admin: false defaultTopicPerm: SUB defaultGroupPerm: SUB topicPerms: - BIZ_TOPICPUB|SUB groupPerms: - BIZ_TOPICPUB|SUB账号说明mq_admin管理员账号用于Dashboard登录、mqadmin运维命令。mq_biz业务账号仅对BIZ_TOPIC主题具备发布、订阅权限。⚠️生产环境务必修改AccessKey、SecretKey不要直接使用示例密码。4.2.2 mq53broker‑a.conf broker‑a配置文件名mq53broker‑a.conf# 集群与节点名称 brokerClusterName DefaultCluster brokerName broker-a # 改成你的服务器实际IP brokerIP1 192.168.10.38 brokerVipEnablefalse namesrvAddr rmqnamesrv:9876 listenPort 9110 aclEnabletrue #此处配置项只需要一个就行配置两个是为了兼容不同的版本 aclFile/home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml aclPlainConfigFile/home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml4.2.3 mq53broker‑b.conf broker‑b配置文件名mq53broker‑b.conf# 集群与节点名称 brokerClusterName DefaultCluster brokerName broker-b # 改成你的服务器实际IP brokerIP1 192.168.10.38 brokerVipEnablefalse namesrvAddr rmqnamesrv:9876 listenPort 9108 aclEnabletrue #此处配置项只需要一个就行配置两个是为了兼容不同的版本 aclFile/home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml aclPlainConfigFile/home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml4.2.4 mq53broker‑c.conf broker‑c配置文件名mq53broker‑c.conf# 集群与节点名称 brokerClusterName DefaultCluster brokerName broker-c # 改成你的服务器实际IP brokerIP1 192.168.10.38 brokerVipEnablefalse namesrvAddr rmqnamesrv:9876 listenPort 9109 aclEnabletrue #此处配置项只需要一个就行配置两个是为了兼容不同的版本 aclFile/home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml aclPlainConfigFile/home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml4.2.5 mq53topics.txt Topic脚本文件文件名mq53topics.txt可以为空文件用于shell脚本批量创建topic如果不需要脚本创建topic直接新建空白文件即可。4.3 创建Docker Swarm Config配置对象进入配置文件存放目录执行命令将本地文件上传为swarm外部config对象docker config create plain_acl.yml plain_acl.yml docker config create mq53broker-a.conf mq53broker‑a.conf docker config create mq53broker-b.conf mq53broker‑b.conf docker config create mq53broker-c.conf mq53broker‑c.conf docker config create mq53topics.txt mq53topics.txt修改配置文件通用流程修改宿主机本地配置文件删除旧config对象docker config rm 配置名使用docker config create重新创建重新执行docker stack deploy更新服务。五、Docker‑Compose Stack编排文件文件名docker‑compose‑rmq53.ymlversion: 3.4 services: rmqnamesrv: image: 192.168.10.74:7080/library/rocketmq:5.3.0 command: sh mqnamesrv environment: - JAVA_OPT_EXT-Xms256M -Xmx256M -Xmn128M deploy: replicas: 1 # 改为 any进程无论何种退出码都拉起长期自愈 restart_policy: condition: any delay: 16s placement: constraints: - node.hostname mq‑docker‑node ports: - published: 9111 target: 9876 protocol: tcp mode: host volumes: - rmqnamesrv_logs:/home/rocketmq/rocketmq-5.3.0/logs - /etc/localtime:/etc/localtime:ro networks: - rocketmq rmqbroker-a: image: 192.168.10.74:7080/library/rocketmq:5.3.0 deploy: replicas: 1 restart_policy: condition: any delay: 16s placement: constraints: - node.hostname mq‑docker‑node ports: - published: 9110 target: 9110 protocol: tcp mode: host configs: - source: mq53broker-a.conf target: /home/rocketmq/rocketmq-5.3.0/conf/mq53broker-a.conf # 注意swarm config 只读挂载mqadmin updateAclConfig 热更新会失败 # 改 ACL 只能 docker config create 新版本后重新 deploy - source: plain_acl.yml target: /home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml - source: mq53topics.txt target: /home/rocketmq/rocketmq-5.3.0/bin/mq53topics.txt command: sh mqbroker -c /home/rocketmq/rocketmq-5.3.0/conf/mq53broker-a.conf environment: - NAMESRV_ADDRrmqnamesrv:9876 - JAVA_OPT_EXT-Xms512M -Xmx512M -Xmn192M # swarm stack deploy 会忽略 depends_onbroker 自行重连 namesrv保留仅为可读性 depends_on: - rmqnamesrv volumes: - rmqbroker_a_store:/home/rocketmq/rocketmq-5.3.0/store - rmqbroker_a_logs:/home/rocketmq/rocketmq-5.3.0/logs - /etc/localtime:/etc/localtime:ro networks: - rocketmq rmqbroker-b: image: 192.168.10.74:7080/library/rocketmq:5.3.0 deploy: replicas: 1 restart_policy: condition: any delay: 16s placement: constraints: - node.hostname mq‑docker‑node ports: - published: 9108 target: 9108 protocol: tcp mode: host configs: - source: mq53broker-b.conf target: /home/rocketmq/rocketmq-5.3.0/conf/mq53broker-b.conf - source: plain_acl.yml target: /home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml command: sh mqbroker -c /home/rocketmq/rocketmq-5.3.0/conf/mq53broker-b.conf environment: - NAMESRV_ADDRrmqnamesrv:9876 - JAVA_OPT_EXT-Xms512M -Xmx512M -Xmn192M depends_on: - rmqnamesrv volumes: - rmqbroker_b_store:/home/rocketmq/rocketmq-5.3.0/store - rmqbroker_b_logs:/home/rocketmq/rocketmq-5.3.0/logs - /etc/localtime:/etc/localtime:ro networks: - rocketmq rmqbroker-c: image: 192.168.10.74:7080/library/rocketmq:5.3.0 deploy: replicas: 1 restart_policy: condition: any delay: 16s placement: constraints: - node.hostname mq‑docker‑node ports: - published: 9109 target: 9109 protocol: tcp mode: host configs: - source: mq53broker-c.conf target: /home/rocketmq/rocketmq-5.3.0/conf/mq53broker-c.conf - source: plain_acl.yml target: /home/rocketmq/rocketmq-5.3.0/conf/plain_acl.yml command: sh mqbroker -c /home/rocketmq/rocketmq-5.3.0/conf/mq53broker-c.conf environment: - NAMESRV_ADDRrmqnamesrv:9876 - JAVA_OPT_EXT-Xms512M -Xmx512M -Xmn192M depends_on: - rmqnamesrv volumes: - rmqbroker_c_store:/home/rocketmq/rocketmq-5.3.0/store - rmqbroker_c_logs:/home/rocketmq/rocketmq-5.3.0/logs - /etc/localtime:/etc/localtime:ro networks: - rocketmq dashboard: image: 192.168.10.74:7080/library/rocketmq-dashboard:1.0.1 deploy: replicas: 1 restart_policy: condition: any delay: 16s placement: constraints: - node.hostname mq‑docker‑node networks: - rocketmq depends_on: - rmqnamesrv ports: - published: 9114 target: 8080 protocol: tcp mode: host environment: - JAVA_OPTS-Drocketmq.namesrv.addrrmqnamesrv:9876 - JAVA_OPT_EXT-Xms256M -Xmx256M -Xmn128M - rocketmq.config.accessKeymq_admin - rocketmq.config.secretKeyAdmin123456 - rocketmq.config.isVIPChannelfalse - rocketmq.config.loginRequiredtrue # 登录用户loginRequiredtrue默认存在容器内文件重建容器即丢失 # 若在页面上维护过用户/角色建议按实际 dataPath 挂卷持久化 volumes: - dashboard_data:/tmp/rocketmq-console/data - /etc/localtime:/etc/localtime:ro networks: rocketmq: volumes: rmqnamesrv_logs: external: true rmqbroker_a_store: external: true rmqbroker_a_logs: external: true rmqbroker_b_store: external: true rmqbroker_b_logs: external: true rmqbroker_c_store: external: true rmqbroker_c_logs: external: true dashboard_data: external: true configs: plain_acl.yml: external: true mq53broker-a.conf: external: true mq53broker-b.conf: external: true mq53broker-c.conf: external: true mq53topics.txt: external: true六、集群部署启动6.1 执行部署命令将上面docker‑compose‑rmq53.yml放到工作目录执行部署栈命名为rmq53docker stack deploy -c docker‑compose‑rmq53.yml rmq536.2 查看集群服务状态docker stack services rmq53输出列表中所有服务的REPLICAS列显示1/1代表实例启动成功。如果状态不为1/1使用docker service logs 服务名查看服务日志排查启动异常。七、Dashboard控制台访问访问地址http://192.168.10.38:9114项目参数值AccessKeymq_adminSecretKeyAdmin123456说明dashboard开启登录鉴权使用ACL管理员账号登录页面上创建的用户角色数据保存在dashboard_data外部卷实现持久化。 ⚠️实际部署替换为自己服务器IP同时修改账号密码。八、业务客户端接入配置客户端连接NameServer地址192.168.10.38:9111业务账号mq_biz参数accessKeymq_biz secretKeyBiz654321权限说明业务账号仅允许对BIZ_TOPIC主题进行消息发布PUB、消息订阅SUB。九、日常运维操作手册9.1 修改ACL权限配置流程❗重要swarm config只读挂载mqadmin updateAclConfig热更新命令不会生效。 完整修改步骤修改宿主机本地plain_acl.yml配置删除旧config对象docker config rm plain_acl.yml重新创建configdocker config create plain_acl.yml plain_acl.yml更新stack使配置生效docker stack deploy -c docker‑compose‑rmq53.yml rmq539.2 JVM内存参数调整说明组件默认JVM参数NameServer-Xms256M -Xmx256M -Xmn128MBroker-Xms512M -Xmx512M -Xmn192MDashboard-Xms256M -Xmx256M -Xmn128M修改方式修改docker‑compose‑rmq53.yml文件中JAVA_OPT_EXT环境变量重新执行docker stack deploy即可更新JVM参数。9.3 集群停止、重启操作停止集群数据卷、config配置全部保留业务数据不会丢失docker stack rm rmq53停止后重新启动集群直接再次执行部署命令即可docker stack deploy -c docker‑compose‑rmq53.yml rmq539.4 资源清理命令谨慎执行执行后数据丢失清理config配置对象docker config rm plain_acl.yml mq53broker-a.conf mq53broker-b.conf mq53broker-c.conf mq53topics.txt⚠️清理存储卷消息、日志全部删除生产环境严禁随意执行docker volume rm rmqnamesrv_logs rmqbroker_a_store rmqbroker_a_logs rmqbroker_b_store rmqbroker_b_logs rmqbroker_c_store rmqbroker_c_logs dashboard_data十、常见问题与注意事项depends_on不生效问题Docker Swarm stack会忽略yaml中的depends_on依赖配置。Broker服务内部会自动循环重试连接NameServer不需要等待nameServer完全启动。ACL权限不生效确认broker.conf配置中aclEnabletrue确认plain_acl.yml已经通过docker config重新创建并且stack已经重新deploy确认客户端传入accessKey、secretKey正确。客户端连接失败检查防火墙端口放行确认brokerIP1配置为宿主机真实IP不要使用127.0.0.1确认NameServer连接地址填写宿主机9111端口。数据持久化说明所有消息存储、日志、dashboard用户数据全部使用external外部volume执行docker stack rm rmq53不会删除volume只有手动执行docker volume rm才会删除数据。安全风险提示本文档中AccessKey、SecretKey、IP均为演示示例生产环境部署务必修改账号密码、修改为实际服务器IP不要直接复制示例配置直接上线。总结本方案使用 Docker Swarm 外部 config 存放配置文件外部 volume 持久化消息与日志删除 stack 不会丢失业务数据swarm config 只读特性ACL 无法热更新修改权限配置需要重建 config生产环境务必修改示例 IP、accessKey、secretKey做好防火墙端口管控可根据服务器内存调整 JVM 的JAVA_OPT_EXT参数优化性能。具体实施操作步骤另外附带批量topic创建脚本【中间件部署】基于DockerSwarm的RocketMQ5.3.0集群部署含ACL权限控制与Dashboard监控的微服务消息队列实施方案资源-CSDN下载https://download.csdn.net/download/zhaojun917/93394051