# 速率限制

EMQX 提供对接入速度、消息速度的限制，从入口处避免了系统过载，保证了系统的稳定和可预测的吞吐。

## 监听器级别限制器

限制器可以在监听器级别上工作，EMQX 使用以下几种类型的限制器来限制速率:

| 类型                      | Dashboard 字段名                       | 描述                                                         | 过载后行为         |
| :------------------------ | :------------------------------------- | :----------------------------------------------------------- | :----------------- |
| bytes_rate                | 最大消息发布流量（单客户端）           | 单个客户端每秒发布的消息的字节数大小。                         | 暂停接收客户端消息 |
| bytes_burst               | 最大消息发布流量突发速率（单客户端）   | 单个客户端在常规 `数据发布速率` 基础上允许突发发送的数据量。   | 暂停接收客户端消息 |
| messages_rate             | 最大消息发布速率（单客户端）           | 单个客户端每秒发布的消息条数。                                 | 暂停接收客户端消息 |
| messages_burst            | 最大消息发布突发速率（单客户端）       | 在常规 `消息发布速率` 基础上，每个客户端允许突发发送的消息数量。 | 暂停接收客户端消息 |
| max_conn_rate             | 最大连接速率（监听器）                 | 当前监听器每秒的连接数。                                       | 暂停接收新的连接   |
| max_conn_burst            | 最大连接突发速率（监听器）             | 在突发情况下当前监听器可以接受的最大连接数。                   | 暂停接收新的连接   |

