proxy_cache_use_stale 是 Nginx 在静态存储故障时安全返回已过期缓存内容的降级机制，需精准配置 error/timeout/502-504 条件、可靠缓存路径、规范 cache_key、合理 cache_valid 时效，并配合 background_update 与 cache_lock 实现静默刷新与防穿透。

proxy_cache_use_stale 是 Nginx 在后端静态存储（如对象存储、文件服务、CDN 源站）不可用时，安全返回已缓存但已过期内容的核心机制。它不是“随便返回旧数据”，而是依赖一套完整、可控的缓存链路，在故障发生时主动降级，保障接口或页面持续可访问。

明确启用适配静态存储故障的 stale 条件

静态存储宕机通常表现为连接失败、超时或返回明确错误码（如 502/503/504），而非随机抖动。应精准配置：

• proxy_cache_use_stale error timeout http_502 http_503 http_504;

  • error：覆盖连接拒绝、上游重置等底层网络中断
  • timeout：应对存储网关响应超时（如 OSS/MinIO 网关卡住）
  • http_502/503/504：匹配存储服务主动返回的错误（如 503 Service Unavailable 表示 bucket 不可达）

• 避免启用 invalid_header 或 updating 单独使用：前者易被不规范响应头误触发；后者需配合 proxy_cache_background_update on 才有意义。

确保缓存本身“存得住、找得准、过得了期”

stale 生效的前提是：该请求路径曾经成功缓存过，且当前缓存条目仍存在于磁盘中、键未漂移、过期时间可识别。

• 必须定义缓存区并启用：

  proxy_cache_path /var/cache/nginx/static levels=1:2 keys_zone=static_cache:256m inactive=7d use_temp_path=off;

  并在 location 中引用：

  proxy_cache static_cache;

• 缓存键要剔除干扰字段：静态资源 URL 通常带版本号或哈希（如 /js/app.a1b2c3.js），但若后端加了时间戳参数（?t=1715455580）或追踪参数（?utm_source=...），必须过滤：

  

  WebChat Voice Proxy

  ⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

  下载

  proxy_cache_key "$scheme$host$uri";
  # 或更稳妥地正则清理 query：
  set $clean_uri $uri;
  if ($args ~ "^([a-zA-Z0-9_\-\.]+=[a-zA-Z0-9_\-\.]+&)*[a-zA-Z0-9_\-\.]+=[a-zA-Z0-9_\-\.]+$") {
      set $clean_uri "$uri?";
  }
  proxy_cache_key "$scheme$host$clean_uri";

• 缓存有效期要覆盖正常响应与错误响应：

  proxy_cache_valid 200 301 302 24h;           # 正常静态资源缓存 1 天
  proxy_cache_valid 502 503 504 10m;          # 错误响应也缓存 10 分钟，供 stale 复用

配合后台更新与锁机制，避免“一击即溃”

单纯返回陈旧内容只是起点。静态资源一旦失效，用户可能长期看到旧版，需静默刷新+防并发穿透：

• 开启后台异步更新：

  proxy_cache_background_update on;

  Nginx 在返回 stale 响应的同时，自动发起一个子请求向后端拉取新资源并写入缓存。

• 加锁防止并发刷新风暴：

  proxy_cache_lock on;
  proxy_cache_lock_timeout 2s;

  当多个请求同时命中同一过期缓存键时，仅首个请求穿透回源，其余在 2 秒内等待；超时则直接返回 stale —— 这正是 proxy_cache_use_stale updating 发挥作用的时机。

从客户端视角验证是否真实生效

别信配置，要验行为。三步确认：

• 主动模拟静态存储故障：停掉 MinIO 容器、iptables 拦截其端口，或 upstream server 直接 return 503；
• 发起请求，检查响应头：
  • X-Cache: STALE（需提前配置 add_header X-Cache $upstream_cache_status;）
  • Age 值大于 s-maxage 或 proxy_cache_valid 设定（例如 Age: 3612 表示已过期 1 小时）
  • 状态码为 200（原始成功码），非 502/503；
• 对比响应体：下载的 JS/CSS/图片二进制内容与故障前完全一致，不是空文件、不是 Nginx 默认错误页、也不是 JSON 错误结构。

不复杂但容易忽略