Лимиты запросов (rate limiting)

Какие виды лимитов можно настроить, как использовать плагины, как выбрать плагин для вашего случая.

Что это

Лимит запросов (rate limit) — порог запросов, которые клиент может отправить к API или которые одновременно могут находиться в обработке.

Все запросы выше порога будут заблокированы: Application Delivery Controller не пропустит их к upstream и вернёт клиенту ошибку.

Зачем нужны

Лимиты запросов помогают:

защитить бэкенд от перегрузки;
остановить клиентов, которые отправляют слишком много запросов из-за ошибки или злоупотребления;
распределить ресурсы между потребителями API;
задать разные лимиты для разных клиентов, маршрутов или тарифов;
сохранить предсказуемое качество сервиса при всплесках трафика.

Какой ответ получает клиент, который превысил лимит

Клиент получит одну из ошибку 503 Service Temporarily Unavailable, 414 Request-URI Too Large либо 400 Bad Request — в зависимости от того, какой лимит превысил.

В настройках плагинов limit-req, limit-count и limit-conn вы можете задать другой код ответа через rejected_code. Обычно для лимитов запросов используют 429 Too Many Requests.

Виды лимитов

Можно устанавливать лимиты по разным основаниям: Consumer, IP-адресу, Route, количеству HTTP-заголовков в запросе, размеру request line / поля HTTP-заголовка или общему трафику, который проходит через Application Delivery Controller.

request line включает в себя HTTP-метод, URI ресурса и версию протокола HTTP. Пример: GET /search?q=iphone&color=black HTTP/1.1.

Вид Как работает Когда использовать Что учитывать

Вид	Как работает	Когда использовать	Что учитывать
По Consumer	Считается число запросов от конкретного Consumer. При превышении лимита запросы этого Consumer отклоняются.	Для API с аутентификацией, тарифами, SLA или индивидуальными лимитами клиентов.	Система должна сначала определить клиента через auth plugin: например, по API key, JWT или другому credential.
По IP-адресу	Считается число запросов с конкретного IP-адреса. При превышении лимита запросы с этого адреса отклоняются.	Для публичных эндпоинтов без аутентификации: открытых справочников, health check или публичных API.	За одним IP может находиться много реальных пользователей: например, в корпоративной сети, за NAT или у мобильного оператора.
По Route	Считается число запросов к конкретному Route. При превышении лимита новые запросы к этому Route отклоняются.	Когда разные эндпоинты создают разную нагрузку на бэкенд: например, простой запрос метаданных можно лимитировать мягче, а тяжёлый поиск по большой базе — жёстче.	Лимит нужно подбирать с учётом нагрузки, которую создаёт конкретный эндпоинт.
Глобально	Считается общий поток запросов через Application Delivery Controller. При превышении лимита новые запросы отклоняются независимо от клиента или маршрута.	Как дополнительная защита всей системы, если суммарный трафик всех клиентов приближается к пределу инфраструктуры.	Лимит лучше ставить на значение суммарной нагрузки, которое приближается к пределу инфраструктуры.
По количеству HTTP-заголовков	Считается количество HTTP-заголовков в запросе. Если их больше заданного `max_headers`, запрос отклоняется с `400 Bad Request`.	Когда нужно защититься от запросов с чрезмерным числом заголовков: ошибок клиентов, некорректно настроенных интеграций или попыток перегрузить обработку заголовков.	При выставлении лимита учитывайте служебные заголовки, которые добавляют прокси, WAF, CDN и клиентские SDK.
По размеру request line и каждого отдельного поля HTTP-заголовка	Nginx принимает request line и поля заголовков в буферы фиксированного размера. Если что-то из этого не помещается в один большой буфер, запрос отклоняется.	Когда нужно ограничить слишком длинную request line или крупные заголовки.	Перед установкой лимита проверьте реальные размеры возможной request line, включая query string, и отдельных заголовков, особенно `Cookie` и `Authorization`.

По Consumer

Считается число запросов от конкретного Consumer. При превышении лимита запросы этого Consumer отклоняются.

Для API с аутентификацией, тарифами, SLA или индивидуальными лимитами клиентов.

Система должна сначала определить клиента через auth plugin: например, по API key, JWT или другому credential.

По IP-адресу

Считается число запросов с конкретного IP-адреса. При превышении лимита запросы с этого адреса отклоняются.

Для публичных эндпоинтов без аутентификации: открытых справочников, health check или публичных API.

За одним IP может находиться много реальных пользователей: например, в корпоративной сети, за NAT или у мобильного оператора.

По Route

Считается число запросов к конкретному Route. При превышении лимита новые запросы к этому Route отклоняются.

Когда разные эндпоинты создают разную нагрузку на бэкенд: например, простой запрос метаданных можно лимитировать мягче, а тяжёлый поиск по большой базе — жёстче.

Лимит нужно подбирать с учётом нагрузки, которую создаёт конкретный эндпоинт.

Глобально

Считается общий поток запросов через Application Delivery Controller. При превышении лимита новые запросы отклоняются независимо от клиента или маршрута.

Как дополнительная защита всей системы, если суммарный трафик всех клиентов приближается к пределу инфраструктуры.

Лимит лучше ставить на значение суммарной нагрузки, которое приближается к пределу инфраструктуры.

По количеству HTTP-заголовков

Считается количество HTTP-заголовков в запросе. Если их больше заданного max_headers, запрос отклоняется с 400 Bad Request.

Когда нужно защититься от запросов с чрезмерным числом заголовков: ошибок клиентов, некорректно настроенных интеграций или попыток перегрузить обработку заголовков.

