upstream в nginx: балансировка нагрузки между серверами
Блок upstream собирает несколько серверов приложения в группу, а nginx раздаёт запросы между ними по очереди. Если один сервер не отвечает, запросы уходят на остальные. Так делят нагрузку и переживают перезапуск одного из экземпляров приложения.
Содержание 9
Что сделать прямо сейчас
Пример: на сервере работают два экземпляра приложения — на портах 3000 и 3001, а nginx уже передаёт запросы на один из них строкой proxy_pass — proxy_pass в nginx.
- Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться) и набирайте их в том же окне.
- Откройте файл сайта:
sudo nano /etc/nginx/sites-available/example.com. Вместо example.com — имя файла вашего сайта: список покажетls /etc/nginx/sites-enabled/. Если система спросит пароль, введите пароль своего пользователя на сервере. Символы при вводе не видны — наберите пароль и нажмите Enter. - В самый верх файла, до строки
server {, добавьте блок upstream из раздела ниже. - В блоке location замените
proxy_pass http://127.0.0.1:3000;наproxy_pass http://app;— имя группы из блока upstream. - Сохраните файл — Ctrl+O, Enter, затем Ctrl+X — и проверьте настройки:
sudo nginx -t. В ответе должны быть слова syntax is ok и test is successful. Тогда примените их:sudo systemctl reload nginx. Если команда ничего не ответила, настройки применены. - Проверьте, что запросы уходят на оба порта, — как проверить.
Если проверка нашла ошибку, nginx назовёт файл и номер строки, а сайт продолжит работать на старых настройках. Что значит сообщение — Все ошибки nginx.
Как устроен блок upstream
upstream app {
server 127.0.0.1:3000;
server 127.0.0.1:3001;
}| Часть | Что значит |
|---|---|
upstream app | группа серверов с именем app. Имя потом пишут в proxy_pass |
server 127.0.0.1:3000 | сервер группы: адрес и порт. Без порта — 80. Можно имя домена или сокет unix:/путь |
Блок upstream пишут только на уровне http — вне блоков server. Файлы сайтов из sites-enabled nginx в Ubuntu подключает внутри http, поэтому блок можно поставить в начало файла сайта.
location / {
proxy_pass http://app;
include proxy_params;
}Строка include proxy_params передаёт приложению имя сайта и адрес посетителя. Без неё приложение увидит имя app вместо домена.
Серверы группы могут быть и на других машинах: server 10.0.0.2:3000;. Тогда откройте порт приложения только для адреса сервера с nginx.
Параметры серверов
upstream app {
server 127.0.0.1:3000 weight=3;
server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3002 backup;
}| Параметр | Что значит |
|---|---|
weight=3 | вес: сервер получает в три раза больше запросов. По умолчанию 1 |
max_fails=3 | после трёх неудачных попыток сервер на время исключается. По умолчанию 1, 0 выключает учёт |
fail_timeout=30s | за какое время считать неудачи и на сколько исключать сервер. По умолчанию 10 секунд |
backup | запасной: получает запросы, только когда остальные недоступны |
down | сервер выключен, запросы на него не идут |
max_conns=100 | не больше 100 одновременных соединений с сервером. По умолчанию без ограничения |
Неудачной попыткой считается ошибка соединения или таймаут — так задаёт строка proxy_next_upstream по умолчанию. Запрос, который не получилось передать, nginx отправляет на следующий сервер группы.
Чтобы перезапустить один экземпляр без ошибок у посетителей, поставьте ему down, примените настройки, перезапустите приложение, уберите down и снова примените настройки.
Как nginx выбирает сервер
| Строка в upstream | Как раздаются запросы |
|---|---|
| нет строки | по очереди, с учётом весов |
least_conn; | серверу, у которого меньше всего активных соединений. Подходит, если запросы обрабатываются разное время |
ip_hash; | посетитель с одного адреса попадает на один и тот же сервер. Для IPv4 учитываются первые три числа адреса |
ip_hash нужен, если приложение хранит вход посетителя в памяти своего процесса: иначе после перехода на другой сервер вход пропадёт. С ip_hash нельзя ставить backup, а сервер, который нужно на время убрать, помечают down.
Открытые соединения с приложением: keepalive
В nginx 1.24 из Ubuntu 24.04 соединение с приложением закрывается после каждого запроса. Чтобы держать их открытыми, добавьте строку keepalive в upstream и две строки в location:
upstream app {
server 127.0.0.1:3000;
server 127.0.0.1:3001;
keepalive 16;
}
location / {
proxy_pass http://app;
include proxy_params;
proxy_http_version 1.1;
proxy_set_header Connection "";
}Число после keepalive — сколько свободных соединений держать открытыми в каждом рабочем процессе nginx. Общее число соединений оно не ограничивает. Для PHP-FPM вместо двух строк нужна fastcgi_keep_conn on; — nginx и PHP-FPM.
Как проверить
Временно добавьте в location строку, которая покажет адрес выбранного сервера в ответе:
add_header X-Upstream $upstream_addr;Примените настройки и отправьте несколько запросов:
for i in 1 2 3 4; do curl -sI https://example.com/ | grep -i x-upstream; doneВ ответах должны чередоваться адреса 127.0.0.1:3000 и 127.0.0.1:3001. Остановите один экземпляр приложения — все ответы должны идти от второго. После проверки уберите строку add_header.
Ошибки и как их исправить
| Что видите | Что делать |
|---|---|
502, в журнале no live upstreams | все серверы группы исключены после неудач: проверьте, что приложения запущены — разбор 502 |
502, в журнале connect() failed (111: Connection refused) | на этом порту ничего не слушает: запустите приложение или исправьте порт в server |
"upstream" directive is not allowed here | блок upstream стоит внутри server: перенесите его выше строки server { — разбор |
duplicate upstream "app" | группа с таким именем уже есть в другом файле: дайте новое имя |
host not found in upstream | nginx не нашёл адрес для имени из строки server — разбор |
balancing method does not support parameter "backup" | backup стоит вместе с ip_hash: уберите один из них |
| посетителей выкидывает из личного кабинета | вход хранится в памяти одного экземпляра: добавьте ip_hash; или храните вход в общей базе |
Источники
- Документация nginx: модуль ngx_http_upstream_module — upstream, server и его параметры, least_conn, ip_hash, keepalive.
- Документация nginx: Using nginx as HTTP load balancer — на английском: round-robin, least_conn, ip_hash и веса серверов.
- Исходный код nginx 1.24.0: ngx_http_upstream.c — параметры server по умолчанию: weight=1, max_fails=1, fail_timeout=10.
- Исходный код nginx 1.24.0: ngx_http_upstream_keepalive_module.c — keepalive держит открытыми соединения с серверами группы, пока директива не задана — не держит.
- Файл proxy_params из пакета nginx в Ubuntu 24.04 — заголовки Host, X-Real-IP, X-Forwarded-For и X-Forwarded-Proto.
Сверено 23 октября 2026 года.
Что почитать дальше
- Настройки nginxкак устроены файлы и блоки, главные директивы.
- proxy_pass в nginxкак передать запросы приложению.
- Ошибка 502 Bad Gatewayкогда приложение не отвечает.
- Ошибка 504 Gateway Timeoutкогда приложение отвечает слишком долго.
- nginx и PHP-FPMсвязка для сайтов на PHP.