Zero-downtime reload Nginx: чек-лист перед продакшеном

Ошибка в конфигурации Nginx может оставить сайт без трафика, а неудачный reload — породить несколько поколений worker-процессов, которые не завершаются из-за долгих соединений. В Nginx 1.24–1.27 безопасная схема занимает минуты: проверить конфигурацию, отправить reload, убедиться, что новые workers поднялись, и заранее знать команду отката. Ниже — практический чек-лист для продакшена без остановки принимающих запросы.

Что именно делает reload

У Nginx есть master-процесс и один или несколько worker-процессов. При reload master перечитывает конфигурацию, открывает новые listen-сокеты и запускает новый набор workers. Старым workers отправляется команда завершиться после обработки текущих соединений.

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

Zero-downtime — это не отсутствие процесса перезапуска. Это способность принять новые запросы, пока старые workers корректно заканчивают свою работу.

[1] Worker-процесс — дочерний процесс Nginx, который принимает соединения и обрабатывает запросы; master управляет его запуском и остановкой.

Чек-лист до изменения конфигурации

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

1. Зафиксируйте версию и способ запуска. Выполните nginx -v и определите, управляется ли процесс через systemd, контейнер или собственный supervisor. Команда reload должна обращаться к тому же экземпляру, который обслуживает трафик. Проверка: в выводе ps или панели процесса виден ожидаемый master Nginx.
2. Сохраните текущую рабочую конфигурацию. Скопируйте изменяемые файлы и зафиксируйте ревизию в Git или другом хранилище. Проверка: вы можете назвать конкретный файл и команду, которая вернёт предыдущую версию.
3. Проверьте синтаксис. Запустите nginx -t с тем же пользователем и параметром prefix, с которыми запускается production-экземпляр. Для systemd удобнее сначала проверить конфигурацию вручную, а затем использовать reload сервиса. Проверка: команда завершается с кодом 0 и сообщает, что проверка конфигурации успешна.
4. Проверьте полный набор подключённых файлов. Используйте nginx -T, если нужно увидеть итоговую конфигурацию вместе с файлами из include. Проверка: изменённый server-блок присутствует в итоговом выводе, а старое значение не осталось в другом подключённом файле.
5. Проверьте доступность upstream. Если меняются proxy_pass, DNS-имя, порт или TLS-параметры, отдельно проверьте соединение до приложения. Проверка: запрос к backend проходит с того же хоста и под тем же сетевым маршрутом, что использует Nginx.
6. Проверьте права и сертификаты. Убедитесь, что master может прочитать сертификат, ключ и включаемые файлы. Проверка: nginx -t не сообщает об ошибке доступа, отсутствующем файле или проблеме с сертификатом.
7. Подготовьте наблюдение. Откройте графики кодов 4xx и 5xx, latency, активных соединений и состояния upstream. Проверка: после reload вы сможете сравнить показатели до и после, а не искать причину по одному сообщению в журнале.

Как выполнять reload

Вариант для systemd

Для обычной установки Nginx через пакетный менеджер используйте проверку и reload отдельными командами:

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl is-active nginx

Первая команда не меняет запущенную конфигурацию. Вторая просит systemd отправить Nginx корректную команду перечитывания конфигурации. Третья показывает состояние сервиса, но сама по себе не доказывает, что backend отвечает.

Вариант через управляющую команду Nginx

Если Nginx запущен не через systemd, reload можно отправить master-процессу:

sudo nginx -t
sudo nginx -s reload

Команда nginx -s reload должна использовать тот же путь к конфигурации и prefix, что и работающий master. В нестандартной установке это важно: проверка одного экземпляра не защищает от reload другого.

Какой способ выбрать

Для изменения upstream, заголовков, маршрутов, лимитов и TLS-конфигурации сначала рассматривайте reload. Restart — это другая операция: master и workers останавливаются, а затем запускаются заново. Она не является «более надёжным reload».

Проверка после reload

Успешный код возврата команды — только первый сигнал. Проверяйте результат на уровне процесса и реального HTTP-запроса.

• Посмотрите журнал ошибок Nginx: там не должно появиться сообщений о невозможности открыть listen-сокет, upstream или worker-процесс.
• Сделайте запрос к изменённому маршруту с хоста мониторинга и проверьте код ответа, заголовки и время ответа.
• Проверьте несколько виртуальных хостов, если конфигурация общая: reload мог затронуть их все.
• Сравните число активных соединений, 5xx и latency с периодом до изменения.
• Убедитесь, что старые workers постепенно исчезают. Их длительное присутствие требует объяснения, а не повторного reload.

Для проверки процесса используйте команды, доступные в вашей системе: systemctl status nginx, журнал сервиса и список процессов. Не привязывайте автоматизацию к конкретному номеру PID: после reload он меняется.

Где zero-downtime ломается

Долгие соединения

WebSocket, long polling, медленная загрузка и большие ответы могут удерживать старый worker дольше обычного. Если такие соединения не заканчиваются, новый reload создаёт ещё одну группу workers. Смотрите возраст процессов и активные соединения, прежде чем повторять операцию.

Директива worker_shutdown_timeout задаёт максимальное время ожидания при корректном завершении worker. Это компромисс: слишком короткое значение может оборвать долгие запросы, слишком длинное — оставить старые процессы и ресурсы на продолжительное время. Подбирать его нужно по реальным длительным операциям приложения.

Изменение listen-параметров

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

Скрытый upstream

Синтаксис proxy_pass может быть правильным, а приложение — недоступным, перегруженным или неправильно настроенным по имени хоста. Поэтому проверка должна включать реальный запрос через Nginx, а не только nginx -t.

Конфигурация внутри контейнера

В контейнере сигнал должен попасть master-процессу, а не оболочке-обёртке. Проверьте PID 1, обработку сигналов и поведение оркестратора. Если reload не предусмотрен моделью запуска, безопаснее выполнить rolling update несколькими экземплярами, сохраняя доступность сервиса.

Откат без паники

Откат выполняйте тем же способом, что и изменение: верните последнюю рабочую конфигурацию, снова запустите nginx -t, затем отправьте reload. Не перезапускайте Nginx автоматически только потому, что проверка HTTP-запроса не прошла: проблема может быть в приложении, DNS или upstream.

1. Остановите дальнейшие изменения конфигурации.
2. Верните сохранённую рабочую ревизию.
3. Проверьте синтаксис и права на файлы.
4. Выполните reload и проверьте контрольный URL.
5. Зафиксируйте причину отката по журналам и метрикам.

Если nginx -t не проходит, рабочая конфигурация не меняется: сначала исправьте файл или верните предыдущую версию. Если проверка проходит, но запросы получают 502 или 504, исследуйте upstream и таймауты.

Что настроить дальше

После первого успешного reload автоматизируйте только последовательность, которую уже проверили вручную: сохранить конфигурацию, выполнить nginx -t, отправить reload, сделать контрольный HTTP-запрос и наблюдать ошибки несколько минут. В продакшене измеряйте не сам факт reload, а время жизни старых workers, долю 5xx, latency и число активных соединений. Именно эти показатели показывают, был ли перезапуск действительно бесшовным.