При выставлении лимита учитывайте служебные заголовки, которые добавляют прокси, WAF, CDN и клиентские SDK.

По размеру request line и каждого отдельного поля HTTP-заголовка

Nginx принимает request line и поля заголовков в буферы фиксированного размера. Если что-то из этого не помещается в один большой буфер, запрос отклоняется.

Когда нужно ограничить слишком длинную request line или крупные заголовки.

Перед установкой лимита проверьте реальные размеры возможной request line, включая query string, и отдельных заголовков, особенно Cookie и Authorization.

Как установить лимиты запросов

Большинство лимитов устанавливаются с помощью плагинов:

limit-req — ограничивает частоту запросов в секунду;
limit-count — ограничивает количество запросов за временной период;
limit-conn — ограничивает количество одновременных активных запросов;
header-count-limit — ограничивает количество HTTP-заголовков в запросе.

Лимиты по максимальному размеру request line и каждого отдельного поля HTTP-заголовка устанавливается через настройки Nginx в conf/config.yaml: client_header_buffer_size и large_client_header_buffers.

Рассказываем ниже конфигурацию и подключение плагинов, а также про лимит, который настраивается на Nginx.

limit-req

Что ограничивает. limit-req ограничивает частоту запросов: сколько запросов в секунду система будет передавать в upstream.

Как работает. Плагин работает по алгоритму leaky bucket. В этом алгоритме вы задаёте два значения:

rate — основную скорость обработки запросов;
burst — небольшой люфт: число запросов, на которое клиент может кратковременно превысить rate.

Если клиент отправляет запросы в пределах rate, система сразу передаёт их в upstream.

Если клиент кратковременно превышает rate, но превышение укладывается в burst, лишние запросы не блокируются. Они становятся в очередь и постепенно отправляются в upstream с заданной скоростью rate.
Если очередь уже заполнена, то есть превышение стало больше burst, новые запросы отклоняются и клиент получает ошибку, заданную в rejected_code.

Пример. Настроено:

rate = 10
burst = 20

Это значит: система стабильно выпускает в upstream 10 запросов в секунду. Если клиент отправит больше, до 20 лишних запросов могут встать в очередь. Всё, что придёт сверх этого люфта, будет отклонено.

Когда пригодится. limit-req подходит, когда нужно защитить бэкенд от резких всплесков и выровнять поток запросов.

Например, его можно использовать для эндпоинтов, которые выдерживают стабильную нагрузку, но плохо переносят резкие пики: поиск, авторизация, генерация отчётов, обращения к внешним системам.

Атрибуты.

Атрибут Тип Обяз. По умолч. Допустимые значения Описание

Атрибут	Тип	Обяз.	По умолч.	Допустимые значения	Описание
`rate`	`integer`	Да		`> 0`	Максимальное число запросов в секунду. Запросы сверх `rate`, но в пределах `burst`, задерживаются и становятся в очередь.
`burst`	`integer`	Да		`>= 0`	Число запросов в секунду, которые можно задержать для throttling. Запросы сверх `rate` и `burst` отклоняются.
`key_type`	`string`	Нет	`var`	`var` / `var_` `combination`	Тип `key.var` интерпретирует `key` как переменную; `var_combination` — как комбинацию переменных.
`key`	`string`	Да	`remote_` `addr`		Признак, по которому считаются запросы. Для `var` указывается имя переменной без `$`. Для `var_combination` все переменные указываются с `$`.
`rejected_code`	`integer`	Нет	`503`	`200…599`	HTTP-код, который возвращается при отклонении запроса из-за превышения лимита.
`rejected_msg`	`string`	Нет		`non-empty`	Тело ответа, которое возвращается при отклонении запроса из-за превышения лимита.
`nodelay`	`boolean`	Нет	`false`		Если `true`, запросы в пределах `burst` не задерживаются.
`allow_degradation`	`boolean`	Нет	`false`		Если `true`, система продолжит обрабатывать запросы без плагина, когда плагин или его зависимости недоступны.
`policy`	`string`	Нет	`local`	`local` / `redis` / `redis-cluster`	Политика хранения счётчика. `local` — в памяти узла; `redis` — в Redis; `redis-cluster` — в Redis Cluster.
`redis_host`	`string`	Нет			Адрес узла Redis. Обязателен при `policy = redis`.
`redis_port`	`integer`	Нет	`6379`	`>= 1`	Порт Redis при `policy = redis`.
`redis_username`	`string`	Нет			Имя пользователя Redis при использовании Redis ACL. Для legacy `requirepass` задавайте только `redis_password`.
`redis_password`	`string`	Нет			Пароль Redis при `policy = redis` или `redis-cluster`.
`redis_ssl`	`boolean`	Нет	`false`		Если `true`, используется SSL-подключение к Redis при `policy = redis`.
`redis_ssl_verify`	`boolean`	Нет	`false`		Если `true`, проверяется SSL-сертификат сервера Redis при `policy = redis`.
`redis_database`	`integer`	Нет	`0`	`>= 0`	Номер базы данных Redis при `policy = redis`.
`redis_timeout`	`integer`	Нет	`1000`	`>= 1`	Таймаут Redis в миллисекундах при `policy = redis` или `redis-cluster`.
`redis_keepalive_` `timeout`	`integer`	Нет	`10000`	`>= 1000`	Keepalive timeout для Redis в миллисекундах при `policy = redis` или `redis-cluster`.
`redis_keepalive_` `pool`	`integer`	Нет	`100`	`>= 1`	Размер keepalive pool для Redis при `policy = redis` или `redis-cluster`.
`redis_cluster_` `nodes`	`array` `[string]`	Нет			Список узлов Redis Cluster. Требуется минимум два адреса. Обязателен при `policy = redis-cluster`.
`redis_cluster_` `name`	`string`	Нет			Имя Redis Cluster. Обязательно при `policy = redis-cluster`.
`redis_cluster_` `ssl`	`boolean`	Нет	`false`		Если `true`, используется SSL-подключение к Redis Cluster при `policy = redis-cluster`.
`redis_cluster_` `ssl_verify`	`boolean`	Нет	`false`		Если `true`, проверяется SSL-сертификат сервера Redis Cluster при `policy = redis-cluster`.

