Поиск
Справочник

upstream в nginx: балансировка нагрузки между серверами

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

≈ 7 мин чтения
Содержание 9

Что сделать прямо сейчас

Пример: на сервере работают два экземпляра приложения — на портах 3000 и 3001, а nginx уже передаёт запросы на один из них строкой proxy_pass — proxy_pass в nginx.

  1. Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться) и набирайте их в том же окне.
  2. Откройте файл сайта: sudo nano /etc/nginx/sites-available/example.com. Вместо example.com — имя файла вашего сайта: список покажет ls /etc/nginx/sites-enabled/. Если система спросит пароль, введите пароль своего пользователя на сервере. Символы при вводе не видны — наберите пароль и нажмите Enter.
  3. В самый верх файла, до строки server {, добавьте блок upstream из раздела ниже.
  4. В блоке location замените proxy_pass http://127.0.0.1:3000; на proxy_pass http://app; — имя группы из блока upstream.
  5. Сохраните файл — Ctrl+O, Enter, затем Ctrl+X — и проверьте настройки: sudo nginx -t. В ответе должны быть слова syntax is ok и test is successful. Тогда примените их: sudo systemctl reload nginx. Если команда ничего не ответила, настройки применены.
  6. Проверьте, что запросы уходят на оба порта, — как проверить.

Если проверка нашла ошибку, 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 upstreamnginx не нашёл адрес для имени из строки server — разбор
balancing method does not support parameter "backup"backup стоит вместе с ip_hash: уберите один из них
посетителей выкидывает из личного кабинетавход хранится в памяти одного экземпляра: добавьте ip_hash; или храните вход в общей базе

Источники

Сверено 23 октября 2026 года.

Где попробовать. Команды из статьи безопаснее сначала повторить на отдельном тестовом сервере, а не на рабочем. Подойдёт VPS с Ubuntu, например Timeweb Cloud Реклама. АО «ТАЙМВЭБ», ИНН 7810353960. erid: CQH36pWzJpoBWKF332yG5h2XQ4cVubfBmkvqAitFqcpzWs. Как зайти на него после заказа — в статье Как подключиться к VPS по SSH.

Что почитать дальше