Nginx debug log на VDS: включаем отладку только для нужного IP

Инструкции
21 июл, 2026
Время на чтение: ~21 мин
Автор: AI (GPT 5)

Искусственный интеллект

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

Обычный error_log в Nginx хорошо показывает явные ошибки: файл не найден, upstream не отвечает, не хватает прав, истёк таймаут. Но иногда этого мало: запрос «зависает» только у одного пользователя, редирект срабатывает не так, как ожидалось, location выбирается странно, а в обычных логах почти тишина.

В таких случаях помогает nginx debug log — подробный отладочный журнал, где Nginx пишет внутренние этапы обработки соединения и запроса. На рабочем VDS включать его для всего трафика опасно: за несколько минут можно получить гигабайты логов и лишнюю нагрузку на диск.

Правильный практический подход — включать debug-лог только для нужного IP через директиву debug_connection, быстро воспроизводить проблему, забирать фрагмент журнала и сразу возвращать обычный режим логирования.

Debug-лог — инструмент точечной диагностики, а не постоянного мониторинга. Держите его включённым ровно столько, сколько нужно для воспроизведения проблемы.

Когда nginx debug log действительно нужен

У Nginx есть уровни журналирования: error, warn, notice, info, debug и другие. На production-серверах обычно используют warn или error, чтобы лог не разрастался и содержал только важные события. Уровень debug принципиально другой: он пишет много внутренних деталей обработки соединения.

Debug-лог полезен, когда нужно понять:

какой server или location выбрал Nginx для конкретного запроса;
как сработали rewrite, try_files, map или внутренний редирект;
на каком этапе появляется редкая ошибка 400, 403, 404, 499, 502 или 504;
как Nginx подключается к upstream, отправляет заголовки и читает ответ;
не мешают ли keepalive, HTTP/2, буферы или чтение тела запроса;
почему проблема проявляется только у одного клиента или тестовой машины.

Важно понимать границу применимости. Debug-лог не заменяет access-лог, трассировку приложения, профилировщик PHP/Node.js/Python или анализ SQL-запросов. Он отвечает на вопрос «что делал Nginx внутри своей обработки запроса». Если ошибка живёт в бизнес-логике приложения, Nginx покажет только внешние признаки: передал запрос upstream, дождался ответа, получил таймаут или разрыв соединения.

Главное условие: Nginx должен быть собран с --with-debug

Директива error_log debug сама по себе ещё не гарантирует подробный вывод. Nginx должен быть собран с опцией --with-debug. Если этой опции нет, конфигурация может пройти проверку, но настоящих debug-сообщений вы не увидите.

Проверьте текущую сборку:

nginx -V 2>&1 | grep -- '--with-debug'

Если команда вывела строку с --with-debug, можно переходить к настройке. Если вывода нет, посмотрите полный набор параметров:

nginx -V 2>&1

На разных дистрибутивах ситуация отличается. Где-то поддержка debug уже включена в обычный пакет, где-то есть отдельный бинарник nginx-debug, а иногда потребуется пакет из другого репозитория или отдельная сборка.

command -v nginx-debug

Если nginx-debug найден, не запускайте его вручную поверх работающего сервиса без проверки путей. На production-сервере важно сохранить те же конфиги, модули, PID-файл и systemd-юнит, иначе можно диагностировать не тот экземпляр Nginx.

Схема точечного включения debug_connection в Nginx

Debian и Ubuntu

Сначала проверьте уже установленный Nginx. Часто этого достаточно:

nginx -V 2>&1 | grep -- '--with-debug'

Если поддержки нет, обновите индекс пакетов и посмотрите доступные варианты:

sudo apt update
apt-cache search nginx | grep -Ei 'debug|nginx'

После установки или замены пакета обязательно снова проверьте nginx -V. Не ориентируйтесь только на название пакета: состав сборки может отличаться между версиями дистрибутива и репозиториями.

AlmaLinux, Rocky Linux, CentOS Stream, Oracle Linux и Fedora

В RHEL-based дистрибутивах и Fedora логика та же: сначала смотрим параметры текущей сборки, затем ищем доступный debug-вариант в подключённых репозиториях.

nginx -V 2>&1 | grep -- '--with-debug'
dnf search nginx | grep -Ei 'debug|nginx'

