# 速率限制器配置

速率限制器是在 EMQX 5.0 中引入的一项新功能，它是一种机制，用于限制客户端或主题在指定时间段内可以发布或订阅的消息数量。有关限制器及其工作原理的更多信息，请参见[速率限制](../rate-limit/rate-limit.md)。

## 监听器级别限制器

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

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

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

例如，要为默认的 TCP 监听器设置一个限制器，您可以使用以下配置：

```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 | 最大连接突发速率  | 每个节点在常规速率基础上可突发接受的连接数。                   | 暂停接收新的连接                                             |

例如，要为节点设置一个限制器，您可以使用以下配置：

```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"
}
```

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

::: tip

EMQX 提供了更多配置项以更好地满足定制化需求。详情请参见 [EMQX 企业版配置手册](https://docs.emqx.com/zh/enterprise/v6.2.0/hocon/)。

:::