proxy_cache_use_stale 是 Nginx 在后端异常时降级返回已缓存旧内容的容错指令，支持 error、timeout、http_500–504 等触发条件，需配合 proxy_cache 启用、缓存未过期及无禁止缓存响应头才生效。
proxy_cache_use_stale 是 Nginx 缓存容错的关键指令，它允许在后端服务异常（如超时、500/502/503/504、连接失败）时，继续返回**已缓存的旧内容**，从而保障用户访问不中断。这不是“刷新缓存”，而是“降级使用缓存”——核心目标是可用性优先。
哪些情况能触发 stale 缓存响应
该指令需配合具体错误条件启用，常见可选值包括：
- error：与后端建立连接失败（如 upstream 拒绝连接）
- timeout：代理请求超时（proxy_read_timeout / proxy_connect_timeout 触发）
- invalid_header：后端返回非法 HTTP 头（如空行、格式错误）
- updating：当前正更新缓存（配合 proxy_cache_lock 使用，避免并发回源）
- http_500 | http_502 | http_503 | http_504：明确匹配对应状态码
基础配置示例（含关键细节）
在 location 或 server 块中添加：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
⚠️ 注意：仅声明该指令不会自动生效，还需确保以下前提成立：
- 已通过 proxy_cache 启用了缓存区域（如
proxy_cache zcy;） - 缓存项本身未过期（即仍在 proxy_cache_valid 定义的有效期内）
- 没有设置 Cache-Control: no-cache / no-store 等禁止缓存的响应头（Nginx 默认会尊重这些头）
增强可用性的常用组合技巧
单纯用 use_stale 还不够稳健，建议搭配以下配置：
-
延长 stale 可用窗口：用
proxy_cache_valid 200 302 10m;确保成功响应至少缓存 10 分钟，为故障期提供缓冲 -
防止缓存雪崩：加
proxy_cache_lock on;，让同一 key 的首个请求回源，其余等待并复用结果 -
主动标记 stale 内容：添加响应头便于前端识别，例如：
add_header X-Cache-Status $upstream_cache_status;add_header X-Cache-Stale $upstream_cache_stale;
（其中$upstream_cache_stale在启用 use_stale 且命中 stale 时为 "1"）
验证是否生效的小方法
模拟后端宕机后观察响应：
- 停掉上游服务（如
systemctl stop your_backend） - 用 curl 请求，检查：
curl -I http://your-domain.com/path
若返回200 OK且X-Cache-Status: HIT、X-Cache-Stale: 1，说明 stale 生效 - 同时确认响应时间明显低于平时（因跳过回源）
