<!-- review: finished -->

<a id="http-limit-req"></a>

# Limit Req

该模块用于限制每个定义键的请求处理速率，特别是来自单个 IP 地址的请求处理速率。该限制是使用"漏桶"方法实现的。

<a id="configuration-example-26"></a>

## 配置示例

```nginx
http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    ...

    server {

        ...

        location /search/ {
            limit_req zone=one burst=5;
        }
```

<a id="directives-27"></a>

## 指令

<a id="index-0"></a>

<a id="limit-req-1"></a>

### limit_req

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req` `zone=`name [`burst=`number] [nodelay | `delay=`number];   |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| 默认                                                                                   | —                                                                      |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                 |

设置共享内存区域和请求的最大突发大小。如果请求速率超过为区域配置的速率，则其处理将被延迟，以使请求以定义的速率进行处理。过多的请求会被延迟，直到其数量超过最大突发大小，此时请求将以 [错误](#limit-req-status) 终止。默认情况下，最大突发大小等于零。例如，以下指令

```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    location /search/ {
        limit_req zone=one burst=5;
    }
```

平均允许每秒不超过 1 个请求，突发不超过 5 个请求。

如果不希望在请求受到限制时延迟过多的请求，则应使用参数 `nodelay`：

```nginx
limit_req zone=one burst=5 nodelay;
```

`delay` 参数指定过多请求变为延迟的限制。默认值为零，即所有过多的请求都将被延迟。

可以有多个 `limit_req` 指令。例如，以下配置将限制来自单个 IP 地址的请求处理速率，同时限制虚拟服务器的请求处理速率：

```nginx
limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;
limit_req_zone $server_name zone=perserver:10m rate=10r/s;

server {
    ...
    limit_req zone=perip burst=5 nodelay;
    limit_req zone=perserver burst=10;
}
```

这些指令仅在当前级别没有定义 `limit_req` 指令时，从上一级配置级别继承。

<a id="index-1"></a>

<a id="limit-req-dry-run"></a>

### limit_req_dry_run

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_dry_run` `on` | `off`;   |
|--------------------------------------------------------------------------------------|-------------------------------------|
| 默认                                                                                   | `limit_req_dry_run off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location              |

启用干运行模式。在此模式下，请求处理速率不受限制，但在 [共享内存区域](#limit-req-zone) 中，过多请求的数量仍然会被正常记录。

<a id="index-2"></a>

<a id="limit-req-log-level"></a>

### limit_req_log_level

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_log_level` `info` | `notice` | `warn` | `error`;   |
|--------------------------------------------------------------------------------------|---------------------------------------------------------------|
| 默认                                                                                   | `limit_req_log_level error;`                                  |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                        |

设置服务器由于速率超限而拒绝处理请求或延迟请求处理的日志记录级别。延迟的日志记录级别比拒绝的日志记录级别低一级；例如，如果指定了 `limit_req_log_level notice`，则延迟将以 `info` 级别记录。

<a id="index-3"></a>

<a id="limit-req-status"></a>

### limit_req_status

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_status` code;   |
|--------------------------------------------------------------------------------------|----------------------------|
| 默认                                                                                   | `limit_req_status 503;`    |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location     |

设置拒绝请求时返回的状态码。

<a id="index-4"></a>

<a id="limit-req-zone"></a>

### limit_req_zone

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `limit_req_zone` key `zone=`name:size `rate=`rate;   |
|--------------------------------------------------------------------------------------|------------------------------------------------------|
| 默认                                                                                   | —                                                    |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                 |

设置共享内存区域的参数，该区域将为各种键保留状态。特别是，状态存储当前的过多请求数量。键可以包含文本、变量及其组合。键值为空的请求不被计入。

使用示例：

```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
```

在这里，状态保存在 10 兆字节的区域 `one` 中，该区域的平均请求处理速率不得超过每秒 1 个请求。

客户端 IP 地址作为键。请注意，这里使用的是 `$binary_remote_addr` 变量，而不是 `$remote_addr`。

对于 IPv4 地址，变量 `$binary_remote_addr` 的大小始终为 4 字节，对于 IPv6 地址，大小为 16 字节。存储的状态在 32 位平台上始终占用 64 字节，在 64 位平台上占用 128 字节。

一个兆字节的区域可以保存大约 16000 个 64 字节的状态或大约 8000 个 128 字节的状态。

如果区域存储已耗尽，将删除最近最少使用的状态。如果即便如此仍无法创建新状态，则请求将以 [错误](#limit-req-status) 终止。

`rate` 以每秒请求数（r/s）表示。如果希望速率低于每秒一个请求，则以每分钟请求数（r/m）表示。例如，每秒半个请求表示为 30r/m。

<a id="built-in-variables-3"></a>

## 内置变量

<a id="v-limit-req-status"></a>

### `$limit_req_status`

保持限制请求处理速率的结果：`PASSED`、`DELAYED`、`REJECTED`、`DELAYED_DRY_RUN` 或 `REJECTED_DRY_RUN`