Ошибка 502 Bad Gateway: причины и пошаговая диагностика

HTTP 502 Bad Gateway означает, что сервер, работающий как gateway или proxy, получил от upstream-сервера некорректный ответ. В типичной инфраструктуре пользователь обращается к Nginx, CDN или балансировщику, а тот передаёт запрос приложению. Если промежуточный сервер не может корректно получить или разобрать ответ upstream, клиент видит 502.

Главная практическая мысль: при 502 не нужно начинать с браузера. Нужно определить, какой компонент является proxy, какой — upstream, и проверить соединение между ними.

Как устроена ошибка 502

Упрощённая цепочка выглядит так:

Клиент → CDN/балансировщик → Nginx → приложение
                                 ↑
                       проблема связи/ответа

Согласно HTTP Semantics, 502 Bad Gateway используется, когда сервер в роли gateway или proxy получает недопустимый ответ от входящего (upstream) сервера.

Это отличает 502 от обычного 500 Internal Server Error: при 500 компонент смог сформировать HTTP-ответ о собственной внутренней ошибке, а при 502 проблема обнаруживается на границе proxy ↔ upstream.

Что чаще всего вызывает 502

Приложение не запущено или перезапускается

Nginx пытается подключиться к заданному upstream, но на адресе или порту никто не слушает. Это типичный сценарий после неудачного релиза или crash loop.

Проверьте процесс или контейнер приложения до изменения настроек Nginx.

Неверный upstream host или port

После изменения docker-compose, Kubernetes Service, имени контейнера или порта конфигурация proxy может продолжать отправлять запросы на старый адрес.

Ошибка Unix socket

Если Nginx соединяется с PHP-FPM или другим процессом через Unix socket, 502 может возникнуть из-за отсутствующего socket, неверного пути или прав доступа.

Upstream аварийно закрывает соединение

Приложение приняло соединение, но завершило его до формирования корректного HTTP-ответа. Причиной может быть crash, необработанная ошибка низкого уровня, лимит ресурсов или неправильный протокол между компонентами.

Ошибка TLS между proxy и upstream

Если Nginx обращается к upstream по HTTPS, проблемы handshake, SNI, сертификата или несовместимой конфигурации TLS также могут нарушить получение ответа.

DNS указывает proxy на неправильный адрес

В динамической инфраструктуре имя upstream может разрешаться не туда, куда ожидается. Сам факт того, что DNS-запись существует, не гарантирует правильный backend.

Пошаговая диагностика 502 Bad Gateway

Шаг 1. Подтвердите ошибку снаружи

curl -i https://example.com/

Для короткой проверки статуса:

curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/

Если видите 502, зафиксируйте время и URL.

Шаг 2. Определите, кто вернул 502

Изучите заголовки:

curl -I https://example.com/

Server, специфические заголовки CDN и структура страницы ошибки могут подсказать слой, который сформировал ответ. Но не полагайтесь только на внешний вид страницы — подтверждайте по инфраструктуре и логам.

Шаг 3. Проверьте error log proxy

Для Nginx:

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

Полезны сообщения вида connect() failed, connection refused, upstream prematurely closed connection, ошибки разрешения имени upstream и TLS.

Каждое такое сообщение сужает поиск. Например, connection refused означает не то же самое, что таймаут: TCP-соединение отклонено быстро, поэтому увеличение timeout проблему не исправит.

Шаг 4. Обратитесь к upstream напрямую

Если приложение должно слушать 127.0.0.1:8080:

curl -i http://127.0.0.1:8080/

Если прямой запрос тоже не работает, сначала исправляйте upstream. Если напрямую всё хорошо, а через Nginx получаете 502, исследуйте конфигурацию proxy, протокол, заголовки и сетевой маршрут между слоями.

В Docker нельзя автоматически считать 127.0.0.1 адресом другого контейнера: внутри контейнера loopback указывает на сам контейнер. Используйте корректное имя сервиса и порт внутренней сети.

Шаг 5. Проверьте, слушается ли ожидаемый порт

На Linux:

