Spring Boot 连接 RabbitMQ 报错 Connection refused 怎么排查

Spring Boot 连接 RabbitMQ 报 Connection refused，通常是因为服务未启动、配置缩进错误、guest 用户远程限制或集群地址格式不匹配。建议按网络连通性、配置文件层级、用户权限的顺序逐一排查。

先说结论：大多数连接拒绝错误并非网络故障，而是客户端配置未能正确指向服务地址或权限被默认策略拦截。

先确认：RabbitMQ 服务状态及 5672 端口是否监听
先处理：修正 YAML 缩进层级与远程用户权限
再验证：观察启动日志是否仍有 AmqpConnectException

快速诊断命令

在部署 RabbitMQ 的服务器上执行以下命令，快速确认服务与端口状态。若无法登录服务器（如云托管场景），请跳过此步直接检查安全组。

# 检查服务运行状态
systemctl status rabbitmq-server
# 或 Docker 环境
docker ps | grep rabbitmq

# 检查 5672 端口是否监听
netstat -tlnp | grep 5672
# 若未安装 netstat，可使用 ss 命令
ss -tlnp | grep 5672

# 本地测试端口连通性
# 注意：最小化 Linux 发行版可能未安装 telnet，建议使用 nc
nc -zv 127.0.0.1 5672
# 或
 telnet 127.0.0.1 5672

核心原因分析

Connection refused 本质是 TCP 连接被目标主机拒绝。在 Spring Boot 集成场景中，常见原因有三点：一是客户端默认配置指向 localhost，而服务在远程；二是 YAML 配置缩进错误导致 Spring Boot 未读取到自定义配置，回退到默认值；三是 RabbitMQ 默认禁止 guest 用户远程连接，这是安全策略而非故障。此外，新版 RabbitMQ 集群对地址格式解析有变化，旧配置可能导致部分节点端口丢失。

Spring Boot 连接 RabbitMQ 报错 Connection refused 怎么排查

分步排查与修复

1. 确认服务端状态与网络
确保 RabbitMQ 服务已启动且监听 5672 端口（注意不是管理界面的 15672 端口）。如果是 Docker 部署，确认端口映射正确，例如 -p 5672:5672。
云托管场景注意：若使用阿里云、AWS 等云厂商的 RabbitMQ 服务，无需检查服务器进程，但必须确认安全组（Security Group）已放行 5672 端口，且连接地址为云服务商提供的专用 Endpoint，而非内网 IP。

2. 检查配置文件层级
在 application.yml 中，rabbitmq 配置必须位于 spring 层级下。错误写法会导致配置失效，客户端尝试连接默认的 localhost:5672。

# 正确示例
spring:
  rabbitmq:
    host: 192.168.1.100
    port: 5672
    username: your_user
    password: your_password

3. 处理用户权限限制
若使用默认 guest 用户，仅允许 localhost 连接。远程连接需新建用户或修改配置。
新建用户命令示例：

rabbitmqctl add_user new_user new_password
rabbitmqctl set_permissions -p / new_user "." "." "."

安全警告：若必须使用 guest 远程（仅限测试环境），需修改 rabbitmq.config 添加 [{rabbit, [{loopback_users, []}]}]. 并重启服务。生产环境严禁修改 loopback_users，否则可能导致严重安全风险。

4. 适配集群地址格式
在 RabbitMQ 3.8.x 及以上集群环境，建议使用 addresses 属性代替 host + port，避免解析异常。格式为 IP:端口，多个节点用逗号分隔。

spring:
  rabbitmq:
    addresses: 10.123.123.123:5672,10.123.123.124:5672
    username: abc
    password: abc

代码级验证方法

除了观察启动日志，建议在项目中添加一个简单的连接验证逻辑，确保应用启动时能主动检测连接状态。以下是一个基于 CommandLineRunner 的验证示例：

@Autowired
private ConnectionFactory connectionFactory;

@Bean
public CommandLineRunner verifyRabbitMQ() {
    return args -> {
        try {
            // 尝试创建连接并立即关闭，验证连通性
            connectionFactory.createConnection().close();
            System.out.println("RabbitMQ 连接成功");
        } catch (Exception e) {
            // 捕获 AmqpConnectException 或 ConnectException
            System.err.println("连接失败：" + e.getMessage());
            // 可选择在此处抛出异常阻止应用启动
            // throw new RuntimeException("RabbitMQ 连接失败", e);
        }
    };
}

常见坑与风险

YAML 缩进错误：spring 节点未顶格写，或被错误缩进到其他配置项下，导致配置未加载。
端口混淆：配置文件误填 15672（管理端口），实际通信应使用 5672。
Guest 远程限制：生产环境直接使用 guest 用户且未修改 loopback 设置，导致远程连接被拒。
集群配置旧格式：在新版集群中使用 host 列表加统一 port 配置，可能导致部分节点地址解析缺失端口。
配置中心遗漏：使用 Config Server 时，未在特定服务配置文件中声明 RabbitMQ 参数，导致默认连接本地。
云安全组未放行：服务器内部网络通畅，但云平台安全组拦截了 5672 入站流量。

官方文档参考

Spring Boot RabbitMQ Properties: https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#application-properties.integration.spring.rabbitmq
RabbitMQ Java Client: https://www.rabbitmq.com/java-client.html
RabbitMQ Access Control: https://www.rabbitmq.com/access-control.html