Ошибка 502 Bad Gateway говорит о том, что сам Nginx работает исправно, но бэкенд, которому он передал запрос, — PHP-FPM, Node.js, Gunicorn или другой сервер приложений — не вернул корректный ответ. Этим она отличается от 504: при 504 бэкенд отвечает, но слишком поздно, а при 502 соединение не устанавливается вовсе, сразу обрывается или ответ приходит повреждённым. Поэтому, увидев 502, первым делом нужно спросить: «жив ли бэкенд и обращается ли к нему Nginx по правильному адресу».
Что означают сообщения в логе Nginx
Угадывать причину 502 не нужно: журнал ошибок Nginx обычно отвечает прямо. На VPS он находится в /var/log/nginx/error.log. Последние записи можно посмотреть так:
sudo tail -n 50 /var/log/nginx/error.log
В таблице ниже собраны самые частые сообщения и их смысл. Каждое указывает на свою причину, поэтому обращайте внимание на точный текст:
| Сообщение в логе | Значение |
|---|---|
connect() failed (111: Connection refused) | На указанном порту никто не слушает: приложение остановлено или работает на другом порту |
(2: No such file or directory) | Файла unix-сокета нет: PHP-FPM не запущен или путь к сокету неверный |
(13: Permission denied) | У пользователя Nginx нет прав на подключение к сокету |
upstream prematurely closed connection | Бэкенд оборвал ответ на середине: обычно упал процесс или кончилась память |
upstream sent too big header | Заголовки ответа не поместились в буфер Nginx, часто из-за большой cookie |
(11: Resource temporarily unavailable) | Очередь сокета переполнена: все воркеры заняты, места для нового соединения нет |
PHP-FPM остановлен или не запускается
На PHP-сайтах самая частая причина 502 — неработающая служба PHP-FPM. Сначала проверьте её состояние, подставив свою версию:
systemctl status php8.2-fpm
sudo journalctl -u php8.2-fpm -n 50
sudo php-fpm8.2 -t
php-fpm8.2 -t покажет синтаксические ошибки в конфигурации. Нередко служба не стартует из-за одного неверного параметра в файле пула. После исправления её перезапускают командой sudo systemctl restart php8.2-fpm. Если служба регулярно падает сама, ищите причину в выводе dmesg: при нехватке памяти система через OOM killer убивает процесс, занимающий больше всего памяти.
sudo dmesg -T | grep -i -E "killed process|out of memory"
Несовпадение пути к сокету
502 после обновления версии PHP — очень типичная ситуация. В конфигурации Nginx остался старый fastcgi_pass unix:/run/php/php8.1-fpm.sock;, а новая версия создала сокет с другим именем. Нужно посмотреть реальное имя сокета и сравнить его со значением listen в файле пула:
ls -l /run/php/
grep -E "^listen" /etc/php/8.2/fpm/pool.d/www.conf
При ошибке прав проверьте, что listen.owner и listen.group в файле пула соответствуют пользователю, под которым работает Nginx (в Debian и Ubuntu обычно www-data).
Упало приложение на Node.js или Python
У приложений за reverse proxy сообщение Connection refused почти всегда означает, что процесс не работает. Проверьте, слушается ли порт, и состояние процесса:
sudo ss -ltnp | grep 3000
pm2 status
pm2 logs --lines 100
Если приложение работает как служба systemd, последние ошибки покажет journalctl -u myapp -n 100. Часто причина банальна: после деплоя новой версии не установлен пакет, в файле .env не хватает переменной или нет подключения к базе, и приложение падает сразу при старте. Ещё одна типичная ошибка: приложение слушает localhost и открывается на IPv6-адресе ::1, а Nginx пытается подключиться к 127.0.0.1. Явное указание одного адреса с обеих сторон убирает проблему.
Большие заголовки и буферы
Сообщение upstream sent too big header встречается, когда сайт в целом работает, но на отдельных страницах или у отдельных пользователей появляется 502. Например, плагин авторизации ставит очень большую cookie или приложение отправляет много заголовков Set-Cookie. Помогает увеличение буферов:
# Для PHP-FPM
fastcgi_buffer_size 32k;
fastcgi_buffers 8 32k;
# Для reverse proxy
proxy_buffer_size 32k;
proxy_buffers 8 32k;
При этом полезно разобраться, почему cookie разрослась до такого размера: часто это признак ошибки в приложении.
Пример: сайт бронирования гостиницы в Бухаре
Сайт бронирования небольшой гостиницы в Бухаре работает на VPS. Администратор обновил системные пакеты, перевёл PHP на новую версию и удалил старую. Утром сайт начал отдавать 502 на всех страницах. В логе Nginx были (2: No such file or directory) и старый путь к сокету, а ls /run/php/ показал только сокет новой версии. После замены строки fastcgi_pass на новый путь и выполнения nginx -t и systemctl reload nginx сайт сразу заработал. С тех пор администратор перед обновлениями делает копию конфигураций и после обновления обязательно проверяет сайт.
502, который появляется время от времени
Если ошибка не постоянная, а возникает только под нагрузкой, причина обычно в нехватке ресурсов. Запись server reached pm.max_children setting в логе PHP-FPM означает, что все воркеры заняты. Бездумно увеличивать pm.max_children опасно: каждый воркер занимает память, и сервер может уйти в OOM. Правильный путь — измерить, сколько памяти в среднем потребляет один процесс PHP, рассчитать число воркеров под доступную память и в первую очередь ускорить медленные запросы. Если виноват бот-трафик, поможет ограничение частоты запросов через limit_req в Nginx.
Если вы видите 502 на виртуальном хостинге
На виртуальном хостинге PHP-FPM и Nginx управляются со стороны сервера, поэтому перезапустить службу самостоятельно нельзя. Но кое-что сделать можно: посмотреть логи ошибок сайта в панели ISPmanager, вернуть недавно изменённую версию PHP или её параметры, временно отключить только что установленный плагин. Если 502 держится дольше нескольких минут или не исчезает после ваших действий, откройте тикет из кабинета sayt.uz и укажите адрес и время ошибки. Помните также, что на сайтах за CDN вроде Cloudflare страницу 502 может показывать сам CDN: тогда проблема в соединении между CDN и вашим сервером.