Исправление ошибок Nginx 502 Bad Gateway: пошаговое руководство

Исправление ошибок Nginx 502 Bad Gateway начинается с понимания того, что Nginx обычно является посредником, а не источником проблемы. Код 502 означает, что Nginx попытался связаться с вышестоящим сервисом и не получил корректного ответа.

Таким вышестоящим сервисом может быть приложение Node.js, PHP-FPM, Gunicorn, Puma, контейнер или другой HTTP-сервер. Ваша задача — найти, на каком этапе происходит сбой.

Что означает ошибка 502 Bad Gateway в Nginx

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

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

• Процесс приложения остановлен.
• Nginx указывает на неправильный порт или сокет.
• Неправильные права доступа к Unix-сокету.
• Вышестоящий сервис аварийно завершает работу во время запроса.
• Брандмауэр или сеть контейнера блокируют соединение.
• Вышестоящий сервер отправляет недопустимый HTTP-ответ.

Начните с точного пути запроса, который вызывает ошибку. Если только /api возвращает 502, а статические страницы загружаются, значит, обслуживание статических файлов в порядке, а проблема, скорее всего, в прокси или бэкенде приложения. Если все страницы не работают, проблема может быть более общей: Nginx, DNS или доступность вышестоящего сервера.

Шаг 1: Проверка статуса и конфигурации Nginx

Сначала убедитесь, что Nginx запущен:

systemctl status nginx

Затем проверьте конфигурацию:

nginx -t

Если проверка конфигурации не удалась, исправьте это, прежде чем разбираться с приложением. Nginx может продолжать работать со старой конфигурацией или не сможет перезагрузиться.

После успешной проверки конфигурации перезагрузите Nginx:

systemctl reload nginx

Не перезапускайте Nginx вслепую на загруженном сервере, если вы не понимаете последствий. Перезагрузка обычно достаточна после изменения конфигурации и менее критична.

Затем проверьте активный блок server. Найдите proxy_pass, fastcgi_pass или uwsgi_pass. Типичный обратный прокси может выглядеть так:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Это означает, что Nginx ожидает приложение на локальном порту 3000. Если приложение на самом деле слушает порт 3001 или работает только внутри сети Docker, Nginx выдаст ошибку.

Для более детальных проверок с помощью команд смотрите Команды проверки конфигурации Nginx.

Шаг 2: Проверка вышестоящего сервиса

Теперь проверьте вышестоящий сервер напрямую с хоста Nginx. Если Nginx проксирует на 127.0.0.1:3000, выполните:

curl -i http://127.0.0.1:3000/

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

Проверьте процесс приложения:

ss -ltnp

Найдите ожидаемый порт. Если сервис использует Unix-сокет, проверьте путь к сокету:

ls -l /run/app/app.sock

Пользователь рабочего процесса Nginx должен иметь доступ к этому сокету. Во многих системах Linux Nginx работает от имени www-data, nginx или пользователя, специфичного для сервиса. Если сокет принадлежит другому пользователю и не доступен для чтения или записи группе, Nginx может зарегистрировать ошибку прав доступа и вернуть 502.

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

systemctl status php-fpm

Имя сервиса может включать версию, например php8.2-fpm, в зависимости от дистрибутива.

Шаг 3: Чтение журнала ошибок Nginx

Журнал ошибок Nginx обычно сообщает, с каким типом сбоя вы имеете дело. Распространенные сообщения журнала включают:

connect() failed (111: Connection refused) while connecting to upstream

Это означает, что Nginx достиг хоста, но ничто не приняло соединение на этом порту.

upstream timed out while reading response header from upstream

Это означает, что Nginx подключился, но бэкенд не ответил вовремя.

permission denied while connecting to upstream

Это часто указывает на права доступа к Unix-сокету или элементы управления безопасностью, такие как SELinux.

Проверьте последние ошибки с помощью:

tail -n 100 /var/log/nginx/error.log

В системах на основе systemd также можно проверить:

journalctl -u nginx -n 100

Сопоставьте временную метку в журнале с временем вашего запроса в браузере. Это поможет не тратить время на старые ошибки, которые уже не актуальны.

Для более глубокого анализа журнала смотрите анализ журналов ошибок Nginx.

Шаг 4: Устранение наиболее распространенных причин

Как только вы определили тип сбоя, примените наименьшее исправление, которое ему соответствует.

Если приложение не запущено, запустите или перезапустите сервис приложения:

systemctl restart your-app

Затем проверьте вышестоящий сервер с помощью curl, прежде чем тестировать через Nginx.

Если Nginx указывает на неправильный порт, обновите цель proxy_pass и перезагрузите Nginx. Убедитесь, что ваше приложение и Nginx согласованы в отношении IPv4 и IPv6. Приложение, слушающее на 127.0.0.1, — это не то же самое, что приложение, слушающее только на ::1.

Если используется Docker, проверьте, работает ли Nginx на хосте или внутри контейнера. 127.0.0.1 внутри контейнера указывает на этот контейнер, а не на хост. Возможно, вам потребуется имя сервиса Docker, мостовая сеть или опубликованный порт.

Если вышестоящий сервер превышает тайм-аут, проверьте журналы приложения. Бэкенд может зависнуть на запросах к базе данных, внешних вызовах API или начальной загрузке. Увеличение тайм-аутов Nginx может скрыть симптомы, но не исправит сломанное или перегруженное приложение.

Когда обращаться к профессионалу

Привлекайте старшего инженера или хостинг-провайдера, когда ошибки 502 затрагивают производственную среду, а причина не очевидна после проверки журналов, статуса вышестоящих серверов и недавних развертываний. Также обратитесь за помощью, если проблема касается балансировщиков нагрузки, оркестрации контейнеров, политик SELinux или настройки тайм-аутов при высоком трафике.

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

Ошибка 502 Bad Gateway устраняется, если вы прослеживаете путь запроса по порядку. Подтвердите, что Nginx работает корректно, проверьте вышестоящий сервер напрямую, прочитайте точную строку журнала ошибок и примените исправление, соответствующее сбою. Такой подход быстрее и безопаснее, чем изменение тайм-аутов или слепой перезапуск сервисов.