Балансировка нагрузки в Nginx: базовый конфиг upstream с нуля (2026) | AdminWiki

Балансировка нагрузки в Nginx: базовый конфиг upstream с нуля (2026)

08 ноября 2026 8 мин. чтения

Nginx ставят перед приложением, чтобы принимать запросы на портах 80 и 443 и передавать их одному из нескольких бэкендов. Такой сервер называют reverse proxy, и кроме балансировки нагрузки он часто берёт на себя терминацию SSL и кэширование (глоссарий по инфраструктуре). Дальше разбираем минимальный конфиг, который можно скопировать на сервер и проверить за пару минут.

Что даёт балансировка нагрузки в Nginx и когда она нужна

Схема простая: клиент приходит на Nginx, тот выбирает живой upstream-сервер и проксирует туда запрос. Бэкенд в этой схеме — серверная часть приложения с логикой, базами и обработкой данных, пользователь общается с ней только через прокси (определение бэкенда).

Что получаете на выходе:

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

Балансировка нужна, когда приложение запущено в двух и более экземплярах, когда планируется горизонтальное масштабирование или когда деплой без простоя входит в требования. Nginx не единственный инструмент: ту же задачу решает HAProxy. Если инфраструктура уже крутится вокруг Nginx, отдельный балансировщик обычно не нужен.

Даже с одним бэкендом блок upstream полезен: вы описываете группу серверов сразу, а добавление второго инстанса сводится к одной строке. Распределение по алгоритмам, веса и резервные узлы разбираем отдельно в материале про алгоритмы балансировки Nginx.

Минимальный конфиг upstream: полный рабочий пример

Три инстанса приложения слушают localhost на портах 8081, 8082 и 8083. Nginx принимает трафик на 80 и проксирует его в группу.

upstream backend {
    server 127.0.0.1:8081;
    server 127.0.0.1:8082;
    server 127.0.0.1:8083;
}

server {
    listen 80;
    server_name example.com;

    access_log /var/log/nginx/example.access.log;
    error_log  /var/log/nginx/example.error.log;

    location / {
        proxy_pass http://backend;
        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;
    }
}

