Java常用中介軟體之 NGINX實現限流功能的官方文件說明

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

Module ngx_http_limit_req_module

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

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當前級別上未定義任何指令時，這些指令才從先前的配置級別繼承。

limit_req_dry_run off;

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.

啟用空執行模式。在這種模式下，請求處理速率不受限制，但是，在共享記憶體區域中，過多請求的數量將照常計算。

limit_req_log_level error;

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級別。

limit_req_status 503;

This directive appeared in version 1.3.15.

該指令出現在1.3.15版中。

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

設定被拒絕的請求而返回響應的狀態程式碼。

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）