Zero-downtime reload Nginx: какой способ выбрать

Изменение конфигурации Nginx не требует остановки веб-сервера: мастер-процесс может проверить новый файл, запустить новые worker-процессы и дождаться завершения старых. Но команды systemctl restart nginx, systemctl reload nginx и nginx -s reload делают разные вещи, а ошибка в конфиге меняет результат от бесшовного обновления до недоступного сайта.

Что именно происходит при reload

Ниже речь о Nginx Open Source 1.25.x и типичной установке под systemd. При reload мастер-процесс получает сигнал HUP. Сначала Nginx проверяет конфигурацию. Если проверка успешна, мастер открывает новые файлы логов и слушающие сокеты, запускает новый набор worker-процессов, а старым запрещает принимать новые соединения.

Старые workers продолжают обслуживать уже принятые запросы. После их завершения они выходят. Поэтому reload обычно не рвёт активные HTTP-соединения и не требует освобождать порт между старым и новым набором процессов.

Для конфигурации Nginx безопасный сценарий — не «остановить и снова запустить», а «проверить, применить, проверить результат и только потом откатить при необходимости».

Graceful shutdown¹ — завершение процесса после обработки уже принятых соединений, без немедленного обрыва каждого запроса. Это не обещание бесконечного ожидания: долгие соединения, зависшие upstream-запросы и ошибки приложения всё равно могут задержать выход старых workers.

Четыре варианта и их цена

systemctl reload nginx и nginx -s reload не являются двумя разными механизмами перезагрузки конфигурации. В большинстве дистрибутивов systemd-unit в итоге вызывает команду Nginx или отправляет мастер-процессу HUP. Точную реализацию стоит проверить командой systemctl cat nginx: сторонний unit может вести себя иначе.

Рабочий процесс для изменения конфигурации

1. Сохраните копию и внесите изменение

Работайте с тем файлом, который подключён через основной конфиг. Частая ошибка — отредактировать файл, который Nginx не читает, и принять отсутствие изменений за успешный reload. Точное дерево подключений покажет команда nginx -T, если у текущего пользователя есть нужные права.

sudo cp -a /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
sudo nginx -T

Проверка: в выводе видны основной файл и подключённые фрагменты conf.d или sites-enabled, а резервная копия существует.

2. Проверьте конфигурацию до reload

Не отправляйте HUP вслепую. Тест проверяет синтаксис и пытается открыть используемые конфигурацией файлы, но не доказывает, что приложение за upstream отвечает.

sudo nginx -t

При успехе вы увидите сообщения о корректном синтаксисе и успешной проверке. Если команда завершилась с ошибкой, reload не выполняйте: исправьте указанный файл и строку, затем повторите тест.

3. Примените конфигурацию без остановки сервиса

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

sudo systemctl reload nginx

Если Nginx запущен не через systemd, примените сигнал через сам бинарник:

sudo nginx -s reload

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

4. Проверьте не только процесс, но и трафик

Сначала посмотрите состояние сервиса и последние сообщения журнала:

sudo systemctl status nginx --no-pager
sudo journalctl -u nginx -n 50 --no-pager

Затем проверьте изменённый маршрут с той точки, откуда к нему обращаются пользователи. Например, запрос к локальному виртуальному хосту:

curl -I http://127.0.0.1/

Проверка: ожидаемый HTTP-статус и заголовки приходят уже по новой конфигурации, а число ошибок 502, 504 и 499 не растёт после reload. Для HTTPS проверяйте также сертификат и имя хоста, а не только код 200.

5. Откатывайте изменение тем же безопасным способом

Если новый маршрут, upstream или TLS-параметры работают неправильно, верните резервную копию, снова выполните nginx -t и только после успешной проверки сделайте reload.

sudo cp -a /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
sudo nginx -t
sudo systemctl reload nginx

Проверка: конфигурация проходит тест, сервис не переходит в состояние failed, а контрольный запрос возвращает прежний результат.

Почему restart опаснее reload

systemctl restart nginx сначала останавливает сервис. В этот момент слушающий порт может быть свободен, а новые соединения — получать отказ или тайм-аут до завершения запуска. Длительность окна зависит от systemd, состояния workers, DNS, сертификатов, подключённых модулей и скорости диска. Называть его гарантированно нулевым нельзя.

Restart также маскирует ошибку процесса управления: если новый запуск не прошёл, старый Nginx уже остановлен. При reload при невалидной конфигурации старый набор workers продолжает обслуживать трафик, потому что мастер не принимает неуспешное изменение.

Где reload ломается

• Ошибка синтаксиса. nginx -t укажет файл и строку. Исправьте ошибку, не заменяйте reload на restart.
• Не тот конфигурационный файл. Изменение в не подключённом файле не повлияет на работающий сервер. Проверьте nginx -T.
• Нет прав на pid-файл. При ручном запуске nginx -s reload может обращаться не к тому процессу или не иметь доступа к pid-файлу. Уточните путь запуска и используйте тот же пользователь, что и при старте.
• Новые workers запустились, но upstream не отвечает. Синтаксис будет правильным, однако приложение может быть выключено, порт закрыт или DNS-имя недоступно. Ищите причину в error log и проверяйте backend отдельно.
• Старые workers не уходят. Такое бывает при долгих запросах, WebSocket и зависших соединениях. Смотрите список процессов и длительность запросов; не убивайте workers сразу, если потеря соединений недопустима.

Когда нужен USR2, а когда достаточно reload

Reload меняет настройки уже запущенного бинарника. Он не обновляет исполняемый файл, динамические модули и библиотечные зависимости. Если вы устанавливаете новую версию Nginx, простой reload не превращает старый процесс в новый.

Для бесшовного обновления бинарника Nginx поддерживает отдельную последовательность сигналов USR2, WINCH и QUIT. Она требует контроля pid-файлов, наследования слушающих сокетов и возможности быстро вернуться к старому master. Ошибка в порядке сигналов может оставить два набора процессов или усложнить откат.

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

Что делать дальше

Вынесите проверку nginx -t в pipeline или release-скрипт до применения конфигурации. После reload наблюдайте не только доступность Nginx, но и коды 502/504, время ответа, число активных соединений и возраст старых workers. Для WebSocket и длинных запросов отдельно задайте допустимое время graceful shutdown и проверьте откат на тестовом стенде.

¹ В Nginx старый worker прекращает принимать новые соединения и завершает уже принятые. Фактическое время выхода зависит от типа трафика и параметров graceful shutdown.