Ошибка 502 или 504 в Nginx: как найти причину

Если Nginx показывает 502 Bad Gateway или 504 Gateway Timeout, сначала проверяйте не сам Nginx, а сервис, которому он передаёт запрос: PHP-FPM, Node.js, Python-приложение, Apache, Docker-контейнер или другой backend. Ошибка 502 чаще возникает, когда Nginx не может нормально подключиться к upstream или получает от него некорректный ответ. Ошибка 504 обычно означает, что соединение было установлено или запрос был передан, но Nginx не дождался ответа вовремя.

Не начинайте с увеличения всех тайм-аутов. Сначала откройте журнал ошибок Nginx: в большинстве случаев там уже написано, на каком этапе возникла проблема.

Чем отличаются ошибки 502 и 504

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

Браузер → Nginx → upstream → приложение

Upstream в данном случае — сервер или приложение за Nginx. Например, конфигурация может содержать:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Здесь Nginx принимает запрос пользователя и пытается получить страницу от приложения на 127.0.0.1:3000.

Если приложение остановлено, слушает другой порт или соединение с ним невозможно, пользователь может получить 502 Bad Gateway.

Если приложение работает, но слишком долго не передаёт данные, может появиться 504 Gateway Timeout. Например, это происходит при зависшем запросе к базе данных, перегрузке приложения или слишком долгой обработке запроса.

С чего начать диагностику

Не меняйте конфигурацию наугад. Сначала определите, куда именно Nginx отправляет запрос.

Проверьте активную конфигурацию:

sudo nginx -T

Команда выводит конфигурацию Nginx с учётом подключённых файлов. Найдите нужный server и обратите внимание на proxy_pass, fastcgi_pass или другие директивы передачи запросов.

Например:

proxy_pass http://127.0.0.1:3000;

означает, что нужно проверить сервис на порту 3000.

А запись:

fastcgi_pass unix:/run/php/php-fpm.sock;

означает, что Nginx обращается к приложению через Unix-сокет.

Шаг 1. Проверьте журнал ошибок Nginx

На многих Linux-серверах журнал находится здесь:

/var/log/nginx/error.log

Посмотреть последние записи можно командой:

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

Для наблюдения за журналом в реальном времени:

sudo tail -f /var/log/nginx/error.log

После запуска второй команды откройте проблемную страницу сайта. Новая ошибка должна появиться в терминале.

Путь к журналу может отличаться, если он изменён директивой error_log в конфигурации Nginx.

Connection refused

Один из наиболее показательных вариантов:

connect() failed (111: Connection refused) while connecting to upstream

Это означает, что Nginx попытался установить соединение с upstream, но подключиться не получилось.

Проверьте:

• запущено ли приложение;
• правильно ли указан порт;
• правильно ли указан IP-адрес;
• слушает ли сервис ожидаемый адрес;
• не изменился ли порт приложения после обновления конфигурации.

Например, если Nginx отправляет запросы на 127.0.0.1:3000, проверьте этот порт:

sudo ss -lntp | grep ':3000'

Если команда ничего не выводит, скорее всего, на этом порту сейчас никто не принимает соединения.

Upstream timed out

Другой характерный вариант:

upstream timed out

Здесь проблема уже связана со временем ожидания. Nginx не получил необходимые данные от upstream за установленный промежуток времени.

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

No such file or directory

При использовании PHP-FPM можно встретить ошибку подключения к Unix-сокету, например:

connect() to unix:/run/php/php-fpm.sock failed (2: No such file or directory)

Nginx пытается открыть сокет, которого нет по указанному пути.

Нужно проверить конфигурацию PHP-FPM и фактический путь к сокету. Не копируйте путь из чужой инструкции: название файла зависит от установленной версии и конфигурации PHP-FPM.

Permission denied

Если журнал содержит:

Permission denied

файл или Unix-сокет существует, но Nginx не может получить к нему доступ.

В этом случае нужно проверить владельца, группу и права доступа. Не исправляйте проблему командой chmod 777: это слишком широкие разрешения и плохая практика для рабочего сервера.

