PHPTime

HTTP/2 и HTTP/3 для PHP-сайта на nginx: настройка и диагностика

После включения HTTP/2 сайт может продолжить работать по HTTP/1.1, а после настройки HTTP/3 браузер может так и не перейти на QUIC. Разберём, как настроить nginx с PHP-FPM, проверить каждый протокол отдельно и определить, где искать причину сбоя.

Где заканчивается HTTP и начинается PHP

SPDY был предшественником HTTP/2. Сегодня для сайта на nginx обычно оставляют HTTP/1.1 для совместимости, включают HTTP/2 поверх TLS и при необходимости добавляют HTTP/3 поверх QUIC. HTTP/1.1 и HTTP/2 принимают соединения по TCP, HTTP/3 использует UDP. Они могут работать одновременно на порту 443.

Версию HTTP согласуют клиент и узел, который принимает его соединение. При прямом подключении это nginx. При использовании CDN или балансировщика это пограничный узел, и до nginx запрос может дойти по другой версии HTTP. Дальше nginx передаёт PHP-запрос в PHP-FPM по FastCGI. Для перехода на HTTP/2 или HTTP/3 менять PHP-код, способ подключения к базе и настройки сессий не требуется. Схема одинакова для PHP 8.3–8.5.

Включаем HTTP/2 и сохраняем рабочий маршрут до PHP

Начните с nginx -V. В параметрах сборки для HTTP/2 ищите --with-http_v2_module. В актуальном синтаксисе HTTPS-сокет объявляют через listen 443 ssl;, а HTTP/2 включают отдельной директивой http2 on;. Если nginx сообщает unknown directive, проверьте состав сборки и её версию. В старых сборках с модулем HTTP/2 встречается прежняя форма listen 443 ssl http2;.

Ниже пример для приложения с единым входом через public/index.php. Подставьте домен, корень сайта, пути к полной цепочке сертификата и закрытому ключу, а также сокет своего пула PHP-FPM. Для приложения с несколькими публичными PHP-скриптами сохраните их существующие маршруты.

nginx
server {
    listen 443 ssl;
    server_name example.com;
    http2 on;

    ssl_certificate     /etc/nginx/tls/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    root /srv/php-site/public;
    index index.php;

    # Статику отдаёт nginx, остальные запросы идут в приложение.
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /index.php {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }

    # В этой схеме публично исполняется только index.php.
    location ~* \.php(?:/|$) {
        return 404;
    }
}

Проверяйте конфигурацию перед каждой перезагрузкой. После неё сделайте запрос к странице, которая выполняет PHP, и к статическому файлу. Так проще отличить проблему с подключением от сбоя PHP-FPM.

Shell
# Выполните с правами, достаточными для проверки и перезагрузки.
sudo nginx -t && sudo nginx -s reload

Добавляем HTTP/3 через QUIC

Для HTTP/3 проверьте в выводе nginx -V наличие --with-http_v3_module и поддержку QUIC выбранной сборкой и её TLS-библиотекой. Для QUIC нужен TLS 1.3. В тот же блок server добавьте UDP-слушатель и заголовок Alt-Svc, который сообщает клиенту, где доступен HTTP/3. TCP-слушатель и http2 on; сохраните.

nginx
# Добавьте к существующему HTTPS-блоку server.
listen 443 quic reuseport;
http3 on;
add_header Alt-Svc 'h3=":443"; ma=300' always;

ma=300 задаёт пятиминутный срок хранения объявления. Это удобно на этапе запуска. При первом визите браузер может подключиться по HTTP/2, получить Alt-Svc и использовать HTTP/3 для следующего соединения. Проверьте заголовок на фактическом ответе сайта. В nginx директивы add_header на уровне location по умолчанию заменяют унаследованный набор заголовков. Если в нужном блоке уже есть собственные add_header, проверьте, что Alt-Svc тоже попадает в ответ.

Откройте входящий 443/UDP по всему пути до узла, который принимает QUIC. Проверьте внешний файрвол, правила хоста и публикацию порта у контейнера. В Docker запись 443:443 публикует TCP. Для UDP нужна отдельная запись 443:443/udp. Если у домена есть AAAA-запись, проверьте слушатели и правила IPv6. При нескольких виртуальных хостах на одном адресе и порту задавайте параметр reuseport для этого сокета один раз.

Если клиентское TLS-соединение принимает CDN, включайте HTTP/3 на стороне CDN и проверяйте внешний ответ. Соединение между CDN и nginx при этом может оставаться на HTTP/2 или HTTP/1.1.

Проверяем объявление и фактическую версию HTTP

Выполняйте проверки с внешней машины. Сначала запустите curl -V и проверьте, что сборка клиента поддерживает нужные протоколы. В примере замените example.com своим доменом. Команды отправляют обычный GET и выводят версию HTTP и код ответа.

Shell
# Проверяем HTTP/2. При откате curl покажет версию 1.1.
curl --proto-default https --http2 -sS -o /dev/null \
  -w 'HTTP %{http_version}, код %{http_code}\n' example.com

# Смотрим заголовки ответа, в том числе Alt-Svc.
curl --proto-default https --http2 -sS -D - -o /dev/null example.com

# Проверяем HTTP/3 с запретом отката на TCP.
curl --proto-default https --http3-only -sS --max-time 15 -o /dev/null \
  -w 'HTTP %{http_version}, код %{http_code}\n' example.com

