在 nginx 中实现多 upstream 的缓存绕过,核心做法是利用 $upstream_cache_status 变量结合 map 指令或 if 判断,根据请求来源、路径或上游返回状态动态决定是否跳过缓存。具体而言,可以通过检查 $upstream_cache_status 是否为 hit 来决定是否将流量转发到备用 upstream,或者通过 x-cache 响应头反向推导缓存命中情况来触发回源逻辑。

如何配置基于缓存命中的主备切换
要实现当主 upstream 缓存命中时直接返回,未命中时则尝试备用 upstream,需要利用 $upstream_cache_status 变量进行条件判断。这种模式通常用于构建一个带有“缓存穿透保护”或“降级策略”的系统,确保在缓存失效时能自动从备用服务获取最新数据。

http {
# 定义两个 upstream
upstream primary {
server 10.0.0.1:80;
}
upstream backup {
server 10.0.0.2:80;
}
# 缓存区域配置
proxy_cache_path /tmp/cache levels=1:2 keys_zone=my_cache:10m;
server {
listen 80;
location /api/ {
# 设置缓存键,例如基于 URI
proxy_cache my_cache;
proxy_cache_key $uri;
# 关键逻辑:如果缓存命中 (HIT),则直接返回;
# 如果未命中 (MISS, EXPIRED, UPDATING) 或无缓存,则尝试备用 upstream
if ($upstream_cache_status = HIT) {
break;
}
# 如果未命中,重定向或代理到备用 upstream
# 注意:Nginx 原生不支持直接“切换” upstream 上下文,
# 通常做法是设置一个内部变量,然后在后续 proxy_pass 中使用
set $target_upstream 'backup';
# 重新评估 proxy_pass
proxy_pass http://$target_upstream;
}
}
}
上述配置中,proxy_cache 定义了缓存存储位置。当请求进入 /api/ 时,Nginx 首先检查缓存。如果 $upstream_cache_status 为 HIT,break 指令会终止当前重写阶段,直接返回缓存内容。如果状态不是 HIT(例如 MISS),则执行 set 指令将 $target_upstream 设置为 backup,随后 proxy_pass 使用这个变量指向备用服务器。这种方式实现了简单的基于缓存状态的故障转移或降级。
如何通过 X-Cache 头实现客户端侧的缓存感知路由
另一种场景是希望客户端或前端网关能够感知缓存状态,从而决定重试或刷新。这可以通过在响应中添加自定义头或利用现有的 X-Cache 头来实现。虽然 Nginx 不直接支持基于响应头的复杂路由决策,但可以通过 add_header 暴露缓存状态,供外部系统处理。
以数据形式体验爵士乐。AI代理流式处理和声分离、色度、音网。误差纳入已测量。

http {
upstream backend {
server 10.0.0.1:80;
}
proxy_cache_path /tmp/cache levels=1:2 keys_zone=my_cache:10m;
server {
listen 80;
location /api/ {
proxy_cache my_cache;
proxy_cache_key $uri;
# 添加缓存状态头,便于客户端或中间件识别
add_header X-Cache-Status $upstream_cache_status;
# 可选:添加缓存过期时间头
add_header Cache-Control "public, max-age=3600";
proxy_pass http://backend;
}
}
}
在这个配置中,add_header X-Cache-Status $upstream_cache_status 会将缓存状态(如 HIT, MISS, BYPASS)添加到 HTTP 响应头中。客户端或前置网关可以读取这个头,如果看到 MISS,可以选择发起新的请求、显示加载状态或触发特定的错误处理逻辑。这种方法将缓存感知的责任部分转移到了应用层,适用于需要更精细控制缓存行为的分布式系统。
当 upstream 返回 502 时缓存如何处理
当配置的 upstream 服务器不可达或返回错误(如 502 Bad Gateway)时,Nginx 的缓存行为取决于 proxy_cache_valid 和 proxy_cache_use_stale 的配置。默认情况下,如果 upstream 返回错误,Nginx 不会使用缓存,而是将错误传递给客户端。但是,通过启用 proxy_cache_use_stale,可以在特定错误条件下返回过期的缓存内容,从而提高系统的可用性。
http {
upstream backend {
server 10.0.0.1:80;
}
proxy_cache_path /tmp/cache levels=1:2 keys_zone=my_cache:10m;
server {
listen 80;
location /api/ {
proxy_cache my_cache;
proxy_cache_key $uri;
# 允许在以下错误情况下使用 stale 缓存
proxy_cache_use_stale error timeout invalid_header updating
http_500 http_502 http_503 http_504;
# 设置 stale 缓存的超时时间,例如 1 小时
proxy_cache_stale_timeout 3600;
proxy_pass http://backend;
}
}
}
在此配置中,proxy_cache_use_stale 指定了当遇到 error, timeout, 或 HTTP 5xx 错误时,Nginx 可以返回旧的缓存副本。这意味着即使后端服务完全宕机,只要之前有成功的缓存记录,用户仍然能看到页面内容,尽管可能不是最新的。这对于提高高可用性和用户体验至关重要。需要注意的是,proxy_cache_stale_timeout 定义了 stale 缓存的有效期限,超过这个时间后,即使没有后端服务,也不会再提供 stale 内容。

















