Docker 部署 RabbitMQ 并实现预配置初始化（用户 / VHost / 插件）

在实际项目中，RabbitMQ 往往不是“临时起一个就用”，而是需要可重复部署、可版本化管理、启动即具备完整初始状态。
如果仍然依赖手工进入容器执行 rabbitmqctl，在测试、交付、自动化部署阶段都会成为隐患。

本文介绍一种生产可用的方式：

通过 Docker + definitions.json + 插件预启用，实现 RabbitMQ 启动即完成用户、VHost、权限及插件配置。

一、为什么要做“预配置初始化”

RabbitMQ 默认行为是：

  • 自动创建 / vhost
  • 自动创建 guest/guest
  • 插件需要手动启用
  • 用户 / 权限需要命令行配置

在以下场景中，这种方式是不可接受的：

  • 多环境（dev / test / prod）一致性要求高
  • Docker / CI/CD 自动化部署
  • 禁止人工进入容器修改状态
  • 安全审计要求（不允许默认账号）

解决思路只有一个：启动即初始化，全量声明状态。

二、整体方案说明

核心思路：

  1. 使用 Docker 官方 RabbitMQ 镜像

  2. 挂载 definitions.json，声明：

    • 用户
    • vhost
    • 权限

  3. 挂载 enabled_plugins，启用：

    • management（Web 管理台）
    • stomp（STOMP 协议）

  4. 通过 rabbitmq.conf 指定启动时加载 definitions

关键认知：
definitions.json 是“全量快照”，不是增量配置。

三、目录结构设计（推荐）

1
2
3
4
5
6
7
8
rabbitmq/
├── docker-compose.yml
└── rabbitmq/
    ├── data/                 # 数据目录（持久化）
    └── conf/
        ├── rabbitmq.conf
        ├── enabled_plugins
        └── definitions.json
  • data：RabbitMQ 内部状态
  • conf：所有初始化配置（可纳入版本控制）

四、docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
version: "3.0"

services:
  rabbitmq:
    image: rabbitmq:3.8.20-management
    container_name: test-rabbitmq
    restart: always
    ports:
      - "5673:5672"     # AMQP
      - "15673:15672"   # Management UI
      - "61614:61613"   # STOMP
    volumes:
      - ./rabbitmq/data:/var/lib/rabbitmq
      - ./rabbitmq/conf/enabled_plugins:/etc/rabbitmq/enabled_plugins:ro
      - ./rabbitmq/conf/definitions.json:/etc/rabbitmq/definitions.json:ro
      - ./rabbitmq/conf/rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro

说明：

  • 不再使用 RABBITMQ_DEFAULT_USER/PASS
  • 完全由 definitions 接管初始化
  • 端口映射按需调整

五、启用插件（enabled_plugins）

1
[rabbitmq_management,rabbitmq_stomp].

注意事项：

  • 末尾的 . 不能省略
  • 文件必须是 Erlang list 语法
  • 容器启动时自动加载

六、RabbitMQ 核心配置（rabbitmq.conf）

1
2
3
4
5
6
listeners.tcp.default = 5672
management.tcp.port = 15672
stomp.listeners.tcp.default = 61613

# 启动时加载 definitions
management.load_definitions = /etc/rabbitmq/definitions.json

说明：

  • 显式声明端口，避免未来升级行为变化
  • 使用 management.load_definitions 而不是环境变量，更直观

七、definitions.json（用户 / VHost / 权限）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "users": [
    {
      "name": "admin",
      "password": "admin",
      "tags": "administrator"
    }
  ],
  "vhosts": [
    { "name": "/" },
    { "name": "stomp" }
  ],
  "permissions": [
    {
      "user": "admin",
      "vhost": "/",
      "configure": ".*",
      "write": ".*",
      "read": ".*"
    },
    {
      "user": "admin",
      "vhost": "stomp",
      "configure": ".*",
      "write": ".*",
      "read": ".*"
    }
  ]
}

关键点说明

  1. 必须显式声明 / vhost

    • 一旦使用 definitions，默认 / 不会自动创建

  2. 用户、vhost、权限必须成套出现

  3. 本地 / 测试环境建议使用 password

  4. 生产环境可替换为 password_hash

八、启动与重建流程（非常重要）

首次或修改 definitions 后：

1
2
3
docker-compose down
rm -rf rabbitmq/data/*
docker-compose up -d

原因：

  • RabbitMQ 一旦初始化完成
  • definitions 不会再次覆盖已有状态
  • 数据目录不清，配置不会生效

九、验证结果

  1. 访问管理台

    1
    http://localhost:15673

  2. 使用 admin / admin 登录

  3. 确认：

    • vhost /、stomp 存在
    • 插件 management / stomp 已启用
    • admin 拥有对应权限

十、总结

通过 Docker + 预配置方式部署 RabbitMQ，可以实现：

  • 启动即具备完整初始状态
  • 无需人工干预
  • 配置可版本化、可审计
  • 适用于 CI/CD 与生产环境

核心原则只有一句话：

RabbitMQ 初始化要“声明式”，不要“命令式”。

一旦接受这个原则，RabbitMQ 在 Docker 环境下会变得非常稳定、可控。