502 Bad Gateway: что это значит, почему возникает и как устранить неполадки

Ключевые слова

Этот краткий глоссарий охватывает термины инфраструктуры, которые с наибольшей вероятностью вызывают путаницу на этапе более детального объяснения.

Почему ошибка 502 ощущается столь разрушительной

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

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

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

Что на самом деле означает ошибка 502 Bad Gateway

Ошибка 502 Bad Gateway обычно означает, что сервер, выступающий в роли шлюза или proxy, не смог использовать ответ, полученный от следующего уровня за ним. Простыми словами: один сервер попытался передать ваш запрос другому серверу, и эта передача завершилась неудачей настолько серьёзной, что фронтальный сервер не смог вернуть нормальный результат.

📝 Примечание: Если upstream возвращает собственную корректную HTTP-ошибку, proxy обычно передаёт её дальше. Если приложение возвращает настоящий 503 Service Unavailable, фронтальный уровень, как правило, должен передать этот 503, а не генерировать 502. Ошибка 502 означает, что сам ответ был непригоден для использования. Если пригодный ответ не поступает вовремя, это чаще всего 504.

Самый быстрый способ перестать неправильно интерпретировать ошибки 5xx — разделить их по месту возникновения сбоя и первому вопросу, который они вызывают:

⚠️ Предупреждение: Не объединяйте 500, 502, 503 и 504 в одну общую категорию «сервер недоступен». Они указывают на различные виды сбоев, и это меняет то, что следует проверять в первую очередь.

Как только это определение станет ясным, следующий вопрос приобретёт гораздо большую практическую ценность: где именно в реальном стеке происходит эта неудавшаяся передача?

Где происходит ошибка в реальной цепочке запросов

Большинство современных запросов не проходят напрямую от браузера к приложению. Они пересекают несколько уровней: браузер → CDN или edge, edge → reverse proxy или load balancer, proxy → процесс приложения. Ошибка 502 становится видимой в одной из этих точек передачи.

Упрощённая цепочка запросов: Браузер → CDN/Edge → Reverse Proxy / Load Balancer → Приложение / Процесс

Reverse proxy принимает публичный запрос и перенаправляет его внутри системы. Load balancer делает нечто похожее, но может выбирать между несколькими работоспособными целями. В обоих случаях фронтальный уровень маршрутизирует запрос, а не выполняет бизнес-логику самостоятельно.

Здесь хорошо работает аналогия с ресепшеном. Представьте proxy как стойку регистрации в офисном здании. Она регистрирует посетителя, находит нужный кабинет и пытается его туда направить. Если кабинет не отвечает, отвечает по неправильной линии или даёт ответ, который стойка регистрации не может использовать, стойка возвращает сообщение об ошибке. Именно поэтому видимая ошибка часто появляется на уровне proxy, даже если глубинная причина находится в другом месте.

📝 Примечание: Proxy зачастую является лишь посредником, сообщающим об ошибке, а не её первопричиной.

«Следующий сервер» за этой стойкой регистрации может быть обычным HTTP-сервисом на порту, слушателем приложения, например 127.0.0.1:3000, или процессом на основе локального сокета, таким как PHP-FPM. Корневая проблема не обязательно находится в proxy. Неудачное развёртывание, аварийно завершившийся рабочий процесс приложения или даже сбой базы данных могут нарушить работу backend настолько, что proxy окажется лишь местом, где проявляется ошибка 502.

Пограничные сервисы добавляют ещё один нюанс. CDN, например Cloudflare, может передавать ошибку 502 со стороны origin из более глубоких уровней вашего стека или генерировать её самостоятельно при сбое передачи от edge к origin. Именно поэтому вопрос «кто вернул эту ошибку?» является первым практическим вопросом, а не второстепенным.

Почему возникают ошибки 502: основные категории сбоев

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

Первая категория — очевидная: upstream отсутствует в работоспособном состоянии. Возможно, приложение аварийно завершилось после развёртывания. Возможно, сервис так и не перезапустился. Возможно, пул PHP-FPM завершил работу или цель была помечена как нездоровая и исключена из ротации. Это классический сценарий «сервис недоступен», но он лишь один из аспектов картины ошибок 502.

Вторая категория — несоответствие при передаче. Здесь оба уровня могут быть запущены, но они не согласуются в том, как обращаться друг к другу. Proxy может указывать на неверный порт. Имя хоста может разрешаться неправильно. Брандмауэр может блокировать путь. Один уровень может ожидать HTTPS, тогда как следующий работает только по обычному HTTP. Путь к сокету мог измениться. В таких случаях приложение может быть работоспособным, а соединение между уровнями всё равно будет нарушено.

Третья категория сложнее: upstream отвечает, но не так, как шлюз может использовать. Цель может сбросить TCP-соединение, закрыть его слишком рано, отправить некорректные или слишком большие заголовки или вернуть неполный вывод под нагрузкой. Приложение не просто «выключено»; оно отвечает настолько плохо, что шлюз отвергает полученное.

Именно поэтому ошибка 502 — это не просто история о тайм-аутах. Некоторые случаи тайм-аута становятся 504 Gateway Timeout, а не 502. Cloudflare может генерировать ошибки 502 на стороне edge при нарушении связи с origin или проблемах со сжатием. Load balancer’ы могут выдавать ошибки 502 при проблемах с таймингом отмены регистрации или сбоях TLS-рукопожатия. «Сервис недоступен» — это одна из категорий причин, а не определение самой ошибки.

