黄兵的个人博客

Docker 部署支持 HTTP/3（QUIC）的 Nginx

你想用 Docker 部署支持 HTTP/3（QUIC）的 Nginx，这其实是最干净、最推荐的方式。
因为不用自己编译、不污染系统环境。

下面我会一步步教你部署一份：
✅ 支持 HTTP/3 (QUIC)
✅ 支持 HTTP/2 与 Brotli
✅ 可直接挂载证书
✅ 自动兼容常规 HTTPS 访问

🧱 一、基础前提

确保你机器上安装好了 Docker：

docker -v

如果还没有，先安装：

sudo apt update
sudo apt install docker.io -y

🚀 二、使用官方 nginx-quic 镜像（推荐）

Nginx 官方并没有在主仓库中提供 QUIC 支持的镜像，
但 nginx-quic 是官方实验性分支，有官方构建的 Docker 镜像可直接使用。

1️⃣ 拉取镜像

docker pull macbre/nginx-http3:latest

来源：https://github.com/nginx/nginx-quic

这是 Nginx 官方 GitHub 仓库自动构建的 HTTP/3 版本镜像，稳定可靠。

2️⃣ 创建目录结构

mkdir -p ~/nginx-quic/{conf,certs,html}

放置：

• ~/nginx-quic/conf/default.conf → Nginx 配置

• ~/nginx-quic/certs/ → 证书文件（fullchain.pem 和 privkey.pem）

• ~/nginx-quic/html/ → 静态文件

3️⃣ 示例配置文件 ~/nginx-quic/conf/default.conf

server {
    listen 443 ssl http2;
    listen 443 quic reuseport;
    listen [::]:443 ssl http2;
    listen [::]:443 quic reuseport;

    server_name example.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    ssl_protocols       TLSv1.3;
    ssl_early_data      on;

    add_header Alt-Svc 'h3=":443"; ma=86400';
    add_header QUIC-Status $quic;

    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

4️⃣ 启动容器

docker run -d \
  --name nginx-quic \
  -p 80:80 \
  -p 443:443/udp \
  -p 443:443/tcp \
  -v ~/nginx-quic/conf:/etc/nginx/conf.d \
  -v ~/nginx-quic/certs:/etc/nginx/certs \
  -v ~/nginx-quic/html:/usr/share/nginx/html \
  macbre/nginx-http3:latest

⚠️ 注意：
QUIC 使用 UDP 协议，因此必须开放 UDP 443 端口（-p 443:443/udp）。

5️⃣ 验证 HTTP/3 是否生效

浏览器访问 https://example.com
然后打开开发者工具 → Network → Protocol 列。

如果显示为：

h3

则表示 HTTP/3 已启用 ✅

你也可以命令行验证：

curl -I --http3 https://example.com

出现 HTTP/3 200 即成功。

Docker 里的 Nginx 如何加载多个 .conf 配置文件？

🧱 一、目录结构复习

之前创建的目录是这样的：

~/nginx-quic/
├── conf/
│   └── default.conf
├── certs/
│   ├── fullchain.pem
│   └── privkey.pem
└── html/
    └── index.html

容器启动命令里这行是关键：

-v ~/nginx-quic/conf:/etc/nginx/conf.d

这表示你 宿主机的 ~/nginx-quic/conf 目录 会映射到 容器里的 /etc/nginx/conf.d/。
Nginx 会自动加载该目录下所有 .conf 文件。

🧩 二、添加多个站点配置（最简单方法）

例如你想添加两个网站：

• example.com

• test.example.com

你只需要在本地 ~/nginx-quic/conf/ 下创建两个配置文件：

cd ~/nginx-quic/conf

# 创建第一个网站配置
nano example.com.conf

内容如下：

server {
    listen 443 ssl http2;
    listen 443 quic reuseport;
    server_name example.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    root /usr/share/nginx/html/example;
    index index.html;
}

然后创建第二个：

server {
    listen 443 ssl http2;
    listen 443 quic reuseport;
    server_name test.example.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    root /usr/share/nginx/html/test;
    index index.html;
}

📁 三、准备对应网页目录

在宿主机创建对应的内容目录：

mkdir -p ~/nginx-quic/html/example ~/nginx-quic/html/test
echo "This is example.com" > ~/nginx-quic/html/example/index.html
echo "This is test.example.com" > ~/nginx-quic/html/test/index.html

🔄 四、重新加载容器配置

你不需要重新构建容器，只要让它重新加载配置即可：

docker exec -it nginx-quic nginx -t

✅ 如果提示 syntax is ok，说明语法没问题。

然后：

docker exec -it nginx-quic nginx -s reload

Nginx 会自动加载你新加的 .conf 文件。

访问 https://example.com 和 https://test.example.com，就能看到不同内容。

🧰 五、常用命令汇总

💡 六、小贴士

1. 不要修改 /etc/nginx/nginx.conf，Docker 官方镜像默认会自动加载 /etc/nginx/conf.d/*.conf。

2. 文件扩展名必须是 .conf，否则不会被加载。

3. 可以把每个站点一个 .conf 文件，这样最清晰。

4. 如果你未来用 docker-compose.yml 管理，这个映射方式完全一样。