---
url: /rabbitmq/RabbitMQ-config.md
---
# Spring Boot RabbitMQ 配置详解

## 基本信息

| 项目 | 值 |
|------|-----|
| **类名** | `org.springframework.boot.autoconfigure.amqp.RabbitProperties` |
| **配置前缀** | `spring.rabbitmq` |
| **Artifact** | `org.springframework.boot:spring-boot-autoconfigure:3.5.16` |

***

## 一、核心连接配置

### 1.1 基础连接参数

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.host` | `localhost` | String | RabbitMQ 服务器主机名 |
| `spring.rabbitmq.port` | 自动判断 | Integer | 端口号（SSL 启用时为 5671，否则为 5672） |
| `spring.rabbitmq.username` | `guest` | String | 用户名 |
| `spring.rabbitmq.password` | `guest` | String | 密码 |
| `spring.rabbitmq.virtual-host` | `/` | String | 虚拟主机名称 |

### 1.2 高级连接配置

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.addresses` | - | `List<String>` | 多地址列表，格式：`amqp://host:port` |
| `spring.rabbitmq.address-shuffle-mode` | `NONE` | AddressShuffleMode | 地址洗牌模式（NONE/RANDOM/ROUND_ROBIN） |
| `spring.rabbitmq.requested-heartbeat` | - | Duration | 心跳间隔时间 |
| `spring.rabbitmq.requested-channel-max` | `2047` | int | 请求的最大通道数 |
| `spring.rabbitmq.connection-timeout` | - | Duration | 连接超时时间 |

### 1.3 发布者确认与返回

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.publisher-returns` | `false` | boolean | 是否启用发布者返回 |
| `spring.rabbitmq.publisher-confirm-type` | - | ConfirmType | 发布者确认类型（SIMPLE/CORRELATED/NONE） |

### 1.4 消息大小限制

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.max-inbound-message-body-size` | `64MB` | DataSize | 最大入站消息体大小 |
| `spring.rabbitmq.channel-rpc-timeout` | `10m` | Duration | 通道 RPC 超时时间 |

***

## 二、SSL 配置 (`spring.rabbitmq.ssl`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.ssl.enabled` | - | Boolean | 是否启用 SSL |
| `spring.rabbitmq.ssl.bundle` | - | String | SSL 绑定器名称 |
| `spring.rabbitmq.ssl.key-store` | - | String | 密钥库路径 |
| `spring.rabbitmq.ssl.key-store-type` | `PKCS12` | String | 密钥库类型 |
| `spring.rabbitmq.ssl.key-store-password` | - | String | 密钥库密码 |
| `spring.rabbitmq.ssl.key-store-algorithm` | `SunX509` | String | 密钥管理器算法 |
| `spring.rabbitmq.ssl.trust-store` | - | String | 信任库路径 |
| `spring.rabbitmq.ssl.trust-store-type` | `JKS` | String | 信任库类型 |
| `spring.rabbitmq.ssl.trust-store-password` | - | String | 信任库密码 |
| `spring.rabbitmq.ssl.trust-store-algorithm` | `SunX509` | String | 信任管理器算法 |
| `spring.rabbitmq.ssl.algorithm` | - | String | SSL 套接字工厂算法 |
| `spring.rabbitmq.ssl.validate-server-certificate` | `true` | boolean | 验证服务器证书 |
| `spring.rabbitmq.ssl.verify-hostname` | `true` | boolean | 验证主机名 |

***

## 三、缓存配置 (`spring.rabbitmq.cache`)

### 3.1 通道缓存 (`spring.rabbitmq.cache.channel`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.cache.channel.size` | - | Integer | 通道缓存大小 |
| `spring.rabbitmq.cache.channel.checkout-timeout` | - | Duration | 通道检出超时时间 |

### 3.2 连接缓存 (`spring.rabbitmq.cache.connection`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.cache.connection.mode` | `CHANNEL` | CacheMode | 缓存模式（CHANNEL/CONNECTION） |
| `spring.rabbitmq.cache.connection.size` | - | Integer | 连接缓存大小 |

***

