nginx在后端故障时返回陈旧缓存需构建“能存、能找、能判、能返”完整链路：精准启用proxy_cache_use_stale http_500-504，配合proxy_cache_path、稳定proxy_cache_key、proxy_cache_valid覆盖5xx，并通过x-cache: stale及响应一致性验证生效。
要让 Nginx 在后端故障时自动返回陈旧缓存，关键不是打开 proxy_cache_use_stale 就完事，而是构建一条“能存、能找、能判、能返”的完整链路。它不保证数据最新，但能确保服务不中断。
只启用真正反映后端崩溃的触发条件
源站宕机最可靠的表现是明确返回 5xx 错误，而不是网络抖动或超时。应精准配置：
-
推荐写法：
proxy_cache_use_stale http_500 http_502 http_503 http_504;—— 这四类状态码由后端主动发出，可信度高 -
避免加
error和timeout：连接失败或读取超时可能是瞬时问题，盲目启用 stale 会掩盖真实异常 -
如需后台静默刷新，可额外加上
updating，但必须同步开启proxy_cache_background_update on;
确保缓存本身“存在且稳定”
stale 不是凭空造缓存，它只复用已存在但过期的内容。常见失效原因都出在基础配置上：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 必须在
http块中定义proxy_cache_path，例如：proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:512m inactive=3d use_temp_path=off; - 在
location中显式引用缓存区：proxy_cache my_cache; -
proxy_cache_key要稳定，禁用时间戳、随机数、用户标识等动态字段，推荐：proxy_cache_key "$scheme$host$request_uri"; -
proxy_cache_valid必须覆盖错误响应：proxy_cache_valid 200 301 302 10m;proxy_cache_valid 500 502 503 504 1m;—— 错误响应进不了缓存，stale 就无内容可返
验证是否真起作用，别只看状态码
停掉上游服务后，从客户端视角确认三件事：
- 响应头中出现
X-Cache: STALE（需提前配置add_header X-Cache $upstream_cache_status;） - 响应体与故障前完全一致，不是空页、不是 Nginx 默认 502 页面、也不是 JSON 错误结构
- 响应耗时在几十毫秒内（比如
proxy_read_timeout 3s，实测返回 40–80ms），说明确实绕过了回源
提升体验：让旧内容过渡到新内容更平滑
单纯返回陈旧数据只是第一步。更优做法是让用户无感完成更新：
- 开启异步刷新：
proxy_cache_background_update on;—— 返回 stale 的同时，Nginx 自动发起子请求拉新内容 - 防止缓存失效雪崩：
proxy_cache_lock on;+proxy_cache_lock_timeout 3s;—— 同一缓存键只允许一个请求去回源，其余直接拿 stale - 对核心接口，可提供带签名的手动刷新入口（如
/cache/refresh?uri=/api/data&sig=xxx），便于运维快速干预
