Ошибка 502 Bad Gateway: почему возникает и как её устранить

Ошибка 502 Bad Gateway значит, что веб-сервер выступил посредником и получил от следующего звена недопустимый ответ. Типичная картина: nginx принимает запрос посетителя и передаёт его PHP-FPM или приложению, а те остановлены, перезапускаются или оборвали соединение. Причину ищут в журнале ошибок nginx, а не перезагрузкой наугад.

Что значит ошибка 502

Ошибка 502 — это ответ шлюза или прокси, у которого не получилось нормально поговорить со следующим сервером. Спецификация HTTP (RFC 9110) описывает её так: сервер, выступая шлюзом или прокси, получил недопустимый ответ от сервера, к которому обратился при выполнении запроса. Яндекс Вебмастер формулирует так же: недопустимый ответ от следующего сервера в цепочке запросов.

Слово «шлюз» здесь буквальное. Между посетителем и вашим кодом стоит как минимум одно звено: nginx перед PHP-FPM, балансировщик перед несколькими серверами, защита от ботов или CDN перед хостингом. Код 502 генерирует именно это звено, когда следующее за ним отвечает мусором, закрывает соединение или не принимает его.

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

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

Чем 502 отличается от 500, 503 и 504?

Все четыре кода относятся к ошибкам сервера, но показывают разные места поломки. MDN говорит об этом прямо: 502 похож на 500 тем, что это общий ответ о сбое сервера, а отличается тем, что привязан к конкретной точке в цепочке запроса. Сравнение удобнее таблицей.

Граница между 502 и 504 тонкая. По MDN, если прокси вообще не получил HTTP-ответа от исходного сервера, он отдаёт 504. На практике nginx выдаёт 502, когда бэкенд отказал в соединении или оборвал ответ, и 504, когда ответ не пришёл за отведённое время.

Факт. RFC 9110 определяет 504 как случай, когда шлюз не получил своевременного ответа от вышестоящего сервера, а 502 — когда ответ получен, но недопустим.

Почему сервер отвечает 502

Причины делятся на три группы: бэкенд недоступен, бэкенд ответил некорректно, стык настроен неверно. Вот частые случаи:

• Бэкенд остановлен — PHP-FPM или приложение не запущены, упали или перезапускаются после обновления. nginx стучится в порт или сокет и получает отказ.
• Закончились рабочие процессы — параметр pm.max_children в PHP-FPM ограничивает число одновременно обслуживаемых запросов. В пик лишние запросы не обрабатываются.
• Процесс завершён по таймауту — директива request_terminate_timeout завершает рабочий процесс, который слишком долго обслуживает один запрос. nginx получает оборванное соединение.
• Слишком большой заголовок ответа — если заголовок не помещается в буфер proxy_buffer_size, nginx считает такой ответ неверным. Часто виноваты раздутые cookie.
• Неверный адрес бэкенда — после переноса сайта proxy_pass или fastcgi_pass указывают на старый порт или сокет, а у nginx нет прав на сокет.
• Нехватка памяти — система завершила процесс бэкенда, и он перестал отвечать.
• Звено перед сайтом — защита от ботов или CDN не достучались до сервера или заблокировали запрос, и сами отдали 502.

Если ошибка появляется после обновления или переноса, подозрение падает на запуск бэкенда и адреса в конфигурации. Если приходит волнами в часы пик, на нехватку рабочих процессов и памяти.

В журнале nginx встречаются три типичные строки. Каждая указывает на свою группу причин:

connect() failed (111: Connection refused) while connecting to upstream
upstream prematurely closed connection while reading response header from upstream
upstream sent too big header while reading response header from upstream

Первая значит, что бэкенд не принимает соединения: он остановлен или адрес указан неверно. Вторая — бэкенд принял запрос и оборвал соединение: упал, был убит по таймауту или исчерпал память. Третья — заголовок ответа не поместился в буфер.

Что настроить в nginx и PHP-FPM