投递速率限制器同样在监听器级别生效，但过载行为有所不同，详见[投递速率限制器](#投递速率限制器)。

### 配置监听器级别限制器

您可以在 Dashboard 的**管理** -> **监听器**页面中，为每个监听器设置速率限制。

也可以通过配置文件设置，例如，要为默认的 TCP 监听器设置限制器，可以在 emqx.conf 中按以下进行配置：

```bash
listeners.tcp.default {
  bind = "0.0.0.0:1883"
  max_conn_rate = "1000/s"
  max_conn_burst = "10000/60m"
  messages_rate = "1000/s"
  messages_burst = "10000/60m"
  bytes_rate = "1MB/s"
  bytes_burst = "100MB/60m"
}
```

该配置表示：

- 监听器上连接建立最大速率为每秒 1000 个。
- 在 60 分钟内，监听器上允许接受最多 10000 个连接。
- 消息的最大发布速率为每个客户端每秒 1000 条。
- 每 60 分钟允许在短时间内突发发送最多 10000 条消息。
- 数据的最大发布速率为每个客户端每秒 1MB。
- 每 60 分钟允许在短时间内突发发送最多 100 兆字节。

## 节点级别限制器

限制器还可以在节点级别上工作，限制单个客户端连接每个 EMQX 节点的速度和向节点发布消息和数据的速率。EMQX 节点使用以下几种类型的限制器来限制速率:

| 类型           | Dashboard 字段名 | 描述                                                         | 过载后行为                                                   |
| :------------- | ----------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| bytes_rate     | 数据发布速率      | 单个客户端向每个 EMQX 节点发布的数据量。                       | 当达到限制时，EMQX 将丢弃 QoS 0 消息，并以 "配额超限" 错误码 (0x97) 拒绝 QoS 1 和 QoS 2 消息。 |
| bytes_burst    | 数据发布突发速率  | 在常规 `数据发布速率` 基础上允许突发发送的数据量。             | 当达到限制时，EMQX 将丢弃 QoS 0 消息，并以 "配额超限" 错误码 (0x97) 拒绝 QoS 1 和 QoS 2 消息。 |
| messages_rate  | 消息发布速率      | 单个客户端向每个 EMQX 节点发布消息的速率。                     | 当达到限制时，EMQX 将丢弃 QoS 0 消息，并以 "配额超限" 错误码 (0x97) 拒绝 QoS 1 和 QoS 2 消息。 |
| messages_burst | 消息发布突发速率  | 在常规 `消息发布速率` 基础上，每个节点允许突发发送的消息数量。 | 当达到限制时，EMQX 将丢弃 QoS 0 消息，并以 "配额超限" 错误码 (0x97) 拒绝 QoS 1 和 QoS 2 消息。 |
| max_conn_rate  | 最大连接速率      | 每个节点上接受新连接的速率。                                   | 当达到限制时，EMQX 将暂停处理 Accept 队列中的连接，从而延迟或拒绝新连接。 |
| max_conn_burst | 最大连接突发速率  | 每个节点在常规速率基础上可突发接受的连接数。                   | 暂停接收新的连接                                             |

### 配置节点级别限制器

您可以在 Dashboard 的**管理** -> **MQTT 配置**页面中，为一个 EMQX 节点设置速率限制。

也可以通过配置文件设置，例如，可以在 emqx.conf 中按以下进行配置：

```bash
mqtt.limiter {
  max_conn_rate = "1000/s"
  max_conn_burst = "10000/60m"
  messages_rate = "500/10s"
  messages_burst = "10000/60m"
  bytes_rate = "500KB/s"
  bytes_burst = "100MB/60m"
}
```

节点级别限制器可以嵌入到 `zone` 配置中，如下所示：

```bash
zones.my_zone.mqtt {
  limiter {...}
}
```

该配置表示：

- 每个节点上每秒最多接受 1000 个连接。
- 每 60 分钟允许在短时间内突发接受最多 10000 个连接。
- 每个节点上每 10 秒最多接收 500 条消息，超出部分将被丢弃/拒绝。
- 每 60 分钟允许在短时间内突发发送最多 10000 条消息。
- 每个节点上每 10 秒最多接收 500 兆字节，超出部分将被丢弃/拒绝。
- 每 60 分钟允许在短时间内突发发送最多 100 兆字节。

## 投递速率限制器

除上述发布端限制器外，EMQX 还支持订阅端的投递速率限制。这些限制器控制 EMQX 向订阅客户端投递消息的速率，与消息由哪些客户端发布无关。

| 类型                    | Dashboard 字段名                       | 描述                                                         | 过载后行为                                                   |
| ----------------------- | -------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| delivery_messages_rate  | 最大消息投递速率（单客户端）           | 每个节点向单个订阅者投递消息的最大速率。                       | QoS 0 消息将被丢弃；QoS 1 和 QoS 2 消息将在内部排队，并按照限制器配置推算的延迟时间后重试投递。 |
| delivery_messages_burst | 最大消息投递突发速率（单客户端）       | 在常规 `delivery_messages_rate` 基础上允许的突发量。           | 同上。                                                       |
| delivery_bytes_rate     | 最大消息投递流量（单客户端）           | 每个节点向单个订阅者投递数据的最大速率（字节）。               | QoS 0 消息将被丢弃；QoS 1 和 QoS 2 消息将在内部排队，并按照限制器配置推算的延迟时间后重试投递。 |
| delivery_bytes_burst    | 最大消息投递流量突发速率（单客户端）   | 在常规 `delivery_bytes_rate` 基础上允许的突发量。              | 同上。                                                       |

与发布端限制器不同，投递限制器为通道独立限制器，作用于单个客户端连接，不在 zone 或监听器之间共享。

:::tip
投递速率限制器仅支持内存会话（`durable_sessions.enable = false`），在持久化会话模式下不生效。
:::

### 配置投递速率限制器

您可以在 Dashboard 的**管理** -> **监听器**页面中，为每个监听器设置投递速率限制。

也可以通过配置文件设置，例如，要为默认的 TCP 监听器设置投递速率限制，可以在 emqx.conf 中按以下进行配置：

```bash
listeners.tcp.default {
  bind = "0.0.0.0:1883"
  delivery_messages_rate = "100/s"
  delivery_messages_burst = "500/10s"
  delivery_bytes_rate = "1MB/s"
  delivery_bytes_burst = "10MB/10s"
}
```

该配置表示：

- EMQX 每秒向每个订阅者最多投递 100 条消息；超出速率的 QoS 0 消息将被丢弃，QoS 1/2 消息将排队等待重试。
- EMQX 每秒向每个订阅者最多投递 1 MB 的消息数据；超出部分行为同上。

如未配置，默认值为 `infinity`，保持向后兼容。

## 单位

### 时间单位

速率值中支持的时间单位可以是：

- **s**: 秒
- **m**: 分钟
- **h**: 小时
- **d**: 天

时间单位也可以是一个间隔值，例如 `1000/10s` 表示将限制设置为每 10 秒 1000。

### 尺寸单位

速率值中支持的字节数大小单位可以是：

- **KB**: 千字节
- **MB**: 兆字节
- **GB**: 吉字节