proxy_cache_use_stale 的作用是当 upstream 返回 502/503/504 或连接错误时，返回过期缓存而非错误响应；需配合缓存配置、稳定 cache_key、5xx 缓存策略及 background_update 等机制共同生效。
proxy_cache_use_stale 的作用不是“规避报错”，而是让 Nginx 在 upstream 已经报错（如 502/503）、连接失败或超时的情况下，不把错误透传给用户，而是返回本地已有的过期缓存内容，从而避免服务中断。它生效的前提是：缓存存在、能命中、且被允许复用——不是故障发生后才补救，而是在正常时期就配好。
关键触发条件要精准匹配 upstream 报错类型
upstream 报错有不同表现形式，需按实际故障特征选参数，避免误触发：
-
http_502 http_503 http_504：后端明确返回这些状态码时启用，覆盖网关错误、服务不可用、网关超时等典型崩溃信号 -
error：适用于 upstream 直接拒绝连接、连接重置（connection reset）、DNS 失败等底层中断场景 - 不建议加
timeout：单次读超时可能是瞬时抖动，非真正宕机，加入后易把本可成功的请求也降级 - 不建议加
http_500：除非你确认后端在崩溃前会主动返回 500；多数情况是直接断连，不会返回 500
推荐配置：
proxy_cache_use_stale error http_502 http_503 http_504;
缓存本身必须“存得住、找得准、用得上”
stale 只是“能否用”，不是“有没有”。以下三点缺一不可：
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
缓存区已定义且启用：
proxy_cache_path /var/cache/nginx/mycache levels=1:2 keys_zone=mycache:128m inactive=1h use_temp_path=off;
并在 location 中引用：proxy_cache mycache;cache_key 必须稳定：
避免含$time_iso8601、$request_id、?t=、?v=等动态字段。推荐：proxy_cache_key "$scheme$host$request_uri";5xx 响应必须进缓存：
否则 upstream 返回 503 时，Nginx 根本不存，后续 stale 就无数据可返：proxy_cache_valid 502 503 504 1m;
同时确保主响应也有合理有效期：proxy_cache_valid 200 301 302 10m;
配合后台更新与并发控制提升可用性
单纯返回旧内容只是起点，还需防止雪崩和静默刷新：
开启异步刷新：
proxy_cache_background_update on;
→ 返回 stale 的同时，Nginx 自动发起子请求更新缓存防止缓存失效瞬间大量请求击穿 upstream：
proxy_cache_lock on;proxy_cache_lock_timeout 3s;暴露状态便于监控和调试：
add_header X-Cache $upstream_cache_status;
正常命中是HIT，stale 返回时是STALE
验证是否真起作用，不能只看日志
停掉 upstream（如 systemctl stop app-server）后，从客户端检查三件事：
- 响应头中出现
X-Cache: STALE - 响应体内容与故障前完全一致（不是空页、不是默认 502 页面）
- 响应耗时在几十毫秒级（远低于
proxy_read_timeout，说明确实绕过了回源）
不复杂但容易忽略
