版本：3.19.0

配置客户端和 APISIX 之间的 HTTP/3 QUIC

HTTP/3 是超文本传输协议 (HTTP) 的第三个主要版本。与依赖 TCP 的前身不同，HTTP/3 基于 QUIC (Quick UDP Internet Connections) 协议。它带来了多项好处，共同导致延迟降低和性能提高：

实现不同网络连接之间的无缝转换，例如从 Wi-Fi 切换到移动数据。
消除队头阻塞，使丢失的数据包不会阻塞所有流。
在 TLS 握手的同时协商 TLS 版本，从而实现更快的连接。
默认提供加密，确保通过 HTTP/3 连接传输的所有数据都受到保护和保密。
在与客户端已建立连接的服务器通信时提供零往返时间 (0-RTT)。

APISIX 目前支持下游客户端和 APISIX 之间的 HTTP/3 连接。尚不支持与上游服务的 HTTP/3 连接。

警告

此功能目前处于实验阶段，不建议用于生产环境。

本指南将向你展示如何配置 APISIX 以启用客户端和 APISIX 之间的 HTTP/3 连接。

前置条件

安装 Docker。
安装 static-curl 或其他支持 HTTP/3 的 curl。
按照快速入门教程在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。
安装 jq 将 PEM 文件编码为 JSON 字符串。
如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 ADMIN_API_KEY。请在 deployment.admin.admin_key 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

在 APISIX 中启用 HTTP/3

将完整的当前 config.yaml 复制到宿主机并保留备份：

docker cp apisix-quickstart:/usr/local/apisix/conf/config.yaml ./config.yaml
cp ./config.yaml ./config.yaml.backup

在本地 config.yaml 中，更新 apisix.ssl.listen 下端口 9443 的监听器；如果该监听器不存在，请将其添加到现有列表中。以下内容只是配置片段，而非完整替换文件：

apisix:
  ssl:
    listen:
      - port: 9443
        enable_http3: true

保留现有的 Admin API 身份验证、白名单、etcd 和插件设置。请勿添加第二个 apisix 或 ssl 映射。将候选文件复制到容器中，然后进行验证，仅在验证成功后重新加载 APISIX：

docker cp ./config.yaml apisix-quickstart:/usr/local/apisix/conf/config.yaml
docker exec apisix-quickstart apisix test && \
  docker exec apisix-quickstart apisix reload

如果验证失败，请先恢复备份，再进行其他更改：

docker cp ./config.yaml.backup apisix-quickstart:/usr/local/apisix/conf/config.yaml

在 HTTP/3 验证成功之前，请保留该备份。

生成证书和密钥

HTTP/3 需要 TLS。你可以购买证书或自行生成证书，视情况而定。

要自行生成，首先生成证书颁发机构 (CA) 密钥和证书：

openssl genrsa -out ca.key 2048 && \
  openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \
  openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt

接下来，为 APISIX 生成通用名称为 test.com 的密钥和证书，并使用 CA 证书进行签名：

openssl genrsa -out server.key 2048 && \
  openssl req -new -sha256 -key server.key -out server.csr -subj "/CN=test.com" && \
  openssl x509 -req -days 36500 -sha256 -extensions v3_req \
  -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \
  -in server.csr -out server.crt

配置 HTTPS

创建 SSL 对象，并将 SNI 设置为与证书通用名称 test.com 匹配。jq 会读取证书和私钥文件，并将其中的换行符编码为有效 JSON：

jq -n --rawfile cert server.crt --rawfile key server.key \
  '{id: "quickstart-tls-client-ssl", sni: "test.com", cert: $cert, key: $key}' \
  | curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT \
    -H "X-API-KEY: ${ADMIN_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-binary @-

在 APISIX 中创建路由

创建一个指向 httpbin.org 的示例路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "id":"httpbin-route",
  "uri":"/get",
  "upstream": {
    "type":"roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

验证客户端和 APISIX 之间的 HTTP/3 连接

向路由发送请求：

curl -kv --http3-only \
  -H "Host: test.com" \
  --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/get"

你应该收到类似以下的 HTTP/3 200 响应：

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* QUIC cipher selection: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
* Skipped certificate verification
* Connected to test.com (127.0.0.1) port 9443
* using HTTP/3
* [HTTP/3] [0] OPENED stream for https://test.com:9443/get
* [HTTP/3] [0] [:method: GET]
* [HTTP/3] [0] [:scheme: https]
* [HTTP/3] [0] [:authority: test.com]
* [HTTP/3] [0] [:path: /get]
* [HTTP/3] [0] [user-agent: curl/8.7.1]
* [HTTP/3] [0] [accept: */*]
> GET /get HTTP/3
> Host: test.com
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/3 200
...
{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "0",
    "Host": "test.com",
    "User-Agent": "curl/8.7.1",
    "X-Amzn-Trace-Id": "Root=1-6656013a-27da6b6a34d98e3e79baaf5b",
    "X-Forwarded-Host": "test.com"
  },
  "origin": "172.19.0.1, 123.40.79.456",
  "url": "http://test.com/get"
}
* Connection #0 to host test.com left intact

下一步

你已了解如何配置客户端和 APISIX 之间的 HTTP/3。与上游服务的 HTTP/3 连接尚不支持，欢迎任何贡献。

前置条件​

在 APISIX 中启用 HTTP/3​

生成证书和密钥​

配置 HTTPS​

在 APISIX 中创建路由​

验证客户端和 APISIX 之间的 HTTP/3 连接​

下一步​