Обработка ошибок 404 и 502 в Nginx: что знать заранее

За 10–20 минут вы сможете настроить отдельные страницы для 404 и 502 в Nginx 1.26.x, проверить их через браузер и команду curl, а затем отличить ошибку маршрутизации от сбоя приложения. Главное заранее разделить два случая: 404 возникает, когда ресурс не найден, а 502 — когда прокси не получил нормальный ответ от upstream-сервера.

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

Инструкция рассчитана на Nginx 1.26.x и конфигурацию, где Nginx принимает запросы на 80-м порту, а приложение работает на 127.0.0.1:8000. Синтаксис подходит для большинства актуальных выпусков Nginx, но перед изменением боевого сервера проверьте версию командой nginx -v.

• SSH-доступ к серверу и права на чтение конфигурации, обычно в /etc/nginx;
• домен или тестовый адрес, который уже направлен на сервер;
• запущенный Nginx и приложение на порту 8000, если вы проверяете 502 от reverse proxy;
• каталог сайта, например /var/www/site;
• резервная копия текущей конфигурации перед изменениями.

Создайте два обычных HTML-файла: /var/www/site/errors/404.html и /var/www/site/errors/502.html. В них достаточно короткого сообщения и ссылки на главную страницу. Не размещайте на странице 502 подробности upstream, пути к файлам и текст из журнала: это диагностическая информация для администратора, а не для посетителя.

Сноска. Upstream — сервер или приложение, которому Nginx передаёт запрос. В этой схеме им выступает процесс на 127.0.0.1:8000, например приложение на Python, PHP или Node.js.

Настройте страницы 404 и 502

Добавьте серверный блок в файл, который подключается из секции http, например /etc/nginx/conf.d/site-errors.conf. Если у вас уже есть такой server, перенесите директивы в него, а не создавайте второй блок с тем же доменом.

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/site;

    location / {
        try_files $uri $uri/ @application;
    }

    location @application {
        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 404 /errors/404.html;
    error_page 502 /errors/502.html;

    location = /errors/404.html {
        internal;
    }

    location = /errors/502.html {
        internal;
    }
}

Замените example.com на свой домен. Директива try_files сначала ищет файл или каталог на диске, а если ничего не находит, передаёт запрос приложению. proxy_intercept_errors on позволяет Nginx заменить некоторые ответы upstream своей страницей ошибки, в том числе настроенной через error_page.

Если приложение должно получать все запросы самостоятельно, блок location / можно построить иначе. Но тогда 404, сформированный самим приложением, не всегда будет заменён страницей Nginx: поведение зависит от маршрутизации и от того, включено ли перехватывание ответов upstream.

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

1. Проверьте синтаксис. Выполните sudo nginx -t. Успешная проверка заканчивается сообщениями syntax is ok и test is successful. Если видите emerg, Nginx не применит конфигурацию, пока ошибка не будет исправлена.
2. Перечитайте конфигурацию. Выполните sudo systemctl reload nginx. При успешной операции команда обычно не выводит текста и не останавливает текущие соединения.
3. Проверьте 404. Откройте несуществующий адрес, например http://example.com/page-that-does-not-exist, или выполните curl -i http://example.com/page-that-does-not-exist. В заголовках должен остаться статус 404, а в теле — содержимое вашей страницы.
4. Проверьте 502. Временно остановите приложение на порту 8000 в тестовой среде и выполните curl -i http://example.com/. Должен вернуться статус 502 и содержимое 502.html. После проверки запустите приложение снова.
5. Сверьте журналы. Посмотрите /var/log/nginx/error.log и журнал сервиса приложения. В access log должен быть зафиксирован код ответа, а в error log — причина, если Nginx не смог подключиться к upstream.

Страница ошибки должна объяснять посетителю, что делать дальше. Причину сбоя ищут не в ней, а в access log, error log и журнале приложения.

Почему появляется 404

404 не всегда означает проблему Nginx. Сервер может корректно вернуть этот статус, потому что файла действительно нет, приложение не знает такой маршрут или запрос попал не в тот server-блок.

Файл есть, но Nginx его не находит

Проверьте директиву root, регистр букв в имени файла и фактические права доступа. Путь /var/www/site/Images/logo.png не равен /var/www/site/images/logo.png в Linux. Если запрос должен обрабатываться приложением, проверьте, не перехватывает ли его слишком узкий или неправильный location.

404 возвращает приложение

Посмотрите заголовки и тело ответа. Nginx может лишь передать статус приложения, не показывая свою страницу. Для единообразного оформления нужен включённый proxy_intercept_errors и корректная цепочка error_page. Не включайте перехватывание вслепую: приложение может использовать собственные полезные страницы и специальные ответы API.

Почему появляется 502

502 Bad Gateway означает, что Nginx выступал посредником, но не получил от upstream корректный ответ. Это не то же самое, что 504 Gateway Timeout: 502 обычно связан с отказом подключения, закрытием соединения или некорректными заголовками, а 504 — с превышением времени ожидания.

• Приложение остановлено. В журнале Nginx часто появляется connect() failed (111: Connection refused) while connecting to upstream.
• Неверный адрес или порт. Приложение слушает, например, 127.0.0.1:3000, а в proxy_pass указан 127.0.0.1:8000.
• Приложение завершило соединение. Сообщение upstream prematurely closed connection указывает, что upstream закрыл соединение до полного ответа. Причину ищите в журнале самого приложения.
• Ошибка Unix-сокета. Если используется сокет, проверьте его путь и права пользователя, под которым работает Nginx.
• Неподходящий ответ upstream. Сломанные или слишком большие заголовки, ошибка протокола и аварийное завершение процесса также могут привести к 502.

Проверяйте upstream отдельно от Nginx. Для TCP-порта подойдёт команда curl -i http://127.0.0.1:8000/ на самом сервере. Если она не получает ответ, настройка страницы ошибки исправна, но первопричина находится в приложении, его процессе или сетевой конфигурации.

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

«nginx: [emerg] directive is not allowed here»

Директива помещена не в тот контекст. server должен находиться внутри http, а location — внутри server. Проверьте полный вывод команды sudo nginx -T, а не только файл, который редактировали.

«duplicate default server» или открывается не тот сайт

Запрос попал в другой виртуальный сервер. Проверьте server_name, DNS-запись и порядок подключаемых конфигураций. Для диагностики используйте curl -i -H 'Host: example.com' http://127.0.0.1/ и убедитесь, что заголовок Host соответствует нужному домену.

Вместо своей страницы снова стандартная страница Nginx

Файл лежит не под тем root, у процесса Nginx нет прав на чтение каталога или запрос обслуживает другой server. Проверьте путь командой ls -l /var/www/site/errors/404.html и посмотрите access log.

502 остаётся после запуска приложения

Проверьте, на каком адресе и порту процесс слушает: ss -ltnp. Затем выполните запрос к upstream напрямую и сопоставьте адрес с proxy_pass. Если прямой запрос успешен, изучите error log Nginx и заголовки, которые приложение возвращает через прокси.

Что проверить дальше

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

Инвалидация кеша, балансировка нескольких upstream и настройка таймаутов — отдельные темы. Сначала убедитесь, что базовый маршрут, журналирование и страницы ошибок работают предсказуемо на одной конфигурации.