rate

integer

Да

> 0

Максимальное число запросов в секунду. Запросы сверх rate, но в пределах burst, задерживаются и становятся в очередь.

burst

integer

Да

>= 0

Число запросов в секунду, которые можно задержать для throttling. Запросы сверх rate и burst отклоняются.

key_type

string

Нет

var

var / var_
combination

Тип key.var интерпретирует key как переменную; var_combination — как комбинацию переменных.

key

string

Да

remote_
addr

Признак, по которому считаются запросы. Для var указывается имя переменной без $. Для var_combination все переменные указываются с $.

rejected_code

integer

Нет

503

200…599

HTTP-код, который возвращается при отклонении запроса из-за превышения лимита.

rejected_msg

string

Нет

non-empty

Тело ответа, которое возвращается при отклонении запроса из-за превышения лимита.

nodelay

boolean

Нет

false

Если true, запросы в пределах burst не задерживаются.

allow_degradation

boolean

Нет

false

Если true, система продолжит обрабатывать запросы без плагина, когда плагин или его зависимости недоступны.

policy

string

Нет

local

local / redis / redis-cluster

Политика хранения счётчика. local — в памяти узла; redis — в Redis; redis-cluster — в Redis Cluster.

redis_host

string

Нет

Адрес узла Redis. Обязателен при policy = redis.

redis_port

integer

Нет

6379

>= 1

Порт Redis при policy = redis.

redis_username

string

Нет

Имя пользователя Redis при использовании Redis ACL. Для legacy requirepass задавайте только redis_password.

redis_password

string

Нет

Пароль Redis при policy = redis или redis-cluster.

redis_ssl

boolean

Нет

false

Если true, используется SSL-подключение к Redis при policy = redis.

redis_ssl_verify

boolean

Нет

false

Если true, проверяется SSL-сертификат сервера Redis при policy = redis.

redis_database

integer

Нет

0

>= 0

Номер базы данных Redis при policy = redis.

redis_timeout

integer

Нет

1000

>= 1

Таймаут Redis в миллисекундах при policy = redis или redis-cluster.

redis_keepalive_
timeout

integer

Нет

10000

>= 1000

Keepalive timeout для Redis в миллисекундах при policy = redis или redis-cluster.

redis_keepalive_
pool

integer

Нет

100

>= 1

Размер keepalive pool для Redis при policy = redis или redis-cluster.

redis_cluster_
nodes

array
[string]

Нет

Список узлов Redis Cluster. Требуется минимум два адреса. Обязателен при policy = redis-cluster.

redis_cluster_
name

string

Нет

Имя Redis Cluster. Обязательно при policy = redis-cluster.

redis_cluster_
ssl

boolean

Нет

false

Если true, используется SSL-подключение к Redis Cluster при policy = redis-cluster.

redis_cluster_
ssl_verify

boolean

Нет

false

Если true, проверяется SSL-сертификат сервера Redis Cluster при policy = redis-cluster.

Пример конфигурации. Route с limit-req ограничивает запросы по IP-адресу клиента: 1 запрос в секунду и 1 дополнительный запрос в очереди.

{
  "uri": "/get",
  "limit_req": {
    "rate": 1,
    "burst": 1,
    "key": "remote_addr",
    "rejected_code": 429
  }
}

limit-count

Что ограничивает. limit-count ограничивает количество запросов за заданный период. Например:

100 запросов в минуту;
10 000 запросов в день;
1 000 000 запросов в месяц.

Как работает. Система считает запросы, которые попадают в один счётчик лимита. Счётчик может быть привязан к Consumer, IP-адресу, Route или другому признаку.

Когда число запросов достигает заданного лимита, новые запросы отклоняются до конца текущего периода.

В распределённой установке, где работает несколько узлов Application Delivery Controller, для limit-count нужен общий счётчик. Для этого используется Redis или Redis Cluster. Тогда лимит считается не отдельно на каждом узле, а для всей группы.

Когда пригодится. limit-count подходит для квот: тарифных планов, SLA, дневных, минутных или месячных лимитов.

Например, его можно использовать, если клиенту разрешено не больше 10 000 запросов в день или не больше 100 запросов в минуту к конкретному Route.

Особенности. limit-count может добавлять в ответы заголовки с состоянием лимита:

Заголовок Что значит

Заголовок	Что значит
`X-RateLimit-Limit`	Общий лимит запросов
`X-RateLimit-Remaining`	Сколько запросов осталось до достижения лимита
`X-RateLimit-Reset`	Через сколько секунд сбросится счётчик

X-RateLimit-Limit

Общий лимит запросов

X-RateLimit-Remaining

Сколько запросов осталось до достижения лимита

X-RateLimit-Reset

Через сколько секунд сбросится счётчик

Эти заголовки помогают API-клиенту отслеживать оставшуюся квоту и заранее замедлять отправку запросов. Добавление заголовков настраивается через атрибуты.

