Краткий ответ
Ошибка 502 Bad Gateway означает, что Nginx не может получить корректный ответ от бэкенд-сервиса (PHP-FPM, Node.js, Gunicorn). Проверьте, работает ли бэкенд-процесс, доступны ли сокеты и порты, и нет ли ошибок в логах. В большинстве случаев решение, перезапустить бэкенд-сервис или исправить конфигурацию.
Как проявляется проблема
- Сайт показывает белую страницу с текстом 502 Bad Gateway
- Некоторые страницы работают, а динамические (PHP, API) возвращают 502
- В error log Nginx появляется connect() failed
- Бэкенд-сервис (PHP-FPM, Node) упал или перезапускается
- 502 появляется периодически, особенно под нагрузкой
Частые причины
Бэкенд-сервис не работает
PHP-FPM, Node.js, Gunicorn или другой сервер приложений упал или остановлен. Nginx тогда некому передать запрос.
Неверный сокет или порт в конфигурации
Nginx обращается к несуществующему Unix-сокету или порту, на котором бэкенд не слушает. Ошибка возникает и после изменения конфигурации или обновления.
Перегруженный бэкенд
Если PHP-FPM или приложение исчерпали все ресурсы, они не могут принять новые запросы. Nginx тогда возвращает 502 или 504.
Права доступа к сокету
Пользователь Nginx (например, www-data или nginx) не имеет прав доступа к Unix-сокету. Это часто случается после смены владельца или политики SELinux.
Бэкенд падает из-за ошибки в коде
Фатальная ошибка в приложении может обрушить рабочий процесс. В логах виден segfault или PHP Fatal error.
Пошаговое решение
- 1
Проверьте статус бэкенд-сервиса
Выполните
systemctl status php8.2-fpm(или соответствующего сервиса:php-fpm,node,gunicorn). Если сервис неактивен, попробуйтеsystemctl restart php8.2-fpm. Если он сразу снова останавливается, перейдите к чтению логов. - 2
Просмотрите error log Nginx
Откройте
/var/log/nginx/error.log(или путь изnginx -T). Ищите строки сconnect() failedилиno live upstreams. Они показывают, может ли Nginx подключиться к сокету или порту. - 3
Проверьте, слушает ли бэкенд
Для Unix-сокета:
ls -l /run/php/php8.2-fpm.sock. Для TCP-порта:ss -tlnp | grep 3000. Если вывода нет, бэкенд не слушает, и проблема в его конфигурации или запуске. - 4
Согласуйте путь в конфигурации Nginx
В файле сайта (например,
/etc/nginx/sites-enabled/example.conf) проверьтеfastcgi_passилиproxy_pass. Путь к сокету или порт должен соответствовать тому, что бэкенд действительно использует. После изменения выполнитеnginx -t, затемsystemctl reload nginx. - 5
Проверьте права доступа к сокету
Сокет должен принадлежать пользователю, под которым работает бэкенд, а пользователь Nginx должен иметь к нему доступ. При необходимости настройте права (например,
chmod 660и соответствующую группу) и перезапустите оба сервиса. - 6
Следите за логами приложения
Посмотрите PHP error log (
/var/log/php8.2-fpm.log),journalctl -u php8.2-fpm -n 50или лог приложения. Если видите фатальные ошибки, исправьте код или конфигурацию до дальнейших перезапусков. - 7
Проверьте доступ локально на сервере
С сервера выполните
curl -I -H 'Host: example.com' http://127.0.0.1иcurl -I http://127.0.0.1:3000(если приложение слушает на этом порту). Если локально работает, а снаружи нет, проблема в сети, firewall или конфигурации Nginx. - 8
Перезапустите сервисы по порядку
Сначала перезапустите бэкенд (
systemctl restart php8.2-fpm), затем Nginx (systemctl restart nginx). После этого снова загрузите сайт. Если 502 сохраняется, вернитесь к логам.
Если ничего не помогло
Если сервисы активны, сокеты доступны, а в логах нет очевидной ошибки, проверьте, не связана ли проблема с сетью или SELinux. Команда getenforce показывает, находится ли SELinux в режиме Enforcing; временно можно перевести его в Permissive (setenforce 0) для теста, но обязательно верните в Enforcing (setenforce 1). Также проверьте, не заполнен ли диск (df -h) и достаточно ли памяти (free -m). Если 502 появляется только под нагрузкой, увеличьте количество процессов PHP-FPM или worker_connections в Nginx. Для продакшн-окружения рассмотрите мониторинг, который предупредит вас до того, как пользователи заметят ошибку.
Как избежать повторения
- Регулярно следите за работой бэкенд-сервисов и настройте оповещение о падении
- Держите конфигурацию Nginx и PHP-FPM в соответствии с реальными сокетами
- Следите за потреблением ресурсов и своевременно увеличивайте лимиты
- Тестируйте изменения конфигурации с помощью `nginx -t` перед reload
Когда лучше обратиться к специалисту
Если ошибка повторяется и требует изменений в конфигурации или коде, или если у вас нет доступа к логам и root-правам, лучше обратиться в IT-поддержку. Они смогут быстро изолировать причину и предотвратить длительный простой сайта.
Обслуживание ИТ-инфраструктуры · Серверы, сети, резервное копирование, безопасность и helpdeskЧастые вопросы
502 это то же самое, что 504?
Нет. 502 означает, что бэкенд вернул некорректный ответ или Nginx не смог подключиться, а 504 означает, что бэкенд слишком долго не отвечал. На практике их часто решают похоже: проверкой бэкенд-сервиса и логов.
Почему 502 появляется только на некоторых страницах?
Статические файлы Nginx отдаёт напрямую, поэтому они работают. Динамические страницы зависят от бэкенда, поэтому они показывают 502. Это подтверждает, что проблема в сервере приложений, а не в Nginx.
Можно ли перезапустить только PHP-FPM?
Да, если проблема в PHP-FPM, достаточно `systemctl restart php8.2-fpm`. Перезапускайте Nginx только если вы меняли его конфигурацию или если проблема сохраняется.