Если Nginx установлен из стороннего репозитория, не смешивайте пакеты из разных источников без необходимости. Разные сборки могут отличаться набором динамических модулей, путями к ним и настройками systemd. Для рабочего VDS безопаснее сначала проверить пакет на staging-сервере или хотя бы сохранить текущую конфигурацию и список установленных пакетов.

Минимальная безопасная схема: error_log debug плюс debug_connection

Для точечной отладки нужны две части. Первая — включить уровень debug в error_log. Вторая — ограничить отладку директивой debug_connection. Она указывается в контексте events и принимает IP-адрес или подсеть.

Пример для одного IPv4-адреса администратора:

error_log /var/log/nginx/debug.log debug;

events {
    worker_connections 1024;
    debug_connection 203.0.113.10;
}

Если у вас уже есть блок events, не создавайте второй. Добавьте debug_connection в существующий блок. В итоговой конфигурации Nginx должен быть один основной блок events.

Можно указать несколько адресов, например IPv4 и IPv6:

error_log /var/log/nginx/debug.log debug;

events {
    worker_connections 1024;
    debug_connection 203.0.113.10;
    debug_connection 2001:db8:1234::10;
}

Можно указать подсеть, если тестовые клиенты выходят через небольшой офисный диапазон:

error_log /var/log/nginx/debug.log debug;

events {
    worker_connections 1024;
    debug_connection 203.0.113.0/24;
}

С подсетями будьте осторожны. Чем шире диапазон, тем больше соединений попадёт в отладку. На публичном VDS не стоит включать debug для больших сетей «на всякий случай», особенно если сайт посещаемый или получает много фоновых запросов от ботов.

Облачный VDS-сервер

Виртуальные серверы с быстрым запуском и гибкой конфигурацией от 390₽ / мес

Доступные локации

Россия

Нидерланды

Смотреть тарифы

Где размещать debug-лог

Технически error_log можно задавать в разных контекстах: глобально, внутри http, server, location. Для диагностики через debug_connection часто удобнее задать отдельный файл на верхнем уровне конфигурации, чтобы не смешивать отладку с обычным журналом ошибок.

error_log /var/log/nginx/debug.log debug;

Так проще запустить tail, передать файл коллеге, вырезать нужный временной диапазон и потом удалить лог. Если писать debug в основной /var/log/nginx/error.log, он быстро станет шумным, а ротация может сработать в неудобный момент.

Перед включением проверьте каталог и права. В Debian/Ubuntu пользователь Nginx часто называется www-data:

sudo install -d -o root -g adm -m 0750 /var/log/nginx
sudo touch /var/log/nginx/debug.log
sudo chown www-data:adm /var/log/nginx/debug.log

В RHEL-based системах чаще используется пользователь nginx:

sudo install -d -o root -g nginx -m 0750 /var/log/nginx
sudo touch /var/log/nginx/debug.log
sudo chown nginx:nginx /var/log/nginx/debug.log

Если включён SELinux и файл создавался нестандартным способом, проверьте контекст:

sudo restorecon -Rv /var/log/nginx

Если не уверены, от какого пользователя работают процессы, посмотрите их напрямую:

ps -o user,group,comm -C nginx

Пошаговая инструкция: включаем debug только для своего IP

Шаг 1. Узнайте внешний IP тестового клиента

Нужен именно тот IP, с которого TCP-соединение приходит на Nginx. Если вы подключены через корпоративный NAT, VPN или мобильного оператора, адрес может меняться. Надёжный способ — выполнить тестовый запрос к сайту и посмотреть последние строки access-лога.

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

Если у виртуального хоста отдельный access-лог, смотрите его. Сверяйте не только IP, но и время, host, URL и user agent, чтобы не перепутать себя с другим клиентом.

Если сайт стоит за reverse proxy, балансировщиком или CDN, в соединении к вашему Nginx клиентом будет IP прокси, а не реальный пользовательский адрес. Директивы real IP меняют переменные вроде $remote_addr для логов и приложения, но debug_connection фильтрует адрес сокета. В таком случае отладку придётся включать по адресу прокси, использовать отдельный тестовый backend или временный обходной домен.

Шаг 2. Сохраните текущую конфигурацию

Перед изменениями полезно сделать быстрый снимок основного файла и итоговой конфигурации со всеми include-файлами:

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.before-debug
sudo nginx -T > /tmp/nginx-full-config-before-debug.txt

Команда nginx -T помогает увидеть, где уже задан error_log, какие виртуальные хосты подключены и нет ли неожиданного переопределения в других файлах.

Шаг 3. Добавьте error_log debug и debug_connection

