Ошибка 502 Bad Gateway в Nginx: перевод, причины и пошаговое устранение на Ubuntu

502 Bad Gateway — одна из тех ошибок, которые заставляют сердце веб-мастера биться чаще. В этой статье мы подробно разберём, что это значит, как переводится на русский, и главное — как исправить эту ошибку в связке Nginx на Ubuntu. Вы узнаете о типичных причинах, диагностике и способах решения — от проверки PHP-FPM до тонкой настройки буферов и директивы reuseport.

Что такое 502 Bad Gateway: перевод на русский и суть ошибки

Перевод на русский у этой ошибки довольно прямой — «Плохой шлюз». Но что это значит на практике?

Представьте себе систему: Nginx выступает в роли «входной двери» (шлюза), принимающей запросы от пользователей. Чтобы сгенерировать страницу, Nginx должен передать задачу внутреннему серверу — «бэкенду» (например, PHP-FPM, Apache или Node.js). Ошибка 502 Bad Gateway означает, что Nginx не получил корректный ответ от этого бэкенда.

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

Почему возникает 502 Bad Gateway в Nginx?

Причин несколько, но они сводятся к одной проблеме: бэкенд не отвечает так, как ожидает Nginx. Рассмотрим самые частые сценарии на Ubuntu.

1. Бэкенд-сервис остановлен или не работает

Для сайтов на PHP это чаще всего PHP-FPM. Если он остановлен, Nginx не сможет обработать PHP-скрипты. Это одна из самых частых причин после обновления системы, когда версия PHP меняется, а конфигурация Nginx остаётся старой.

2. Некорректный путь в fastcgi_pass

В конфигурации Nginx (обычно в файлах в /etc/nginx/sites-enabled/) есть директива fastcgi_pass, которая указывает, как и где искать PHP-FPM. Она может ссылаться на сокет (например, unix:/run/php/php7.4-fpm.sock). Если после обновления Ubuntu PHP изменился на версию 8.1 или 8.2, старый сокет может не существовать. Это приводит к ошибке соединения, которую Nginx возвращает как 502.

3. Перегрузка и нехватка ресурсов

Если на сайт приходит много запросов, все PHP-воркеры могут быть заняты, а новые соединения будут уходить в таймаут. Nginx не дождётся ответа и вернёт 502 . Это также может быть связано с нехваткой оперативной памяти на VPS, когда systemd или OOM Killer принудительно завершают PHP-FPM или MySQL.

4. Слишком большой заголовок ответа (upstream sent too big header)

Иногда бэкенд (например, PHP-скрипт) пытается вернуть слишком много данных в заголовках или установить очень большую сессионную куку. Буферы Nginx по умолчанию могут быть просто не рассчитаны на такой объём, и он прерывает соединение с ошибкой 502.

Как исправить 502 Bad Gateway: пошаговая инструкция

Вот практический план действий для системного администратора в среде Ubuntu. Все команды требуют прав суперпользователя (sudo).

Шаг 1: Проверьте логи — это ваш главный инструмент

Прежде чем что-то менять, загляните в логи Nginx:

sudo tail -f /var/log/nginx/error.log

Или посмотрите последние 50 строк:

sudo tail -n 50 /var/log/nginx/error.log

Лог часто сразу указывает на причину: «connection refused» (соединение отвергнуто), «upstream timed out» (таймаут) или упоминание о слишком большом заголовке.

Шаг 2: Проверьте статус PHP-FPM

Убедитесь, что сервис PHP-FPM запущен. Узнайте версию PHP, которая у вас установлена:

php -v

Затем проверьте статус сервиса (подставьте вашу версию):

sudo systemctl status php8.1-fpm

или, если не знаете точную версию:

sudo systemctl status php*-fpm

Если он остановлен, запустите его:

sudo systemctl start php8.1-fpm

и настройте автозапуск:

sudo systemctl enable php8.1-fpm

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

Откройте конфигурацию вашего сайта в Nginx, например:

sudo nano /etc/nginx/sites-available/ваш_сайт

