Java常用中间件之 NGINX实现限流功能的官方文档说明

官方文档：http://nginx.org/en/docs/http/ngx_http_limit_req_module.html

Module ngx_http_limit_req_module

Example Configuration 示例配置 指令 Directives      limit_req      limit_req_dry_run      limit_req_log_level      limit_req_status      limit_req_zone   嵌入式变量 Embedded Variables

The ngx_http_limit_req_module module (0.7.21) is used to limit the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address. The limitation is done using the “leaky bucket” method.

ngx_http_limit_req_module模块（0.7.21）用于限制每一个定义的密钥的请求的处理速率，特别是从一个单一的IP地址的请求的处理速率。使用“漏桶算法”完成限制。

 

Example Configuration

配置示例

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

    ...

    server {

        ...

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

 

Directives

Syntax:语法	limit_req zone=name [burst=number] [nodelay | delay=number];
Default: 默认	—
Context:内容（作用范围）	http, server, location

Sets the shared memory zone and the maximum burst size of requests. If the requests rate exceeds the rate configured for a zone, their processing is delayed such that requests are processed at a defined rate. Excessive requests are delayed until their number exceeds the maximum burst size in which case the request is terminated with an error. By default, the maximum burst size is equal to zero. For example, the directives

设置共享内存区域和请求的最大突发大小。如果请求速率超过了区域配置的速率，则会延迟其处理，以便以定义的速率处理该请求。过多的请求将被延迟，直到其数量超过最大突发大小为止，在这种情况下，该请求将因错误而终止 。默认情况下，最大突发大小等于零。例如，指令

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

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

allow not more than 1 request per second at an average, with bursts not exceeding 5 requests.

If delaying of excessive requests while requests are being limited is not desired, the parameter nodelay should be used:

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

如果不需要在限制请求时延迟过多的请求，则应使用nodelay参数：

limit_req zone=one burst=5 nodelay;

The delay parameter (1.15.7) specifies a limit at which excessive requests become delayed. Default value is zero, i.e. all excessive requests are delayed.

There could be several limit_req directives. For example, the following configuration will limit the processing rate of requests coming from a single IP address and, at the same time, the request processing rate by the virtual server:

delay参数（1.15.7），用于指定过多的请求延迟的限制。默认值为零，即所有多余的请求都会延迟。

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

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;
}

These directives are inherited from the previous configuration level if and only if there are no limit_req directives defined on the current level.

当且仅当limit_req当前级别上未定义任何指令时，这些指令才从先前的配置级别继承。

Syntax:	limit_req_dry_run on | off;
Default:	limit_req_dry_run off;
Context:	http, server, location

This directive appeared in version 1.17.1.

该指令出现在1.17.1版中

Enables the dry run mode. In this mode, requests processing rate is not limited, however, in the shared memory zone, the number of excessive requests is accounted as usual.

启用空运行模式。在这种模式下，请求处理速率不受限制，但是，在共享内存区域中，过多请求的数量将照常计算。

Syntax:	limit_req_log_level info | notice | warn | error;
Default:	limit_req_log_level error;
Context:	http, server, location

This directive appeared in version 0.8.18.

该指令出现在版本0.8.18中。

Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Logging level for delays is one point less than for refusals; for example, if “limit_req_log_level notice” is specified, delays are logged with the info level.

在服务器由于速率超出而拒绝处理请求或延迟请求处理的情况下，设置所需的日志记录级别。延迟的记录级别比拒绝的记录级别少一个等级；例如，如果limit_req_log_level notice指定“ ” ，则将延迟记录为该info级别。

Syntax:	limit_req_status code;
Default:	limit_req_status 503;
Context:	http, server, location

This directive appeared in version 1.3.15.

该指令出现在1.3.15版中。

Sets the status code to return in response to rejected requests.

设置被拒绝的请求而返回响应的状态代码。

Syntax:	limit_req_zone key zone=name:size rate=rate [sync];
Default:	—
Context:	http

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state stores the current number of excessive requests. The key can contain text, variables, and their combination. Requests with an empty key value are not accounted.

设置共享内存区域的参数，该参数将保留各种键的状态。特别是，状态存储了当前过多请求的数量。该key可以包含文本，变量，他们的组合。具有空键值的请求不予考虑。

Prior to version 1.7.6, a  key could contain exactly one variable.

在版本1.7.6之前，一个 key只包含一个变量。

Usage example:

用法示例：

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

Here, the states are kept in a 10 megabyte zone “one”, and an average request processing rate for this zone cannot exceed 1 request per second.

A client IP address serves as a key. Note that instead of $remote_addr, the $binary_remote_addr variable is used here. The $binary_remote_addr variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 64 bytes on 32-bit platforms and 128 bytes on 64-bit platforms. One megabyte zone can keep about 16 thousand 64-byte states or about 8 thousand 128-byte states.

在这里，状态保持在10兆字节的区域“ one”中，并且该区域的平均请求处理速率不能超过每秒1个请求。

客户端IP地址用作密钥。注意，代替$remote_addr，该 $binary_remote_addr变量在这里使用。$binary_remote_addr对于IPv4地址，变量的大小始终为4个字节，对于IPv6地址，变量的大小始终为16个字节。存储状态在32位平台上始终占据64字节，在64位平台上始终占据128字节。一兆字节的区域可以保留约1.6万个64字节状态或约8000个128字节状态。

If the zone storage is exhausted, the least recently used state is removed. If even after that a new state cannot be created, the request is terminated with an error.

The rate is specified in requests per second (r/s). If a rate of less than one request per second is desired, it is specified in request per minute (r/m). For example, half-request per second is 30r/m.

如果区域存储已用尽，则将删除最近最少使用的状态。如果即使在此之后仍无法创建新状态，则请求将以error终止。

该速率以每秒请求数（r / s）指定。如果希望速率小于每秒一个请求，则以每分钟请求数（r / m）来指定。例如，每秒0.5请求为30r / m。

The sync parameter (1.15.3) enables synchronization of the shared memory zone.

sync参数（1.15.3）开启 同步 共享存储区域。

The  sync parameter is available as part of our  commercial subscription.

此外，作为我们的商业订阅的一部分， 可以从1.17.7开始 使用API获取或 重置每个此类共享存储区 的 状态信息。

Additionally, as part of our  commercial subscription, the  status information for each such shared memory zone can be  obtained or  reset with the  API since 1.17.7.

 

Embedded Variables

嵌入式变量

$limit_req_status

keeps the result of limiting the request processing rate (1.17.6): 

使用PASSED, DELAYED, REJECTED, DELAYED_DRY_RUN, or REJECTED_DRY_RUN 保持限制请求处理率的结果（1.17.6）