Table of Contents

HTTP/3（QUIC）启用

HTTP/3 让 QUIC 客户端在同一端口号的 UDP 面上获得 0-RTT 与连接迁移能力。 平台的 H3 形态＝同端点直启：TCP 面照常服务 h1/h2-over-TLS，UDP 面由 MsQuic 直绑同一端口号——不是两个端口，也不是代理层转换。

前提

  • 运行 OS 支持 QUIC（QuicListener.IsSupported）——不支持时启动 fail-fast（退出码 10）， 把问题暴露在引导期而不是首笔 H3 流量；
  • H3 强制 TLS——listener 必须已配置 tls 块，否则编译拒绝（422）；
  • Alt-Svc 由 Kestrel 原生自动播发，客户端经 h1/h2 首连后自动升级 H3，无需额外配置。

启用方式：双轨决策

轨 写法 适用
部署级声明 worker.json http3: true 集群 DP 新卷冷启动时明确声明
发布态侦测 不声明（缺省 null） 单卷 standalone——启动时扫描 listener，发现 http3: true 即启用 UDP 面

listener 声明

{
  "port": 5443,
  "protocol": "http",
  "http3": true,
  "tls": {
    "default": { "certPath": "/etc/traffic/certs/default.pfx" },
    "sni": [
      { "hostSuffix": ".shop.example.com", "cert": { "certPath": "/etc/traffic/certs/shop.pfx" } }
    ]
  }
}

TLS/SNI 证书映射与 TCP 面共用（QUIC 握手＝TLS 1.3；SNI 选证同源）—— 详见TLS 与 SNI。

与 QUIC 直通的互斥

同端口声明 结果
http3: true（终止） UDP 面 H3 终止＋进路由管线
quicRules[]（直通） UDP 面按 SNI 后缀转交 UDP 目标
两者同口 编译拒绝（唯一性裁决） 
{ "port": 5443, "protocol": "tcp",
  "quicRules": [ { "sni": ".media.example.com", "target": "10.0.5.7:8443" } ] }

防火墙清单

启用 H3 的端口必须同时放行 TCP＋UDP 同号——只放行 TCP 时客户端 降级到 h2（功能不损，但 H3 不生效）。

观测

  • quic.handshake_ok——连接准入；
  • quic.handshake_fail——SNI 选证失败等（证书配置错误的现场）；
  • 版本协商状态 MsQuic 不外显，指标面如实留位。

指标消费见可观测。

Edit this page