Шаг 2. Убедитесь, что upstream запущен

Если приложение работает как служба systemd, проверьте её состояние:

systemctl status ИМЯ-СЛУЖБЫ

Например, для конкретного сервиса нужно использовать его настоящее имя.

Посмотреть запущенные службы можно так:

systemctl --type=service --state=running

Если нужная служба остановлена, сначала выясните причину. Для просмотра её журнала используйте:

journalctl -u ИМЯ-СЛУЖБЫ -n 100 --no-pager

Простой перезапуск иногда временно возвращает сайт в работу, но не объясняет, почему приложение остановилось. Если процесс падает снова, изучайте его журнал.

Шаг 3. Проверьте порт приложения

Посмотреть слушающие TCP-порты можно командой:

sudo ss -lntp

Допустим, в Nginx указано:

proxy_pass http://127.0.0.1:8080;

Проверьте:

sudo ss -lntp | grep ':8080'

Если приложение работает, но слушает, например, 127.0.0.1:8000, а Nginx обращается к 127.0.0.1:8080, необходимо исправить конфигурацию одной из сторон.

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

Для HTTP-приложения полезно временно исключить Nginx из цепочки.

Например:

curl -v http://127.0.0.1:3000/

Замените адрес и порт на значения из вашей конфигурации.

Если приложение отвечает напрямую, а через Nginx сайт не работает, область поиска заметно сужается: нужно проверять настройки проксирования, адрес upstream, заголовки и журналы Nginx.

Если curl также не может получить ответ, проблема находится на стороне приложения, его сетевых настроек или зависимости, к которой оно обращается.

Шаг 5. Проверьте Unix-сокет

PHP-FPM и некоторые другие сервисы могут принимать соединения не через TCP-порт, а через Unix-сокет.

Например:

fastcgi_pass unix:/run/php/php-fpm.sock;

Проверьте существование указанного файла:

ls -l /run/php/

Путь из fastcgi_pass должен соответствовать реально созданному сокету.

Если после обновления PHP имя сокета изменилось, а конфигурация Nginx осталась старой, сайт может начать возвращать 502.

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

После любых изменений обязательно выполните:

sudo nginx -t

При корректной конфигурации Nginx сообщит, что проверка синтаксиса прошла успешно.

Только после этого применяйте изменения:

sudo systemctl reload nginx

reload предпочтительнее бездумного перезапуска: Nginx перечитывает конфигурацию без обычного полного прекращения обслуживания текущих соединений.

Как разбираться с ошибкой 504 Gateway Timeout

Если upstream работает и отвечает, но Nginx периодически показывает 504, проверьте время выполнения проблемного запроса.

Для HTTP-прокси важна, в частности, директива:

proxy_read_timeout 60s;

По умолчанию proxy_read_timeout составляет 60 секунд. Важно понимать его правильно: это не максимальная продолжительность обработки всего запроса. Таймер действует между последовательными операциями чтения ответа от проксируемого сервера. Если upstream ничего не передаёт в течение этого времени, Nginx закрывает соединение.

Для установки соединения используется другая директива:

proxy_connect_timeout 60s;

Она определяет время ожидания установки соединения с проксируемым сервером.

Поэтому просто устанавливать огромные значения вроде:

proxy_read_timeout 3600s;

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

Проверьте нагрузку на сервер

Если 502 или 504 появляется только периодически, особенно при большом количестве посетителей, проверьте ресурсы сервера.

uptime

Для просмотра процессов:

top

Для проверки памяти:

free -h

Для проверки свободного места:

df -h

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

Безопасное восстановление сайта

Если причина найдена, действуйте в зависимости от результата диагностики.

1. Если остановилось приложение — изучите его журнал и только затем запустите или перезапустите сервис.
2. Если указан неправильный порт или адрес — исправьте конфигурацию.
3. Если отсутствует Unix-сокет — проверьте PHP-FPM или другой создающий его сервис.
4. Если проблема в правах — настройте корректного владельца, группу и разрешения вместо использования chmod 777.
5. Если приложение отвечает слишком долго — найдите причину задержки и только при необходимости корректируйте тайм-аут.
6. После изменения Nginx выполните sudo nginx -t и только затем применяйте конфигурацию.

