今天，我决定在本地用Docker搭建一个 Apache RocketMQ 环境，用于学习消息队列。原本以为简单复制粘贴命令就能跑起来，谁知踩了一堆坑，从 NameServer连接失败，到 Dashboard 端口错乱，再到 ACL 签名诡异报错……过程曲折，但最终大功告成！这篇文章记录了整个心路历程，感谢一位AI助手（Grok）的耐心指导。如果您也想玩 RocketMQ ，希望我的血泪史能帮您避坑。

前言：为什么选 RocketMQ ？它支持高吞吐、低延迟、分布式事务，适合微服务解耦。版本用 4.4.0（旧但稳定），Docker 镜像 rocketmqinc/rocketmq。

1. 环境准备：基础容器启动

一切从 NameServer 开始。它是 RocketMQ 的 “黄页”，Broker 和客户端都靠它发现彼此。

• 启动 NameServer：

  docker run -d --name rmqnamesrv -p 9876:9876 rocketmqinc/rocketmq sh mqnamesrv

• 启动 Broker

  （Master 模式，加配置卷）： 先创建 broker.conf 文件（内容：brokerClusterName=DefaultCluster; brokerName=broker-a; brokerId=0; deleteWhen=04; fileReservedTime=48; brokerRole=ASYNC_MASTER; flushDiskType=ASYNC_FLUSH）。

  docker run -d --name rmqbroker -p 10909:10909 -p 10911:10911 --network rocketmq \
  -v /path/to/broker.conf:/opt/rocketmq-4.4.0/conf/broker.conf \
  -e "NAMESRV_ADDR=rmqnamesrv:9876" \
  rocketmqinc/rocketmq sh mqbroker -c /opt/rocketmq-4.4.0/conf/broker.conf

  坑1：忘记加 -e "NAMESRV_ADDR=rmqnamesrv:9876"，Broker不会注册，导致后续查询null。

• 网络设置：创建自定义网络 docker network create rocketmq，并 connect 所有容器，确保容器间解析（如 rmqnamesrv:9876）。

2. Dashboard控制台：可视化监控的救星

用 apacherocketmq/rocketmq-dashboard:latest 镜像。

• 启动命令：

  docker run -d --name rmq-dashboard -p 8080:8082 --network rocketmq \
  -e "JAVA_OPTS=-Xms256m -Xmx256m -Drocketmq.namesrv.addr=rmqnamesrv:9876 -Dcom.rocketmq.sendMessageWithVIPChannel=false" \
  apacherocketmq/rocketmq-dashboard:latest

• 坑2：端口不匹配。镜像默认Tomcat监听8082，不是8080。映射用-p 8080:8082。访问http://localhost:8080，登录admin/admin。

• 坑3：RemotingConnectException: connect to null failed。页面弹出此错，是因为Broker未注册或ACL干扰。解决：检查Broker日志（docker logs rmqbroker，应有"boot success... name server is namesrv:9876"），重启Dashboard。

• 坑4：mqadmin命令ACL签名失败（HmacSHA1 not available）。容器JDK bug！解决：在主机下载RocketMQ二进制包，用本地mqadmin clusterList -n localhost:9876验证集群。或加卷修复日志路径 /v /host/path:/root/logs。

最后终于成功：

3. 功能验证：创建Topic和发消息

• 创建Topic：主机 mqadmin updateTopic -n localhost:9876 -t TestTopic -c DefaultCluster。

• 坑5：容器 mqadmin 报 FileNotFound 和 ACL。绕过用主机工具，或 Broker conf 加 autoCreateTopicEnable=true 自动创建。

• 测试：Dashboard 的 Message > Send Message 发送，Query 查询。或命令 docker exec -it rmqbroker ping rmqnamesrv 确认连通。

4. Spring Boot集成：HelloWorld实战

搭建一个简单 Producer/Consumer。

• POM依赖：

  <dependency>
      <groupId>org.apache.rocketmq</groupId>
      <artifactId>rocketmq-spring-boot-starter</artifactId>
      <version>2.3.0</version>
  </dependency>

• application.yml：

  rocketmq:
    name-server: localhost:9876
    producer:
      group: producer-group

• 代码：Producer用RocketMQTemplate.syncSend，Consumer用@RocketMQMessageListener 监听。启动类@PostConstruct发消息。

• 运行：mvn package 后 java -jar。控制台见 "Received Message: Hello RocketMQ!"，Dashboard 查询消息。

• 坑6：消息不消费。确保 Consumer Group 匹配，Tag 对齐。

5. 完整Docker Compose（推荐一键部署）

用 yml 避免手动坑：

version: '3.5'
services:
  rmqnamesrv:
    image: rocketmqinc/rocketmq
    container_name: rmqnamesrv
    ports: - 9876:9876
    command: sh mqnamesrv
  rmqbroker:
    image: rocketmqinc/rocketmq
    container_name: rmqbroker
    ports: - 10909:10909 - 10911:10911
    environment: NAMESRV_ADDR: rmqnamesrv:9876
    volumes: - ./conf/broker.conf:/opt/rocketmq-4.4.0/conf/broker.conf
    depends_on: - rmqnamesrv
    command: sh mqbroker -c /opt/rocketmq-4.4.0/conf/broker.conf
  rmq-dashboard:
    image: apacherocketmq/rocketmq-dashboard:latest
    container_name: rmq-dashboard
    ports: - 8080:8082
    environment: JAVA_OPTS: -Drocketmq.namesrv.addr=rmqnamesrv:9876
    depends_on: - rmqnamesrv
networks: default: driver: bridge

运行docker-compose up -d。

结语：收获与反思

这个过程花了我好久，从沮丧（端口打不开、ACL诡异）到兴奋（消息飞起来）。关键教训：

• 环境变量别忘：NAMESRV_ADDR是灵魂。

• 端口/网络仔细查：docker logs 和 ps是神器。

• 工具坑用主机绕：容器 JDK 老，主机新。

• 社区力量：AI助手超棒，耐心解答。

现在我的本地MQ稳了，下步集成到Spring Cloud项目。感谢Grok（xAI）的陪伴！如果您有类似经历，评论区交流。点赞关注，咱们下篇见~