用 Docker 部署 RabbitMQ：从入门到实战全细节

默认端口一览#

RabbitMQ 镜像启动后，常见端口：

• 5672：AMQP 协议端口（应用连 MQ 用的端口）；
• 15672：Web 管理控制台端口；
• （可选）5671：AMQP over TLS；
• （可选）15671：管理界面 HTTPS；
• （可选）25672：集群节点间通信端口。

后文的端口映射都围绕这些展开。

默认账号密码#

RabbitMQ 默认会创建一个：

• 用户名：guest
• 密码：guest

重要限制：

• 默认 guest/guest 只能本机访问（localhost），如果你从远程 IP 访问，会被拒绝。

这也是为什么生产环境一定要创建自己的账号，并关掉或限制 guest 的原因。

1. 最小运行示例（仅用于本地试用）#

先用一个最简单的命令把 RabbitMQ 跑起来：

1
docker run --name my-rabbitmq \
2
  -p 5672:5672 \
3
  -p 15672:15672 \
4
  -d rabbitmq:3-management

参数含义：

• --name my-rabbitmq：容器名称，后续方便用 docker logs my-rabbitmq 来看日志等；
• -p 5672:5672：暴露核心的 AMQP 服务端口；
• -p 15672:15672：暴露 Web 管理控制台；
• -d：后台运行；
• rabbitmq:3-management：使用带管理控制台的官方镜像。

启动后查看容器状态：

1
docker ps

2. 打开 Web 管理控制台#

浏览器访问：

1
http://127.0.0.1:15672

默认账号：

• 用户名：guest
• 密码：guest

能够登录就说明 RabbitMQ 已经跑起来了。

不过，目前这个环境还存在几个问题：

• 没有数据卷，容器删了配置就没了（包括用户、虚拟主机、队列持久化等）；
• 仍然使用默认 guest/guest，并且理论上只允许本机登录；
• 没有任何自定义配置（如集群、TLS、限流等）。

接下来一步步补齐。

1. 创建宿主机目录#

以 Linux / macOS 为例：

1
mkdir -p ~/docker-data/rabbitmq/data
2
mkdir -p ~/docker-data/rabbitmq/conf

Windows（PowerShell）类似：

1
mkdir C:\docker-data\rabbitmq\data
2
mkdir C:\docker-data\rabbitmq\conf

2. 用数据卷重新运行容器#

先停掉之前的试用容器：

1
docker stop my-rabbitmq
2
docker rm my-rabbitmq

再用带卷的命令重新启动：

1
docker run --name my-rabbitmq \
2
  -p 5672:5672 \
3
  -p 15672:15672 \
4
  -v ~/docker-data/rabbitmq/data:/var/lib/rabbitmq \
5
  -v ~/docker-data/rabbitmq/conf:/etc/rabbitmq \
6
  -d rabbitmq:3-management

现在，RabbitMQ 的数据和配置文件都落在宿主机，对应目录中。
后面添加的用户、虚拟主机、队列等信息都会持久化保存。

注意：刚启动时 /etc/rabbitmq 可能是空的，但只要我们不挂载配置文件，RabbitMQ 会用默认配置启动。这时挂载 conf 目录主要是为将来扩展准备。

1. 通过 Web UI 创建#

进入 http://127.0.0.1:15672，默认 guest/guest 登录。

创建新用户：

• 进入 Admin 标签页；
• Add a user：
  • Username：比如 app_user
  • Password：自行设定一个复杂点的密码
  • Tags：选 administrator（也可以按需控制权限）
  • 点击 Add user。

创建虚拟主机：

• 仍然在 Admin 标签页；
• Virtual Hosts → Add a new virtual host；
• Name：比如 /app 或 app_vhost；
• 点击 Add virtual host。

给用户授权：

• 在 Admin → Users 找到 app_user；
• 点击用户名进入详情页；
• 在 Permissions 部分选择刚刚创建的 vhost（比如 /app）；
• 配置 Configure / Write / Read 权限（简单起见可以写 .*）；
• 点击 Set permission。

之后，客户端只需要使用：

• user：app_user
• pass：你设置的密码
• vhost：/app（或 app_vhost）

即可连接到 RabbitMQ，并在这个 vhost 中创建交换机和队列。