Найдите блок location ~ \.php$ и директиву fastcgi_pass. Проверьте, указывает ли она на реально существующий сокет. Обычно они лежат в /run/php/. Если там написано php7.4-fpm.sock, а у вас версия 8.1, исправьте путь .

fastcgi_pass unix:/run/php/php8.1-fpm.sock;

Особые случаи: reuseport, Majestic, FunPay и версии Nginx

Иногда ошибка 502 может проявляться в специфических ситуациях.

Директива reuseport

В логах или на странице ошибки можно заметить упоминание nginx-reuseport. Это не причина ошибки, а информация о версии Nginx и используемой директиве (reuseport помогает распределять нагрузку по ядрам процессора). Сама по себе директива не вызывает 502, но если у вас в конфигурации есть reuseport и вы видите ошибку, проблема всё равно в бэкенде. Однако в некоторых случаях встречается ошибка, связанная с nginx-reuseport при сохранении большого списка блокировок (например, для защиты от спама), что может быть вызвано лимитами PHP или самого Nginx .

Majestic, FunPay и сторонние сервисы

Названия Majestic (сервис анализа ссылок) и FunPay (торговая площадка) могут фигурировать в контексте сайтов, использующих внешние API. Если ваш сайт на WordPress обращается к API Majestic или FunPay, а внешний сервис отвечает слишком долго, PHP-воркер может зависнуть. Это вызовет таймаут со стороны Nginx и, как следствие, 502 Bad Gateway. В таком случае нужно увеличивать max_execution_time в PHP или proxy_read_timeout в Nginx.

Версии Nginx: 1.31, 1.30, 1.29 … 1.14

Упомянутые версии (от 1.31 до 1.14) охватывают практически все актуальные и устаревшие релизы. Многие из них активно используются на хостингах и в сборках вроде VestaCP . Сама ошибка 502 не зависит от конкретной версии — она возникает на любых релизах, но методы её решения (проверка PHP, буферов, SELinux) едины для всех перечисленных версий. Если вы используете устаревшую версию (1.14, 1.18), и проблема возникла при обновлении ОС, возможно, пора обновить и сам Nginx до более свежего релиза из официального репозитория.

Другие причины и их исправление

Если базовые шаги не помогли, рассмотрите эти варианты.

SELinux

На некоторых конфигурациях Ubuntu (или CentOS, но бывает и на Ubuntu с включенным SELinux) он может блокировать сетевые соединения Nginx с бэкендом. Проверьте это по логам: если видите (13: Permission denied) while connecting to upstream, разрешите сетевые подключения :

sudo setsebool -P httpd_can_network_connect 1

Недостаточно буферов

Если в логе ошибка upstream sent too big header while reading response header, это значит, что Nginx не хватает места в буферах для обработки заголовка ответа бэкенда . Увеличьте размеры буферов в конфигурации nginx (например, в файле /etc/nginx/nginx.conf или в настройках виртуального хоста):

proxy_buffers 8 16k;
proxy_buffer_size 32k;
fastcgi_buffers 8 16k;
fastcgi_buffer_size 32k;

После изменений проверьте конфигурацию (sudo nginx -t) и перезагрузите Nginx (sudo systemctl reload nginx).

Исчерпание портов

В редких случаях, если сайт работает под большой нагрузкой и открывает и закрывает множество соединений с бэкендом, могут закончиться свободные локальные порты. Это может проявляться как периодический 502 . Решение — увеличить диапазон доступных портов в настройках ядра или оптимизировать keepalive-соединения.

Заключение

502 Bad Gateway — это не «сломался сервер», а «Nginx не смог подружиться с бэкендом». Главный инструмент в борьбе с ним — логи. Проверяйте PHP-FPM, его статус и пути сокетов. Изучайте логи Nginx и PHP-FPM, проверяйте, не переполнена ли оперативная память (команда free -h) . Директивы reuseport, версии Nginx (1.31, 1.30, 1.29…), а также интеграции с сервисами вроде Majestic или FunPay — это лишь контекст, в котором может появиться ошибка. Её суть всегда одна: бэкенд не отвечает, как нужно. Системный подход к диагностике позволит вам быстро локализовать и исправить проблему, вернув ваш сайт к жизни.