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-скриптами сохраните их существующие маршруты.
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.
# Выполните с правами, достаточными для проверки и перезагрузки.
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; сохраните.
# Добавьте к существующему 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 и код ответа.
# Проверяем 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 приходит из окружения запроса и тоже описывает только то, что приложение получило от веб-сервера.
Чек-лист перед завершением перехода
- Проверьте сборку nginx, цепочку сертификата и конфигурацию через
nginx -t. Подтвердите HTTP/2 внешним запросом. - Проверьте маршруты приложения по TCP. Откройте динамическую страницу, загрузите статический ресурс и пройдите основной пользовательский сценарий.
- Добавьте UDP-слушатель и короткий
Alt-Svc. Подтвердите HTTP/3 черезcurl --http3-onlyи проверьте заголовок на внешнем ответе. - Сверьте результат в браузере. При наличии CDN и IPv6 проверьте публичный маршрут через CDN и обе семьи адресов.
- Если после запуска нужно отключить 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 из той же сети.