在Windows Docker环境下部署RocketMQ并实现消息持久化，是许多开发者在本地测试或小规模生产中的常见需求。然而，由于Docker网络、Windows防火墙、配置文件细节等问题，整个过程往往充满“坑”。本文记录了一次完整的部署经历，包括正确的配置方法、常见问题及最终解决方案，希望能帮助你少走弯路。

一、目录结构准备

        在Windows上创建以下持久化目录（路径可自定义，但需与后续挂载一致）：

        打开PowerShell（管理员），执行：

New-Item -ItemType Directory -Force -Path "D:/docker/rocketmq/namesrv/logs"
New-Item -ItemType Directory -Force -Path "D:/docker/rocketmq/namesrv/store"
New-Item -ItemType Directory -Force -Path "D:/docker/rocketmq/broker/logs"
New-Item -ItemType Directory -Force -Path "D:/docker/rocketmq/broker/store"
New-Item -ItemType Directory -Force -Path "D:/docker/rocketmq/broker/conf"

二、编写Broker配置文件

        在 D:/docker/rocketmq/broker/conf/broker.conf 中写入以下内容（注意：不要添加行尾注释，否则会导致IP解析异常）：

# ========== 集群基础 ==========
brokerClusterName = RocketMQ-Cluster
brokerName = broker-a
brokerId = 0
brokerRole = ASYNC_MASTER

# ========== 网络 ==========
brokerIP1 = 192.168.1.1        # 替换为你的宿主机真实IP，可通过ipconfig查看IPv4地址，替换之后删除注释，不然会影响后面的ip解析
listenPort = 10911
vipChannelEnabled = false

# ========== 存储路径 ==========
storePathRootDir = /home/rocketmq/store
storePathCommitLog = /home/rocketmq/store/commitlog
storePathConsumeQueue = /home/rocketmq/store/consumequeue
storePathIndex = /home/rocketmq/store/index
storeCheckpoint = /home/rocketmq/store/checkpoint
abortFile = /home/rocketmq/store/abort

# ========== 日志路径 ==========
logRootDir = /home/rocketmq/logs

# ========== 刷盘策略 ==========
flushDiskType = ASYNC_FLUSH
flushIntervalCommitLog = 500
flushIntervalConsumeQueue = 3000

# ========== 消息清理 ==========
fileReservedTime = 72
deleteWhen = 04
cleanFileForciblyEnable = true

# ========== 功能开关 ==========
autoCreateTopicEnable = true
autoCreateSubscriptionGroup = true
enablePropertyFilter = true

# ========== 事务消息 ==========
transactionCheckInterval = 60
transactionTimeout = 60000

# ========== 性能 ==========
maxMessageSize = 65536000
defaultQueueNums = 8

# ========== 高可用（单节点） ==========
haListenPort = 10912
slaveReadEnable = true

三、编写 docker-compose.yml

        以下配置包含RocketMQ核心组件（NameServer + Broker + Dashboard），并已关闭VIP通道、正确映射端口。如果之前没有配置过docker-compose.yml可直接粘贴，有的话粘贴services下的内容并替换你的networks：

networks:
  rocketmq-net:
    name: rocketmq-net

services:
  rocketmq-namesrv:
    image: apache/rocketmq:5.1.0
    container_name: rocketmq-namesrv
    ports:
      - "9876:9876"
    volumes:
      - D:/docker/rocketmq/namesrv/logs:/home/rocketmq/logs
      - D:/docker/rocketmq/namesrv/store:/home/rocketmq/store
    environment:
      - MAX_POSSIBLE_HEAP=100m
    command: sh mqnamesrv
    networks:
      - rocketmq-net
    restart: always

  rocketmq-broker:
    image: apache/rocketmq:5.1.0
    container_name: rocketmq-broker
    ports:
      - "10909:10909"
      - "10911:10911"
      - "10912:10912"
    volumes:
      - D:/docker/rocketmq/broker/logs:/home/rocketmq/logs
      - D:/docker/rocketmq/broker/store:/home/rocketmq/store
      - D:/docker/rocketmq/broker/conf/broker.conf:/home/rocketmq/rocketmq-5.1.0/conf/broker.conf
    environment:
      - NAMESRV_ADDR=rocketmq-namesrv:9876
      - MAX_POSSIBLE_HEAP=256m
    command: sh mqbroker -c /home/rocketmq/rocketmq-5.1.0/conf/broker.conf
    depends_on:
      - rocketmq-namesrv
    networks:
      - rocketmq-net
    restart: always

  rocketmq-dashboard:
    image: apacherocketmq/rocketmq-dashboard:latest
    container_name: rocketmq-dashboard
    ports:
      - "8080:8082"                # 注意：容器内端口是8082，不是8080
    environment:
      - JAVA_OPTS=-Drocketmq.namesrv.addr=rocketmq-namesrv:9876 -Dcom.rocketmq.sendMessageWithVIPChannel=false
    depends_on:
      - rocketmq-namesrv
    networks:
      - rocketmq-net
    restart: always

