Docker Compose 部署 RabbitMQ 单节点指南

通过 Docker Compose 一个命令拉起带 Web 管理后台 的 RabbitMQ 单节点实例，本文给出完整 docker-compose.yml、逐项参数说明、账号密码登录方式，以及从 0 到 1 的整体流程、生产消费验证和常见排障。

1. 环境与前置

一台已安装 Docker Engine + Docker Compose v2（本文用到 v5.5.1）的 Docker 主机。
目录规划：

mkdir -p /opt/data/rabbitmq-compose/{data,conf,logs}
# data  : Mnesia 数据（队列/交换机/绑定/用户）
# conf  : /etc/rabbitmq 的自定义配置(rabbitmq.conf / enabled_plugins)
# logs  : /var/log/rabbitmq 运行日志

注意：绑定挂载的 conf、data、logs 若为空且宿主目录为 root 属主，容器内以 UID 999(rabbitmq) 运行的进程会写不进去，启动报 eacces。请务必执行下面授权（见 §6 排障一）：

chown -R 999:999 /opt/data/rabbitmq-compose/{data,logs,conf}
chmod 755 /opt/data/rabbitmq-compose/{data,logs,conf}

2. docker-compose.yml（完整）

services:
  rabbitmq-manage:
    image: rabbitmq:management          # 预装 Web 管理插件，自带可视化后台
    container_name: rabbitmq-manage
    hostname: rabbitmq-manage
    restart: unless-stopped             # 崩溃/重启自动拉起
    ports:
      - "5672:5672"                     # AMQP 0-9-1/1.0 客户端端口
      - "15672:15672"                   # Management Web UI
    environment:
      RABBITMQ_DEFAULT_USER: admin      # 默认账号
      RABBITMQ_DEFAULT_PASS: q1w2e3r4   # 默认密码
      RABBITMQ_DEFAULT_VHOST: /         # 默认虚拟主机
      TZ: Asia/Shanghai                 # 时区
    volumes:
      - ./data:/var/lib/rabbitmq        # 持久化 Mnesia 数据
      - ./conf:/etc/rabbitmq            # 自定义 conf / enabled_plugins
      - ./logs:/var/log/rabbitmq        # 日志
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
      interval: 30s
      timeout: 10s
      retries: 5

networks:
  default:
    name: rmq-compose-net               # 自定义驱动网络

3. 字段逐项说明

image / 镜像标签

标签	说明	适用场景
`rabbitmq:latest`	仅消息服务，无 Web 后台	纯客户端、生产简洁镜像
`rabbitmq:management`	预装 Web 管理插件	开发、测试、单节点部署（本文）
`rabbitmq:3.13-management`	指定大版本 + 管理插件	需要锁定版本

environment / 环境变量

变量	值	作用	是否必须
`RABBITMQ_DEFAULT_USER`	admin	首次启动创建的管理员账号	推荐
`RABBITMQ_DEFAULT_PASS`	q1w2e3r4	该账号密码	推荐
`RABBITMQ_DEFAULT_VHOST`	/	预建虚拟主机名	可选
`TZ`	Asia/Shanghai	容器时区	可选

首次启动（数据目录无 Mnesia）才会用上述变量创建默认用户；一旦数据卷已有库，变更该变量不会改已有密码。

ports / 端口

端口	协议	用途
`5672`	TCP/AMQP	客户端生产/消费（对外）
`15672`	HTTP	Management Web UI 与 HTTP API
`25672`	TCP/erlang	集群节点间（未映射，集群时再映射）

volumes / 数据卷：./data:/var/lib/rabbitmq 持久化元数据与消息数据；./conf:/etc/rabbitmq 放入自定义 enabled_plugins、rabbitmq.conf；./logs:/var/log/rabbitmq 持久化日志。

⚠️ management 镜像在制作时于镜像内 /etc/rabbitmq/enabled_plugins 预置了 [rabbitmq_management].。若你挂载 ./conf:/etc/rabbitmq，空挂载会把镜像预置的 enabled_plugins 遮蔽，导致 management 插件不生效（见 §6 排障四）。让挂载目录保留该文件，或在容器内 rabbitmq-plugins enable rabbitmq_management。

healthcheck / 健康检查：可用 rabbitmq-diagnostics -q ping 检查 Erlang 节点是否可用，实现容器健康状态（health: healthy）。

4. 启动与账号密码登录

cd /opt/data/rabbitmq-compose
docker compose up -d
# Network rmq-compose-net      Created
# Container rabbitmq-manage    Started