Эта ментальная модель даёт вам реальный контрольный список ещё до того, как вы откроете какой-либо файл конфигурации. Определите, в какой категории вы, вероятно, находитесь, затем ищите доказательства. Именно это делает процесс устранения неполадок логичным, а не ритуальным.

Разумная последовательность устранения ошибок 502

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

💡 Совет: Прежде чем перезапускать или редактировать что-либо, определите, кто вернул 502. Чёткое определение источника ошибки зачастую экономит больше времени, чем первые пять «исправлений», которые люди пробуют под давлением.

Фаза 1: Определите уровень

Начните с публичной стороны и выясните, что именно возвращает интернет-facing уровень:

curl -I https://example.com

Это показывает HTTP-статус и заголовки публичного URL. Если заголовки явно принадлежат CDN, load balancer’у или reverse proxy, у вас есть первая подсказка. Если страница с ошибкой оформлена в стиле Cloudflare, возможно, ошибку 502 сгенерировал сам Cloudflare; если она без брендинга, edge может просто передавать сбой со стороны origin. Заголовки вроде cf-error-type или cf-error-origin могут присутствовать на страницах ошибок, сгенерированных Cloudflare, что полезно именно потому, что они не появляются на каждой ошибке 502.

📝 Примечание: Если ошибку видит только один посетитель, тогда как другие могут получить доступ к сайту, локальные настройки VPN, proxy, брандмауэра или DNS всё равно могут быть частью проблемы. Ошибка 502 обычно возникает на стороне сервера, но изолированный клиентский путь может затруднить наблюдение.

Фаза 2: Проверьте путь upstream

Как только вы определили, какой уровень вернул ошибку 502, проверьте следующий узел за ним. Если задействован reverse proxy, убедитесь, что и proxy, и backend-сервис запущены, и что ожидаемый слушатель существует:

systemctl status nginx
systemctl status <app-service>
ss -tlnp

Замените <app-service> на имя вашего backend-сервиса. systemctl status покажет, работает ли proxy или процесс приложения, завершился ли он с ошибкой или перезапускается. ss -tlnp показывает, прослушивает ли что-либо на ожидаемом порту.

Затем проверьте, отвечает ли backend напрямую, без proxy посередине:

curl -i http://127.0.0.1:3000

Если прямой запрос работает, а публичный URL по-прежнему возвращает 502, backend может быть работоспособным, и реальной проблемой может оказаться передача. Это указывает на настройки целей proxy, несоответствия протоколов, имена хостов upstream, ожидания TLS или правила брандмауэра, а не только на код приложения.

Фаза 3: Используйте команды как доказательство, а не как ритуал

После прямых проверок переходите к доказательствам, объясняющим почему передача завершается неудачей:

journalctl -u nginx -u <app-service> --since "15 min ago"
dig +short example.com
nginx -t

Эти три проверки отвечают на разные вопросы. journalctl выявляет недавние аварийные завершения, сбросы соединений, признаки тайм-аутов и сбои, связанные с развёртыванием. dig +short показывает, разрешается ли имя хоста, от которого вы зависите, так, как ожидает сервер. nginx -t проверяет синтаксис конфигурации reverse proxy перед перезагрузкой, что важно, поскольку неверное определение upstream может порождать ошибку 502, даже когда backend работает нормально.

Практические признаки обычно выглядят следующим образом:

Вот основной шаблон, который следует запомнить: определите уровень, проверьте следующий узел, затем используйте логи и прямые тесты для объяснения несоответствия. Сначала доказательства. Потом настройки.

Как путь устранения неполадок меняется в зависимости от модели хостинга

Следующий шаг после ошибки 502 зависит от того, насколько большой частью стека вы управляете. Логика устранения неполадок остаётся той же, но объём того, что вы можете самостоятельно проверить, существенно различается между общим хостингом, VPS, выделенными серверами и конфигурациями с edge-proxy.

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

На общем хостинге самое полезное, что вы можете сделать, — это собрать доказательства: время, затронутый URL, является ли ошибка постоянной или периодической, и началась ли она после развёртывания или изменения конфигурации. Это даёт поддержке что-то конкретное для работы. Если вы не управляете reverse proxy, сервисом приложения или логами сервера, полноценная диагностика по уровням быстро заходит в тупик.

На VPS полный рабочий процесс становится реалистичным, поскольку вы можете напрямую проверять сервисы, слушателей, логи и конфигурацию proxy. Именно здесь уместно устранение неполадок с reverse proxy. На инфраструктуре AlexHost VPS проверка systemctl, journalctl, ss, целей upstream и конфигурации Nginx является частью обычного управления, а не чем-то, всегда скрытым за поддержкой.

Выделенный сервер даёт ту же видимость, но с большей ответственностью. Вы управляете большей частью полного стека и, возможно, большим количеством окружающих сетевых допущений. Если вы добавляете CDN или другой пограничный сервис перед ним, первый вопрос об ответственности остаётся прежним: сгенерировал ли edge ошибку 502 или передал сбой со стороны origin? Больший контроль не делает устранение неполадок проще по умолчанию. Он даёт вам больше мест для проверки.

Мыслите уровнями, а не в панике

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

Поэтому придерживайтесь простой последовательности: определите уровень, проверьте следующий узел, подтвердите с помощью прямых тестов и логов, и изменяйте настройки только тогда, когда доказательства указывают на конкретное место. Если повторяющиеся инциденты постоянно подталкивают вас к более глубокой видимости логов, proxy и сервисов, именно в этот момент среды с более широким контролем — включая AlexHost VPS или выделенные серверы — становятся полезными по операционным причинам, а не маркетинговым. Метод важнее заучивания.