Атрибуты.

Атрибут Тип Обяз. По умолч. Допустимые значения Описание

Атрибут	Тип	Обяз.	По умолч.	Допустимые значения	Описание
`count`	`integer`	Нет		`> 0`	Максимальное число запросов за заданный интервал. Обязателен, если не настроен `rules`.
`time_window`	`integer`	Нет		`> 0`	Интервал времени в секундах, которому соответствует `count`. Обязателен, если не настроен `rules`.
`rules`	`array` `[object]`	Нет			Список правил rate limiting. Каждое правило содержит `count`, `time_window` и `key`.
`rules.count`	`integer`	Да		`> 0`	Максимальное число запросов за заданный интервал.
`rules.time_window`	`integer`	Да		`> 0`	Интервал времени в секундах, которому соответствует `count`.
`rules.key`	`string`	Да			Ключ для подсчёта запросов. Если ключ не существует, правило не выполняется. Интерпретируется как комбинация переменных, например `$http_custom_a $http_custom_b`.
`rules.header_prefix`	`string`	Нет			Префикс для rate limit headers: `X-{header_prefix}-RateLimit-Limit`, `X-{header_prefix}-RateLimit-Remaining`, `X-{header_prefix}-RateLimit-Reset`. Если не задан, используется индекс правила.
`key_type`	`string`	Нет	`var`	`var` / `var_` `combination` / `constant`	Тип `key`. `var` — переменная; `var_combination` — комбинация переменных; `constant` — постоянное значение.
`key`	`string`	Нет	`remote_addr`		Признак, по которому считаются запросы. Для `var` указывается имя переменной без `$`. Для `var_combination` все переменные указываются с `$`. Для `constant` `key` считается постоянным значением.
`rejected_code`	`integer`	Нет	`503`	`200…599`	HTTP-код, который возвращается при отклонении запроса из-за превышения лимита.
`rejected_msg`	`string`	Нет		`non-empty`	Тело ответа, которое возвращается при отклонении запроса из-за превышения лимита.
`allow_degradation`	`boolean`	Нет	`false`		Если `true`, система продолжит обрабатывать запросы без плагина, когда плагин или его зависимости недоступны.
`policy`	`string`	Нет	`local`	`local` / `redis` / `redis-cluster`	Политика хранения счётчика. `local` — в памяти узла; `redis` — в Redis; `redis-cluster` — в Redis Cluster.
`show_limit_quota_` `header`	`boolean`	Нет	`true`		Если `true`, в ответ добавляются `X-RateLimit-Limit` и `X-RateLimit-Remaining`.
`group`	`string`	Нет		`non-empty`	ID группы плагина. Routes с одной `group` могут использовать общий счётчик запросов.
`redis_host`	`string`	Нет			Адрес узла Redis. Обязателен при `policy = redis`.
`redis_port`	`integer`	Нет	`6379`	`>= 1`	Порт Redis при `policy = redis`.
`redis_username`	`string`	Нет			Имя пользователя Redis при использовании Redis ACL. Для legacy `requirepass` задавайте только `redis_password`.
`redis_password`	`string`	Нет			Пароль Redis при `policy = redis` или `redis-cluster`.
`redis_ssl`	`boolean`	Нет	`false`		Если `true`, используется SSL-подключение к Redis при `policy = redis`.
`redis_ssl_verify`	`boolean`	Нет	`false`		Если `true`, проверяется SSL-сертификат сервера Redis при `policy = redis`.
`redis_database`	`integer`	Нет	`0`	`>= 0`	Номер базы данных Redis при `policy = redis`.
`redis_timeout`	`integer`	Нет	`1000`	`>= 1`	Таймаут Redis в миллисекундах при `policy = redis` или `redis-cluster`.
`redis_keepalive_` `timeout`	`integer`	Нет	`10000`	`>= 1000`	Keepalive timeout для Redis в миллисекундах при `policy = redis` или `redis-cluster`.
`redis_keepalive_` `pool`	`integer`	Нет	`100`	`>= 1`	Размер keepalive pool для Redis при `policy = redis` или `redis-cluster`.
`redis_cluster_` `nodes`	`array` `[string]`	Нет			Список узлов Redis Cluster. Требуется минимум два адреса. Обязателен при `policy = redis-cluster`.
`redis_cluster_` `name`	`string`	Нет			Имя Redis Cluster. Обязательно при `policy = redis-cluster`.
`redis_cluster_` `ssl`	`boolean`	Нет	`false`		Если `true`, используется SSL-подключение к Redis Cluster при `policy = redis-cluster`.
`redis_cluster_` `ssl_verify`	`boolean`	Нет	`false`		Если `true`, проверяется SSL-сертификат сервера Redis Cluster при `policy = redis-cluster`.

count

integer

Нет

> 0

Максимальное число запросов за заданный интервал. Обязателен, если не настроен rules.

time_window

integer

Нет

> 0

Интервал времени в секундах, которому соответствует count. Обязателен, если не настроен rules.

rules

array
[object]

Нет

Список правил rate limiting. Каждое правило содержит count, time_window и key.

rules.count

integer

Да

> 0

Максимальное число запросов за заданный интервал.

rules.time_window

integer

Да

> 0

Интервал времени в секундах, которому соответствует count.

rules.key

string

Да

Ключ для подсчёта запросов. Если ключ не существует, правило не выполняется. Интерпретируется как комбинация переменных, например $http_custom_a $http_custom_b.

rules.header_prefix

string

Нет

