Provision
—— XP

Маршрут: сайт не открывается и 502 от nginx

теория~7 минут+290 XP

Ответ 502 Bad Gateway — самая частая поломка сайта за прокси, и почти каждый DevOps-инженер видел её в первую же неделю работы. Её отдаёт nginx — веб-сервер и прокси из раздела 05, — когда сам он работает, а приложение за ним ответить не смогло. Коды 504 и 500 выглядят похоже, но ведут в разные места, и путать их значит потерять полчаса.

Адрес, куда nginx передаёт запросы, называют upstream — «выше по течению»: у нас это контейнер приложения, описанный в блоке upstream app_backend. Чтобы найти поломку, нужны два источника. Код ответа говорит, что именно случилось с upstream, а лог ошибок nginx — где и почему. В уроке разберёшь оба, четыре частые строки из лога и ловушку, при которой 502 идёт, хотя приложение живо.

Три кода

Все три кода значат «плохо», но плохо в разных местах. По ним сразу понятно, куда смотреть.

КодКто виноватЧто случилось
502 Bad Gatewayсвязь прокси с приложениемсоединиться не удалось или ответ битый
504 Gateway Timeoutприложение медленноепринял запрос и молчал дольше таймаута
503 Service Unavailableприложение или то, от чего оно зависитживо, но честно говорит «сейчас не могу»
500 Internal Server Errorсамо приложениеответило, но упало внутри

Возьмём вторую строку. 504 приходит ровно через proxy_read_timeout — сколько nginx ждёт ответа от приложения. В нашем stand.conf эта настройка не задана, значит, действует значение по умолчанию — 60 секунд. Если ответ 504 приходит всегда через одно и то же время, это верный признак: приложение живо, но что-то держит его — чаще всего медленный запрос к базе.

503 на стенде отдаёт само приложение: адрес /items так отвечает, когда не может подключиться к базе. Строки Server: nginx тут мало — nginx лишь передал ответ, а тело ответа, {"error":"database unavailable"}, написано приложением.

А 500 отдаёт уже приложение, не прокси. С ним идут сразу в логи приложения: nginx тут ни при чём, он просто передал ответ.

Где nginx пишет причину

У nginx два лога. Журнал доступа (access log) пишет строку на каждый запрос: время, адрес, код. Лог ошибок (error log) — подробности, когда что-то пошло не так. В журнале доступа ты увидишь только «502», а причину nginx кладёт во второй.

Для пакетного nginx лог ошибок лежит в /var/log/nginx/error.log. Флаг -n 5 у tail печатает пять последних строк:

ubuntu@stand:~$
sudo tail -n 5 /var/log/nginx/error.log
2026/10/01 11:31:07 [error] 29#29: *812 connect() failed (111: Connection refused) while connecting to upstream, client: 10.0.0.7, server: stand.provision.internal, request: "GET /api/items HTTP/1.1", upstream: "http://172.20.0.4:8000/items"

Строка длинная, но читается по частям: время, уровень [error], сама причина — Connection refused, — и в конце upstream: куда nginx пытался пойти. Здесь видно и адрес, и порт: 172.20.0.4:8000.

Если nginx работает в контейнере, как на стенде, лог ошибок уходит в поток вывода, и смотрят его через docker compose logs proxy. Это мы настроили в миссии раздела про Compose.

Четыре частые строки

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

Что nginx пишет в лог ошибок
Connection refused (111)
Адрес есть, на порту никто не слушает. Приложение остановлено, упало или слушает другой порт.
upstream timed out (110)
Приложение не ответило за отведённое время. Это уже 504: смотри, чем оно занято.
host not found in upstream
Имя приложения не превращается в адрес. Опечатка в имени сервиса или контейнер в другой сети.
upstream prematurely closed connection
Приложение приняло запрос и оборвало соединение: упало посреди ответа или его убили.