Откройте основной конфиг:

sudo editor /etc/nginx/nginx.conf

Добавьте или измените error_log на верхнем уровне:

error_log /var/log/nginx/debug.log debug;

В существующий блок events добавьте ваш IP:

events {
    worker_connections 1024;
    debug_connection 203.0.113.10;
}

Если в блоке уже есть другие настройки, оставьте их и добавьте только строку debug_connection. Не удаляйте worker_connections, use и другие параметры, если они были настроены ранее.

Шаг 4. Проверьте конфигурацию и выполните graceful reload

Сначала проверьте синтаксис:

sudo nginx -t

Если всё хорошо, примените конфигурацию без остановки сервиса:

sudo systemctl reload nginx

Проверьте статус:

systemctl status nginx --no-pager

Если reload не удался, не продолжайте диагностику. Сначала исправьте ошибку, которую показал nginx -t или systemd. Частые причины — опечатка в контексте директивы, неверный путь к файлу лога или второй блок events.

Шаг 5. Воспроизведите проблему и смотрите лог

Откройте отдельную SSH-сессию и следите за debug-файлом:

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

Затем с тестового IP выполните запрос, который воспроизводит проблему. Удобно добавить уникальный маркер, чтобы быстро найти нужный фрагмент:

curl -I 'https://example.test/problem-url?debug_marker=fastfox_test_001'

В реальной команде используйте свой домен. Если диагностируете POST-запрос, загрузку файла или API-метод, воспроизводите минимальный безопасный сценарий без персональных данных.

Терминал с фрагментом debug-лога Nginx

Как понять, что debug_connection работает

После reload файл debug.log не обязан сразу заполниться. Debug-сообщения пишутся только для соединений, которые соответствуют debug_connection. Если файл пустой, проверьте базовые условия.

текущий внешний IP совпадает с указанным в debug_connection;
вы подключаетесь именно к этому Nginx, а не к другому frontend-серверу;
Nginx собран с --with-debug;
после изменения был выполнен systemctl reload nginx;
директива добавлена в блок events;
файл /var/log/nginx/debug.log доступен для записи;
тестовый запрос попадает на тот же узел, где включена отладка.

Типичные строки debug-лога выглядят примерно так:

2026/01/15 12:10:11 [debug] 12345#12345: *701 accept: 203.0.113.10:53422 fd:15
2026/01/15 12:10:11 [debug] 12345#12345: *701 http process request line
2026/01/15 12:10:11 [debug] 12345#12345: *701 http request line: "GET /problem-url?debug_marker=fastfox_test_001 HTTP/2.0"
2026/01/15 12:10:11 [debug] 12345#12345: *701 test location: "/"
2026/01/15 12:10:11 [debug] 12345#12345: *701 using configuration "/"

Число после звёздочки, например *701, — идентификатор соединения. По нему удобно фильтровать один поток событий:

sudo grep ' \*701 ' /var/log/nginx/debug.log

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

Что искать в debug-логе

Debug-лог подробный, поэтому двигайтесь от симптома. Если проблема с выбором location, ищите строки test location, using configuration, internal redirect. Если проблема с upstream, ищите connect to upstream, http upstream, upstream timed out, recv, send.

Для диагностики try_files полезны строки, где Nginx проверяет файлы на диске. Для FastCGI и PHP-FPM смотрите, какой socket или TCP-адрес используется, какие параметры передаются и на каком этапе появляется таймаут. Для proxy_pass обращайте внимание на итоговый URI, особенно если в конфигурации есть нюансы со слешем в конце proxy_pass и location.

Хороший практический приём — параллельно держать обычный access-лог с расширенным форматом, где есть request time, upstream time и request id. Debug-лог объясняет внутренние шаги, а access-лог даёт компактную сводку по статусу и времени.

Как не дать debug.log занять весь диск

Даже при debug_connection лог может расти быстро, если тестовый клиент открывает много соединений, браузер загружает десятки ресурсов, а сайт использует HTTP/2. На небольшом VDS это особенно чувствительно: переполненный диск может ударить по Nginx, базе данных и systemd-журналу.

Перед включением проверьте свободное место:

df -h /var/log
sudo du -sh /var/log/nginx

Во время диагностики можно наблюдать размер файла:

watch -n 2 'ls -lh /var/log/nginx/debug.log'

На production-сервере обычно достаточно 1–5 минут debug-лога. Если за это время проблема не воспроизвелась, лучше отключить отладку, уточнить сценарий и включить снова.

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

