HTTP/3 в Nginx: полное руководство по установке и настройке

Коротко о главном

HTTP/3 работает поверх QUIC и UDP, быстрее устанавливает соединение и лучше переносит потери пакетов. Nginx поддерживает его в свежих версиях, но не во всех дистрибутивных сборках. Прежде чем включать, нужно проверить версию и модули.

Для сайта HTTP/3 даёт ускорение на мобильных и нестабильных соединениях. Даже если выигрыш невелик, браузеры выбирают протокол автоматически, а откат на HTTP/2 остаётся доступным.

В этой статье разберём HTTP/3 в Nginx по шагам: установка, базовая конфигурация, практические сценарии и ошибки, которые встречаются чаще всего.

Зачем нужен HTTP/3 в Nginx

HTTP/3 в Nginx решает вполне конкретные задачи: Включение HTTP/3 и QUIC в Nginx: требования, конфигурация, проверка и откат на HTTP/2. Важно не превращать инструмент в самоцель — если задача проще решается штатными средствами системы, начните с них.

Установка

В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:

sudo apt install nginx

В Fedora и RHEL-совместимых системах пакет ставится через DNF:

sudo dnf install nginx

В Arch Linux и производных пакет доступен в официальных репозиториях:

sudo pacman -S nginx

Пошаговая настройка

После установки переходите к базовому сценарию. Команды ниже выполняйте от пользователя с достаточными правами, но не запускайте всё под root без необходимости.

1. Проверьте поддержку

Модуль HTTP/3 должен быть собран в бинарнике. Если в выводе нет http_v3, потребуется другая сборка или репозиторий с новой версией.

nginx -V 2>&1 | tr ' ' '\n' | grep -i http_v3
nginx -v

2. Откройте UDP-порт

HTTP/3 использует UDP 443. Если открыт только TCP, браузер не сможет подключиться по новому протоколу.

sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status numbered

3. Настройте сервер

Добавьте директивы quic и http3 к существующему блоку. Не отключайте HTTP/2: он нужен как запасной вариант.

sudo nginx -t
sudo systemctl reload nginx

4. Проверьте извне

Локальная проверка может не показать QUIC. Используйте curl с поддержкой HTTP/3 и внешний тест.

curl --http3 -I https://example.com
curl -I https://example.com

5. Подготовьте откат

Если что-то ломается, уберите директивы quic и http3 и перезагрузите Nginx. Сайт продолжит работать по HTTP/2.

sudo cp /etc/nginx/sites-available/example.conf ~/example.conf.bak

Базовая конфигурация

Начните с минимального рабочего варианта. Не копируйте большой конфиг целиком: добавляйте параметры по одному и проверяйте результат после каждого изменения.

server {
    listen 443 ssl;
    listen 443 quic reuseport;
    http2 on;
    http3 on;
    add_header Alt-Svc 'h3=":443"; ma=86400' always;
    ssl_protocols TLSv1.2 TLSv1.3;
}

Практические советы

Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.

Совет 1. HTTP/3 требует TLS 1.3: без него протокол не включится.

HTTP/3 требует TLS 1.3: без него протокол не включится.

Совет 2. Не полагайтесь только на UDP: часть сетей блокирует его, и HTTP/2 долж

Не полагайтесь только на UDP: часть сетей блокирует его, и HTTP/2 должен оставаться рабочим.

Совет 3. Проверяйте поведение через мобильную сеть, а не только из локальной се

Проверяйте поведение через мобильную сеть, а не только из локальной сети.

Совет 4. Alt-Svc кэшируется браузером: после изменений может понадобиться очист

Alt-Svc кэшируется браузером: после изменений может понадобиться очистка.

Совет 5. Следите за версией Nginx: поддержка HTTP/3 активно меняется.

Следите за версией Nginx: поддержка HTTP/3 активно меняется.

Практический сценарий

Представьте типовую задачу: нужно развернуть HTTP/3 в Nginx на одной машине, проверить работу и передать доступ коллеге. Начните с чистой системы или снапшота, чтобы результат был воспроизводим. Запишите все команды в отдельный файл — это одновременно шпаргалка и черновик будущей автоматизации.

Дальше действуйте короткими шагами: установка, минимальная конфигурация, проверка, затем расширение. После каждого шага фиксируйте, что именно изменилось и как это проверить. Такой журнал экономит время, когда через месяц понадобится повторить настройку на другом сервере или объяснить её коллеге.

Порядок работ для этого сценария выглядит так:

1. Проверьте поддержку
2. Откройте UDP-порт
3. Настройте сервер
4. Проверьте извне
5. Подготовьте откат

Отдельно продумайте, что произойдёт при сбое. Для HTTP/3 в Nginx важно заранее знать, где хранятся данные, как их скопировать и сколько времени займёт восстановление. Если ответа нет, не двигайтесь дальше: сначала закройте этот пробел, потом добавляйте новые возможности.

Типичные ошибки

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

1. HTTP/3 не включается

Проверьте сборку Nginx, TLS 1.3 и открытый UDP-порт. Директивы http3/quic доступны не во всех версиях.

2. Сайт перестал открываться по HTTPS

Проверьте nginx -t и журнал. Верните резервную конфигурацию и перезагрузите службу; UDP-правила не влияют на TCP.

3. Браузер не переключается на HTTP/3

Очистите кэш Alt-Svc или проверьте тестом из другой сети. Некоторые прокси и антивирусы блокируют QUIC.

Что проверить перед вводом в работу

Перед тем как считать настройку завершённой, пройдитесь по короткому списку. Он не заменяет полноценный аудит, но отсекает большинство очевидных проблем.

Если какой-то пункт вызывает затруднение, это сигнал вернуться к соответствующему разделу, а не откладывать проверку. Настройка, которую нельзя повторить, плохо работает не только у коллег, но и у вас самих через полгода.

Итог

HTTP/3 в Nginx — это не «поставил и забыл». Рабочая конфигурация складывается из понимания задачи, аккуратной установки и проверки результата. Начните с базового сценария, затем добавляйте только те возможности, которые действительно используете.