Nginx后端故障时秒级返回需配置proxy_cache为可验证降级通路:定义cache区、启用区域、固定cache_key、缓存5xx响应;开启proxy_cache_use_stale指定四类HTTP错误;配合background_update、cache_lock防击穿;通过X-Cache: STALE及响应一致性验证生效。

要让 Nginx 在后端挂掉时仍能秒级返回可用内容,关键不是“凑合用旧数据”,而是把 proxy_cache 配置成一条可验证、可预期的降级通路。陈旧缓存(stale cache)不是兜底补丁,而是一条提前铺好的应急车道。
必须配齐的四个基础项
stale 生效的前提是缓存真实存在、能稳定命中、且过期后仍被认可。缺一不可:
-
定义缓存区:在
http块中声明proxy_cache_path,例如:proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off; -
启用缓存区域:在
location中通过proxy_cache my_cache挂载,不能只写proxy_cache_valid却没引用区域 -
固定缓存键:使用稳定、无随机参数的
proxy_cache_key,推荐:proxy_cache_key "$scheme$host$request_uri";
避免含$cookie_、$arg_t=、时间戳等易变字段 -
缓存 5xx 响应本身:加这一行,否则错误响应根本进不了缓存:
proxy_cache_valid 500 502 503 504 1m;
精准打开 stale 开关
只对可信的后端故障信号启用 stale,不扩大范围:
- 明确写入:
proxy_cache_use_stale http_500 http_502 http_503 http_504;
这四类是源站主动返回的语义明确错误,比error或timeout更可靠 - 如需后台悄悄刷新,追加
updating,但必须同步开启:proxy_cache_background_update on; - 防缓存失效瞬间并发击穿,建议加上:
proxy_cache_lock on;<br>proxy_cache_lock_timeout 3s;
从用户侧验证是否真生效
别信配置文件,要看真实请求反馈:
- 停掉上游服务后发请求,响应头中出现:
X-Cache: STALE(需提前配add_header X-Cache $upstream_cache_status;) - 响应体与故障前完全一致,不是空页、不是 Nginx 默认 502 页面
- 耗时应在几十毫秒内(比如
proxy_read_timeout 3s,实测返回
配套体验升级动作
返回旧内容只是起点,做到“用户无感更新”才算完整:
- 开启
proxy_cache_background_update on:stale 返回的同时,Nginx 自动异步拉新数据更新缓存 - 对核心接口,可暴露带签名的刷新入口(如
/cache/refresh?path=/api/product&sig=xxx),供运维手动触发 - 前端可配合加一层轻量 fallback UI,比如显示“内容已缓存,正在刷新…”提示,提升感知友好度