Префикс для rate limit headers: X-{header_prefix}-RateLimit-Limit, X-{header_prefix}-RateLimit-Remaining, X-{header_prefix}-RateLimit-Reset. Если не задан, используется индекс правила.

key_type

string

Нет

var

var / var_
combination / constant

Тип key. var — переменная; var_combination — комбинация переменных; constant — постоянное значение.

key

string

Нет

remote_addr

Признак, по которому считаются запросы. Для var указывается имя переменной без $. Для var_combination все переменные указываются с $. Для constant key считается постоянным значением.

rejected_code

integer

Нет

503

200…599

HTTP-код, который возвращается при отклонении запроса из-за превышения лимита.

rejected_msg

string

Нет

non-empty

Тело ответа, которое возвращается при отклонении запроса из-за превышения лимита.

allow_degradation

boolean

Нет

false

Если true, система продолжит обрабатывать запросы без плагина, когда плагин или его зависимости недоступны.

policy

string

Нет

local

local / redis / redis-cluster

Политика хранения счётчика. local — в памяти узла; redis — в Redis; redis-cluster — в Redis Cluster.

show_limit_quota_
header

boolean

Нет

true

Если true, в ответ добавляются X-RateLimit-Limit и X-RateLimit-Remaining.

group

string

Нет

non-empty

ID группы плагина. Routes с одной group могут использовать общий счётчик запросов.

redis_host

string

Нет

Адрес узла Redis. Обязателен при policy = redis.

redis_port

integer

Нет

6379

>= 1

Порт Redis при policy = redis.

redis_username

string

Нет

Имя пользователя Redis при использовании Redis ACL. Для legacy requirepass задавайте только redis_password.

redis_password

string

Нет

Пароль Redis при policy = redis или redis-cluster.

redis_ssl

boolean

Нет

false

Если true, используется SSL-подключение к Redis при policy = redis.

redis_ssl_verify

boolean

Нет

false

Если true, проверяется SSL-сертификат сервера Redis при policy = redis.

redis_database

integer

Нет

0

>= 0

Номер базы данных Redis при policy = redis.

redis_timeout

integer

Нет

1000

>= 1

Таймаут Redis в миллисекундах при policy = redis или redis-cluster.

redis_keepalive_
timeout

integer

Нет

10000

>= 1000

Keepalive timeout для Redis в миллисекундах при policy = redis или redis-cluster.

redis_keepalive_
pool

integer

Нет

100

>= 1

Размер keepalive pool для Redis при policy = redis или redis-cluster.

redis_cluster_
nodes

array
[string]

Нет

Список узлов Redis Cluster. Требуется минимум два адреса. Обязателен при policy = redis-cluster.

redis_cluster_
name

string

Нет

Имя Redis Cluster. Обязательно при policy = redis-cluster.

redis_cluster_
ssl

boolean

Нет

false

Если true, используется SSL-подключение к Redis Cluster при policy = redis-cluster.

redis_cluster_
ssl_verify

boolean

Нет

false

Если true, проверяется SSL-сертификат сервера Redis Cluster при policy = redis-cluster.

Пример конфигурации. Route с limit-count разрешает 1 запрос за 30 секунд для каждого IP-адреса клиента.

{
  "uri": "/get",
  "plugins": {
    "limit-count": {
      "count": 1,
      "time_window": 30,
      "rejected_code": 429,
      "key_type": "var",
      "key": "remote_addr"
    }
  }
}

limit-conn

Что ограничивает. limit-conn ограничивает количество одновременных активных запросов.

Этот плагин смотрит не на частоту и не на количество запросов за период, а на то, сколько запросов прямо сейчас находится в обработке.

Как работает. Система ведёт счётчик активных запросов по выбранному признаку: например, по Consumer, IP-адресу или другому ключу.

Когда запрос начинается, счётчик увеличивается. Когда запрос завершён и ответ отправлен клиенту, счётчик уменьшается.

Если новый запрос приходит в момент, когда счётчик уже достиг лимита, система отклоняет этот запрос и не передаёт его в upstream.

Пример. Настроен лимит: не больше 5 одновременных запросов от одного клиента.

Клиент отправил 5 запросов, и все они ещё выполняются. Пока хотя бы один из них не завершится, шестой запрос будет отклонён.

Как только один из активных запросов завершится, счётчик уменьшится, и система снова сможет принять новый запрос от этого клиента.

Когда пригодится. limit-conn полезен для API, где запросы могут долго занимать соединения или ресурсы бэкенда:

загрузка больших файлов;
streaming-ответы;
long polling;
медленные клиенты;
операции с долгой обработкой;
WebSocket-соединения.

Такой лимит помогает защитить бэкенд не от большого числа коротких запросов, а от ситуаций, когда клиент удерживает слишком много одновременных обработок.

Атрибуты.

Атрибут Тип Обяз. По умолч. Допустимые значения Описание

