当前位置：首页 > news >正文

Nginx如何部署HTTP/3

news 2025/9/10 13:06:49

Nginx如何部署HTTP/3

在 Nginx 中部署 HTTP/3（其前身为 QUIC）需要一个特定的、支持 QUIC 的 Nginx 版本，因为标准的稳定版 Nginx 尚未原生包含此功能。

目前，部署 HTTP/3 最可靠的方法是使用 Cloudflare 维护的 QUIC 分支，或者等待该功能正式合并到 Nginx 主线中。

以下是基于 Cloudflare QUIC 分支的详细部署步骤：

前提条件

操作系统：本文以 Ubuntu 为例，其他 Linux 发行版步骤类似。
域名与 SSL 证书：需要一个有效的域名和该域名对应的 SSL 证书（例如，从 Let‘s Encrypt 获取）。HTTP/3 强制使用加密。
编译环境：需要安装基本的编译工具和依赖库。
防火墙：确保防火墙开放 UDP 443 端口（HTTP/3 基于 UDP），而不仅仅是 TCP 443（HTTPS）。

第一步：安装必要的依赖库

首先，更新软件包列表并安装编译 Nginx 所需的开发工具和库。

sudo apt update
sudo apt install build-essential mercurial pkg-config \libpcre3-dev zlib1g-dev libssl-dev \git cmake golang

mercurial：Cloudflare 的代码托管在 Mercurial 上，需要此工具来拉取代码。
libssl-dev：提供 SSL/TLS 支持（BoringSSL 或 OpenSSL 需要）。
git, cmake, golang：编译 BoringSSL（QUIC 的加密库）所必需。

第二步：获取并构建 BoringSSL

Nginx 的 QUIC 实现推荐使用 Google 的 BoringSSL 而不是 OpenSSL。

# 1. 创建一个工作目录并进入
mkdir ~/nginx-quic && cd ~/nginx-quic# 2. 克隆 BoringSSL 仓库
git clone https://github.com/google/boringssl.git
cd boringssl# 3. BoringSSL 需要 Go 来编译
mkdir build
cd build
cmake ..
make -j$(nproc) # 使用所有可用的 CPU 核心进行编译# 4. 将编译好的库安装到系统目录
sudo make install

第三步：获取 Nginx QUIC 分支代码

使用 Mercurial 克隆 Cloudflare 的 Nginx QUIC 分支。

# 返回到工作目录根目录
cd ~/nginx-quic# 克隆代码
hg clone -b quic https://hg.nginx.org/nginx-quic

第四步：编译 Nginx

现在配置并编译支持 HTTP/3 的 Nginx。

cd nginx-quic# 运行配置脚本，指定 BoringSSL 路径和其他模块
./auto/configure --with-debug \--with-http_v3_module \          # 启用 HTTP/3 模块--with-http_ssl_module \         # 启用 SSL 模块--with-cc-opt="-I/usr/local/include" \--with-ld-opt="-L/usr/local/lib" \--with-stream_quic_module        # 启用 QUIC 流模块# 编译并安装
make -j$(nproc)
sudo make install

默认安装路径是 /usr/local/nginx/。

第五步：配置 Nginx

关键的一步是修改 Nginx 的配置文件 (/usr/local/nginx/conf/nginx.conf)，在 server 块中启用 HTTP/3。

# 在 http 块中的 server 配置
server {listen       443 ssl;listen       443 quic reuseport; # 关键：启用 QUIC 并开启 reuseport# 你的域名server_name  your_domain.com;# SSL 证书路径（必须）ssl_certificate      /path/to/your/fullchain.pem;ssl_certificate_key  /path/to/your/privkey.pem;# 启用 TLS 1.3，它与 HTTP/3 配合得更好ssl_protocols        TLSv1.2 TLSv1.3;# 告诉浏览器此服务器支持 HTTP/3add_header Alt-Svc 'h3=":443"; ma=86400'; # 重要：端口必须与监听端口一致# 你的网站根目录和其他配置location / {root   html;index  index.html index.htm;}
}

配置说明：

listen 443 quic reuseport;：
- quic：指示 Nginx 在此端口上监听 QUIC（HTTP/3）连接。
- reuseport：为每个工作进程创建一个独立的套接字，显著提升 QUIC 性能。
add_header Alt-Svc：
- 这是浏览器发现服务器支持 HTTP/3 的机制。
- 当浏览器第一次通过 HTTPS（TCP）访问时，Nginx 会在响应头中返回 Alt-Svc，告诉浏览器：“这个站点在 UDP 443 端口也支持 HTTP/3（h3），下次你可以尝试用那个。”
- ma=86400 表示此信息可以缓存 86400 秒（一天）。

第六步：启动 Nginx 并测试

启动 Nginx：
```
sudo /usr/local/nginx/sbin/nginx
```
检查 UDP 443 端口是否监听：
```
sudo ss -lanu | grep 443
```
你应该能看到 Nginx 进程在监听 UDP 443 端口。
使用在线工具测试：
- 访问 https://http3.check
- 输入你的域名进行测试。如果配置成功，它会显示 “HTTP/3 is supported”。
使用浏览器开发者工具检查：
- 用 Chrome 或 Edge 访问你的网站。
- 打开 开发者工具 (F12) -> 网络 (Network) 选项卡。
- 刷新页面。
- 点击域名请求，在 标头 (Headers) 部分查看 protocol 字段。如果显示 h3，则表示此次连接是通过 HTTP/3 进行的。
- 你也可以在响应头中看到 alt-svc 的声明。

常见问题与故障排除

编译错误：最常见的是依赖问题。确保所有依赖库都已正确安装，并且 BoringSSL 的路径正确。
Nginx 启动报错：检查配置文件语法：sudo /usr/local/nginx/sbin/nginx -t。
检测不到 HTTP/3：
- 确保防火墙放行了 UDP 443 端口。
- 清除浏览器缓存，或者尝试使用隐身模式。浏览器可能需要几次 TCP 访问后才会尝试切换到 QUIC。
- 检查 alt-svc 头是否正确发送。可以使用 curl -I https://your_domain.com 查看响应头。
性能调优：QUIC 是一个新的传输协议，可能需要针对你的网络环境调整 keepalive_timeout、stream_quic_required_address 等参数。