RabbitMQ Docker 镜像文档

概述

镜像概述与主要用途

RabbitMQ 是一款开源的多协议消息代理软件（有时称为面向消息的中间件），实现了高级消息队列协议（AMQP）。其服务器端基于 Erlang 编程语言开发，并构建于 Open Telecom Platform 框架之上，支持集群和故障转移。客户端库支持所有主流编程语言，可用于在分布式系统中实现可靠的异步通信。

核心功能与特性

• 多协议支持：原生支持 AMQP，同时可通过插件支持 MQTT、STOMP 等协议
• 可靠消息传递：提供持久化、确认机制、事务等特性，确保消息可靠投递
• 灵活路由：支持直接路由、主题路由、扇形交换等多种消息路由模式
• 集群与高可用：基于 Erlang/OTP 框架，支持节点集群、镜像队列和故障自动转移
• 管理与监控：通过管理插件提供 Web 界面，支持队列监控、用户管理、策略配置等功能
• 可扩展性：支持自定义插件扩展功能，如联邦队列、 shovel 跨集群同步等

使用场景与适用范围

• 应用解耦：分离系统组件，减少模块间直接依赖，提高系统弹性
• 异步任务处理：处理耗时操作（如日志处理、数据转换），避免阻塞主流程
• 分布式系统通信：作为微服务架构中的消息枢纽，实现服务间松耦合通信
• 流量削峰：缓冲突发流量，保护下游服务不被过载（如秒杀场景）
• 实时数据流：处理实时生成的消息流（如监控数据、用户行为跟踪）

快速参考

维护者

Docker 社区

支持渠道

Docker 社区 Slack、Server Fault、Unix & Linux 或 Stack Overflow

问题反馈

GitHub Issues

支持的架构

(更多信息)
amd64、arm32v6、arm32v7、arm64v8、i386、ppc64le、riscv64、s390x

镜像元数据

repo-info 仓库的 repos/rabbitmq/ 目录（包含镜像元数据、传输大小等信息）

镜像更新

official-images 仓库的 library/rabbitmq 标签
official-images 仓库的 library/rabbitmq 文件（更新历史）

支持的标签及对应 Dockerfile 链接

如何使用本镜像

运行 RabbitMQ 守护进程

RabbitMQ 的数据存储依赖于 "节点名称"（默认与主机名关联）。在 Docker 中使用时，建议显式指定 --hostname 以确保数据存储路径稳定：

docker run -d --hostname my-rabbit --name some-rabbit amd64/rabbitmq:3

容器启动后，默认监听 5672 端口（AMQP 协议端口）。通过 docker logs some-rabbit 可查看日志，其中包含节点名称、数据目录等关键信息：

=INFO REPORT==== 6-Jul-2015::20:47:02 ===
node           : rabbit@my-rabbit
home dir       : /var/lib/rabbitmq
config file(s) : /etc/rabbitmq/rabbitmq.config
cookie hash    : UoNOcDhfxW9uoZ92wh6BjA==
log            : tty
sasl log       : tty
database dir   : /var/lib/rabbitmq/mnesia/rabbit@my-rabbit

注：镜像默认将 /var/lib/rabbitmq 设为数据卷，确保数据持久化。

环境变量

RabbitMQ 本身支持的环境变量列表可参考 官方文档的环境变量部分。

已弃用变量（RabbitMQ 3.9+）

自 RabbitMQ 3.9 起，以下 Docker 专用变量已弃用，不再生效。建议使用配置文件进行自定义（详见 RabbitMQ 配置文档）：

RABBITMQ_DEFAULT_PASS_FILE
RABBITMQ_DEFAULT_USER_FILE
RABBITMQ_MANAGEMENT_SSL_CACERTFILE
RABBITMQ_MANAGEMENT_SSL_CERTFILE
RABBITMQ_MANAGEMENT_SSL_DEPTH
RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT
RABBITMQ_MANAGEMENT_SSL_KEYFILE
RABBITMQ_MANAGEMENT_SSL_VERIFY
RABBITMQ_SSL_CACERTFILE
RABBITMQ_SSL_CERTFILE
RABBITMQ_SSL_DEPTH
RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT
RABBITMQ_SSL_KEYFILE
RABBITMQ_SSL_VERIFY
RABBITMQ_VM_MEMORY_HIGH_WATERMARK