ss -lntp

Сравните адрес и порт с proxy_pass или upstream-конфигурацией.

Шаг 6. Проверьте контейнеры

docker ps
docker logs --tail 200 <container>

Если контейнер постоянно рестартует, 502 является следствием, а не корневой причиной. Ищите причину завершения приложения.

В Kubernetes:

kubectl get pods
kubectl get svc
kubectl get endpoints
kubectl describe pod <pod-name>
kubectl logs <pod-name> --tail=200

Пустые endpoints у Service — сильный сигнал, что трафик некуда направлять.

Шаг 7. Проверьте конфигурацию Nginx

Перед reload:

sudo nginx -t

Затем найдите соответствующий proxy_pass, fastcgi_pass или upstream block и убедитесь, что адрес соответствует фактическому приложению.

Не делайте nginx -s reload после случайных изменений без успешного nginx -t.

Шаг 8. Проверьте DNS upstream, если используется имя

getent hosts api.internal.example

или:

dig api.internal.example

Сравните полученный адрес с ожидаемым backend.

Шаг 9. Если upstream использует HTTPS — проверьте TLS

openssl s_client -connect upstream.example.com:443 -servername upstream.example.com

Это позволяет увидеть, устанавливается ли TLS-соединение и какой сертификат отдаёт сервер.

502 и 504 — в чём разница

MDN подчёркивает важное различие: 502 означает некорректный ответ upstream, тогда как при 504 Gateway Timeout gateway не получил HTTP-ответ вовремя.

Упрощённо:

502 → ответ/соединение оказалось некорректным
504 → нужный ответ не пришёл до истечения таймаута

На практике логи proxy важнее этой короткой формулы, потому что конкретное ПО может фиксировать много разных низкоуровневых причин.

Почему увеличение timeout часто не помогает при 502

Если upstream не запущен и соединение получает connection refused, ждать дольше бессмысленно. Если указан неверный порт, увеличение таймаута тоже ничего не изменит.

Timeout имеет смысл менять только после того, как доказано: upstream действительно выполняет допустимо долгую операцию, а текущий лимит меньше ожидаемого времени. Даже тогда сначала стоит понять, почему пользовательский запрос должен выполняться так долго.

502 после релиза: что проверить первым

1. Запустилось ли приложение.
2. Прошли ли миграции.
3. Не изменился ли внутренний порт.
4. Совпадает ли имя сервиса с конфигурацией proxy.
5. Есть ли healthy endpoints.
6. Нет ли crash loop или OOM.
7. Не изменился ли протокол HTTP ↔ HTTPS между слоями.
8. Не сломалась ли конфигурация секретов и переменных окружения.

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

Как обнаруживать 502 автоматически

Внешняя проверка должна обращаться к тому же публичному URL, который используют клиенты. Если монитор проверяет только внутренний /health приложения, он может не заметить проблему между CDN/Nginx и upstream.

UpWatch может регулярно выполнять HTTP-проверку критичного URL. Когда вместо ожидаемого успешного ответа появляется 502, неуспешная проверка фиксируется в истории и может инициировать уведомление. Затем server logs помогают определить низкоуровневую причину.

Чек-лист при 502 Bad Gateway

1. Подтвердить 502 через curl.
2. Определить proxy/gateway, который формирует ответ.
3. Открыть его error log.
4. Проверить upstream напрямую.
5. Убедиться, что процесс и порт существуют.
6. Проверить Docker/Kubernetes endpoints.
7. Проверить proxy_pass и протокол.
8. Проверить DNS, если upstream задаётся именем.
9. Проверить TLS, если соединение к upstream защищённое.
10. После исправления проверить публичный URL, а не только localhost.

Источники и спецификации

Определение 502 Bad Gateway зафиксировано в HTTP Semantics (RFC 9110). MDN отдельно поясняет отличие 502 от 500 и 504: proxy получил некорректный ответ upstream, а не просто внутреннюю ошибку самого приложения.

• RFC 9110: HTTP Semantics, раздел 15.6.3
• MDN: 502 Bad Gateway