Куда положить файл: дистрибутивы Debian и Ubuntu читают /etc/nginx/sites-available/* и sites-enabled, RHEL-семейство и официальные сборки — каталог /etc/nginx/conf.d/. Создайте /etc/nginx/conf.d/backend.conf с содержимым выше. Блок upstream определяет группу серверов, на которую ссылаются proxy_pass и другие директивы передачи запросов (модуль ngx_http_upstream_module). Размещать его нужно на уровне http, рядом с другими блоками upstream, а не внутри server: вложенное объявление не пройдёт проверку конфигурации.

Проверка и применение:

nginx -t
systemctl reload nginx

Чек-лист перед reload:

  1. nginx -t выдаёт «syntax is ok» и «test is successful».
  2. Порты в upstream совпадают с теми, что реально слушает приложение.
  3. server_name указывает на ваш домен, DNS уже смотрит на этот хост.
  4. Файл лежит в каталоге, который включён директивой include в основном конфиге.
  5. Есть доступ к логам, указанным в access_log и error_log.

Для правки конфига на работающем сервере используйте reload, а не restart: это плановая перезагрузка конфигурации без остановки обслуживания. Точный порядок завершения старых worker-процессов сверяйте с документацией по управлению процессами Nginx для вашей версии.

Разбор директив proxy_set_header

Без этих заголовков бэкенд видит IP прокси вместо клиента и схему http даже там, где стоит HTTPS. По умолчанию Nginx при проксировании выставляет Host в значение $proxy_host и Connection в close (модуль ngx_http_proxy_module), поэтому нужные значения задают явно.

ЗаголовокЗначениеЗачем нуженЧто ломается без него
Host$hostБэкенд получает исходное имя хоста и строит корректные абсолютные ссылкиРедиректы уводят на внутренний адрес, а приложение может выбрать не тот виртуальный хост
X-Real-IP$remote_addrРеальный IP клиента в одном заголовкеВ логах приложения и в rate-limit видны только адреса Nginx
X-Forwarded-For$proxy_add_x_forwarded_forЦепочка прокси, добавляется к существующему значениюТеряется исходный адрес при нескольких уровнях проксирования
X-Forwarded-Proto$schemeПриложение понимает, был ли запрос по httpsВозникают циклы редиректа http ↔ https или не выставляются secure-cookies

Если приложение проверяет доверенные прокси, добавьте адрес Nginx в его настройки. Иначе подделанный клиентом X-Forwarded-For попадёт в логи и повлияет на ограничения.

Как Nginx распределяет запросы: round-robin по умолчанию

Когда в блоке upstream не указан метод, Nginx распределяет запросы по кругу: первый уходит на 8081, второй на 8082, третий на 8083, четвёртый снова на 8081. Это и есть round-robin, балансировка в Nginx по умолчанию: запросы передаются серверам последовательно, после последнего сервера цикл начинается заново (документация модуля upstream). Порядок обхода соответствует порядку перечисления серверов в блоке, менять его вручную не нужно.

При недоступности узла запросы перекидываются на живые. В open-source версии это пассивная логика: Nginx считает неудачные попытки и на время fail_timeout перестаёт слать трафик на проблемный сервер. Директивы max_fails и fail_timeout управляют этим поведением. Полноценного активного HTTP health-check «из коробки» в классической open-source сборке нет: активные проверки реализуют коммерческие возможности, сторонние модули или внешний мониторинг. Подробнее про это в статье про health checks и keepalive в upstream.

Другие методы (least_conn, ip_hash) в минимальном конфиге не нужны. Они решают отдельные задачи: соединения с долгим временем жизни и привязку сессии к конкретному серверу.

Чтобы увидеть round-robin на практике, нужен различимый ответ от каждого бэкенда или отдельные логи. Иначе все ответы выглядят одинаково, и проверить распределение нечем.

Проверка результата: curl и логи доступа

Шаг 1. Настройте бэкенды так, чтобы они возвращали своё имя. Простейший вариант на каждом инстансе: эндпоинт, который отдаёт строку вида backend-8081. Альтернатива — смотреть логи приложения на каждом сервере.

Шаг 2. Прогоните шесть запросов подряд:

for i in $(seq 1 6); do curl -s http://localhost/; echo; done

Ожидаемый вывод при трёх живых бэкендах:

backend-8081
backend-8082
backend-8083
backend-8081
backend-8082
backend-8083

Шаг 3. Проверьте статус и заголовки одного запроса:

curl -I http://localhost/

Код 200 и валидные заголовки означают, что проксирование работает. Код 301 или 302 на неожиданный адрес почти всегда указывает на проблему с Host или X-Forwarded-Proto.

Шаг 4. Сверьте распределение по логам:

tail -n 20 /var/log/nginx/example.access.log
tail -n 20 /var/log/nginx/example.error.log

В access.log видно время, адрес клиента, запрос, статус и апстрим, если в log_format добавлена переменная $upstream_addr. Она показывает, какой сервер обработал конкретный запрос: по двадцати строкам сразу понятно, чередуются ли бэкенды. Логи самих приложений подтверждают картину с другой стороны.

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

Что означают 502 и 503 в логах

502 Bad Gateway значит, что прокси или балансировщик получил недопустимый ответ от upstream-сервера, обычно потому что бэкенд-приложение упало (расшифровка кода). Смотрите error.log: запись «connect() failed (111: Connection refused)» указывает, что на порту никто не слушает.

503 Service Unavailable означает, что сервер временно не может обрабатывать запросы: обслуживание, перегрузка, деплой. В паре с балансировщиком этот код часто отдаёт само приложение, когда не готово принимать трафик. Разница принципиальная: 502 ищите в связке Nginx и процесса приложения, 503 — в готовности приложения и его лимитах.

Типичные ошибки, которые ломают конфиг, и как их устранить

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

СимптомПричинаЧто сделать
502 на всех запросах, в error.log «Connection refused»Приложение не слушает указанный порт или адрес в upstream неверныйПроверьте ss -tlnp | grep 8081 и сверьте адрес с конфигом приложения
502 только на части запросовОдин из трёх инстансов лежит, Nginx шлёт туда запросыПоднимите упавший сервис, проверьте systemctl status и логи приложения
404 или редирект на чужой доменНе передан Host, бэкенд выбрал не тот виртуальный хостДобавьте proxy_set_header Host $host, проверьте server_name на бэкенде
Изменения не применяютсяЗабыли reload или конфиг не прошёл проверкуВсегда nginx -t && systemctl reload nginx, смотрите вывод целиком
504 Gateway Time-outБэкенд отвечает дольше таймаута, дефолт слишком мал для тяжёлого запросаЗадайте proxy_read_timeout и proxy_connect_timeout под профиль нагрузки
Ошибка «upstream» не распознанБлок upstream объявлен внутри serverВынесите блок на уровень http, рядом с другими upstream

Отдельно про порты: 80 и 443 — стандартные для HTTP и HTTPS, но приложение может слушать кастомный порт (глоссарий по инфраструктуре). Перепутанные значения дают те же 502 и «Connection refused», поэтому первым делом сверяйте не имя сервиса, а фактический список слушающих сокетов. Если нужно аккуратно вывести узел из работы во время деплоя, пригодится материал про graceful shutdown и резервные серверы.

Keepalive и безопасность: что добавить после базового конфига

Базовый конфиг открывает новое TCP-соединение к бэкенду на каждый запрос. На нагрузке это заметные накладные расходы. Keepalive переиспользует соединения Nginx → бэкенд.

upstream backend {
    server 127.0.0.1:8081;
    server 127.0.0.1:8082;
    server 127.0.0.1:8083;
    keepalive 32;
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://backend;
        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;
    }
}

Три условия работают только вместе: keepalive 32 в upstream, proxy_http_version 1.1 и пустой Connection. Директива proxy_http_version переключает соединение на HTTP/1.1 вместо версии по умолчанию, а proxy_set_header Connection "" убирает значение close из заголовка (ngx_http_proxy_module). Забыли любой пункт — соединения закрываются, и смысл настройки пропадает. Значение keepalive задаёт количество ожидающих keepalive-соединений с upstream, сохранённых в кэше каждого рабочего процесса, и не ограничивает общее число соединений, которые worker может открыть (ngx_http_upstream_module).

Безопасность начинается с границ. Upstream-адреса не должны быть доступны из интернета: слушайте приложения на loopback или во внутренней сети и закрывайте порты фаерволом. Терминацию SSL держите на Nginx, порт 80 оставляйте только для редиректа на 443. Служебные страницы вроде stub_status закрывайте по IP или basic auth, иначе состояние кластера увидит любой.

Итоговый набор действий:

  1. nginx -t и systemctl reload nginx после каждого изменения.
  2. Проверка чередования бэкендов циклом curl и по $upstream_addr в логах.
  3. Настроенный keepalive с корректной тройкой директив.
  4. Заголовки Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto в каждом location с проксированием.
  5. Закрытые наружу порты бэкендов и защищённые служебные страницы.

Адаптация под свой стек сводится к замене трёх вещей: адресов и портов в upstream, server_name и путей в location. Если нужны отказоустойчивые группы с проверками и таймаутами, смотрите схему отказоустойчивости с upstream-группами. Перед выкладкой на прод прогоните конфиг на стенде с теми же портами и убедитесь, что все три бэкенда отвечают напрямую, до включения прокси.

Поделиться: