Ошибка 502 Bad Gateway в Nginx

MAATRIX

Сайт вместо страницы отдаёт короткое «502 Bad Gateway», и посетители упираются в стену. Эта ошибка означает одно: Nginx работает, но не смог получить нормальный ответ от бэкенда, которому он передаёт запросы. Хорошая новость — причин у 502 немного, и они хорошо диагностируются по логам. Ниже — как найти и устранить каждую по шагам.

Что на самом деле означает 502

Важно правильно понять смысл ошибки, иначе диагностика уйдёт не туда. Nginx в типичной схеме не обрабатывает запросы сам, а выступает фронтендом и передаёт их дальше — обработчику PHP, приложению на Python или Node, другому серверу. Этот обработчик и называется бэкендом или апстримом. Ошибка 502 означает, что Nginx исправно принял запрос от посетителя, попытался передать его бэкенду, но получил в ответ мусор или вовсе ничего.

Ключевой вывод: сам Nginx, скорее всего, в порядке — проблема на стороне бэкенда или в связи между ними. Поэтому бессмысленно перезапускать Nginx по кругу в надежде, что поможет; копать надо в сторону обработчика, которому он передаёт запросы. Это сразу отсекает половину ложных направлений и экономит время. 502 — это не «сломался веб-сервер», а «веб-сервер не дождался вменяемого ответа от того, кто стоит за ним».

Полезно отличать 502 от соседних ошибок, потому что они указывают на разные вещи. Ошибка 504 Gateway Timeout — это частный случай, когда бэкенд не ответил вовремя, то есть проблема именно в скорости, а не в доступности. Ошибка 500 Internal Server Error, наоборот, обычно означает, что бэкенд как раз ответил, но сам столкнулся с ошибкой в коде, — и тогда искать надо в логах приложения, а не в связке с Nginx. А 502 говорит, что вменяемого ответа не пришло вовсе. Правильно определив, какую именно ошибку вы видите, вы сразу сужаете область поиска и не тратите время на неверный слой — сеть, бэкенд или код приложения.

Первым делом: читаем лог ошибок Nginx

Nginx честно записывает причину отказа в свой лог ошибок, и там почти всегда есть прямое указание на проблему. Откройте его и посмотрите свежие записи:

tail -30 /var/log/nginx/error.log

Формулировка в логе сразу направляет расследование. Строка о невозможности подключиться к апстриму, «connect() failed» или «no live upstreams», означает, что бэкенд не отвечает — он упал или не слушает нужный адрес. Упоминание «Permission denied» при обращении к сокету указывает на проблему с правами. «Upstream timed out» говорит, что бэкенд жив, но не успел ответить вовремя — он перегружен или завис на тяжёлой операции. Каждая из этих формулировок ведёт к своей причине, поэтому первый и главный шаг — не гадать, а прочитать, что именно написал Nginx.

Бэкенд упал или не запущен

Самая частая причина 502 — бэкенд просто не работает. Обработчик PHP, приложение или другой сервис, которому Nginx передаёт запросы, мог упасть из-за ошибки, нехватки памяти или не запуститься после перезагрузки. Проверьте его статус — например, для обработчика PHP:

systemctl status php-fpm

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

Неверный адрес, сокет или порт

Если бэкенд запущен, но Nginx всё равно не может до него достучаться, вероятно, они «разговаривают» на разных адресах. В конфигурации Nginx директива передачи запросов указывает, куда слать их — на сокет или на порт. Если этот адрес не совпадает с тем, что реально слушает бэкенд, получается 502: Nginx стучится не туда.

Проверьте, что именно слушает бэкенд, и сверьте с конфигом Nginx:

ss -tlnp | grep -E 'php|9000|8000'

Частая ситуация — после обновления или переустановки бэкенд стал слушать unix-сокет вместо TCP-порта или сменил путь сокета, а конфиг Nginx остался старым. Приведите их в соответствие: адрес в директиве передачи запросов Nginx должен в точности совпадать с тем, что слушает обработчик. После правки обязательно проверьте синтаксис конфига и перезагрузите Nginx, чтобы изменения вступили в силу:

nginx -t && systemctl reload nginx

Команда проверки покажет ошибки в конфигурации до перезагрузки, что убережёт от полного падения сайта из-за опечатки. Это хорошая привычка — никогда не перезагружать Nginx, не прогнав проверку.

Таймауты и перегрузка бэкенда

Отдельный класс 502 возникает, когда бэкенд жив, но не успевает ответить в отведённое время. Nginx ждёт ответа ограниченное число секунд и, не дождавшись, отдаёт 502. Причин две, и они разные. Первая — бэкенд реально перегружен: не хватает рабочих процессов, все они заняты, и запросы стоят в очереди. Вторая — конкретная операция выполняется слишком долго: тяжёлый отчёт, медленный внешний запрос, зависший процесс.

Лечение зависит от причины. Если бэкенду не хватает воркеров под нагрузку, увеличьте их число в его настройках — но только если позволяет память, иначе получите нехватку RAM и новые падения. Если виновата медленная операция, оптимизируйте её или вынесите в фоновую обработку, чтобы она не держала веб-запрос. Простое увеличение таймаутов Nginx маскирует симптом, но не лечит причину: посетитель всё равно ждёт слишком долго. Поэтому таймауты поднимают лишь как временную меру, а настоящее решение — разгрузить или ускорить бэкенд.

Права доступа и мелкие ловушки

Если в логе фигурирует «Permission denied» при обращении к сокету, дело в правах. Nginx работает от своего пользователя и должен иметь право читать и писать в сокет бэкенда. После смены пользователя, обновления или переноса конфигурации права на сокет могут перестать совпадать, и возникает 502, хотя оба сервиса запущены и настроены верно.

Отдельно стоит помнить про последовательность запуска после перезагрузки сервера. Иногда Nginx стартует раньше, чем бэкенд успел подняться и создать свой сокет, и первые запросы ловят 502, пока обработчик ещё инициализируется. Обычно это самоустраняется за секунды, но если бэкенд по какой-то причине не стартовал автоматически, ошибка останется висеть. Поэтому после перезагрузки, поймав 502, всегда проверяйте, что все нужные службы действительно запущены и добавлены в автозагрузку, — банально забытый автозапуск бэкенда даёт ровно эту картину и легко принимается за что-то более сложное.

Убедитесь, что пользователь Nginx и пользователь бэкенда согласованы, а права на сокет позволяют им общаться. На системах с усиленной защитой вроде SELinux дополнительно может блокировать соединение сама политика безопасности — это ещё одно место, куда стоит заглянуть, если всё остальное выглядит правильным. Такие мелочи легко упустить, но лог ошибок Nginx, как правило, прямо на них указывает, если внимательно его прочитать. Именно поэтому диагностику 502 всегда начинают с лога, а не с догадок.

Профилактика: чтобы 502 не возвращалась

Большинство появлений 502 предотвратимо. Первое — мониторинг бэкенда и памяти, чтобы замечать падения и приближение к пределу RAM заранее, а не по жалобам посетителей. Настройте автоматический перезапуск бэкенда при сбое, чтобы разовая ошибка не превращалась в долгий простой. Второе — держите память с запасом: именно её нехватка чаще всего убивает бэкенд под нагрузкой и порождает плавающие 502.

Третье — включите кэширование, чтобы снизить нагрузку на бэкенд: чем меньше запросов доходит до обработчика, тем меньше шансов, что он захлебнётся. Четвёртое — после любых изменений конфигурации проверяйте её командой теста перед перезагрузкой. И, наконец, если 502 возникает регулярно именно на пиках и упирается в нехватку ресурсов, это честный сигнал, что проекту тесно на текущем тарифе: запас по памяти и мощности убирает саму почву для этой ошибки. Быстрый сервер с достаточным объёмом RAM избавляет от плавающих отказов надёжнее любых тонких настроек таймаутов.

Частые вопросы