2. 通过命令行创建（可脚本化）#

如果你想把这些写进自动化脚本，可以用 rabbitmqctl / rabbitmq-plugins 等命令。

先进入容器：

1
docker exec -it my-rabbitmq bash

容器内部执行：

1
# 创建用户
2
rabbitmqctl add_user app_user 'Your_Strong_Password'
3

4
# 给用户加管理员标签（可选）
5
rabbitmqctl set_user_tags app_user administrator
6

7
# 创建虚拟主机
8
rabbitmqctl add_vhost /app
9

10
# 为用户在 /app vhost 上设置权限
11
rabbitmqctl set_permissions -p /app app_user ".*" ".*" ".*"
12

13
# （按需）禁用 guest 用户的远程访问，或者直接删掉 guest
14
# 禁用 guest 最常见做法是只允许本地访问，这通常通过配置文件完成

退出容器：

1
exit

这些命令产生的用户 / vhost 配置同样会写入 /var/lib/rabbitmq，即已经被我们持久化。

使用 .env 管理账号密码#

在 docker-compose.yml 同目录下创建 .env：

1
RABBITMQ_USER=app_user
2
RABBITMQ_PASS=Your_Strong_Password
3
RABBITMQ_VHOST=/app

然后在 docker-compose.yml 中这么写：

1
environment:
2
  RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER}
3
  RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASS}
4
  RABBITMQ_DEFAULT_VHOST: ${RABBITMQ_VHOST}

这样，你可以在不同环境用不同 .env 文件，而 compose 文件本身保持不变。

1. 队列持久化#

上面 Node.js 示例中的：

1
await channel.assertQueue(queue, {
2
  durable: true,
3
});

中的 durable: true 就是设置队列为持久化队列。

2. 消息持久化#

发送消息时：

1
channel.sendToQueue(queue, Buffer.from("..."), {
2
  persistent: true,
3
});

这里的 persistent: true 即把 delivery_mode 设置为 2。

3. Publisher Confirms（发布确认）#

为了确保消息真正被 Broker 接收（而不是在网络途中丢失），推荐：

• 使用 confirm channel，即在 Node.js 中 createConfirmChannel；
• 每发送一批消息都等 RabbitMQ 返回 ack。

简单示例：

1
const confirmChannel = await conn.createConfirmChannel();
2

3
confirmChannel.sendToQueue(
4
  queue,
5
  Buffer.from("message with confirm"),
6
  { persistent: true },
7
  (err, ok) => {
8
    if (err) {
9
      console.error("消息未被确认", err);
10
    } else {
11
      console.log("消息已被 Broker 确认");
12
    }
13
  }
14
);

这是深入生产环境时必备的可靠性手段。

1. 基本思路#

• 准备两个节点 rabbit1 和 rabbit2，加入同一个集群；
• 用同一份 ERLANG_COOKIE，保证它们能互相通信；
• 把 rabbit2 加入到以 rabbit1 为核心的集群。

2. 示例 docker-compose.yml（精简版）#

在一个单独的目录（如 deploy/rabbitmq-cluster）创建：

1
version: "3.9"
2

3
services:
4
  rabbit1:
5
    image: rabbitmq:3-management
6
    hostname: rabbit1
7
    container_name: rabbit1
8
    environment:
9
      RABBITMQ_ERLANG_COOKIE: "MY_SECRET_COOKIE"
10
      RABBITMQ_DEFAULT_USER: app_user
11
      RABBITMQ_DEFAULT_PASS: Your_Strong_Password
12
      RABBITMQ_DEFAULT_VHOST: /app
13
    ports:
14
      - "5672:5672"
15
      - "15672:15672"
16
    volumes:
17
      - ./data/rabbit1:/var/lib/rabbitmq
18

19
  rabbit2:
20
    image: rabbitmq:3-management
21
    hostname: rabbit2
22
    container_name: rabbit2
23
    environment:
24
      RABBITMQ_ERLANG_COOKIE: "MY_SECRET_COOKIE"
25
    depends_on:
26
      - rabbit1
27
    volumes:
28
      - ./data/rabbit2:/var/lib/rabbitmq

启动集群：

1
docker compose up -d