/var/log/nginx/debug.log {
    size 100M
    rotate 3
    missingok
    notifempty
    compress
    create 0640 nginx nginx
    sharedscripts
    postrotate
        systemctl reload nginx >/dev/null 2>&1 || true
    endscript
}

В Debian/Ubuntu для строки create часто нужно заменить пользователя и группу на www-data adm или на значения, принятые в вашей системе. После изменения logrotate-конфига проверьте его в debug-режиме:

sudo logrotate -d /etc/logrotate.d/nginx-debug

Как отключить debug-лог и вернуть обычный режим

После воспроизведения проблемы не оставляйте error_log debug в конфигурации. Верните прежний уровень, например warn или error, и удалите или закомментируйте debug_connection.

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

events {
    worker_connections 1024;
}

Затем проверьте конфигурацию и перезагрузите Nginx:

sudo nginx -t
sudo systemctl reload nginx

После отключения можно сжать или очистить временный debug-файл:

sudo gzip -9 /var/log/nginx/debug.log
sudo install -o root -g root -m 0600 /dev/null /var/log/nginx/debug.log

Если лог нужен для дальнейшего анализа, лучше вырезать только релевантный фрагмент по времени или connection id, а не хранить весь файл. Так меньше риск случайно передать лишние cookie, токены, приватные URL, внутренние IP и домены.

Частые ошибки при настройке debug_connection

Директива стоит не в том контексте

debug_connection работает в контексте events. Если поставить её внутрь http, server или location, Nginx выдаст ошибку конфигурации.

Перед Nginx стоит прокси

В access-логе вы можете видеть реальный IP благодаря realip-модулю, но debug_connection фильтрует адрес соединения на уровне сокета. Если соединение пришло от прокси, фильтр должен соответствовать адресу прокси.

Включили debug для всех

Если прописать только error_log debug и не использовать debug_connection, отладочные сообщения могут пойти для всего трафика. На тестовом стенде это допустимо, на боевом VDS — почти всегда плохая идея.

Забыли про IPv6

Если у домена есть AAAA-запись, браузер администратора может подключаться по IPv6, а вы указали только IPv4. Проверьте access-лог и добавьте IPv6-адрес отдельной строкой debug_connection.

Смотрите не тот файл

В конфигурации может быть несколько error_log: глобальный, внутри http, в конкретном server. Команда nginx -T помогает увидеть итоговую картину.

Безопасность и приватность debug-логов

Debug-лог может содержать больше информации, чем обычный error-лог: URI, заголовки, сведения о внутренней маршрутизации, upstream-адреса, иногда чувствительные параметры. Не публикуйте полный debug-файл в открытых местах и не прикладывайте его целиком к задачам без предварительной очистки.

включайте debug только на короткое время;
ограничивайте отладку конкретным IP через debug_connection;
не воспроизводите проблему на реальных пользовательских данных, если можно сделать тестовый запрос;
перед передачей лога удаляйте cookie, токены, приватные URL и внутренние адреса, если они не нужны для анализа;
после диагностики удаляйте или архивируйте файл с ограниченными правами;
учитывайте внутренние политики хранения логов и требования к персональным данным.

Особенно внимательно относитесь к URL с query string. Многие приложения по ошибке передают в параметрах одноразовые токены, email или идентификаторы восстановления доступа. Debug-лог сохранит то, что увидел Nginx.

Короткий runbook для боевого VDS

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

nginx -V 2>&1 | grep -- '--with-debug'

Сохраняем текущую конфигурацию:

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.before-debug
sudo nginx -T > /tmp/nginx-full-config-before-debug.txt

Добавляем в /etc/nginx/nginx.conf отдельный debug-лог и IP администратора:

error_log /var/log/nginx/debug.log debug;

events {
    worker_connections 1024;
    debug_connection 203.0.113.10;
}

Применяем:

sudo nginx -t
sudo systemctl reload nginx

Воспроизводим проблему и смотрим лог:

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

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

sudo nginx -t
sudo systemctl reload nginx

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

Итоги

nginx debug log — мощный инструмент, но пользоваться им нужно точечно. Рабочая схема для VDS выглядит так: проверить --with-debug, задать отдельный error_log debug, ограничить отладку через debug_connection на конкретный IP, быстро воспроизвести проблему, забрать нужный фрагмент и отключить debug.

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

Поделиться статьей