proxy_cache_use_stale 的核心作用是允许 Nginx 在上游故障、超时或返回 5xx 等错误时，继续提供本地已缓存的过期内容以保障服务可用性；需配合 proxy_cache、proxy_cache_valid 和 proxy_cache_lock 等指令生效。

proxy_cache_use_stale 的核心作用

当上游服务器（如源站）出现故障、超时或返回错误响应时，Nginx 默认会将错误直接透传给客户端。而 proxy_cache_use_stale 指令的作用，就是允许 Nginx 在这些异常情况下，**继续提供本地已缓存的“过期但尚可接受”的内容**，从而避免服务完全中断，实现类似 CDN 故障兜底的效果。

哪些场景下会触发陈旧缓存？

该指令通过参数明确指定可降级的条件，常见组合包括：

• error：上游连接失败、被拒绝、超时（proxy_connect_timeout / proxy_read_timeout 触发）
• timeout：代理请求过程中读取响应超时（注意与 error 中的超时略有重叠，但更侧重于响应体传输阶段）
• updating：当前缓存正被后台更新（配合 proxy_cache_background_update on），此时可先返回旧版本，避免用户等待
• http_500 | http_502 | http_503 | http_504：上游明确返回这些网关类错误时启用兜底
• invalid_header：上游响应头格式非法（如缺少 Host、含控制字符等）

关键配置要点与注意事项

仅开启 proxy_cache_use_stale 不足以让兜底生效，还需配套设置：

Umbrel Proxy Manager

高效管理与交互 Umbrel 代理服务，支持 Docker 容器。自动发现运行服务，将内部 Docker IP 映射为可访问的外部地址。

下载

• 缓存必须已存在且曾成功存储过——首次请求无缓存时，即使配置了 stale，仍会回源失败并报错
• 需启用缓存（proxy_cache + proxy_cache_valid），并确保 proxy_cache_valid 设定了合理过期时间（如 200 301 302 10m）
• 建议搭配 proxy_cache_lock on 防止缓存失效时大量并发回源压垮源站
• 若希望陈旧缓存也带明确提示（如响应头 X-Cache: STALE），可通过 add_header 结合 $upstream_cache_status 变量实现

一个典型 CDN 故障兜底配置示例

假设你用 Nginx 充当边缘节点，后端是不稳定的源站或 CDN 回源地址：

proxy_cache my_cache;
proxy_cache_valid 200 301 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
<h1>可选：标记响应来源</h1><p>add_header X-Cache-Status $upstream_cache_status;
</p>

这样，当源站宕机或返回 503 时，只要本地有 10 分钟内缓存过的 200 响应，Nginx 就会照常返回它，并在响应头中写入 X-Cache-Status: STALE，既保障可用性，又便于监控识别。