3. 手动把 rabbit2 加入 rabbit1#

进入 rabbit2 容器：

1
docker exec -it rabbit2 bash

执行如下命令（注意有停服务 / 加入集群 / 启服务的顺序）：

1
rabbitmqctl stop_app
2
rabbitmqctl join_cluster rabbit@rabbit1
3
rabbitmqctl start_app

回到 rabbit1 的 Web 管理界面 http://127.0.0.1:15672，登录后在 Overview 页面就能看到集群节点列表中出现 rabbit1 与 rabbit2。

再次强调：生产环境需要考虑磁盘节点（disc）与内存节点（ram）、镜像队列策略（HA）、跨机房网络延迟等，这里只是一个把多节点拉起来的起步版本。

1. 容器一直重启 / 退出#

首先看日志：

1
docker logs my-rabbitmq

常见错误包括：

• 权限问题（对 /var/lib/rabbitmq 或 /etc/rabbitmq 目录无写入权限）；
• 配置文件语法错误（尤其是自己写了 rabbitmq.conf 或 advanced.config）；
• ERLANG_COOKIE 不一致（在做集群时）。

排查建议：

• 先去掉自定义配置和卷，只用最小命令确认基础镜像没问题；
• 再一步步加上卷和配置；
• 没必要一上来就搞集群，把单节点跑稳再说。

2. 端口被占用#

如果启动时报 bind (..) failed: port is already allocated，说明 5672 或 15672 已经被占用。

解决：

• 换宿主机端口映射，比如：

1
ports:
2
  - "5673:5672"
3
  - "15673:15672"

连接时就用 5673 / 15673。

3. 客户端连接被拒绝 / 授权失败#

常见错误消息：

• ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN. For details see the broker logfile.
• ACCESS_REFUSED - vhost '/app' refused.

检查清单：

• 用户名、密码是否正确；
• 指定的 vhost 是否存在；
• 是否给该用户在 vhost 上授权了 Configure/Read/Write 权限；
• 是否使用 guest/guest 在远程访问（默认不允许）。

4. 消费者和队列的关系混乱#

有时候你会发现：

• 队列里看起来有消息，但消费者收不到；
• 或者消费者连接的 vhost / queue 与你在 Web 上看的不一样。

排查要点：

• 确认 vhost：RabbitMQ 多个 vhost 相互隔离，很容易“连错房间”；
• 确认队列名：保证生产者和消费者使用的队列名完全一致；
• 确认 exchange 与 binding：尤其是在用 topic / direct / fanout 交换机时。

5. 性能问题与监控#

RabbitMQ 的性能受多因素影响：

• 磁盘 IO（消息持久化时尤其明显）；
• 网络延迟和带宽；
• 消费者 ack 策略（是否开启手动 ack、防止消息在未确认时大量堆积）；
• prefetch（basic.qos）设置是否合理。

排查时可以：

• 打开 Web 控制台的 Overview / Queues 观察 rate；
• 设置合理的 prefetch 值（比如每个消费者一次处理 50 条）；
• 避免在一个 queue 上堆积海量未消费完的消息。

1. 升级镜像版本#

前提：你已经用 docker-compose 部署，并挂载了数据卷。

步骤：

1. 修改 docker-compose.yml 中的镜像标签，例如从 rabbitmq:3.11-management 升到 rabbitmq:3.13-management；

2. 拉取新镜像：

   1
   docker compose pull

3. 重启服务：

   1
   docker compose up -d

4. 观察日志和 Web 控制台，确认队列 / 用户 / 虚拟主机等都正常。

如果发现严重问题：

• 把镜像标签改回旧版本；
• 再次 docker compose up -d，数据仍然在卷里。

2. 数据备份#

最简单粗暴的方式：

• 停掉服务（确保数据一致性）：

  1
  docker compose down

• 打包 ./data 目录（对应 /var/lib/rabbitmq）：

  1
  tar czf rabbitmq-data-backup-$(date +%Y%m%d).tar.gz ./data

• 把压缩包丢到异地存储（对象存储、另一台机器等）。

更细粒度的备份：

• 使用 rabbitmq-dump-queue 等工具导出关键队列数据；
• 使用集群 + 镜像队列来提升高可用性。