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:
- nginx -t выдаёт «syntax is ok» и «test is successful».
- Порты в upstream совпадают с теми, что реально слушает приложение.
- server_name указывает на ваш домен, DNS уже смотрит на этот хост.
- Файл лежит в каталоге, который включён директивой include в основном конфиге.
- Есть доступ к логам, указанным в 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, иначе состояние кластера увидит любой.
Итоговый набор действий:
- nginx -t и systemctl reload nginx после каждого изменения.
- Проверка чередования бэкендов циклом curl и по $upstream_addr в логах.
- Настроенный keepalive с корректной тройкой директив.
- Заголовки Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto в каждом location с проксированием.
- Закрытые наружу порты бэкендов и защищённые служебные страницы.
Адаптация под свой стек сводится к замене трёх вещей: адресов и портов в upstream, server_name и путей в location. Если нужны отказоустойчивые группы с проверками и таймаутами, смотрите схему отказоустойчивости с upstream-группами. Перед выкладкой на прод прогоните конфиг на стенде с теми же портами и убедитесь, что все три бэкенда отвечают напрямую, до включения прокси.