proxy_cache_background_update 的作用是缓存过期后返回旧内容的同时后台异步更新缓存，需配合 proxy_cache_use_stale updating 和 proxy_cache_valid 使用，避免用户等待，提升响应速度。

proxy_cache_background_update 的作用是：当缓存过期后，Nginx 在返回旧缓存内容给客户端的同时，**后台异步发起新请求更新缓存**，避免用户等待后端响应，提升响应速度和用户体验。它本身不控制刷新逻辑，而是配合 proxy_cache_valid、proxy_cache_use_stale 等指令协同工作。

启用 background update 的基本配置

该指令默认为 off，需显式设为 on 才生效：

• 必须在 location 或 server 块中启用：proxy_cache_background_update on;
• 必须已启用缓存（即配置了 proxy_cache 和 proxy_cache_key）
• 必须设置缓存过期时间（如 proxy_cache_valid 200 5m;），否则无“过期”可言
• 推荐同时启用 proxy_cache_use_stale updating; —— 这是关键，它允许 Nginx 在缓存处于 “updating” 状态时仍返回旧内容

完整可用的最小示例

以下是一个典型配置片段（假设已定义名为 my_cache 的缓存区）：

location /api/ {
    proxy_pass https://backend;
    proxy_cache my_cache;
    proxy_cache_key "$scheme$request_method$host$request_uri";
<pre class="brush:php;toolbar:false;"># 缓存 200 响应 5 分钟
proxy_cache_valid 200 5m;

# 允许在缓存过期、正在后台更新时，继续返回旧缓存
proxy_cache_use_stale updating;

# 启用后台异步更新（核心）
proxy_cache_background_update on;

# 可选：防止后台请求被频繁触发（配合 proxy_cache_lock）
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;

}

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

说明：当一个请求命中已过期的缓存时，Nginx 立即返回旧内容，并在后台悄悄发起一次到后端的请求，成功后覆盖缓存。后续请求将拿到新内容（或继续命中正在更新的旧内容，直到更新完成）。

注意 cache lock 与 background update 的关系

proxy_cache_background_update 通常与 proxy_cache_lock 搭配使用，但二者职责不同：

• proxy_cache_lock on：确保同一缓存 key 只有一个请求去回源（其余请求等待或返回 stale），防止“缓存击穿”式并发回源
• proxy_cache_background_update on：在返回 stale 内容后，自动触发一个后台更新线程，不阻塞任何请求
• 两者可共存 —— lock 控制首次过期时的回源竞争，background_update 控制后续持续刷新行为

验证是否生效的方法

可通过日志或响应头辅助判断：

• 开启 log_format 记录 $upstream_cache_status，观察是否出现 UPDATING 状态（表示后台更新已触发）
• 在响应头中查看 X-Cache-Status（需自定义添加）：可设为 HIT（命中）、STALE（返回过期内容）、UPDATING（后台正在刷新）
• 抓包或后端日志：在缓存过期后发起多次请求，观察后端是否只收到 1 次回源请求（lock + background update 正常时），且响应极快（来自缓存）