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 生效
• 同时确认响应时间明显低于平时（因跳过回源）