启用 proxy_cache_use_stale updating 与 proxy_cache_background_update on 后，用户请求可立即返回过期缓存内容（X-Cache: STALE），同时后台异步刷新缓存，避免多请求同步回源导致的“请求风暴”。

用 proxy_cache_use_stale updating 配合 proxy_cache_background_update on，就能在缓存即将过期或已过期时，让主请求立刻返回旧内容，同时后台悄悄刷新缓存——彻底避开“请求风暴”。

为什么缓存过期会引发请求风暴

当大量用户在同一时刻访问一个刚过期的热门资源（比如首页、活动页），Nginx 默认行为是：所有请求都同步回源。哪怕只差几毫秒，也可能触发几十甚至上百个并发回源请求，瞬间压垮上游服务。

这种现象不是流量大才出现，而是缓存时间固定 + 用户访问集中 + 缺少协调机制共同导致的。

updating 参数的作用机制

proxy_cache_use_stale updating 的核心逻辑是：只要缓存条目正在被后台更新，就允许立即返回当前已有的（哪怕已过期）缓存内容。

它本身不触发更新，只是“授权”使用旧缓存；真正负责后台更新的是 proxy_cache_background_update on ——这个指令会让 Nginx 在检测到缓存快过期时，自动发起一个子请求去上游拉新内容，而主响应不受影响。

WebChat Voice Proxy

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

下载

两者配合后，流程变成：

• 用户请求到达，发现缓存存在但已过期（或即将过期）
• Nginx 不阻塞，直接返回旧缓存（X-Cache: STALE）
• 同时，Nginx 启动一个低优先级子请求，异步去上游获取新响应并写入缓存

必须配套的基础配置

单独加 updating 不起作用。以下四项缺一不可：

• proxy_cache_path 正确定义缓存区（含 keys_zone）
• proxy_cache 在 location 中启用对应缓存区
• proxy_cache_valid 明确设置缓存有效期（如 200 302 5m），否则没有“过期”概念
• proxy_cache_background_update on 开启后台更新能力

示例关键片段：

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=30m;
location /api/ {
  proxy_cache my_cache;
  proxy_cache_valid 200 5m;
  proxy_cache_use_stale error timeout updating http_502 http_503 http_504;
  proxy_cache_background_update on;
  proxy_pass http://backend;
}

验证是否生效的实操方法

别只看日志，重点观察三点：

• 停掉后端服务后，仍能快速返回响应（响应时间远低于 proxy_read_timeout）
• 响应头中出现 X-Cache: STALE（需用 add_header X-Cache $upstream_cache_status; 暴露）
• 重新启动后端后，过几秒再请求，响应头变为 X-Cache: HIT，说明后台更新已成功落库

如果始终看到 MISS 或直接报错，大概率是 proxy_cache_valid 没覆盖对应状态码，或 proxy_cache_background_update 未开启。