Проверить конфигурацию Nginx перед перезагрузкой можно двумя командами: nginx -t тестирует синтаксис и доступность файлов, nginx -T делает то же самое и дополнительно печатает в stdout итоговую конфигурацию со всеми подключёнными include. Первая отвечает на вопрос "конфиг валиден?", вторая показывает, что именно применится после reload.
Рабочий порядок на проде такой: сохранить текущую конфигурацию, прогнать nginx -t от правильного пользователя и с явными путями, снять nginx -T и сравнить с предыдущим снимком, разобрать сообщения [emerg] и [warn], выполнить reload, проверить статус, логи и ответы по ключевым доменам. Ниже разбираем каждый шаг с командами и типичными ошибками из вывода.
Главное ограничение запомните сразу: успешный тест подтверждает только то, что Nginx смог прочитать и разобрать конфиг. Работающий сервис зависит ещё от бэкендов, сертификатов, портов, DNS и прав пользователя, под которым крутятся worker-процессы.
Зачем проверять конфигурацию Nginx перед перезагрузкой
Nginx не применит конфигурацию, которая не прошла синтаксическую проверку: reload завершится ошибкой, а сервис продолжит работать на прежней версии конфига. Проверка занимает секунды. Разбор последствий неудачного restart на проде занимает минуты или часы, если поднимать сервис приходится вручную.
Разница между reload и restart критична. При reload (сигнал HUP) master-процесс сначала проверяет корректность синтаксиса конфигурации, затем запускает новые worker-процессы с новой конфигурацией и плавно завершает старые: они переходят в состояние "is shutting down", дорабатывают запросы и через некоторое время завершаются, после чего запросы обрабатывают только новые worker-процессы. Соединения при этом не рвутся. При restart сервис останавливается полностью, поэтому ошибка в конфиге означает простой до отката правок. Именно поэтому проверка идёт до команды перезагрузки, а не после.
Второй риск - правки, которые формально валидны, но меняют поведение: перекрытый location, забытый include, директива в чужом контексте, дубль виртуального хоста. Синтаксис чистый, тест зелёный, а после reload часть запросов уходит не туда. От этого спасает только nginx -T с последующей сверкой итоговой конфигурации.
Механику graceful shutdown и то, как reload применяет новую конфигурацию без обрыва соединений, разбираем отдельно: как работает nginx -s reload и как встроить его в CI/CD.
nginx -t: базовая проверка синтаксиса и как читать вывод
Команда не меняет состояние работающего сервиса и безопасна на проде. Запускайте её так:
sudo nginx -t sudo nginx -t; echo "exit code: $?"
Успешный вывод выглядит предсказуемо:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful
При ошибке появляется строка с уровнем журнала, текстом, файлом и номером строки:
nginx: [emerg] unknown directive "proxy_set_heder" in /etc/nginx/sites-enabled/app.conf:42 nginx: configuration file /etc/nginx/nginx.conf test failed
Формат читается так: уровень в квадратных скобках, что именно не так, файл и строка. Начинайте разбор с файла и строки, а не с текста сообщения. Exit code 0 означает успех, ненулевой код - ошибку, поэтому в скриптах и CI проверяйте именно код возврата, а не наличие слова "successful" в выводе.
Уровень [emerg] блокирует загрузку конфигурации. Уровень [warn] не мешает запуску, но сигнализирует о проблеме: конфликтующие server_name, переопределённые параметры протокола, устаревшая директива. Предупреждения стоит разбирать до reload, иначе они превращаются в источник странных ошибок в логах.
Что именно проверяет nginx -t, а что нет
Границы проверки проще держать перед глазами в виде таблицы.
| Проверяет | Не проверяет |
|---|---|
| Синтаксис директив и допустимость контекста | Доступность upstream и бэкендов |
| Число аргументов у директив | Срок действия и полноту цепочки сертификата |
| Читаемость include-файлов | Занятость портов другими процессами |
| Читаемость файлов ключей и сертификатов | Права пользователя worker на статику и логи |
| Корректность значений: числа, размеры, IP-адреса | Резолв DNS-имён в момент запроса |
| Наличие файлов путей из директив на момент теста | Поведение приложения и таймауты |
Поясним строку про сертификаты. При тесте nginx пытается открыть файлы, на которые ссылается конфигурация, а приватный ключ должен быть доступен для чтения master-процессу. То есть успешный nginx -t подтверждает читаемость ключа и сертификата, но не проверяет срок действия и полноту цепочки: в объединённом файле сертификат сервера должен идти перед промежуточными, а отправку полной цепочки проверяют отдельно утилитой openssl s_client. Набор проверок зависит от версии Nginx и собранных модулей. Список модулей и путь к конфигу по умолчанию смотрите в выводе nginx -V, а поведение конкретных директив сверяйте с документацией своей версии.
Официальное описание ключей -t, -T и -q приведено в документации Nginx: Command-line parameters. Требования к хранению ключа и порядку сертификатов в файле описаны в разделе Configuring HTTPS servers.
Как запускать nginx -t от нужного пользователя
Тест под root проходит там, где рабочий процесс потом получит permission denied: root читает всё, а worker-процессы работают под www-data, nginx или отдельным сервисным пользователем. Сначала выясните, кто именно запускает процессы:
ps -o user=,pid=,cmd= -C nginx systemctl show nginx -p User -p Group whoami
Если сервис работает под непривилегированным пользователем, проверьте его доступ к ключевым файлам явно:
sudo -u www-data test -r /etc/nginx/ssl/example.key && echo readable sudo -u www-data test -x /var/www/site && echo traversable
Запускать тест только от лица worker-пользователя тоже неверно: он не прочитает приватный ключ, который доступен лишь root, и вы получите ложную ошибку. Практика такая: тестируйте от root с явным указанием -c и -p, а права worker-пользователя проверяйте отдельными командами test -r и test -x по статике, логам и сокетам.
nginx -T: как вывести итоговую собранную конфигурацию
Ключ -T проверяет конфигурационный файл и дополнительно выводит конфигурационные файлы в стандартный вывод; опция появилась в версии 1.9.2. Перед каждым файлом идёт комментарий с его путём, поэтому видно, из какого include пришёл конкретный server или location:
# configuration file /etc/nginx/nginx.conf: # configuration file /etc/nginx/conf.d/app.conf: # configuration file /etc/nginx/sites-enabled/site.conf:
Вывод большой, поэтому сохраняйте его в файл и снимайте снимки до и после правок:
sudo nginx -T > /tmp/nginx-full-$(date +%F-%H%M).conf sudo nginx -T > /tmp/nginx-new.conf diff -u /tmp/nginx-full-2026-11-01-1200.conf /tmp/nginx-new.conf
Diff по итоговой конфигурации показывает реальные изменения, включая те, что пришли из подключённых файлов. Это ловит две частые ситуации: include не подхватился, потому что файл лежит не в sites-enabled, и правка сделана в файле, который перекрывается другим include. Флаг -q подавляет не связанные с ошибками сообщения при проверке конфигурации, это удобно в скриптах.
Как найти нужный блок в выводе nginx -T
Ищите по server_name или пути location, выводя контекст вокруг найденной строки:
sudo nginx -T | grep -n 'server_name example.com' sudo nginx -T | grep -n -B3 'location /api/' sudo nginx -T | grep -c 'location '
Если нужного server_name в выводе нет, значит файл не подключён, и никакие правки в нём не действуют. Если блок есть дважды, вы нашли источник конфликта. Алгоритм отладки маршрутизации, приоритетов location и proxy_pass разбираем в материале отладка маршрутизации Nginx: логи, проверка location и типичные ошибки.
Явное указание -c и -p: когда это обязательно
-c задаёт путь к главному конфигу, -p задаёт prefix, от которого разрешаются относительные пути внутри конфигурации. Значения по умолчанию зашиты при сборке, их видно в nginx -V:
nginx -V 2>&1 | tr ' ' '\n' | grep -E 'prefix|conf-path' sudo nginx -t -c /etc/nginx/nginx.conf -p /etc/nginx/ sudo nginx -T -c /opt/nginx/conf/nginx.conf -p /opt/nginx/
Явные пути обязательны в четырёх случаях: нестандартная установка из исходников, запуск в контейнере с другим prefix, несколько инстансов Nginx на одной машине и проверка конфига до деплоя на сервер. Без -p относительные пути вроде include conf.d/*.conf или logs/error.log разрешаются от другого каталога, и проверка покажет не тот результат, который получится после reload.
Типичные ошибки из вывода nginx -t и как их исправить
В каждом сообщении есть файл и строка: nginx: [emerg] текст in файл:строка. Начинайте с них. Сводка частых сообщений:
| Сообщение | Причина | Что делать |
|---|---|---|
| unexpected end of file | Незакрытый блок, кавычка или пропущенная точка с запятой | Проверить баланс фигурных скобок и ; в указанном файле, смотреть на 10-20 строк выше |
| unknown directive | Опечатка, модуль не собран или не загружен, директива вне своего контекста | Сверить имя директивы с документацией версии, проверить nginx -V и контекст |
| invalid number of arguments | Лишний или пропущенный аргумент, кавычки склеили или разорвали строку | Сверить сигнатуру директивы и расставить кавычки |
| duplicate location | Два одинаковых location в одном server, двойной include | Найти дубль через nginx -T, убрать повтор |
unexpected end of file
Сообщение выглядит так: nginx: [emerg] unexpected end of file, expecting "}" in /etc/nginx/conf.d/app.conf:87. Nginx дошёл до конца файла и не нашёл закрывающую скобку. Строка 87 часто оказывается последней строкой файла, а реальная ошибка расположена выше.
Что проверить в указанном файле: баланс фигурных скобок, незакрытую двойную кавычку, пропущенную точку с запятой после директивы. Грубая оценка баланса:
grep -c '{' /etc/nginx/conf.d/app.conf
grep -c '}' /etc/nginx/conf.d/app.conf
Счёт приблизительный: строки с регулярными выражениями искажают результат. Незакрытая кавычка опаснее всего, потому что съедает остаток файла, и Nginx сообщает о конце файла вместо строки с опечаткой.
unknown directive
Пример: nginx: [emerg] unknown directive "proxy_set_heder" in /etc/nginx/sites-enabled/app.conf:42. Причина первая и самая частая - опечатка в имени директивы. Вторая - директива принадлежит модулю, который не собран в вашем бинарнике. Третья - директива стоит в неподходящем контексте, например используется там, где её не бывает.
nginx -V 2>&1 | tr ' ' '\n' | grep with- nginx -V 2>&1 | grep -o 'with-[a-z0-9_]*module' | sort -u
Список с with- показывает, какие модули включены при сборке. Если нужного модуля нет, директива не появится ни при какой правке текста. Отдельный случай - конфиг, перенесённый со старого сервера: в nginx 1.25.1 параметр http2 в директиве listen объявлен устаревшим, вместо него следует использовать отдельную директиву http2. Устаревание не ломает работу сразу: nginx выдаёт предупреждение вида "the listen ... http2 directive is deprecated, use the http2 directive instead", и конфиг продолжает работать. Сверяйте такие места с документацией именно своей версии.
invalid number of arguments
Пример: nginx: [emerg] invalid number of arguments in "root" directive in /etc/nginx/conf.d/site.conf:12. Директива получила не то количество аргументов, которое ожидает. Типичные причины: путь с пробелом без кавычек превратился в два аргумента, лишний параметр после значения, пропущенный обязательный аргумент.
root /var/www/my site; # ошибка: два аргумента root "/var/www/my site"; # корректно
Проверяйте сигнатуру директивы по документации версии и следите за кавычками: они спасают пути с пробелами, но могут склеить то, что должно остаться раздельным списком.
duplicate location
Пример: nginx: [emerg] duplicate location "/api/" in /etc/nginx/sites-enabled/api.conf:8. В одном server-блоке оказались два location с одинаковым префиксом. Классика: файл сайта лежит в sites-available, на него сделан симлинк в sites-enabled, и при этом тот же файл дополнительно подключён через include в conf.d.
sudo nginx -T | grep -n 'location "/api/"' ls -l /etc/nginx/sites-enabled/ readlink -f /etc/nginx/sites-enabled/*.conf
Первая команда покажет все вхождения и файлы, откуда они пришли. Дальше ищите двойное подключение: симлинк и оригинал, два include одного каталога, копию конфига с другим именем. Уберите повтор и повторите тест.
Проблемы с правами и отсутствующими include-файлами
Часть ошибок не связана с синтаксисом. Nginx не может открыть файл и сообщает об этом отдельным кодом в скобках.
nginx: [emerg] open() "/etc/nginx/ssl/example.key" failed (13: Permission denied) nginx: [emerg] open() "/etc/nginx/sites-enabled/old-site.conf" failed (2: No such file or directory)
Код 13 означает запрет доступа, код 2 - отсутствие файла. Для прав используйте namei, она показывает права на каждом уровне пути, а не только на конечном файле:
namei -l /etc/nginx/ssl/example.key ls -l /etc/nginx/ssl/example.key
Рабочая схема: приватный ключ 600 и владелец root:root, каталоги 755 с битом x для всех, конфиги 644. Если на пути к файлу есть каталог без права выполнения, Nginx не откроет файл даже с правами 777 на сам файл. В дистрибутивах с SELinux проверьте контекст и политику:
getenforce ls -Z /etc/nginx/ssl/example.key restorecon -Rv /etc/nginx
Для AppArmor смотрите aa-status и профили в /etc/apparmor.d/. Часть таких ошибок проявляется уже после reload, в виде 403 на статике: разбор этих сценариев есть в материале раздача статики через Nginx: права, симлинки, SELinux и коды 403/404.
Отсутствующий include выглядит как код 2 при открытии файла. Самая частая причина - висячий симлинк в sites-enabled после удаления файла сайта. Проверяйте так:
ls -l /etc/nginx/sites-enabled/ readlink -f /etc/nginx/sites-enabled/old-site.conf find /etc/nginx -xtype l
find с ключом -xtype l покажет все битые симлинки. Отдельно стоит помнить, что include с маской (например, conf.d/*.conf) и include с прямым указанием файла - не одно и то же: при маске в выборку попадают только реально существующие совпадения, а прямой путь к несуществующему файлу даёт ошибку открытия. Поведение с симлинками и масками зависит от версии, поэтому проверяйте на своей сборке. Логика доступа к файлам и каталогам подробно разобрана в статье права доступа к данным в Nginx: аутентификация и контроль.
Почему успешный nginx -t не гарантирует корректную работу сервиса
Тест проверяет текст конфигурации и доступность файлов. Сервис же зависит от сети, процессов и окружения. Что остаётся вне проверки:
- доступность upstream: бэкенд может лежать, и вы получите 502 при полностью валидном конфиге;
- срок действия и цепочка сертификата: просроченный сертификат загружается без ошибок;
- занятость портов: конфликт с другим процессом выяснится только при reload или старте;
- права worker-пользователя на статику, логи и unix-сокеты;
- DNS-имена upstream, которые резолвятся при загрузке конфигурации;
- поведение приложения, таймауты и лимиты соединений.
Что проверить после успешного nginx -t
- Итоговая конфигурация. sudo nginx -T > /tmp/nginx-new.conf и diff с прошлым снимком. Показывает, что реально изменилось.
- Reload вместо restart. sudo systemctl reload nginx. Соединения не рвутся, старые worker-процессы дорабатывают запросы.
- Статус сервиса. systemctl status nginx --no-pager и journalctl -u nginx -n 50 --no-pager. Ловит неудачный reload и падение worker-процессов.
- Логи ошибок. tail -n 50 /var/log/nginx/error.log. Смотрите [emerg] и [alert] за последние минуты.
- Ответы по доменам. curl -I https://example.com и curl -s -o /dev/null -w '%{http_code}\n' https://example.com. Проверяет коды 200/301/403/502 по факту.
- Сертификат. openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject. Показывает даты действия и CN.
- Бэкенд. curl -I http://127.0.0.1:8080/health напрямую, минуя Nginx. Отделяет проблему приложения от проблемы проксирования.
Пункты 2 и 3 связаны с механикой применения конфигурации, детали и сценарий быстрого отката описаны в руководстве по безопасному обновлению конфигурации Nginx через reload. Как именно master-процесс обрабатывает сигнал HUP и завершает старые worker-процессы, описано в документации Controlling nginx.
Чек-лист проверки конфигурации Nginx перед перезагрузкой на проде
Список рассчитан на применение прямо сейчас, по шагам, без пропусков.
- Бэкап конфигурации. tar -czf /root/nginx-$(date +%F-%H%M).tar.gz /etc/nginx. Без копии откат превращается в ручное восстановление по памяти. Готовые сценарии бэкапа и восстановления за 5 минут есть в чек-листе по бэкапу и восстановлению Nginx.
- Пользователь и контекст. ps -o user=,pid=,cmd= -C nginx и systemctl show nginx -p User -p Group. Определяет, под кем работают worker-процессы и чьи права проверять.
- Тест с явными путями. sudo nginx -t -c /etc/nginx/nginx.conf -p /etc/nginx/; echo $?. Ноль в конце обязателен, иначе дальше идти нельзя.
- Снимок итоговой конфигурации. sudo nginx -T > /tmp/nginx-new.conf плюс diff с предыдущим снимком. Показывает, что именно применится после reload.
- Include и дубли. grep по server_name и location в выводе -T, ls -l /etc/nginx/sites-enabled/, find /etc/nginx -xtype l. Ловит неподключённые файлы, висячие симлинки и двойные location.
- Права на ключи, конфиги и статику. namei -l по ключевым путям, sudo -u www-data test -r по файлам статики. Закрывает ошибки, которые тест под root не видит.
- Reload вместо restart. sudo systemctl reload nginx. Приложение не простаивает, соединения не обрываются.
- Статус и логи. systemctl status nginx, journalctl -u nginx -n 50, tail -n 50 /var/log/nginx/error.log. Подтверждает, что новые worker-процессы поднялись без ошибок.
- Проверка ответов. curl -I по ключевым доменам и эндпоинтам, openssl s_client по сертификату, curl к upstream напрямую. Подтверждает, что сервис отвечает нужными кодами и отдаёт действующий сертификат.
- План отката. знать путь к архиву, команду восстановления и что откатывать: распаковать /etc/nginx из архива, выполнить nginx -t, затем reload. План фиксируется до начала работ, а не в момент инцидента.
Прогоняйте этот список перед каждым изменением в /etc/nginx, включая правку одной директивы. Проверка занимает пару минут, а откат без бэкапа и без снимка nginx -T обычно растягивается на весь вечер.