Ошибки 404 и 502 в Nginx: что ломают новички

404 и 502 требуют разного ремонта, но новичок часто лечит их одинаково: меняет proxy_pass, добавляет редиректы или перезапускает Nginx без проверки конфига. За 20–30 минут вы соберёте понятную схему: отдельные страницы ошибок, проверку конфигурации, диагностику upstream и безопасную перезагрузку Nginx 1.24+.

Что подготовить до настройки

Пример рассчитан на Linux-сервер с Nginx 1.24 или новее и приложением, которое слушает 127.0.0.1:8000. Синтаксис директив в этой части конфигурации не менялся между указанными версиями, но пути к файлам и способ управления сервисом зависят от дистрибутива.

• SSH-доступ с правами на чтение конфигурации и перезагрузку Nginx;
• домен или тестовая запись, которая указывает на сервер;
• работающее приложение на порту 8000 либо понимание, что именно этот upstream нужно заменить;
• каталог сайта, например /var/www/example/public;
• две HTML-страницы: 404.html и 502.html.

Сноска. Upstream — сервер или группа серверов, куда Nginx передаёт запросы. В этой статье upstream — локальное приложение на 127.0.0.1:8000.

Какая ошибка у вас на самом деле

404 Not Found означает, что запрошенный ресурс не найден. Причина может быть в неправильном URL, удалённом файле, неверном root или маршрутизации приложения.

502 Bad Gateway означает, что Nginx выступил прокси, но не получил корректный ответ от upstream. Частые причины — приложение остановилось, слушает другой порт, отказалось принимать соединение или вернуло некорректный ответ.

404 ищет пропавший ресурс. 502 ищет сломанное соединение между Nginx и приложением. Пока вы не разделили эти две цепочки, диагностика будет случайным перебором настроек.

Настройте страницы ошибок

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

<!doctype html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <title>Страница не найдена</title>
</head>
<body>
  <h1>404</h1>
  <p>Такой страницы нет. Проверьте адрес или перейдите на главную.</p>
</body>
</html>

Сохраните этот файл как /var/www/example/public/404.html. Для 502.html используйте тот же каркас, но напишите, что сервис временно недоступен. Не выводите стек ошибки, адрес внутреннего сервиса или текст исключения приложения.

Проверьте, что пользователь, от имени которого работает Nginx, может прочитать файлы:

sudo -u www-data test -r /var/www/example/public/404.html && echo "404.html readable"
sudo -u www-data test -r /var/www/example/public/502.html && echo "502.html readable"

В системах, где Nginx работает не от www-data, подставьте фактического пользователя. Проверка успешна, если обе команды напечатали сообщение о доступности файла.

Добавьте конфигурацию Nginx

Ниже — полный серверный блок для отдельного файла в каталоге виртуальных хостов, например /etc/nginx/conf.d/example.conf. Замените example.test на свой домен, путь к каталогу — на свой, а порт — на порт приложения.

server {
    listen 80;
    server_name example.test;

    root /var/www/example/public;
    index index.html;

    error_page 404 /404.html;
    error_page 502 /502.html;

    location = /404.html {
        internal;
    }

    location = /502.html {
        internal;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_intercept_errors on;
    }
}

Директива error_page отправляет внутренний запрос к подготовленному файлу. internal не позволяет посетителю открыть служебную страницу напрямую по URL. proxy_intercept_errors on нужен, если вы хотите заменить ошибочные ответы, которые уже вернуло приложение, собственной страницей.

Проверка после сохранения:

sudo nginx -t

Ожидаемый результат — сообщения syntax is ok и test is successful. Если тест завершился ошибкой, не выполняйте reload: сначала исправьте указанную строку.

Проверьте 404 отдельно от 502

Тест страницы 404