Быстрый алгоритм поиска ошибки

Для большинства случаев достаточно пройти следующую цепочку:

502 или 504
      ↓
Проверить /var/log/nginx/error.log
      ↓
Определить upstream
      ↓
Проверить процесс
      ↓
Проверить порт или Unix-сокет
      ↓
Проверить upstream напрямую
      ↓
Проверить журнал приложения
      ↓
Проверить нагрузку и зависимости
      ↓
nginx -t
      ↓
reload nginx

Такой подход обычно полезнее, чем случайное изменение параметров Nginx.

Простой health check для upstream

Если приложение периодически падает, полезно проверять его независимо от основного сайта. Хороший вариант — добавить в само приложение лёгкий endpoint, например:

/health

Он должен быстро отвечать без выполнения тяжёлых операций.

Проверить такой адрес можно командой:

curl -f http://127.0.0.1:3000/health

Ключ -f заставляет curl завершиться с ошибкой при HTTP-кодах 400 и выше. Это удобно для скриптов мониторинга.

Не делайте health check слишком тяжёлым. Если для каждой проверки приложение строит большой отчёт или выполняет сложный запрос к базе данных, сама проверка может создавать дополнительную нагрузку.

Что не стоит делать при ошибках 502 и 504

• Не увеличивайте все тайм-ауты сразу.
• Не перезапускайте весь сервер до изучения журналов.
• Не используйте chmod 777 для исправления доступа к сокету.
• Не меняйте одновременно конфигурацию Nginx, приложения и PHP-FPM — иначе будет сложно понять, какое изменение помогло.
• Не применяйте конфигурацию Nginx без nginx -t.

FAQ

Что означает 502 Bad Gateway в Nginx?

Nginx выступает шлюзом или прокси и не смог нормально получить ответ от upstream. Причиной может быть остановленный backend, неправильный адрес или порт, отсутствующий Unix-сокет, проблемы с доступом или другая ошибка соединения с приложением.

Что означает 504 Gateway Timeout?

Nginx не получил необходимый ответ от upstream за допустимое время. Нужно проверить производительность приложения, базу данных, внешние зависимости, нагрузку сервера и соответствующие тайм-ауты.

Поможет ли перезапуск Nginx?

Только если проблема действительно связана с Nginx. Если остановился PHP-FPM, Node.js, Python-приложение или другой upstream, перезапуск одного Nginx причину не устранит.

Нужно ли увеличивать proxy_read_timeout?

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

Где искать причину ошибки в первую очередь?

Начните с error.log Nginx, затем определите адрес upstream и проверьте сам backend. Сообщения Connection refused, upstream timed out, No such file or directory и Permission denied позволяют быстро определить направление дальнейшей диагностики.

Заключение

При ошибке 502 или 504 в Nginx главное — определить, на каком участке цепочки перестал нормально обрабатываться запрос. Начните с error.log, найдите используемый upstream, проверьте процесс, порт или Unix-сокет и попробуйте обратиться к приложению напрямую.

Если upstream недоступен, увеличение тайм-аутов не поможет. Если приложение отвечает, но делает это слишком медленно, сначала ищите причину задержки и только после этого меняйте настройки ожидания Nginx. Такой порядок позволяет устранить источник проблемы, а не просто скрыть её на некоторое время.

Официальная справка: документация ngx_http_proxy_module

Обсуждение

Комментарии

Только для участников

Обсуждение доступно после входа

Авторизуйтесь через VK ID, чтобы читать комментарии, отвечать, ставить лайки и сохранять статьи.

Войти через VK ID

Автор статьи

Кудашев Дмитрий Витальевич

IT-специалист из Ростова-на-Дону. Делюсь практическим опытом, объясняю технологии понятным языком

Об авторе →