# HTTP/3 为客户端连接提供 [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114) 协议支持, 同时也支持与使用以下 [Proxy](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 模块指令 配置的代理服务器的连接: - [proxy_http3_hq](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-hq) - [proxy_http3_max_concurrent_streams](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-concurrent-streams) - [proxy_http3_max_table_capacity](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity) - [proxy_http3_stream_buffer_size](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-stream-buffer-size) - [proxy_http_version](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) - [proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) - [proxy_quic_active_connection_id_limit](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-active-connection-id-limit) - [proxy_quic_gso](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-gso) - [proxy_quic_host_key](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-host-key) 当 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时, 此模块默认不会被构建; 需要使用 `‑‑with‑http_v3_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 来启用。 在来自 [我们仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的软件包和镜像中, 该模块已包含在构建中。 ## 配置示例 ```nginx http { log_format quic '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" "$http3"'; access_log logs/access.log quic; server { # 为了更好的兼容性,建议 # 对 http/3 和 https 使用相同的端口 listen 8443 quic reuseport; listen 8443 ssl; ssl_certificate certs/example.com.crt; ssl_certificate_key certs/example.com.key; location / { # 用于通告 HTTP/3 的可用性 add_header Alt-Svc 'h3=":8443"; ma=86400'; } } } ``` #### NOTE 请注意,通过 TLS 接受 HTTP/3 连接需要 TLSv1.3 协议支持,该协议从 [OpenSSL](http://www.openssl.org/) 1.1.1 版本开始可用。 0-RTT 支持需要 OpenSSL 3.5.1 或更高版本。或者,可以使用 [BoringSSL](https://boringssl.googlesource.com/boringssl/)、[LibreSSL](https://www.libressl.org) 或 [QuicTLS](https://github.com/quictls/openssl) 来构建和运行此模块。 在 1.29.1 版本之前,无论 [ssl_early_data](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) 指令的值如何,都无法通过 OpenSSL 启用 0-RTT 支持。 对于 HTTP/3 请求,如果未传递 `Host` 头,则 `$http_host` 变量会从 `:authority` 伪头初始化。 此外,:samp:reuseport 选项只能在服务器上的一个 `listen ... quic` 指令中指定。所有其他 `listen ... quic` 指令必须不带此选项。 ## 指令 ### http3 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http3` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------| | 默认值 | `http3 on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 启用 HTTP/3 协议协商。 ### http3_hq | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_hq` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `http3_hq off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 启用在 [QUIC 互操作性测试](https://github.com/marten-seemann/quic-interop-runner) 中使用的 HTTP/0.9 协议协商。 #### WARNING 仅在运行明确需要此模式的专门测试时才启用。 ### http3_max_concurrent_streams | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_max_concurrent_streams` number; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `http3_max_concurrent_streams 128;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 初始化 HTTP/3 和 QUIC 设置, 并设置一个连接中并发 HTTP/3 请求流的最大数量。 ### http3_max_table_capacity | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_max_table_capacity` number; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `http3_max_table_capacity 4096;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置服务器连接的 [动态表](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table) 容量。 #### NOTE 类似的 [proxy_http3_max_table_capacity](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity) 指令 用于代理连接。 为避免错误, 当启用带缓存的代理时,动态表使用会被禁用。 ### http3_stream_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_stream_buffer_size` size; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `http3_stream_buffer_size 64k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置用于读取和写入 QUIC 流的缓冲区 [大小](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)。 ### quic_active_connection_id_limit | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_active_connection_id_limit` number; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `quic_active_connection_id_limit 2;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置 QUIC active_connection_id_limit 传输参数值。这是可以存储在服务器上的连接 ID 的最大数量。 ### quic_bpf | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_bpf` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `quic_bpf off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 启用使用 [eBPF](https://ebpf.io/) 路由 QUIC 数据包。启用后,可以支持 QUIC 连接迁移。 #### NOTE 该指令仅在 Linux 5.7+ 上支持。 ### quic_gso | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_gso` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `quic_gso off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 启用使用分段卸载的优化批量发送模式。 #### NOTE 优化发送仅在支持 `UDP_SEGMENT` 的 Linux 上受支持。 ### quic_host_key | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_host_key` file; | |--------------------------------------------------------------------------------------|-------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置包含用于加密无状态重置和地址验证令牌的密钥的 file 文件。默认情况下,每次重新加载时都会生成一个随机密钥。使用旧密钥生成的令牌不会被接受。 ### quic_retry | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_retry` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `quic_retry off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 启用 [QUIC 地址验证](https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation) 功能。这包括在 Retry 数据包或 NEW_TOKEN 帧中发送新令牌,以及验证在 Initial 数据包中收到的令牌。 ## 内置变量 http_v3 模块支持以下内置变量: ### `$http3` 协商的协议标识符: | `h3` | 用于 HTTP/3 连接 | |--------|----------------| | `hq` | 用于 hq 连接 | | `""` | 否则为空字符串 | ### `$quic_connection` QUIC 连接序列号