Две пары настроек определяют, как долго nginx ждёт бэкенд и что считает нормальным ответом. По умолчанию proxy_connect_timeout равен 60 секундам, и это таймаут установления соединения. Для чтения ответа есть отдельный таймаут: если проксируемый сервер за это время ничего не передал, nginx закрывает соединение. Для PHP-FPM аналог называется fastcgi_read_timeout, и его значение по умолчанию тоже 60 секунд.

Пример для приложения за прокси. Значения условные, их подбирают по журналу медленных запросов конкретного сайта:

server {
    server_name site.ru;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
        proxy_buffer_size 16k;
    }
}

Увеличивать таймауты стоит осторожно. Они лечат симптом: тяжёлый запрос перестаёт обрываться, но продолжает занимать рабочий процесс, и под нагрузкой 502 вернётся. Сначала найдите медленный запрос в журнале и ускорьте его.

С PHP-FPM работают два параметра. Первый — pm.max_children: он задаёт предел одновременных запросов, и при слишком малом значении сайт упирается в него на каждом пике. Второй — request_terminate_timeout: он страхует от зависших скриптов, но слишком короткое значение убивает легитимные долгие операции вроде импорта каталога.

Мнение. Если 502 повторяется только в пик, поднимайте число рабочих процессов PHP-FPM по свободной памяти сервера, а не таймауты. Если сервера не хватает под обычную нагрузку, это вопрос тарифа или кода сайта, и конфигурация его не решит.

Что делать посетителю, если 502 видите вы

Посетитель мало что может исправить, но может выяснить, где проблема. Обновите страницу через минуту: сбой часто кратковременный, например бэкенд перезапускался после обновления. Откройте сайт с другой сети, например через мобильный интернет, и с другого устройства.

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

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

Как 502 влияет на поиск?

Кратковременная 502 поиску почти не вредит, затяжная — вредит. Google пишет, что при ошибках сервера 5xx его роботы временно замедляют сканирование. Уже проиндексированные адреса остаются в индексе, но вскоре удаляются, если ошибка не проходит.

Факт. Когда сервер снова начинает отвечать кодом 2xx, Google постепенно возвращает прежнюю частоту сканирования сайта.

Яндекс строже к отдельной странице: страница с кодом ответа, отличным от 200 OK, недоступна для роботов и не может попасть в поиск. Если робот пришёл в момент сбоя, страница рискует выпасть до следующего обхода. Проверить, что видит робот Яндекса, можно в Вебмастере: на странице «Проверка ответа сервера» показан код и содержимое, которое получил бот.

Отдельная опасность — 502 только для роботов. Защита от ботов иногда принимает поисковый краулер за парсер и режет его, а у посетителей сайт открывается. Поэтому после любых изменений в защите проверяйте ответ главной страницы для роботов.

Как не получать 502 снова

Повторяющаяся 502 — сигнал, что связка веб-сервера и бэкенда работает без запаса. Что стоит сделать:

• Мониторинг с внешней проверкой — сервис, который ходит на сайт снаружи и сообщает о 502 раньше, чем позвонит клиент.
• Запас рабочих процессов и памяти — число процессов PHP-FPM рассчитано на пик, а не на средний день.
• Кэш страниц — готовые страницы отдаются без обращения к PHP и базе, и бэкенд не упирается в предел при всплеске посетителей.
• Аккуратные обновления — после правки конфигурации проверяйте её синтаксис и перезапускайте службы в правильном порядке, а ответ сайта смотрите сразу после выката.
• Журналы под рукой — ротация настроена, доступ к ним есть у того, кто разбирается с аварией.

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

Если 502 повторяется, а причина не находится по журналу, подключите техподдержку сайта: разберём связку nginx и бэкенда, найдём тяжёлые запросы и настроим мониторинг.

Источники

• RFC 9110: HTTP Semantics — IETF
• 502 Bad Gateway — MDN
• Модуль ngx_http_proxy_module — nginx
• Модуль ngx_http_fastcgi_module — nginx
• PHP-FPM: настройка — PHP
• Справочник по кодам статуса HTTP — Яндекс Вебмастер
• Как проверить, что сайт доступен для посетителей и поисковых роботов — Яндекс Вебмастер
• Как коды статуса HTTP влияют на сканирование — Google