Атрибут	Тип	Обяз.	По умолч.	Допустимые значения	Описание
`conn`	`integer`	Нет		`> 0`	Максимальное число одновременных запросов. Запросы сверх `conn`, но в пределах `conn + burst`, задерживаются. Обязателен, если не настроен `rules`.
`burst`	`integer`	Нет		`>= 0`	Число превышающих одновременных запросов, которые можно задержать. Запросы сверх лимита отклоняются сразу. Обязателен, если не настроен `rules`.
`default_conn_delay`	`number`	Да		`> 0`	Базовая задержка в секундах для запросов сверх `conn`, но в пределах `conn + burst`. Итоговая задержка зависит от `only_use_default_delay`.
`only_use_default_` `delay`	`boolean`	Нет	`false`		Если `false`, задержка растёт пропорционально превышению `conn`. Если `true`, все запросы в пределах `burst` задерживаются ровно на `default_conn_delay`.
`rules`	`array` `[object]`	Нет			Список правил connection limiting. Если задан, имеет приоритет над `conn`, `burst` и `key`.
`rules.conn`	`integer` or `string`	Да		`> 0 или variable expression`	Максимальное число одновременных запросов. Может быть статическим числом или выражением переменной, например `$http_custom_conn`.
`rules.burst`	`integer` or `string`	Да		`>= 0 или variable expression`	Число превышающих одновременных запросов, которые можно задержать. Может быть статическим числом или выражением переменной.
`rules.key`	`string`	Да			Ключ для подсчёта запросов. Если ключ не существует, правило не выполняется. Интерпретируется как комбинация переменных.
`key_type`	`string`	Нет	var	`var / var_` `combination`	Тип `key`. `var` интерпретирует `key` как переменную; `var_combination` — как комбинацию переменных.
`key`	`string`	Нет	`remote_addr`		Признак, по которому считаются запросы. Для `var` указывается имя переменной без `$`. Для `var_combination` все переменные указываются с `$`. Обязателен, если не настроен `rules`.
`key_ttl`	`integer`	Нет	`3600`		TTL ключа Redis в секундах. Используется при `policy = redis` или `redis-cluster`.
`rejected_code`	`integer`	Нет	`503`	`200…599`	HTTP-код, который возвращается при отклонении запроса из-за превышения лимита.
`rejected_msg`	`string`	Нет		`non-empty`	Тело ответа, которое возвращается при отклонении запроса из-за превышения лимита.
`allow_degradation`	`boolean`	Нет	`false`		Если `true`, система продолжит обрабатывать запросы без плагина, когда плагин или его зависимости недоступны.
`policy`	`string`	Нет	`local`	`local / redis / redis-cluster`	Политика хранения счётчика. `local` — в памяти узла; `redis` — в Redis; `redis-cluster` — в Redis Cluster.
`redis_host`	`string`	Нет			Адрес узла Redis. Обязателен при `policy = redis`.
`redis_port`	`integer`	Нет	`6379`	`>= 1`	Порт Redis при `policy = redis`.
`redis_username`	`string`	Нет			Имя пользователя Redis при использовании Redis ACL. Для legacy `requirepass` задавайте только `redis_password`.
`redis_password`	`string`	Нет			Пароль Redis при `policy = redis` или `redis-cluster`.
`redis_ssl`	`boolean`	Нет	`false`		Если `true`, используется SSL-подключение к Redis при `policy = redis`.
`redis_ssl_verify`	`boolean`	Нет	`false`		Если `true`, проверяется SSL-сертификат сервера Redis при `policy = redis`.
`redis_database`	`integer`	Нет	`0`	`>= 0`	Номер базы данных Redis при `policy = redis`.
`redis_timeout`	`integer`	Нет	`1000`	`>= 1`	Таймаут Redis в миллисекундах при `policy = redis` или `redis-cluster`.
`redis_keepalive_` `timeout`	`integer`	Нет	`10000`	`>= 1000`	Keepalive timeout для Redis в миллисекундах при `policy = redis` или `redis-cluster`.
`redis_keepalive_` `pool`	`integer`	Нет	`100`	`>= 1`	Размер keepalive pool для Redis при `policy = redis` или `redis-cluster`.
`redis_cluster_nodes`	`array` `[string]`	Нет			Список узлов Redis Cluster. Требуется минимум два адреса. Обязателен при `policy = redis-cluster`.
`redis_cluster_name`	`string`	Нет			Имя Redis Cluster. Обязательно при `policy = redis-cluster`.
`redis_cluster_ssl`	`boolean`	Нет	`false`		Если `true`, используется SSL-подключение к Redis Cluster при `policy = redis-cluster`.
`redis_cluster_ssl_` `verify`	`boolean`	Нет	`false`		Если `true`, проверяется SSL-сертификат сервера Redis Cluster при `policy = redis-cluster`.

conn

integer

Нет

> 0

Максимальное число одновременных запросов. Запросы сверх conn, но в пределах conn + burst, задерживаются. Обязателен, если не настроен rules.

burst

integer

Нет

>= 0

Число превышающих одновременных запросов, которые можно задержать. Запросы сверх лимита отклоняются сразу. Обязателен, если не настроен rules.

default_conn_delay

number

Да

> 0

Базовая задержка в секундах для запросов сверх conn, но в пределах conn + burst. Итоговая задержка зависит от only_use_default_delay.

only_use_default_
delay

boolean

Нет

false

Если false, задержка растёт пропорционально превышению conn. Если true, все запросы в пределах burst задерживаются ровно на default_conn_delay.

rules

array
[object]

Нет

Список правил connection limiting. Если задан, имеет приоритет над conn, burst и key.

rules.conn

integer or string

Да

> 0 или variable expression

Максимальное число одновременных запросов. Может быть статическим числом или выражением переменной, например $http_custom_conn.

rules.burst

integer or string

Да

>= 0 или variable expression

Число превышающих одновременных запросов, которые можно задержать. Может быть статическим числом или выражением переменной.

rules.key

string

Да

Ключ для подсчёта запросов. Если ключ не существует, правило не выполняется. Интерпретируется как комбинация переменных.

key_type

string

Нет

var

var / var_
combination

Тип key. var интерпретирует key как переменную; var_combination — как комбинацию переменных.

key

string

Нет

remote_addr

