proxy_cache_background_update 本身不主动更新动态缓存，只在缓存过期且配置了 proxy_cache_use_stale updating、proxy_cache_valid 定义过期规则、proxy_cache_lock on 防并发的前提下，静默触发一次后台回源请求。

`proxy_cache_background_update` 本身不主动“更新”动态缓存，它只在特定条件下**静默触发一次后台回源请求**——前提是缓存已过期、且 Nginx 被明确授权可以返回陈旧内容。它不是定时器，也不是轮询机制，更不适用于实时性要求高的接口。 真正决定“能否更新”“何时更新”“更新几次”的，是一整套协同配置，而非单开这个指令。

必须启用 proxy_cache_use_stale updating

这是整个机制的启动开关。Nginx 默认遇到过期缓存会阻塞等待回源；只有你写明 proxy_cache_use_stale updating，它才敢把旧内容立刻返回，并顺手发起后台刷新。

仅写 updating 不够健壮，建议补全常见异常：

• error timeout：网络或连接异常时兜底
• http_500 http_502 http_503 http_504：上游服务出问题时仍可用旧数据

漏掉 updating，后台更新永远不会启动。

必须定义清晰的 proxy_cache_valid 过期规则

没有有效期，就没有“过期”，也就谈不上“过期后后台更新”。例如：

FastAPI Flask Proxy

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

下载

• proxy_cache_valid 200 302 10s; —— 正常响应缓存 10 秒
• proxy_cache_valid 404 1s; —— 404 缓存 1 秒，防恶意探测

对动态 API，建议设为 10s～2m；对带哈希的静态资源（如 app.a1b2c3.js），可设为 1h+，因文件名变即内容变。

必须开启 proxy_cache_lock 防并发击穿

100 个请求同时命中同一过期 key，若没加锁，就会触发 100 次后台回源——这不是静默更新，是雪崩式打垮上游。

• proxy_cache_lock on;：确保同一 key 只有一个请求真正回源
• proxy_cache_lock_timeout 5s;：抢锁失败就直接走 stale 分支，不卡主响应
• proxy_cache_lock_age 15s;（可选）：刚刷完的缓存，15 秒内禁止再次刷新，防抖动

缓存键与存储路径要稳定可靠

后台子请求必须能复用原缓存项的 key 和位置，否则刷新成功也写不进缓存：

• proxy_cache_path 的 keys_zone 名称需与 proxy_cache 值严格一致
• proxy_cache_key 推荐用：$scheme$host$request_uri$is_args$args
• 避免混入易变字段：如未过滤的 $cookie_session、$time_iso8601、随机数等

后台更新请求默认不携带 If-Modified-Since 或 If-None-Match，是完整 GET 请求，需确保后端能正确响应（尤其注意鉴权逻辑）。