Для первой команды ожидается версия 2, для последней — 3. Код ответа оценивайте по выбранному маршруту. Например, перенаправление подтверждает соединение, а для проверки PHP нужен запрос к странице с ожидаемым ответом приложения. Успех с --http3-only подтверждает доступность QUIC напрямую. Наличие Alt-Svc показывает, что сервер объявляет его браузерам. Для полноценной проверки нужны оба результата.

В инструментах разработчика браузера откройте вкладку Network, включите колонку Protocol и проверьте значения h2 и h3 у запросов к своему домену. Сделайте повторный заход после получения Alt-Svc. Если результаты curl и браузера расходятся, сравните сети и проверьте, не проходит ли браузер через прокси. При наличии IPv4 и IPv6 можно повторить команды отдельно с -4 и -6.

Ищем сбой по симптому

  • После перезагрузки остаётся HTTP/1.1. Проверьте, какой узел принимает TLS и какой блок server обслуживает домен. В выводе curl -v посмотрите, какой протокол сервер выбрал через ALPN. Если клиент предложил h2, а сервер выбрал http/1.1, ищите настройку на узле, который ответил клиенту.
  • HTTP/2 работает, HTTP/3 завершается по тайм-ауту. Сверьте UDP-слушатель, публикацию порта и правила файрволов. Сравните запросы из двух сетей. Если из одной сети QUIC работает, проверьте ограничения UDP в другой.
  • Прямой тест HTTP/3 проходит, браузер остаётся на HTTP/2. Проверьте Alt-Svc на внешнем ответе главной страницы и на ответах после перенаправлений. Посмотрите, сохраняет ли его CDN и не переопределяет ли набор заголовков вложенный location. Проверьте новый сеанс, чтобы исключить повторное использование уже открытого соединения.
  • Статика открывается, а PHP отвечает 502. Проверьте журнал ошибок nginx, состояние пула PHP-FPM, путь к сокету и права на подключение к нему. Если nginx отдаёт 404 или PHP-FPM пишет Primary script unknown, проверьте root, правила маршрутизации и значение SCRIPT_FILENAME. В контейнерах переданный путь должен существовать внутри контейнера PHP-FPM.

Для диагностики добавьте $server_protocol в используемый формат журнала nginx. Он покажет версию соединения, которое принял этот экземпляр nginx. За CDN для протокола браузера смотрите данные на пограничном узле или в самом браузере. Значение $_SERVER['SERVER_PROTOCOL'] в PHP приходит из окружения запроса и тоже описывает только то, что приложение получило от веб-сервера.

Чек-лист перед завершением перехода

  1. Проверьте сборку nginx, цепочку сертификата и конфигурацию через nginx -t. Подтвердите HTTP/2 внешним запросом.
  2. Проверьте маршруты приложения по TCP. Откройте динамическую страницу, загрузите статический ресурс и пройдите основной пользовательский сценарий.
  3. Добавьте UDP-слушатель и короткий Alt-Svc. Подтвердите HTTP/3 через curl --http3-only и проверьте заголовок на внешнем ответе.
  4. Сверьте результат в браузере. При наличии CDN и IPv6 проверьте публичный маршрут через CDN и обе семьи адресов.
  5. Если после запуска нужно отключить HTTP/3, оставьте TCP и HTTP/2, замените объявление QUIC на Alt-Svc: clear и уберите UDP-слушатель. Клиенты, которые ещё не получили clear, могут пробовать сохранённый адрес до истечения срока объявления.

Частые вопросы

Нужно ли обновлять PHP, чтобы включить HTTP/2 или HTTP/3?

Версию HTTP согласует nginx, CDN или другой узел, принимающий клиентское соединение. PHP-FPM продолжает получать запросы по FastCGI. Ветка PHP не определяет доступность HTTP/2 или HTTP/3.

Могут ли HTTP/2 и HTTP/3 работать на одном порту?

Да. HTTP/2 использует 443/TCP, а HTTP/3 — 443/UDP. Для прямого подключения к nginx нужно настроить оба слушателя и пропустить оба вида трафика.

Почему браузер показывает h2 сразу после включения HTTP/3?

Браузер может получить объявление Alt-Svc по HTTP/2 и попробовать QUIC при следующем соединении. Если h3 так и не появляется, проверьте заголовок на внешнем ответе и запустите curl с флагом --http3-only из той же сети.

Справка по теме

Ещё в разделе «Linux и серверы»

Горячие клавиши в PhpStorm на Linux: чиним работу в русской раскладке

Почему в PhpStorm на Linux не работают горячие клавиши в русской раскладке и как это исправить: javaagent, vmoptions, XIM, Wayland и настройки IDE.

6 мин

Поиск текста в файлах в Linux: grep, find, ripgrep и примеры для PHP-проекта

Как искать текст в файлах Linux: grep -rn, find с фильтрами по дате, ripgrep для больших проектов. Разбор на примере современного PHP-кода.

5 мин

Сайт на PHP недоступен: пошаговый чек-лист диагностики

Пошаговая диагностика недоступного PHP-сайта: проверяем DNS, TLS, веб-сервер, PHP-FPM, базу данных, свободное место и логи, чтобы найти причину сбоя.

8 мин

Google Drive в Linux: rclone, монтирование, синхронизация и бэкапы сайта

Настройка Google Drive в Linux через rclone: подключение, монтирование, синхронизация и автоматические бэкапы сайта. Практическое руководство для разработчиков.

8 мин