1. Запросите заведомо отсутствующий адрес. Выполните curl -i http://example.test/path-that-does-not-exist. В ответе должен быть статус 404, а тело — содержимое вашей страницы.
2. Проверьте прямой доступ к файлу ошибки. Выполните curl -i http://example.test/404.html. Ожидаемый ответ — 404, а не 200: файл доступен только для внутренней подстановки.
3. Посмотрите журнал. Обычно запросы находятся в /var/log/nginx/access.log, ошибки — в /var/log/nginx/error.log. В access log для первого запроса должен быть код 404.

Если Nginx возвращает 404 для существующего файла, проверьте значение root, регистр букв в имени и права на все каталоги в пути. Linux различает Index.html и index.html.

Тест страницы 502

1. Проверьте приложение напрямую. Выполните curl -i http://127.0.0.1:8000/ на сервере. Нормальный ответ должен прийти от приложения, а не от Nginx.
2. Сверьте адрес upstream. Посмотрите, какой процесс слушает порт: sudo ss -ltnp | grep ':8000'. Если вывода нет, приложение не слушает этот порт.
3. Отключите приложение только на тестовом стенде или используйте остановленный тестовый сервис. После запроса к домену Nginx должен вернуть 502 и вашу страницу 502.html.
4. Проверьте журнал ошибок. Сообщение connect() failed (111: Connection refused) while connecting to upstream указывает, что по указанному адресу никто не принимает соединение. Сообщение upstream timed out означает превышение времени ожидания, а не обязательно неправильный порт.

После проверки запустите приложение снова и убедитесь, что запрос к домену возвращает его рабочий ответ. Затем примените конфигурацию без остановки сервиса:

sudo nginx -t && sudo systemctl reload nginx

Успешная проверка — команда завершилась без ошибки, а следующий запрос к сайту получает актуальный ответ. reload перечитывает конфигурацию и постепенно переводит новые соединения на неё; это не то же самое, что принудительная остановка Nginx.

Частые ошибки новичков

• 404 заменяют редиректом. Перенаправлять любой неизвестный URL на главную удобно визуально, но это скрывает ошибки ссылок и может испортить индексацию. Сохраняйте статус 404, если ресурса действительно нет.
• В root указывают каталог уровнем выше или ниже. Nginx формирует путь из root и URI. При запросе /404.html он ищет файл внутри указанного корня, поэтому путь нужно проверять на сервере, а не угадывать по структуре проекта.
• Пишут proxy_pass на публичный домен самого сайта. Это может создать цикл через DNS или внешний балансировщик. Для приложения на том же сервере используйте его фактический локальный адрес, Unix-сокет или внутреннее имя сервиса.
• Меняют порт только в Nginx. Если приложение слушает 8001, а в конфигурации указан 8000, исправление одного файла не поможет. Сверьте порт с настройками systemd, Docker Compose или менеджера процессов.
• Сразу делают restart. При синтаксической ошибке сервис может не вернуться после остановки. Безопаснее сначала выполнить nginx -t, затем systemctl reload nginx.

Если не получилось

«open() ... failed (2: No such file or directory)»

Nginx не нашёл файл страницы или другого ресурса. Сравните полный путь из журнала с фактическим расположением файла командой ls -l. Частая причина — опечатка в root или отсутствие файла после выкладки.

«permission denied»

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

«connect() failed ... Connection refused»

Соединение с upstream отклонено. Проверьте состояние приложения, адрес прослушивания и порт. Если приложение слушает только IPv6 или только Unix-сокет, адрес в proxy_pass должен соответствовать этому способу подключения.

«upstream timed out»

Приложение не ответило в отведённый срок. Сначала измерьте время ответа напрямую через curl, изучите журнал приложения и проверьте медленные запросы. Не увеличивайте таймаут вслепую: так вы можете лишь дольше удерживать соединения Nginx.

Что проверить после исправления

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

Следующим шагом настройте ротацию логов и мониторинг upstream. Если сайт работает за HTTPS, повторите проверки через реальный TLS-виртуальный хост: отдельный конфиг для порта 443 может содержать другую цепочку location и другой upstream.