QUIC 和 HTTP/3 支持

提示

来自deepseek解释

原文链接：https://nginx.org/en/docs/quic.html

自 1.25.0 版本起，nginx 开始支持 QUIC 和 HTTP/3 协议，该支持已包含在 Linux 二进制包 中。

请参阅 ngx_http_v3_module 模块文档。

从源码构建

构建时使用 configure 命令进行配置。详情请参阅 构建 nginx。

建议使用 OpenSSL 3.5.1 或更高版本编译支持 QUIC 的 nginx。否则，将使用 OpenSSL 兼容层，该层不支持 early data。

也可以使用预编译的 BoringSSL、LibreSSL 或 QuicTLS 库。

使用以下命令配置 nginx 以使用 BoringSSL：

./configure --with-debug --with-http_v3_module --with-cc-opt="-I../boringssl/include" --with-ld-opt="-L../boringssl/build -lstdc++"

或者，使用 QuicTLS 配置 nginx：

./configure --with-debug --with-http_v3_module --with-cc-opt="-I../quictls/build/include" --with-ld-opt="-L../quictls/build/lib"

或者，使用 LibreSSL 配置 nginx：

./configure --with-debug --with-http_v3_module --with-cc-opt="-I../libressl/build/include" --with-ld-opt="-L../libressl/build/lib"

配置完成后，使用 make 编译并安装 nginx。

配置建议

ngx_http_core_module 模块中的 listen 指令新增了 quic 参数，用于在指定端口启用基于 QUIC 的 HTTP/3。

与 quic 参数一起，还可以指定 reuseport 参数，以确保在多工作进程下正常工作。

启用地址验证：

quic_retry on;

启用 0-RTT：

ssl_early_data on;

启用 GSO（通用分段卸载）：

quic_gso on;

设置各类令牌的主机密钥：

quic_host_key <key>;

QUIC 需要 TLSv1.3 协议版本，该版本在 ssl_protocols 指令中默认启用。

默认情况下，GSO Linux 特定优化 是禁用的。如果相应的网络接口已配置支持 GSO，则启用它。

故障排查

以下技巧可能有助于识别问题：

• 确保 nginx 使用正确的 SSL 库进行构建。
• 确保 nginx 在运行时使用了正确的 SSL 库（nginx -V 会显示当前使用的库）。
• 确保客户端确实通过 QUIC 发送请求。建议先从简单的控制台客户端（如 ngtcp2）开始，以确保服务器配置正确，然后再使用可能对证书较为挑剔的真实浏览器进行测试。
• 使用 debug 支持 构建 nginx，并检查调试日志。日志应包含有关连接及失败原因的所有详细信息。所有相关消息都包含 “quic” 前缀，可以轻松过滤。
• 如需更深入的研究，可以使用以下宏启用额外的调试功能：
  • NGX_QUIC_DEBUG_PACKETS
  • NGX_QUIC_DEBUG_FRAMES
  • NGX_QUIC_DEBUG_ALLOC
  • NGX_QUIC_DEBUG_CRYPTO

示例配置命令：

./configure --with-http_v3_module --with-debug --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"