在搭建支持 HTTP/3 的回源链路时，Nginx 作为反向代理不仅需要处理客户端侧的 QUIC 连接，还要以 HTTP/3 协议回源到上游服务。此时头部压缩机制从 HTTP/2 的 HPACK 切换为 QPACK。QPACK 引入动态表的概念，允许两端在连接内记住已发送的请求头字段，后续仅需发送索引即可。Nginx 的 ngx_http_v3_module 提供了相关指令来控制回源时的 QPACK 行为，而日志则是观察动态表实际运行状态的主要窗口。
QPACK 动态表在回源场景中的基本原理
QPACK 动态表与 HPACK 动态表最大的区别在于它允许乱序处理。在 HTTP/3 基于 QUIC 的可靠流与不可靠数据报混合传输中，头部块可能引用尚未被对端确认插入的动态表项，因此 QPACK 设计了严格的编码规则和阻塞机制。当 Nginx 以 HTTP/3 回源时，它会作为 QPACK 解码端接收上游的动态表更新指令，同时也作为编码端将客户端请求头压缩后发给上游。动态表容量由指令 http3_max_field_size 与连接级设置共同约束。
在实际回源中，如果上游服务频繁变更响应头或请求头集合很大，动态表会产生大量插入与逐出操作。Nginx 默认的动态表大小通常足够中小流量使用，但在多租户回源网关中容易因为表满而退化为只使用静态表，失去压缩收益。我们可以通过日志中的 $http3_qpack_sent 与内部调试变量观察表命中率。理解这一原理能帮助我们在日志中发现“动态表未命中”是否由容量不足引起，而非网络问题。
另一个容易忽视的点是 QPACK 动态表与连接绑定。QUIC 连接迁移或 0-RTT 恢复并不会保留动态表状态，因此回源日志里偶尔出现动态表重置属于正常行为。若错误日志频繁报出 QPACK 解码错误，往往意味着上下游实现存在兼容偏差，例如某一方发送了超过对方最大表容量的增量。下面用一段配置展示如何显式设定回源 HTTP/3 与表大小。
http {
# 开启回源 HTTP/3 支持
upstream backend {
server 192.168.0.1:443;
# 使用 quic 作为回源协议
# 需要在 proxy_pass 中指定 https 且开启 http3
}
server {
listen 443 quic;
http3 on;
location / {
proxy_pass https://backend;
# 指定回源使用 HTTP/3
proxy_http_version 3;
# 设置 QPACK 动态表最大尺寸（字节）
http3_max_table_size 4096;
# 记录 qpack 相关变量到日志
access_log /var/log/nginx/back.log main_qpack;
}
}
log_format main_qpack '$remote_addr - $http3_qpack_sent - $http3_qpack_recv';
}
如何在 Nginx 中配置回源并激活动态表
要让 Nginx 真正以 HTTP/3 回源并启用 QPACK 动态表，核心是指令 proxy_http_version 3 与编译时包含 ngx_http_v3_module。默认 Nginx 包可能未编译该模块，需要自行构建或在商业版中开启。激活后，Nginx 会在回源 QUIC 连接上协商 QPACK 参数，动态表尺寸由 http3_max_table_size 控制，该值需小于等于上游支持的最大值，否则上游会发送 Limit 指令截断。
配置时建议将动态表日志单独拆分。因为默认 combined 格式不含 QPACK 变量，我们需要在 log_format 中加入 $http3_qpack_sent 等内部变量。这些变量记录当前连接动态表编码已发送的字节数或条目数，借此可计算压缩比。若发现 sent 值极小而头部原始体积大，说明动态表几乎没有命中，可能上游每次都要求表刷新。
此外，在回源 TLS 配置中必须启用 ALPN 包含 h3，否则 QUIC 握手后会回退到 HTTP/2 或 HTTP/1.1，QPACK 自然不会生效。以下片段展示最小可用回源配置，并配合 error_log 的 debug 级别捕获 QPACK 事件。注意生产环境不要长期开 debug，否则日志量巨大。
server {
listen 443 ssl quic;
ssl_protocols TLSv1.3;
ssl_alpn h3,http/1.1;
location /api/ {
proxy_pass https://192.168.0.1:443;
proxy_http_version 3;
http3_max_table_size 8192;
http3_max_blocked_streams 100;
access_log /var/log/nginx/qpack.log qpackfmt;
}
}
log_format qpackfmt '$time_local $host $http3_qpack_sent $http3_qpack_recv $request_length';
error_log /var/log/nginx/err.log debug;
从 Nginx 日志中分析 QPACK 动态表运行状态
当回源链路运行一段时间后，我们可以通过访问日志与错误日志交叉分析动态表健康度。访问日志里自定义的 $http3_qpack_sent 代表 Nginx 作为编码端向下游发送的动态表相关字节，若其值随请求重复头部增加而下降，说明动态表命中正在降低传输量。相反，若该值居高不下，可能是上游不支持复用或表被频繁清空。
错误日志在 debug 级别会输出类似 “QPACK decoder stream error” 或 “dynamic table size update ignored” 的条目。前者通常意味着收到的头部块引用了不存在的动态表索引，属于实现 bug 或版本错配；后者则说明我们设置的 http3_max_table_size 超过上游公告值，Nginx 主动忽略更新以维持协议一致。这类信息不会出现在普通 error 级别，因此排障时需临时调低级别。
还可以写一个简单的脚本定期抽取日志计算压缩效率。例如用 awk 统计单位时间内的 $http3_qpack_sent 总和与 $request_length 总和，得出平均头部压缩率。如果发现压缩率低于百分之二十，应检查是否所有回源请求都携带了完全不同的请求头（如大量随机 trace id），这种情况下动态表收益本就有限，不必强行调大表尺寸。下面给出一个日志分析示例脚本。
#!/bin/bash
# 简单分析 qpack 日志压缩率
LOG=/var/log/nginx/qpack.log
awk '{
sent+=$3;
recv+=$4;
req+=$5;
n++;
}
END {
if (n>0) {
print "平均动态表发送字节:", sent/n;
print "平均原始请求长度:", req/n;
print "估算压缩率:", (1 - (sent+recv)/req) * 100 "%";
}
}' $LOG
最后需要提醒，QPACK 动态表日志只是回源性能的一环。若 QUIC 连接本身存在大量丢包，动态表更新指令迟到也会导致编码端阻塞，表现为请求延迟突增但日志中动态表条目正常。此时应结合 quic 层统计与 QPACK 日志共同判断，避免单看头部压缩而忽略传输层问题。