RabbitMQ 在 Ubuntu 上的系统化故障排查指南
一 快速定位流程
- 确认服务状态与端口：检查服务是否运行、AMQP 端口 5672 与管理端口 15672 是否监听，排查端口占用与防火墙。
- 查看节点与资源：用 rabbitmqctl status 检查节点健康、内存与磁盘告警；必要时调整 vm_memory_high_watermark、disk_free_limit。
- 查阅日志：优先看 /var/log/rabbitmq/rabbit@.log，关注启动失败、插件、认证、连接关闭等关键字。
- 校验连通与认证：从客户端测试连通（如 telnet 到 5672），核对用户名、密码、vhost 权限与插件启用状态。
二 常见故障与修复
-
服务无法启动
- 检查状态与日志：sudo systemctl status rabbitmq-server；sudo tail -f /var/log/rabbitmq/rabbit@*.log
- 端口冲突：ss -ltnp | grep 5672；释放或更换端口后重启。
- 依赖/加密模块缺失：安装 libssl-dev 等依赖并重新安装匹配版本的 Erlang/OTP；验证 erlang crypto：erl -eval “crypto:start(), ssl:start(), io:format(‘~p~n’, [ok]).” -s init stop
- 资源告警：出现 memory/disk alarm 时，临时放宽阈值：sudo rabbitmqctl set_vm_memory_high_watermark 0.4；sudo rabbitmqctl set_disk_free_limit 500MB
- Mnesia/权限异常：确认 /var/lib/rabbitmq 与 /etc/rabbitmq 属主为 rabbitmq:rabbitmq；必要时在停机后谨慎清理 /var/lib/rabbitmq/mnesia（会丢本地状态）。
-
无法远程连接 AMQP 5672
- 服务与端口：systemctl 确认运行；ss -ltnp | grep 5672 确认监听 0.0.0.0:5672（而非仅 127.0.0.1）。
- 防火墙/云安全组：sudo ufw allow 5672/tcp 或按需放行；云主机同步放通安全组规则。
- 客户端配置：核对 host/port/username/password/virtual-host 与服务器一致。
-
管理界面 15672 无法访问
- 启用插件：rabbitmq-plugins enable rabbitmq_management
- 防火墙/云安全组：sudo ufw allow 15672/tcp
- 账户与权限：默认 guest/guest 仅限本机；创建管理员并赋权：
- rabbitmqctl add_user admin StrongPass!
- rabbitmqctl set_user_tags admin administrator
- rabbitmqctl set_permissions -p / admin “." ".” “.*”
-
认证与权限错误 ACCESS_REFUSED
- 核对用户名、密码与 vhost 是否匹配。
- 为用户授予目标 vhost 的 configure/write/read 权限（三个 “.*” 或按需细化）。
-
插件或依赖导致的连接关闭
- 例如启用 AMQP 1.0 插件但未在客户端启用对应协议，会在日志看到 “amqp1_0_plugin_not_enabled” 并关闭连接；启用/禁用插件保持一致：rabbitmq-plugins {enable|disable} rabbitmq_amqp1_0。
三 日志与定位技巧
- 日志位置与实时查看：默认在 /var/log/rabbitmq/rabbit@.log；使用 sudo tail -f、less、grep 等定位错误与告警。
- 日志级别与输出：可在 rabbitmq.conf 中调整日志级别与输出方式（文件或 syslog），便于生产问题追踪与审计。
- 管理界面查看：启用 rabbitmq_management 后，在 Admin → Logs 区域可直接浏览服务日志，适合快速排障。
四 常用命令清单
- 服务与状态：sudo systemctl {start|stop|restart|status} rabbitmq-server；sudo rabbitmqctl status
- 插件管理：rabbitmq-plugins list；rabbitmq-plugins enable rabbitmq_management
- 用户与权限：
- rabbitmqctl add_user
- rabbitmqctl set_user_tags administrator
- rabbitmqctl set_permissions -p “." ".” “.*”
- 资源阈值：
- sudo rabbitmqctl set_vm_memory_high_watermark 0.4
- sudo rabbitmqctl set_disk_free_limit 500MB
- 连通性测试：ss -ltnp | grep 5672；telnet 5672；nc -vz 5672
五 环境与权限要点
- 目录与文件权限：确保 /var/lib/rabbitmq 与 /etc/rabbitmq 属主为 rabbitmq:rabbitmq；.erlang.cookie 权限应为 600，仅属主可读写。
- 主机名解析：如 epmd 报 “cannot connect to host/port”，检查 /etc/hosts 是否包含 127.0.0.1 映射。
- 版本兼容：确认 Erlang/OTP 与 RabbitMQ 版本匹配；Erlang 缺少 crypto/ssl 依赖会直接导致启动或连接失败。
