nginx可通过proxy_cache_use_stale在后端不可用时返回陈旧缓存实现优雅降级，需配合proxy_cache_path、proxy_cache、proxy_cache_valid及proxy_cache_background_update等指令协同生效，并通过x-cache: stale验证。
当后端服务不可用时，Nginx 可以通过 proxy_cache_use_stale 指令启用“陈旧缓存托底”机制，在不中断用户访问的前提下维持基础响应能力。这不是兜底重试，而是有策略地复用已缓存但可能过期的内容，属于典型的优雅降级实践。
proxy_cache_use_stale 的核心作用
该指令告诉 Nginx：在与后端通信失败（如超时、500/502/503/504）、或缓存内容已过期但正在后台更新时，仍可将本地缓存的旧版本返回给客户端。它不等待后端恢复，也不直接报错，而是用“可用即用”的思路保障服务连续性。
- 适用场景明确：仅在 proxy_cache 已启用且缓存命中前提下生效；未缓存的请求不会被托底
- 不替代健康检查：它不感知后端是否宕机，只响应连接失败或状态码异常等即时错误
- 需配合 cache_valid 使用：否则无法判断哪些响应允许被缓存，也就没有“陈旧”可言
关键配置项与典型组合
最常用且稳妥的写法是：
proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504 updating;
- error：DNS解析失败、连接被拒绝等底层错误
- timeout：proxy_connect_timeout 或 proxy_read_timeout 触发时
- http_5xx：后端返回 500/502/503/504 等错误状态码
- updating：缓存条目正被 background_update 刷新，此时可先返回旧内容
注意：updating 需搭配 proxy_cache_background_update on; 和 proxy_cache_lock on; 才能生效，否则只是空转。
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
必须配套的基础缓存配置
单独启用 proxy_cache_use_stale 不会起效，需确保以下三项已就位：
-
定义缓存区：使用
proxy_cache_path声明存储路径、keys_zone 名称和大小，例如：proxy_cache_path /var/cache/nginx/mycache levels=1:2 keys_zone=mycache:10m max_size=1g inactive=1h; -
启用缓存作用域：在 location 块中指定
proxy_cache mycache; -
设定缓存有效期：用
proxy_cache_valid明确哪些状态码缓存多久，例如：proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m;
若后端返回了 Cache-Control: no-cache 或 Set-Cookie 头，默认会被 Nginx 跳过缓存。必要时可通过 proxy_ignore_headers Cache-Control Expires Set-Cookie; 强制缓存。
验证与可观测性建议
上线前建议通过日志确认托底行为是否触发：
- 开启
log_format记录缓存状态：log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_cache_status"'; - 查看
$upstream_cache_status字段：值为STALE表示当前响应来自陈旧缓存，UPDATING表示后台正在刷新，HIT/MISS是常规缓存状态 - 模拟后端宕机（如临时停掉 upstream 服务），发起请求观察是否返回 200 且日志中标记为 STALE
不复杂但容易忽略：托底能力依赖于缓存本身的存在和时效性，定期清理无效缓存、监控磁盘空间与 keys_zone 命中率，才是长期稳定的关键。