## 四、监听器配置 (`spring.rabbitmq.listener`)

### 4.1 通用监听器配置

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.listener.type` | `SIMPLE` | ContainerType | 容器类型（SIMPLE/DIRECT/STREAM） |

### 4.2 SIMPLE 容器 (`spring.rabbitmq.listener.simple`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.listener.simple.concurrency` | - | Integer | 初始消费者数量 |
| `spring.rabbitmq.listener.simple.max-concurrency` | - | Integer | 最大消费者数量 |
| `spring.rabbitmq.listener.simple.batch-size` | - | Integer | 批处理大小 |
| `spring.rabbitmq.listener.simple.missing-queues-fatal` | `true` | boolean | 队列缺失是否致命 |
| `spring.rabbitmq.listener.simple.consumer-batch-enabled` | `false` | boolean | 是否启用消费者批处理 |
| `spring.rabbitmq.listener.simple.observation-enabled` | - | boolean | 是否启用可观测性 |

### 4.3 DIRECT 容器 (`spring.rabbitmq.listener.direct`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.listener.direct.consumers-per-queue` | - | Integer | 每个队列的消费者数 |
| `spring.rabbitmq.listener.direct.missing-queues-fatal` | - | boolean | 队列缺失是否致命 |
| `spring.rabbitmq.listener.direct.observation-enabled` | - | boolean | 是否启用可观测性 |

### 4.4 STREAM 容器 (`spring.rabbitmq.listener.stream`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.listener.stream.native-listener` | - | boolean | 是否使用原生流监听器 |
| `spring.rabbitmq.listener.stream.observation-enabled` | - | boolean | 是否启用可观测性 |

### 4.5 基础容器通用配置 (AmqpContainer)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.listener.*.auto-startup` | `true` | boolean | 是否自动启动 |
| `spring.rabbitmq.listener.*.acknowledge-mode` | - | AcknowledgeMode | 确认模式（AUTO/MANUAL/NACK_REQUEUE） |
| `spring.rabbitmq.listener.*.prefetch` | - | Integer | 预取消息数 |
| `spring.rabbitmq.listener.*.default-requeue-rejected` | - | Boolean | 拒绝后是否重新入队 |
| `spring.rabbitmq.listener.*.idle-event-interval` | - | Duration | 空闲事件间隔 |
| `spring.rabbitmq.listener.*.de-batching-enabled` | `true` | boolean | 是否启用解批处理 |
| `spring.rabbitmq.listener.*.force-stop` | - | boolean | 是否强制停止 |

### 4.6 监听器重试配置 (`spring.rabbitmq.listener.*.retry`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.listener.*.retry.enabled` | `false` | boolean | 是否启用重试 |
| `spring.rabbitmq.listener.*.retry.max-attempts` | `3` | int | 最大重试次数 |
| `spring.rabbitmq.listener.*.retry.initial-interval` | `1000ms` | Duration | 初始重试间隔 |
| `spring.rabbitmq.listener.*.retry.multiplier` | `1.0` | double | 重试间隔倍增系数 |
| `spring.rabbitmq.listener.*.retry.max-interval` | `10000ms` | Duration | 最大重试间隔 |
| `spring.rabbitmq.listener.*.retry.stateless` | `true` | boolean | 是否无状态重试 |

***

## 五、模板配置 (`spring.rabbitmq.template`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.template.mandatory` | - | Boolean | 是否强制投递 |
| `spring.rabbitmq.template.receive-timeout` | - | Duration | 接收超时时间 |
| `spring.rabbitmq.template.reply-timeout` | - | Duration | 回复超时时间 |
| `spring.rabbitmq.template.exchange` | ``| String | 默认交换机 |
| `spring.rabbitmq.template.routing-key` |`` | String | 默认路由键 |
| `spring.rabbitmq.template.default-receive-queue` | - | String | 默认接收队列 |
| `spring.rabbitmq.template.observation-enabled` | - | boolean | 是否启用可观测性 |
| `spring.rabbitmq.template.allowed-list-patterns` | - | `List<String>` | 允许列表模式 |