四、拉取镜像并启动服务

        拉取RocketMQ 5.1.0相关镜像：

# 拉取 RocketMQ 5.1.0 镜像
docker pull apache/rocketmq:5.1.0

# 拉取 Dashboard 最新镜像
docker pull apacherocketmq/rocketmq-dashboard:latest

        在 docker-compose.yml 所在目录执行：

docker-compose up -d

        查看所有容器状态：

docker-compose ps

        确保 rocketmq-namesrv、rocketmq-broker、rocketmq-dashboard 均为 Up 状态。

五、踩坑与解决

1、Dashboard无法访问 http://localhost:8080

• 现象：浏览器打不开，访问超时或连接拒绝。

• 原因：Dashboard镜像内部Tomcat监听的是 8082 端口，而不是传统的8080。docker-compose.yml 中如果写 "8080:8080" 就会映射错误。

• 解决：改为 "8080:8082"。

2、容器内无法连接宿主机IP（如 192.168.1.1:10911），mqadmin 报 RemotingConnectExceptio

• 现象：

  • docker exec 使用 telnet 能连接但立即断开。

  • RocketMQ的 mqadmin clusterList 命令报 connect to 192.168.1.1:10911 failed。

  • Dashboard日志中出现 RemotingConnectException: connect to 192.168.1.1:10909 failed（或10911）。

• 原因：Windows防火墙阻止了来自Docker虚拟网络（Hyper-V）的入站流量。即使添加了入站规则，默认只允许来自“同一子网”或“公共/专用”网络的流量，而Docker容器使用的是Hyper-V虚拟交换机，属于特殊网络。

• 解决：

  1. 打开“Windows Defender防火墙” → “高级设置” → “入站规则” → “新建规则”。

  2. 选择“端口” → 下一步 → 选择“TCP”，在“特定本地端口”中输入 10911,9876,10909（RocketMQ所需端口）。

  3. 操作选择“允许连接” → 下一步。

  4. 关键步骤：在“配置文件”中，勾选“域”、“专用”、“公用”全部。

  5. 命名规则（例如 RocketMQ-TCP-Ports），完成。

  6. 重启Docker Desktop（系统托盘右键 → Restart），使防火墙规则完全生效。

3、Broker注册到NameServer的IP错误（带注释）

• 现象：docker logs rocketmq-broker 显示：

  text

  The broker[broker-a, 192.168.1.1 # ???????????????????????????????????? IP:10911] boot success. serializeType=JSON and name server is rocketmq-namesrv:9876

  有乱码或空格，导致客户端无法正确连接。

• 原因：broker.conf 中 brokerIP1 = 192.168.1.1 # 替换... 行尾的注释被当作配置值的一部分，导致实际注册的IP包含了空格和注释符。

• 解决：删除行尾所有空格和注释，只保留 brokerIP1 = 192.168.1.1（宿主机ip）。

4、Dashboard始终报 RemotingConnectException: connect to ...:10909 failed

• 现象：虽然Broker正常，但Dashboard控制台不断报无法连接10909端口。

• 原因：Dashboard默认启用了VIP通道，会尝试连接 brokerIP1:10909（标准端口10911减2）。而我们在Broker中已设置 vipChannelEnabled=false，此端口并未开放。

• 解决：在Dashboard的环境变量 JAVA_OPTS 中添加 -Dcom.rocketmq.sendMessageWithVIPChannel=false，禁用VIP通道。

六、最终验证

1.、检查集群状态

docker exec rocketmq-namesrv sh -c "echo 'getBrokerClusterInfo' | ./mqadmin clusterList -n localhost:9876"

        输出应显示 broker-a 的 Addr 为 192.168.10.101:10911，ACTIVATED 为 true，无 RemotingConnectException。

2.、访问Dashboard

        浏览器打开 http://127.0.0.1:8080（或 http://localhost:8080）。Cluster界面正常。

七、总结

        通过以上步骤，我们成功在Windows Docker环境中部署了RocketMQ 5.1.0，并实现了消息持久化。过程中遇到的典型问题包括：

• 端口映射（8080 → 8082）

• Windows防火墙入站规则及作用域配置

• 配置文件行尾注释导致的IP解析异常

• VIP通道关闭

希望这篇博客能帮助你快速搭建一个稳定、可用的RocketMQ开发测试环境。