Keepalive в Nginx: чек-лист для прокси и upstream

Если Nginx работает reverse proxy, один запрос может открыть два TCP-соединения: от клиента до Nginx и от Nginx до upstream. Без keepalive соединение с приложением приходится создавать заново, а под нагрузкой это добавляет TCP-запросы, TLS-рукопожатия и очередь на стороне backend. Ниже — практический чек-лист для Nginx 1.25.x: что включить, какие директивы не перепутать и чем проверить результат.

Сначала разделите два вида keepalive

У Nginx нет одной универсальной настройки «keepalive для всего». Нужно отдельно настроить:

• клиентский keepalive — сколько времени Nginx держит соединение браузера или API-клиента открытым;
• keepalive к upstream — сколько простаивающих соединений Nginx сохраняет между worker-процессами и приложением.

Эти параметры решают разные задачи. Клиентский keepalive уменьшает число подключений к Nginx. Upstream keepalive уменьшает стоимость повторных подключений к Node.js, Python-приложению, PHP-FPM через HTTP или другому HTTP-сервису.

Главная ошибка — увеличить keepalive_timeout и ожидать, что Nginx начнёт переиспользовать соединения с приложением. Эта директива относится к клиенту, а не к upstream.

[1] Upstream — сервер или группа серверов, куда Nginx передаёт запросы после получения их от клиента.

Базовый чек-лист перед изменением конфигурации

1. Уточните роль Nginx. Keepalive к upstream нужен только для проксирования HTTP-запросов. Если Nginx раздаёт исключительно статические файлы, настраивать пул соединений к приложению нечего.
2. Проверьте версию. Выполните nginx -v и зафиксируйте результат. Примеры ниже написаны для синтаксиса Nginx 1.25.x; перед выкладкой сверяйте директивы с документацией вашей сборки.
3. Посмотрите реальные таймауты приложения. Балансировщик, приложение, база данных и firewall могут закрывать простаивающие соединения раньше Nginx. Тогда в логах появятся обрывы или повторные подключения, даже если конфигурация прокси выглядит правильно.
4. Снимите базовые показатели. Сравните долю ответов 502/504, время установления соединения с upstream, число активных соединений и нагрузку на backend до изменения.

Проверка после этого этапа простая: вы знаете, какой блок конфигурации отвечает за proxy, какой сервис является upstream и какие ошибки уже происходят без изменений.

Настройте keepalive от клиента до Nginx

Для HTTP/1.1 Nginx обычно поддерживает постоянное соединение с клиентом, если его не закрывает конфигурация или заголовки. Таймаут задаётся в контексте http, server или location:

http {
    keepalive_timeout 15s;
    keepalive_requests 1000;

    server {
        listen 443 ssl;
        server_name example.com;

        location / {
            proxy_pass http://application;
        }
    }
}

keepalive_timeout задаёт время ожидания следующего запроса на уже открытом соединении. Второе значение можно использовать для заголовка Keep-Alive, но оно не меняет внутренний таймер закрытия соединения Nginx. keepalive_requests ограничивает число запросов через одно клиентское соединение.

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

Включите переиспользование соединений к upstream

Для reverse proxy важны сразу три части: блок upstream, HTTP/1.1 между Nginx и приложением и отсутствие принудительного Connection: close.

http {
    upstream application {
        server 127.0.0.1:3000;
        keepalive 32;
    }

    server {
        listen 443 ssl;
        server_name example.com;

        location / {
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://application;
        }
    }
}

В этой схеме keepalive 32 задаёт размер кэша простаивающих соединений для каждого worker-процесса. Это не общий лимит на весь Nginx и не число одновременных запросов. Если работает четыре worker-процесса, теоретически к upstream может сохраняться до 128 простаивающих соединений, если трафик и конфигурация это позволяют.

proxy_http_version 1.1 нужен, чтобы запросы к upstream шли по HTTP/1.1. Директива proxy_set_header Connection "" убирает заголовок, который мог бы заставить backend закрывать соединение после ответа. Не копируйте эту настройку вслепую в другие протоколы: она относится к HTTP-проксированию.

Сравните настройки по цене и эффекту

Начинайте не с максимального пула, а с небольшого значения и наблюдайте за приложением. Размер пула должен соответствовать параллельности запросов и способности backend обслуживать открытые соединения. Увеличение числа простаивающих сокетов само по себе не ускоряет медленный обработчик.

Что ломается чаще всего

Пул включён, но соединения всё равно закрываются

Проверьте, что в нужном location действительно стоят proxy_http_version 1.1 и очистка заголовка Connection. Ищите также общие настройки в подключаемых файлах: отдельная директива с Connection close может отменить ожидаемое поведение.

Слишком много соединений к приложению

Помните о worker-процессах: значение keepalive применяется к каждому из них. Если приложение само ограничивает число клиентов, большой пул в Nginx может занять его лимит простаивающими соединениями. Уменьшайте пул и сопоставляйте его с числом worker-процессов и лимитами backend.

Появились 502 после периода простоя

Одна из причин — upstream или сетевое устройство закрыло неактивное соединение, а Nginx попытался использовать его повторно. Сравните таймауты Nginx, приложения, балансировщика и firewall. Если закрытие происходит на другом уровне, keepalive нельзя исправить одной директивой в Nginx.

Настройка не влияет на метрики

Проверьте тип нагрузки. Если запросы редкие и почти всегда приходят от новых клиентов, свободные соединения не успевают переиспользоваться. Если backend отвечает медленно, keepalive сокращает стоимость подключения, но не время выполнения запроса.

Как проверить изменение безопасно

1. Проверьте синтаксис: nginx -t. Команда должна завершиться сообщением об успешной проверке конфигурации.
2. Примените конфигурацию штатным способом вашей системы и убедитесь, что процесс Nginx не перезапустился с ошибкой.
3. Сделайте нагрузочный прогон с тем же количеством параллельных запросов, что и в базовом измерении. Сравнивайте одинаковый endpoint, размер ответа и версию протокола.
4. Посмотрите access log, error log, метрики соединений и логи приложения. Ищите не только снижение времени ответа, но и рост 502, 504, открытых файлов и очередей.

Для HTTP/2 клиентская сторона устроена иначе: несколько запросов могут идти по одному мультиплексированному соединению, поэтому оценивать клиентский keepalive только по числу TCP-сокетов некорректно. При этом соединения Nginx с HTTP-upstream всё равно требуют отдельной проверки.

Когда keepalive лучше не увеличивать

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

Инвалидация кэша, балансировка по весам и таймауты proxy_connect_timeout, proxy_read_timeout и proxy_send_timeout — отдельные темы. Keepalive не заменяет их настройку.

Что сделать дальше

После включения keepalive добавьте в наблюдение четыре показателя: число соединений к upstream на worker, долю 502/504, время установления соединения и лимит файловых дескрипторов. Затем проведите повторный тест с реальным профилем трафика. Если соединения переиспользуются, а задержка не меняется, узкое место, вероятно, находится в обработчике, базе данных или очереди, а не в создании TCP-соединения.