### 5.1 模板重试配置 (`spring.rabbitmq.template.retry`)

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.template.retry.enabled` | `false` | boolean | 是否启用重试 |
| `spring.rabbitmq.template.retry.max-attempts` | `3` | int | 最大重试次数 |
| `spring.rabbitmq.template.retry.initial-interval` | `1000ms` | Duration | 初始重试间隔 |
| `spring.rabbitmq.template.retry.multiplier` | `1.0` | double | 重试间隔倍增系数 |
| `spring.rabbitmq.template.retry.max-interval` | `10000ms` | Duration | 最大重试间隔 |

***

## 六、Stream 配置 (`spring.rabbitmq.stream`)

Spring Boot 3.x 对 RabbitMQ Stream 协议的原生支持配置。

| 配置属性 | 默认值 | 类型 | 说明 |
|----------|--------|------|------|
| `spring.rabbitmq.stream.host` | `localhost` | String | Stream 服务器主机名 |
| `spring.rabbitmq.stream.port` | `5552` | int | Stream 端口号 |
| `spring.rabbitmq.stream.virtual-host` | - | String | Stream 虚拟主机 |
| `spring.rabbitmq.stream.username` | - | String | Stream 用户名 |
| `spring.rabbitmq.stream.password` | - | String | Stream 密码 |
| `spring.rabbitmq.stream.name` | - | String | Stream 名称 |

***

## 七、示例配置 (application.yml)

```yaml
spring:
  rabbitmq:
    # 基础连接配置
    host: localhost
    port: 5672
    username: guest
    password: guest
    virtual-host: /

    # 多地址配置（可选）
    addresses:
      - amqp://host1:5672
      - amqp://host2:5672
    address-shuffle-mode: ROUND_ROBIN

    # SSL 配置
    ssl:
      enabled: true
      key-store: classpath:client.keystore.p12
      key-store-type: PKCS12
      key-store-password: password
      trust-store: classpath:client.truststore.jks
      trust-store-type: JKS
      trust-store-password: password

    # 连接配置
    requested-heartbeat: 60s
    requested-channel-max: 2047
    connection-timeout: 30s
    channel-rpc-timeout: 10m
    max-inbound-message-body-size: 64MB

    # 发布者确认
    publisher-returns: true
    publisher-confirm-type: CORRELATED

    # 缓存配置
    cache:
      channel:
        size: 25
        checkout-timeout: 5s
      connection:
        mode: CONNECTION
        size: 10

    # 监听器配置
    listener:
      type: SIMPLE
      simple:
        concurrency: 5
        max-concurrency: 10
        prefetch: 10
        missing-queues-fatal: true
        retry:
          enabled: true
          max-attempts: 3
          initial-interval: 1000ms
          multiplier: 2.0
          max-interval: 10s

    # 模板配置
    template:
      exchange: my-exchange
      routing-key: my-routing-key
      receive-timeout: 5s
      reply-timeout: 10s
      retry:
        enabled: true
        max-attempts: 3

    # Stream 配置
    stream:
      host: localhost
      port: 5552
      name: my-stream
```

***

## 八、枚举类型说明

### 8.1 ContainerType（容器类型）

* `SIMPLE` - SimpleMessageListenerContainer
* `DIRECT` - DirectMessageListenerContainer
* `STREAM` - Stream 专用容器

### 8.2 CacheMode（缓存模式）

* `CHANNEL` - 缓存通道（默认）
* `CONNECTION` - 缓存连接

### 8.3 AddressShuffleMode（地址洗牌模式）

* `NONE` - 不洗牌（默认）
* `RANDOM` - 随机选择
* `ROUND_ROBIN` - 轮询选择

***

## 九、注意事项

1. **多主机支持**：如需配置多个主机，请使用 `spring.rabbitmq.addresses` 而非 `spring.rabbitmq.host`
2. **SSL 端口**：启用 SSL 时，默认端口自动切换为 5671
3. **Stream 端口**：RabbitMQ Stream 协议默认使用 5552 端口
4. **虚拟主机**：为空时默认为 `/`
5. **重试机制**：监听器和模板的重试配置是独立的