在 nginx 中配置按请求头区分缓存,核心做法是启用 proxy_cache_key 并引用对应的 $http_ 变量。通过修改缓存键的组成,nginx 会将带有不同请求头值的请求视为不同的资源,从而生成独立的缓存文件。例如,将 $http_accept_language 加入缓存键,即可实现基于语言偏好的内容隔离。

如何配置缓存键以包含自定义 Header
要实现这一功能,需要在 location 块中设置 proxy_cache_key。默认情况下,Nginx 仅使用 URL、proxy_cache_key 和 $scheme 作为键。若需区分特定请求头,只需将其追加到该指令的值中。Nginx 会自动处理变量为空的情况,但为了安全起见,建议对可能为空的头部进行判断或使用默认值,防止产生大量空键缓存。

server {
listen 80;
server_name example.com;
# 定义缓存路径和参数
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;
location /api/data {
proxy_pass http://backend_server;
# 启用缓存
proxy_cache my_cache;
# 关键配置:将 Accept-Language 加入缓存键
# 如果 header 缺失,使用 'default' 作为 fallback
proxy_cache_key "$scheme$host$request_uri$http_accept_language";
# 设置缓存过期时间
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
# 传递必要的头部给后端(可选,视后端需求而定)
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
上述配置中,proxy_cache_key 由四部分组成:$scheme(协议)、$host(域名)、$request_uri(请求路径及查询字符串)以及 $http_accept_language(Accept-Language 请求头)。当用户发送 Accept-Language: zh-CN 时,生成的缓存键与发送 Accept-Language: en-US 时完全不同,Nginx 会分别存储两份响应。若请求中未携带该头部,$http_accept_language 将为空字符串,导致所有无此头部的请求共享同一个缓存条目。为避免这种情况,可在应用层或 Nginx 中使用 if 或 map 指令提供默认值,或者确保客户端始终发送该头部。
如何处理多 Header 组合导致的缓存爆炸
当需要同时依据多个请求头(如 Accept-Encoding 和 Accept-Language)来区分缓存时,缓存键的组合数量会呈指数级增长。这可能导致缓存目录中文件过多,即“缓存爆炸”问题。解决思路是评估哪些头部真正影响内容差异,并限制参与缓存键计算的头部数量。通常,只有直接影响响应体内容的头部才应纳入缓存键。

# 在 http 块中定义 map,用于规范化头部值
# 避免大小写或细微差异导致缓存碎片化
map $http_accept_encoding $cache_enc {
default "gzip";
"gzip, deflate" "gzip";
"identity" "none";
}
server {
listen 80;
server_name example.com;
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;
location /api/data {
proxy_pass http://backend_server;
proxy_cache my_cache;
# 组合多个规范后的头部
proxy_cache_key "$scheme$host$request_uri$cache_enc$http_accept_language";
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
}
}
在第二个示例中,我们引入了 map 指令来标准化 Accept-Encoding 的值。原始请求头可能包含 gzip, deflate, br 等复杂组合,直接将其放入缓存键会导致每个变体都生成一个缓存文件。通过 map 将其映射为简化的标识符(如 gzip),可以显著减少缓存键的数量。最终缓存键结合了标准化的编码类型和语言偏好。这种设计既保证了内容分发的准确性,又控制了缓存存储的增长。开发者应根据实际业务需求,选择必要的头部进行组合,并定期监控缓存命中率与磁盘使用情况。
当请求头缺失时缓存行为如何表现
在之前的配置中,如果客户端未发送 Accept-Language 头部,$http_accept_language 变量的值为空。此时,所有缺少该头部的请求都会匹配同一个缓存键,即 httpexample.com/api/data。这意味着第一个到达的请求会被缓存,后续相同 URL 但无该头部的请求将直接命中该缓存,而不会向后端发起新请求。这种行为在某些场景下是期望的,但在其他场景下可能导致内容不一致。例如,如果后端根据是否携带该头部返回不同的错误码或默认内容,则可能出现偏差。
为了验证这一行为,可以使用 curl 命令进行测试。首先发送带头的请求,然后发送不带头的请求,观察响应来源。在实际部署前,建议通过 proxy_cache_key 的日志记录或调试模式确认键的生成逻辑。若发现缓存命中率异常低或内容错乱,应检查是否有未预期的头部参与了键的计算,或考虑使用 proxy_no_cache 和 proxy_cache_bypass 指令对特定条件进行豁免。


