Первая строка — самая частая. Проверка одной командой: docker compose ps покажет, работает ли контейнер приложения, а если работает — запрос из контейнера прокси покажет, слушает ли оно тот порт. curl в образе приложения нет, поэтому спрашиваем маленьким wget, который есть в образе nginx: docker compose exec proxy wget -qO- app:8000/health.

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

Ловушка: запомненный адрес

Есть поломка, которая сбивает с толку почти всех, кто держит nginx в контейнере. Приложение пересоздали, оно работает и отвечает изнутри — а nginx продолжает отдавать 502.

Причина в том, как nginx читает блок upstream. Имя app он превращает в адрес один раз, при своём запуске, и дальше ходит по запомненному адресу. Пересозданный контейнер получил от Docker новый адрес, а nginx стучится в старый, где никого нет.

Лечится просто — заставить nginx перечитать настройки. Флаг -s reload посылает ему сигнал «перечитай», не обрывая текущие соединения:

ubuntu@stand:~$
docker compose exec proxy nginx -s reload
2026/10/01 11:40:02 [notice] 41#41: signal process started

Строка signal process started значит, что сигнал доставлен. Навсегда эту ловушку закрывают две настройки. Директива resolver 127.0.0.11 valid=10s; говорит nginx, у кого спрашивать адреса: 127.0.0.11 — встроенный DNS Docker внутри каждого контейнера, valid=10s — помнить ответ десять секунд. А пометка resolve у строки server app:8000 в блоке upstream (вместе со строкой zone, общей памятью для адресов) велит переспрашивать адрес, а не помнить его с запуска. В бесплатном nginx это появилось в версии 1.27.3, подробности — в документации. На стенде мы так не делаем; здесь достаточно узнавать ловушку и знать, чем её закрывают.

Маршрут целиком

Сложим всё в маршрут, по которому идут при ответе 502.

Маршрут при 502
1. Код
curl -sSI: точно 502, а не 504, 503 или 500? И кто ответил — Server: nginx?
2. Причина
Лог ошибок прокси: какая из четырёх строк и какой upstream.
3. Приложение
docker compose ps: контейнер работает? Если нет — его логи.
4. Порт
Из контейнера прокси приложение отвечает на тот порт, что указан в upstream?
5. Адрес
Приложение пересоздавали? Перечитать настройки прокси.

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

Словарь урока

502 Bad Gateway
Прокси работает, но не получил нормального ответа от приложения. ↩ к тексту
504 Gateway Timeout
Приложение приняло запрос и не ответило за время таймаута прокси.
Upstream
Адрес, куда nginx передаёт запросы, — у нас контейнер приложения. ↩ к тексту
Лог ошибок
Файл или поток, куда nginx пишет причины неудач; там видна настоящая ошибка за кодом 502. ↩ к тексту

Что спросят на собеседовании

  • Пользователи видят 502. Как будешь искать причину?
    Посмотрю лог ошибок nginx: какой upstream и какая ошибка. Дальше проверю, жив ли контейнер приложения и слушает ли он нужный порт.
  • Чем 502 отличается от 504?
    502 — не удалось соединиться или ответ битый. 504 — приложение не ответило за время proxy_read_timeout, обычно оно занято медленной операцией.
  • Почему после пересоздания контейнера nginx может отдавать 502?
    Он превратил имя upstream в адрес при старте и помнит старый. Нужно перечитать настройки или настроить resolver.

Что дальше

В практике сломаем стенд двумя способами — остановим приложение и укажем не тот порт — и найдём обе поломки по логу ошибок.

Проверь себя+290 XPдве попытки
1
502, 504 и 500
Чем 504 отличается от 502?
2
Где причина
Где искать настоящую причину ответа 502?
3
Четыре строки
В логе nginx: connect() failed (111: Connection refused) while connecting to upstream. Что проверить?
4
Запомненный адрес
Контейнер приложения пересоздали, он работает, а nginx продолжает отдавать 502. Почему?
ответь на все вопросы, чтобы проверить

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.