Совместимость версий Nginx

Обзор

Nginx меняет синтаксис директив между релизами, поэтому план, затрагивающий конфигурацию nginx, ОБЯЗАН сначала зафиксировать целевую версию, а не предполагать синтаксис. Это встроенный чеклист для /dr-plan на любую задачу, редактирующую конфигурацию nginx.

1. Сначала проверьте запущенную версию

ssh <host> 'nginx -v'          # выводит "nginx version: nginx/1.MM.p" в stderr
ssh <host> 'nginx -V 2>&1 | tr " " "\n" | grep -- --with'   # встроенные модули (http_v2, http_v3)

Зафиксируйте точную версию 1.MM.p в плане. Никогда не предполагайте — дистрибутивы фиксируют старые ветки (Debian bookworm поставляет 1.22.x, Ubuntu 22.04 — 1.18.x).

2. Сопоставление версии и синтаксиса

• HTTP/2 — до 1.25.0: listen 443 ssl http2;. С 1.25.1: listen 443 ssl; плюс отдельная директива http2 on;.
• HTTP/3 / QUIC — недоступно до 1.25.0. С 1.25.1: listen 443 quic reuseport; плюс http3 on; (требует сборки с --with-http_v3_module).

С версии 1.25.1 http2 и http3 — самостоятельные директивы, а не параметры listen; старая форма listen ... http2 устарела и выдаёт предупреждение на 1.25.1+.

3. Частые ловушки breaking-изменений

• quic / http3 требуют сборки nginx с --with-http_v3_module (отсутствует в большинстве дистрибутивных пакетов) — подтвердите через nginx -V перед планированием HTTP/3.
• ssl_protocols и дефолтные шифры отличаются между сборками — указывайте их явно, не полагаясь на значения по умолчанию.
• Безопасный reload: nginx -t (проверка конфига) ОБЯЗАНА пройти перед nginx -s reload.