docker compose ps
# NAME              IMAGE                 STATUS                  PORTS
# rabbitmq-manage   rabbitmq:management   Up (health: starting)   0.0.0.0:5672->5672/tcp, 15691-15692/tcp, 0.0.0.0:15672->15672/tcp

Web 管理后台登录

浏览器访问 http://<主机IP>:15672，输入：

用户名：admin
密码：q1w2e3r4

或命令行验证登录（HTTP API）：

# 账号正确 -> 200
curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://127.0.0.1:15672/api/overview
# 200

# 密码错误 -> 401（认证被拦截）
curl -s -o /dev/null -w "%{http_code}\n" -u admin:wrongpass http://127.0.0.1:15672/api/overview
# 401

# 查看版本与节点
curl -s -u admin:q1w2e3r4 http://127.0.0.1:15672/api/overview | python3 -c \
  'import sys,json;d=json.load(sys.stdin);print(d["node"],d["rabbitmq_version"],d["object_totals"]["queues"])'
# rabbit@rabbitmq-manage 4.3.6 0

5. 生产 / 消费验证（HTTP API 闭环）

B=http://127.0.0.1:15672; A=admin:q1w2e3r4

# 1) 创建持久队列 hello
echo '{"durable":true,"auto_delete":false}' >/tmp/q.json
curl -s -o /dev/null -w "create=%{http_code}\n" -XPUT -u $A -H 'content-type: application/json' \
     --data @/tmp/q.json $B/api/queues/%2F/hello
# create=201

# 2) 发布一条消息到默认交换机(amq.default, routing_key=队列名)
echo '{"properties":{"delivery_mode":2},"routing_key":"hello","payload":"dind-rabbitmq-compose-OK","payload_encoding":"string"}' >/tmp/pub.json
curl -s -u $A -H 'content-type: application/json' --data @/tmp/pub.json $B/api/exchanges/%2F/amq.default/publish
# {"routed":true}

# 3) 消费一条
echo '{"count":1,"ackmode":"ack_requeue_false","encoding":"auto"}' >/tmp/get.json
curl -s -u $A -H 'content-type: application/json' --data @/tmp/get.json $B/api/queues/%2F/hello/get | python3 -m json.tool
# payload: "dind-rabbitmq-compose-OK", message_count: 0

{"routed":true} 表示消息已投递到队列；get 后 message_count:0 表示消息被成功消费。在 Web 后台 Overview → Queues 可见 hello 队列与消息数。

6. 常见排障（本次实际踩坑）

① 启动报 failed to open log file ... permission denied（eacces） 挂载目录属主为 root，容器以 UID999 运行写不进去。解决：

chown -R 999:999 ./data ./logs ./conf

② .erlang.cookie must be accessible by owner only 给数据目录 chmod -R 777 会把 .erlang.cookie 变成全局可读，RabbitMQ 拒绝启动。正确收紧：

chmod 755 ./data ./logs
chmod 600 ./data/.erlang.cookie

③ 拉取镜像 whiteout 失败（嵌套 Docker 环境 overlay2） 在 dockerd 嵌套/受限环境 overlay2 无法转换 whiteout。将内层 daemon 存储驱动切为 vfs：

{ "storage-driver": "vfs",
  "registry-mirrors": ["https://docker.1ms.run","https://docker.m.daocloud.io"] }

④ 端口 15672 打不开 / 插件未启用 多为挂载 ./conf:/etc/rabbitmq 遮蔽了镜像预置的 enabled_plugins。容器内重新启用并落盘：

docker exec rabbitmq-manage rabbitmq-plugins enable rabbitmq_management
# 输出: rabbitmq_management / rabbitmq_management_agent / rabbitmq_web_dispatch 已启用
cat ./conf/enabled_plugins
# [rabbitmq_management].

7. 常用维护命令

docker compose ps                 # 查看状态
docker compose logs -f --tail=50  # 查看实时日志
docker compose restart            # 重启
docker compose down               # 停止并移除容器(数据卷/data 目录保留)
docker exec rabbitmq-manage rabbitmqctl list_users        # 列出用户
docker exec rabbitmq-manage rabbitmqctl list_queues       # 列出队列
docker exec rabbitmq-manage rabbitmq-diagnostics -q ping  # 健康探测

持久化目录（./data/...、./logs/...）保留在宿主上，docker compose down 不会删除，重启后数据仍在，实现单节点数据持久化。