Анализ логов Nginx для устранения ошибки «Connection refused»

Анализ логов ошибок Nginx для устранения проблемы «connection refused» помогает перейти от общей страницы 502 к конкретному сбою бэкенда. Фраза «connection refused» обычно означает, что Nginx попытался подключиться к upstream-адресу, но ни один процесс не принял соединение.

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

Что означает «Connection refused»

В логах Nginx часто встречается такое сообщение:

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

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

Вы можете увидеть это, когда Nginx проксирует на:

proxy_pass http://127.0.0.1:3000;

но приложение остановлено или слушает на другом порту.

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

Не воспринимайте каждую ошибку 502 как «connection refused». Сообщение о тайм-ауте указывает в другом направлении. Сообщение об отказе в доступе часто указывает на сокеты или политику безопасности. Точный текст лога имеет значение.

Поиск правильного лога ошибок Nginx

Путь к логу ошибок по умолчанию часто такой:

/var/log/nginx/error.log

Но серверные блоки могут определять пользовательские логи:

error_log /var/log/nginx/app-error.log warn;

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

Полезные команды:

tail -n 100 /var/log/nginx/error.log

и:

journalctl -u nginx -n 100

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

Хороший анализ лога включает четыре элемента информации:

• Временная метка неудачного запроса.
• Адрес и порт upstream.
• Путь запроса.
• Точная системная ошибка, например 111: Connection refused.

Для более широкого устранения неполадок Nginx см. исправление ошибок 502 Bad Gateway в Nginx.

Сопоставление записи лога с upstream

Типичная строка лога может содержать значение upstream, например:

upstream: "http://127.0.0.1:3000/api/status"

Это точно указывает, куда Nginx пытался отправить запрос. Теперь проверьте, слушает ли кто-то там:

ss -ltnp

Ищите 127.0.0.1:3000, 0.0.0.0:3000 или ожидаемый адрес. Если порт отсутствует, приложение не слушает там, где ожидает Nginx.

Проверьте upstream напрямую:

curl -i http://127.0.0.1:3000/api/status

Если это не удается с «connection refused», вы подтвердили проблему без участия Nginx.

Если приложение работает в Docker, будьте осторожны с 127.0.0.1. С хоста это означает хост. Изнутри контейнера Nginx это означает сам контейнер Nginx. В настройке Compose Nginx обычно должен проксировать на имя сервиса, например:

proxy_pass http://app:3000;

при условии, что оба контейнера находятся в одной сети Docker.

Для Unix-сокетов лог может указывать на путь вместо порта:

upstream: "http://unix:/run/app/app.sock:/"

В этом случае проверьте, существует ли сокет и может ли пользователь рабочего процесса Nginx получить к нему доступ.

Частые причины и исправления

Наиболее частая причина — остановленный бэкенд-сервис. Проверьте его с помощью:

systemctl status your-app

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

Другая частая причина — несоответствие портов. Например, приложение перешло с порта 3000 на 8080, но Nginx все еще проксирует на 3000. Исправьте цель upstream в Nginx или восстановите ожидаемый порт приложения.

Третья причина — привязка к неправильному интерфейсу. Приложение, слушающее только на 127.0.0.1, доступно локальному Nginx на том же хосте. Но если Nginx работает в другом контейнере или на другом сервере, оно не будет доступно через этот loopback-адрес. В таких настройках приложению может потребоваться привязка к 0.0.0.0 внутри частной сети.

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

Наконец, время развертывания может вызвать кратковременные ошибки «connection refused». Если Nginx отправляет трафик до того, как новый процесс приложения будет готов, пользователи могут видеть периодические ошибки 502. Проверка работоспособности, зонд готовности или стратегия плавного перезапуска могут это предотвратить.

Практический процесс устранения неполадок

Используйте этот порядок, когда в логе указано «connection refused»:

1. Скопируйте хост и порт upstream из лога ошибок Nginx.
2. Выполните curl к этому точному upstream с сервера Nginx.
3. Выполните ss -ltnp, чтобы подтвердить, что процесс слушает.
4. Проверьте статус бэкенд-сервиса и логи приложения.
5. Сравните значение proxy_pass в Nginx с фактическим адресом привязки приложения.
6. Перезагружайте Nginx только после того, как конфигурация верна и nginx -t проходит.

Этот процесс предотвращает распространенную ошибку: редактирование Nginx, когда приложение просто не работает. Он также предотвращает противоположную ошибку: многократный перезапуск приложения, когда Nginx указывает не туда.

Основы команд см. в командах мониторинга логов Nginx.

Когда обращаться к профессионалу

Обращайтесь за помощью, когда ошибки «connection refused» возникают только под нагрузкой, на нескольких upstream или во время последовательных развертываний. Эти случаи могут включать супервизию процессов, контейнерные сети, проверки работоспособности балансировщика нагрузки или ограничения емкости.

Также следует обратиться за помощью, если upstream является производственным платежным, аутентификационным или клиентским API-сервисом. Быстрое восстановление важно, но сохранение логов и понимание сбоя также важны.

«Connection refused» — одна из самых понятных ошибок Nginx, если внимательно ее прочитать. Найдите upstream в логе, протестируйте эту цель напрямую и исправьте сервис, порт, интерфейс или сетевой путь, который мешает Nginx подключиться. Лог уже дает вам отправную точку.