关键不是自动降级,而是确保缓存有旧内容、Nginx明确允许复用、链路稳定命中;需配置proxy_cache_use_stale http_502 http_504、proxy_cache_valid 502 504 1m、稳定cache_key,并配合background_update与cache_lock实现边服务边更新。

后端返回 502 或 504 时启用陈旧缓存兜底,关键不是让 Nginx “自动降级”,而是提前确保:缓存里有可用的旧内容、Nginx 明确知道哪些错误允许复用它、且整个链路能稳定命中并返回。
只对可信的 502/504 启用 stale
502(Bad Gateway)和 504(Gateway Timeout)是后端网关或上游服务明确发出的失败信号,语义清晰、误判率低,适合纳入 stale 触发条件:
- 写入 proxy_cache_use_stale http_502 http_504; —— 这是最精简、最稳妥的配置
- 不加
error或timeout:连接中断或读超时可能是瞬时抖动,盲目启用 stale 容易把本可恢复的请求也降级 - 如需后台静默刷新,可追加
updating,但必须同步开启 proxy_cache_background_update on;
让 502/504 响应本身进缓存
stale 不生成缓存,只复用已存在的过期条目。如果 502/504 根本没被缓存过,后续就无“旧内容”可返:
- 添加 proxy_cache_valid 502 504 1m; —— 确保这类响应也会落盘,哪怕只存 1 分钟
- 配合常规状态码缓存,例如:
proxy_cache_valid 200 301 302 10m; - 避免缓存键含动态字段,推荐使用 proxy_cache_key "$scheme$host$request_uri";
验证是否真走 stale 路径
不能只看返回状态码,要确认用户实际拿到的是旧内容:
- 停掉 upstream 后发起请求,响应头中出现 X-Cache: STALE(需提前配置
add_header X-Cache $upstream_cache_status;) - 响应体与故障前完全一致,不是空页、不是默认 502 页面、也不是 JSON 结构错乱
- 响应耗时远低于
proxy_read_timeout(比如设为 5s,实测返回在 30–80ms),说明确实跳过了回源
搭配 background_update 实现边服务边更新
返回陈旧内容只是第一步,真正提升体验的是无缝过渡到新数据:
- 开启 proxy_cache_background_update on; —— 返回 stale 的同时,Nginx 自动发起异步子请求拉取新响应
- 配合 proxy_cache_lock on; 和 proxy_cache_lock_timeout 3s; —— 防止多个并发请求同时触发回源,造成上游压力
- 二者缺一不可:没有 background_update,updating 条件永不满足;没有 cache_lock,高并发下可能刷爆上游


