常用环境变量

• RABBITMQ_DEFAULT_USER：默认管理员用户名（替代原 guest）
• RABBITMQ_DEFAULT_PASS：默认管理员密码（替代原 guest）
• RABBITMQ_DEFAULT_VHOST：默认虚拟主机（默认为 /）
• RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS：额外 Erlang 参数（用于补充配置，如 -rabbit channel_max 4007）

设置默认用户和密码

通过环境变量 RABBITMQ_DEFAULT_USER 和 RABBITMQ_DEFAULT_PASS 自定义管理员账号（需使用带管理插件的镜像）：

docker run -d \
  --hostname my-rabbit \
  --name some-rabbit \
  -e RABBITMQ_DEFAULT_USER=admin \
  -e RABBITMQ_DEFAULT_PASS=secret \
  amd64/rabbitmq:3-management

启动后，通过 http://localhost:15672 或 [***] 访问管理界面，使用 admin/secret 登录。

设置默认虚拟主机

通过 RABBITMQ_DEFAULT_VHOST 指定默认虚拟主机：

docker run -d \
  --hostname my-rabbit \
  --name some-rabbit \
  -e RABBITMQ_DEFAULT_VHOST=my_vhost \
  amd64/rabbitmq:3-management

内存限制配置

RabbitMQ 需感知容器的内存限制（如 docker run --memory=2g），以避免因内存不足被系统 OOM 终止。通过配置文件设置 vm_memory_high_watermark 参数（详见 内存告警文档）：

# rabbitmq.conf 示例
vm_memory_high_watermark.relative = 0.7  # 允许使用容器内存的 70%

Erlang Cookie 配置

Erlang Cookie 用于节点间认证（集群或 rabbitmqctl 远程管理时必需）。默认存储路径为 /var/lib/rabbitmq/.erlang.cookie，可通过以下方式自定义：

• Docker Secrets（Swarm 模式）：

  docker service create \
    --name rabbitmq \
    --secret source=erlang-cookie,target=/var/lib/rabbitmq/.erlang.cookie,uid=999,gid=999,mode=0600 \
    amd64/rabbitmq:3
  

• 本地文件挂载：

  docker run -d \
    --hostname my-rabbit \
    --name some-rabbit \
    -v /local/path/to/.erlang.cookie:/var/lib/rabbitmq/.erlang.cookie:ro \
    amd64/rabbitmq:3
  

注：Cookie 文件需设置权限 0600，且属主为容器内的 rabbitmq 用户（UID/GID 通常为 999）。

启用管理插件

带 -management 后缀的标签已预装管理插件，默认监听 15672 端口。如需外部访问，可映射端口：

docker run -d \
  --hostname my-rabbit \
  --name some-rabbit \
  -p 5672:5672  # AMQP 端口
  -p 15672:15672  # 管理界面端口
  amd64/rabbitmq:3-management

启用额外插件

方法 1：通过 Dockerfile 构建

FROM amd64/rabbitmq:3.8-management
RUN rabbitmq-plugins enable --offline rabbitmq_mqtt rabbitmq_federation_management rabbitmq_stomp

方法 2：挂载插件配置文件

创建 enabled_plugins 文件（Erlang 列表格式）：

[rabbitmq_federation_management, rabbitmq_management, rabbitmq_mqtt, rabbitmq_stomp].

通过挂载文件启用插件：

docker run -d \
  --hostname my-rabbit \
  --name some-rabbit \
  -v /local/path/to/enabled_plugins:/etc/rabbitmq/enabled_plugins \
  amd64/rabbitmq:3

高级配置

推荐通过配置文件 /etc/rabbitmq/rabbitmq.conf 进行自定义（详见 RabbitMQ 配置文件文档）。支持以下挂载方式：

• 本地文件挂载：

  docker run -d \
    --hostname my-rabbit \
    --name some-rabbit \
    -v /local/path/to/rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro \
    amd64/rabbitmq:3
  

• Docker Configs（Swarm 模式）：

  docker config create rabbitmq-config /local/path/to/rabbitmq.conf
  docker service create \
    --name rabbitmq \
    --config source=rabbitmq-config,target=/etc/rabbitmq/rabbitmq.conf \
    amd64/rabbitmq:3
  

健康检查配置

本镜像未预设健康检查。根据 [官方建议]([***]