Признак, по которому считаются запросы. Для var указывается имя переменной без $. Для var_combination все переменные указываются с $. Обязателен, если не настроен rules.

key_ttl

integer

Нет

3600

TTL ключа Redis в секундах. Используется при policy = redis или redis-cluster.

rejected_code

integer

Нет

503

200…599

HTTP-код, который возвращается при отклонении запроса из-за превышения лимита.

rejected_msg

string

Нет

non-empty

Тело ответа, которое возвращается при отклонении запроса из-за превышения лимита.

allow_degradation

boolean

Нет

false

Если true, система продолжит обрабатывать запросы без плагина, когда плагин или его зависимости недоступны.

policy

string

Нет

local

local / redis / redis-cluster

Политика хранения счётчика. local — в памяти узла; redis — в Redis; redis-cluster — в Redis Cluster.

redis_host

string

Нет

Адрес узла Redis. Обязателен при policy = redis.

redis_port

integer

Нет

6379

>= 1

Порт Redis при policy = redis.

redis_username

string

Нет

Имя пользователя Redis при использовании Redis ACL. Для legacy requirepass задавайте только redis_password.

redis_password

string

Нет

Пароль Redis при policy = redis или redis-cluster.

redis_ssl

boolean

Нет

false

Если true, используется SSL-подключение к Redis при policy = redis.

redis_ssl_verify

boolean

Нет

false

Если true, проверяется SSL-сертификат сервера Redis при policy = redis.

redis_database

integer

Нет

0

>= 0

Номер базы данных Redis при policy = redis.

redis_timeout

integer

Нет

1000

>= 1

Таймаут Redis в миллисекундах при policy = redis или redis-cluster.

redis_keepalive_
timeout

integer

Нет

10000

>= 1000

Keepalive timeout для Redis в миллисекундах при policy = redis или redis-cluster.

redis_keepalive_
pool

integer

Нет

100

>= 1

Размер keepalive pool для Redis при policy = redis или redis-cluster.

redis_cluster_nodes

array
[string]

Нет

Список узлов Redis Cluster. Требуется минимум два адреса. Обязателен при policy = redis-cluster.

redis_cluster_name

string

Нет

Имя Redis Cluster. Обязательно при policy = redis-cluster.

redis_cluster_ssl

boolean

Нет

false

Если true, используется SSL-подключение к Redis Cluster при policy = redis-cluster.

redis_cluster_ssl_
verify

boolean

Нет

false

Если true, проверяется SSL-сертификат сервера Redis Cluster при policy = redis-cluster.

Пример конфигурации. Route с limit-conn ограничивает число одновременных WebSocket-соединений и включает проксирование WebSocket.

{
  "uri": "/.ws",
  "limit_conn": {
    "conn": 2,
    "burst": 1,
    "default_conn_delay": 0.1,
    "key": "remote_addr",
    "rejected_code": 429
  },
  "enable_websocket": true
}

header-count-limit

Что ограничивает. header-count-limit ограничивает максимально допустимое число HTTP-заголовков в запросе.

Как работает. Плагин считает заголовки входящего HTTP-запроса. Если их количество превышает max_headers, система не передаёт запрос в upstream — вместо этого он отклоняет запрос и возвращает клиенту 400 Bad Request.

Когда пригодится. Плагин полезен, когда нужно ограничить запросы с чрезмерным числом заголовков: например, такие бывают при ошибках клиента, некорректно настроенных интеграциях или попытках перегрузить обработку заголовков.

Атрибуты.

Атрибут Тип Обяз. По умолч. Допустимые значения Описание

Атрибут	Тип	Обяз.	По умолч.	Допустимые значения	Описание
`max_headers`	`integer`	Да		`> 0`	Максимально допустимое количество HTTP-заголовков в запросе. При превышении лимита запрос отклоняется с `400 Bad Request`.

max_headers

integer

Да

> 0

Максимально допустимое количество HTTP-заголовков в запросе. При превышении лимита запрос отклоняется с 400 Bad Request.

Пример конфигурации. Плагин header-count-limit разрешает не больше 10 HTTP-заголовков в запросе.

{
  "max_headers": 10
}

Размер заголовков запроса через Nginx

Что ограничивает. Настройки Nginx ограничивают максимальный размер request line и каждого отдельного поля заголовка HTTP-запроса.

Как работает. Nginx проверяет request line и каждое поле заголовка по отдельности. Сначала он пытается принять каждое из этих значений в основной буфер, который задаётся параметром client_header_buffer_size.

Если каждое значение влезает в буфер, Nginx обрабатывает запрос дальше.

Если какое-то из значений не помещается в основной буфер, Nginx пытается принять его в большой буфер, который задаётся через large_client_header_buffers. Если значение помещается в один большой буфер, Nginx обрабатывает запрос дальше. Если нет, отклоняет запрос.

При отклонении запроса система возвращает клиенту:

414 Request-URI Too Large — если слишком длинная request line;
400 Bad Request — если слишком длинное поле заголовка.

Где настраивается. Параметры задаются в конфигурационном файле conf/config.yaml в блоке nginx_config.http. Вы можете изменить эти настройки через CLI сервера, подключившись к нему по SSH.

Параметры.

Параметр Тип Обяз. По умолч. в Nginx Пример значения Описание

