Чем 502 отличается от 504

В RFC 9110 коды gateway разделены по смыслу: 502 Bad Gateway - шлюз получил некорректный ответ от upstream; 504 Gateway Timeout - он не дождался своевременного ответа. При коде 502 не обязательно выключено само приложение. Ошибка может появиться на CDN, балансировщике, Nginx, Apache или сервисе выше по цепочке.

Сначала зафиксируйте URL, время, частоту и область сбоя: одна страница, весь домен или только часть пользователей. Сохраните полный статус и заголовки ответа. В браузере их можно посмотреть в панели Network, а из терминала - запросом вроде curl -sS -D - -o /dev/null https://example.org/path. Замените домен своим и не добавляйте секретные query-параметры в историю терминала.

Сравните ответ с другого устройства или сети. Если 502 виден только через CDN, сначала проверяйте его маршрут к origin; если напрямую к прокси тоже приходит 502, переходите к upstream. Сам факт одинаковой страницы ошибки не доказывает, что код выдал именно Nginx: текст может подменять CDN или собственная страница сайта.

Найдите узел, который вернул ошибку

Нарисуйте цепочку запроса: клиент, DNS/CDN, reverse proxy, приложение и при необходимости база. У каждой точки свой журнал. Ищите один и тот же временной интервал, путь, request ID и адрес upstream. Если идентификатор запроса не передается между слоями, сопоставляйте секунды и URI, но учитывайте параллельные запросы.

Для Nginx изучите access log и error log. Сообщение о невозможности соединиться с upstream отличается от ответа, который пришел от приложения, но содержал непригодный статус или заголовки. Проверьте адрес и порт в директиве proxy_pass, DNS-имя upstream и сетевое пространство, в котором работает процесс. Порт из примера чужого конфигурационного файла не должен становиться предположением о вашей установке.

Если перед приложением Apache, выясните, какой proxy-модуль обрабатывает запрос и какой backend записан в конфигурации. Не включайте открытое проксирование: документация Apache отдельно предупреждает, что публичный forward proxy создает риск для вашей сети и других пользователей.

Проверьте приложение и соединение с ним

Проверьте службу через systemd и журнал приложения. Сначала используйте запрос к локальному адресу, который реально задан в конфигурации proxy. Например, если upstream слушает loopback на заданном порту, сделайте локальный HTTP-запрос именно к нему. Путь проверки должен существовать; условный /health не станет рабочим endpoint автоматически.

Если локальный тест проходит, а внешний URL дает 502, сравните путь клиента с путем до upstream. Проверьте DNS, CDN origin, TLS и Host: proxy может достучаться до IP, но отправить имя виртуального хоста, которое приложение не обслуживает. Не меняйте сразу сертификат или DNS, пока журнал не указывает на этот слой.

Если локальный запрос тоже не проходит, проверьте, запущена ли служба, какой порт она слушает и может ли proxy-процесс к нему подключиться. Сравните socket или адрес из действующей конфигурации с выводом ss -lntp или ss -lx. Первая команда показывает слушающие TCP-сокеты; Unix socket проверяйте отдельно. Важны и права socket-файла.

После перезапуска приложения проверьте runtime-каталог, свободное место, лимит памяти и обязательные внешние подключения. Сообщение «connection refused» отличается от «upstream timed out»: в первом случае соединение не установилось, во втором proxy ждал ответ. Это разные симптомы.

Для CDN запросите журнал или идентификатор origin-запроса у оператора сервиса, если у вас нет доступа к edge-логам. Не заявляйте, что сервер упал, только по пользовательскому скриншоту: проблема может касаться одного маршрута, edge-узла или сетевого пути. Сохраните время и результат проверки с обеих сторон.

Сравните заголовки и IP на каждом доступном участке. Запрос к CDN может вернуть закешированный экран ошибки, а прямой запрос к origin - другой результат. Если есть request ID, передайте его администратору CDN и сопоставьте с журналом reverse proxy. Не отключайте CDN и TLS постоянно только ради диагностики.

Проверьте и соседние коды. 500 обычно описывает внутреннюю ошибку сервера, 503 - временную недоступность службы, 504 - отсутствие своевременного ответа upstream. RFC определяет смысл статуса на ответившем узле, но не называет конкретную причину в вашем приложении. Код может быть создан шлюзом для нескольких событий, поэтому найдите запись в его access/error log.

Попросите коллегу воспроизвести сбой с точным URI и временем, не пересылая пароль, cookie или токен. Если ошибка непостоянная, сохраните один успешный и один неуспешный запрос: сравнение статуса, времени и request ID часто сужает участок. Не очищайте журналы или кеш до фиксации признаков.

Проверьте следующие причины по очереди:

1. Приложение остановилось, перезапускается или завершает запрос с исключением. 2. Процесс слушает другой адрес или порт, либо proxy обращается к неверному имени. 3. Upstream отвечает по HTTPS, а proxy отправляет HTTP, либо наоборот. 4. Backend возвращает некорректный заголовок, сбрасывает соединение или закрывается до отправки заголовков. 5. Файловый дескриптор, память или процессный лимит исчерпан; подтверждайте это журналом и метриками, а не предположением.

Для PHP-проекта проверьте не только Nginx, но и FastCGI/PHP-FPM: правильный socket или порт, работающий пул, путь к скрипту и журнал PHP. Для Python/Node-приложения смотрите управляющий service unit, команду запуска и собственный лог. Не перезапускайте все службы одновременно: так теряются признаки причины и создаются дополнительные ошибки.

Сверьте proxy_pass, Host и URI

У Nginx наличие URI после адреса в proxy_pass меняет правило передачи запроса: часть пути, совпавшая с location, может заменяться указанным URI. Если backend ожидает /api/items, а proxy отправляет другой путь, он может отвечать ошибкой, которую верхний шлюз покажет как 502. Сверьте документацию директивы и фактический маршрут.

Проверьте передаваемый заголовок Host и схему запроса. Приложение может выбирать виртуальный хост по имени, формировать редиректы или проверять HTTPS за reverse proxy. Заголовки реального IP передавайте только по документированной цепочке доверенных proxy. Иначе приложение или журнал может считать подставленное клиентом значение настоящим адресом.

Не повышайте таймауты «для исправления 502» до выяснения причины. Таймаут чаще приводит к 504, а больший лимит способен лишь дольше занимать worker. Он уместен только если операция действительно занимает больше времени и это подтверждается логами или замером.

Исправьте один слой и проверьте откат

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

В статье нет универсальной правки конфигурации, потому что 502 - результат разных архитектурных причин. Для маршрутизации читайте руководство по Nginx reverse proxy, при ошибке приложения сверяйте ошибку 500, а DNS проверяйте отдельно через диагностику DNS. Полезны также наблюдение за доступностью и мониторинг сервера. RFC 9110 и официальные модули proxy, FastCGI и Apache mod_proxy проверены 8 октября 2026 года; чужие серверы не тестировались.