如何让你的.NET WebAPI程序支持HTTP3？
内容提要
本文总结了构建Http3的经验，以Token Gateway项目为例。文章介绍了使用Http3的限制和配置步骤，包括动态加载证书、配置Kestrel监听端口和协议、构建Docker镜像等。还提到了一些注意事项，如浏览器支持QUIC和服务器防火墙开启UDP。文章提供了开源地址和技术交流群。
延伸解读
HTTP/3 的协议协商与降级机制
文章指出，Kestrel 配置 Http1AndHttp2AndHttp3 后会自动协商协议：若客户端不支持 HTTP/3 则降级至 HTTP/2，再降级至 HTTP/1。浏览器首次请求通常使用 HTTP/1 或 HTTP/2，服务器通过响应头 Alt-Svc 告知支持 HTTP/3，后续请求才会尝试 h3。因此，首次访问看不到 h3 协议是正常现象，需关注 Alt-Svc 头是否返回。
Docker 部署中的 UDP 端口映射与权限
由于 HTTP/3 基于 UDP，Docker 默认只监听 TCP，因此部署时必须同时映射 TCP 和 UDP 端口，例如 8081:8081/tcp 和 8081:8081/udp。此外，构建镜像需 root 权限安装 libmsquic，运行容器时若映射目录权限不足，可能导致 SQLite 文件创建失败，进而登录失败。这些是实际部署中容易忽略的细节。
证书与 Alt-Svc 端口一致性要求
HTTP/3 强制使用 HTTPS，文章通过 ServerCertificateSelector 实现动态加载证书，并强调证书文件必须存在，否则抛出异常。同时，Alt-Svc 头中的端口必须与前端访问端口一致，例如 Alt-Svc:h3=":8081"; ma=86400 要求访问时使用 8081 端口，否则浏览器不会使用 HTTP/3。自签证书似乎无法生效，需使用受信任的证书。
Q&A
在Windows上使用HTTP/3需要满足哪些系统要求？
需要Windows 11版本22000或更高版本，或Windows Server 2022，并且需要TLS 1.3或更高版本的连接。
如何在Kestrel中配置端口以同时支持HTTP/1、HTTP/2和HTTP/3？
在Kestrel的监听配置中，将端口的Protocols属性设置为HttpProtocols.Http1AndHttp2AndHttp3，并调用UseHttps()强制使用HTTPS。例如：kestrel.ListenAnyIP(8081, portOptions => { portOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3; portOptions.UseHttps(); });
为什么Docker镜像中需要安装libmsquic？如何安装？
因为微软提供的默认ASP.NET Core镜像不包含libmsquic，而HTTP/3在Linux上依赖它。需要在Dockerfile中以root用户身份安装，例如：USER root，然后运行apt-get update && apt-get install -y libmsquic。
部署HTTP/3服务时，Docker端口映射需要注意什么？
由于HTTP/3基于UDP，而Docker默认使用TCP，因此需要同时映射UDP和TCP端口。例如在docker-compose中，对8081端口需分别映射为8081:8081/udp和8081:8081/tcp。
浏览器如何从HTTP/2降级或升级到HTTP/3？Alt-Svc头的作用是什么？
浏览器首次请求时会使用HTTP/1或HTTP/2，如果服务器支持HTTP/3，会在响应头中返回Alt-Svc值（如Alt-Svc: h3=":8081"; ma=86400），浏览器后续请求便会尝试使用HTTP/3。如果HTTP/3不可用，则会降级到HTTP/2或HTTP/1。
使用HTTP/3时，有哪些常见的注意事项？
需要确认浏览器支持并开启QUIC，检查服务器防火墙是否开放UDP端口，同时确保Alt-Svc头中的端口与前端访问端口一致，否则不会使用HTTP/3。