Параметр	Тип	Обяз.	По умолч. в Nginx	Пример значения	Описание
`client_` `header_` `buffer_` `size`	`size`	Нет	`1k`	`32k`	Размер основного буфера для чтения request line и полей заголовков запроса клиента. Если значение не поместится в основной буфер, Nginx попытается прочитать его через буфер, указанный в параметре `large_client_header_buffers`.
`large_` `client_` `header_` `buffers`	`string`	Нет	`4 8k`	`4 32k`	Максимальное число и размер больших буферов — то есть буферов для чтения больших request line и полей заголовков запроса клиента, которые не поместились в основной буфер. Запрос будет отклонён в любом из двух случаев: request line/поле заголовка не помещается в один большой буфер; для чтения всех больших полей заголовков и request line запроса не хватает больших буферов (их максимальное число устанавливаете вы).

client_
header_
buffer_
size

size

Нет

1k

32k

Размер основного буфера для чтения request line и полей заголовков запроса клиента. Если значение не поместится в основной буфер, Nginx попытается прочитать его через буфер, указанный в параметре large_client_header_buffers.

large_
client_
header_
buffers

string

Нет

4 8k

4 32k

Максимальное число и размер больших буферов — то есть буферов для чтения больших request line и полей заголовков запроса клиента, которые не поместились в основной буфер. Запрос будет отклонён в любом из двух случаев:

request line/поле заголовка не помещается в один большой буфер;
для чтения всех больших полей заголовков и request line запроса не хватает больших буферов (их максимальное число устанавливаете вы).

Пример конфигурации. В этом примере request line или одно поле заголовка могут занимать до 32k.

nginx_config:
  http:
    client_header_buffer_size: 32k
    large_client_header_buffers: 4 32k

Если request line превышает размер в 32k, клиент получает 414 Request-URI Too Large. Если поле заголовка запроса превышает размер в 32k, клиент получает 400 Bad Request.

Как выбрать плагин / механизм лимита

Задача Плагин / механизм лимита

Задача	Плагин / механизм лимита
Ограничить RPS	`limit-req`
Задать 1000 запросов в минуту	`limit-count`
Задать дневную или месячную квоту	`limit-count`
Защититься от долгих активных запросов	`limit-conn`
Сгладить всплески трафика	`limit-req`
Ограничить дорогой эндпоинт	`limit-count` или `limit-req`
Ограничить одновременные downloads/streams/WebSocket	`limit-conn`
Защититься от запросов с чрезмерным числом заголовков	`header-count-limit`
Защититься от запросов с аномально длинными URL или крупными заголовками	настройки Nginx: `client_header_buffer_size` и `large_client_header_buffers`

Ограничить RPS

limit-req

Задать 1000 запросов в минуту

limit-count

Задать дневную или месячную квоту

limit-count

Защититься от долгих активных запросов

limit-conn

Сгладить всплески трафика

limit-req

Ограничить дорогой эндпоинт

limit-count или limit-req

Ограничить одновременные downloads/streams/WebSocket

limit-conn

Защититься от запросов с чрезмерным числом заголовков

header-count-limit

Защититься от запросов с аномально длинными URL или крупными заголовками

настройки Nginx: client_header_buffer_size и large_client_header_buffers

Плагины часто комбинируют. Например, для одного Route можно настроить:

limit-count — не больше 10 000 запросов в день;
limit-req — не больше 20 запросов в секунду;
limit-conn — не больше 5 одновременных запросов;
header-count-limit — не больше 50 HTTP-заголовков в запросе.

Если один из плагинов отклоняет запрос, запрос не передаётся в upstream. Остальные проверки дальше уже не имеют практического смысла для этого запроса.

Как подключить плагины

Через API

Плагины можно добавить к Route через Admin API. Для этого отправьте запрос на создание или обновление Route:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "route-id",
    "uri": "/example",
    "plugins": {
      "limit-count": {
        "...": "ваши настройки плагина"
      },
      "limit-req": {
        "...": "ваши настройки плагина"
      },
      "limit-conn": {
        "...": "ваши настройки плагина"
      },
      "header-count-limit": {
        "...": "ваши настройки плагина"
      }
    },
    "upstream": {
      "...": "ваши настройки upstream"
    }
  }'

Здесь id — идентификатор Route, uri — путь, по которому запрос попадает в Route, plugins.limit-count и другие объекты внутри plugins содержат конфигурацию плагинов, а upstream — настройки бэкенд-серверов.

Через UI

Откройте раздел Маршруты и нажмите + Добавить.
В настройках маршрута (Route) перейдите в раздел Плагины.
Нажмите + Добавить и выберите нужный плагин.
Укажите конфигурацию плагина как JSON-объект.
Аналогично добавьте и настройте другие плагины, если нужно.
Сохраните созданный маршрут (Route). Он будет добавлен с подключённым плагином.

Что учитывать при настройке

Глобальный лимит должен соответствовать реальной ёмкости бэкенда. Если поставить слишком высокий лимит, бэкенд всё равно может перегрузиться. Если слишком низкий — легитимные клиенты будут получать ошибки.
Для публичных эндпоинтов без авторизации можно использовать лимит по IP, но не стоит считать его точной идентификацией пользователя.
Для клиентских квот лучше использовать лимит по Consumer: так лимит будет привязан к конкретному потребителю API, а не к сетевому адресу.
Для тяжёлых, долгих или потоковых запросов одного лимита по количеству запросов недостаточно. В таких случаях стоит добавить limit-conn.
При настройке лимита по количеству HTTP-заголовков учитывайте весь путь запроса; прокси, CDN, WAF и клиентские SDK могут добавлять собственные заголовки.
Для лимитов на request line и отдельные заголовки ориентируйтесь на реальные запросы: помните, что легитимные клиенты могут передавать длинные фильтры в query string, большие токены авторизации или крупные Cookie.