proxy_cache_background_update on 是 Nginx 实现“先返回旧缓存、后异步更新”的关键配置：当缓存过期时，首个请求触发后台回源刷新，其余请求立即返回陈旧内容，避免排队等待，从而防止缓存雪崩；其生效必须配合 proxy_cache_use_stale updating、明确的 proxy_cache_valid 及可写缓存路径。
proxy_cache_background_update 是什么
当缓存过期时，Nginx 默认行为是：第一个请求触发回源拉取新内容，其余请求排队等待，直到新响应返回才一并返回——这会造成“缓存雪崩”式延迟。而 proxy_cache_background_update on 的作用，就是让第一个过期请求去后台异步更新缓存，同时立刻用**旧缓存内容**响应后续所有请求，实现“先返回、后更新”，真正平滑过渡。
启用 background update 的必要前提
这个功能不是开个开关就能用的，必须配合以下配置生效：
- proxy_cache_use_stale updating：告诉 Nginx，当缓存处于 “updating” 状态（即后台正在刷新）时，允许直接使用旧缓存响应请求；
-
proxy_cache_valid 必须明确指定状态码和缓存时间（例如
proxy_cache_valid 200 302 10m），否则 Nginx 不知道哪些响应可缓存、该缓多久； - 建议搭配 proxy_cache_lock on（可选但推荐）：避免多个并发请求同时触发回源，进一步减少上游压力；
- 确保 proxy_cache_path 已正确定义且磁盘可写，否则后台更新会静默失败。
典型配置示例与关键点说明
以下是一个生产可用的精简配置片段：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
proxy_cache_path /var/cache/nginx/mycache levels=1:2 keys_zone=mycache:10m max_size=1g inactive=60m use_temp_path=off;
server {
location /api/ {
proxy_pass https://backend;
proxy_cache mycache;
proxy_cache_valid 200 302 5m;
proxy_cache_valid 404 1m;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_background_update on;
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
}
}
注意几个细节：
-
updating必须显式写在 proxy_cache_use_stale 列表中，否则即使开了 background update，Nginx 也不会用旧缓存响应； -
proxy_cache_lock_timeout要合理设置（如 5s），避免锁太久导致请求堆积； -
inactive=60m表示 60 分钟内未被访问的缓存条目会被自动清理，不影响 background update 的触发逻辑； - 后台更新失败时，旧缓存仍会继续提供服务，直到下次满足更新条件或被清理。
如何验证 background update 是否生效
最直接的方式是结合日志与缓存头观察：
- 开启 log_format 记录
$upstream_cache_status，你会看到UPDATING状态——表示当前请求命中了正在后台更新的缓存项； - 用 curl 查看响应头：
curl -I http://yourdomain/api/data，正常情况下会看到X-Cache: HIT或X-Cache: UPDATING（取决于你是否自定义了该 header）； - 模拟缓存过期：临时把
proxy_cache_valid改小（比如 10s），然后连续发请求，观察第 1 个请求耗时明显长（回源），后续请求几乎瞬间返回（用旧缓存），同时access.log中对应时间点出现UPDATING日志； - 检查 Nginx error log，若后台更新出错（如后端不可达），通常会有类似
upstream timed out的提示，但不会影响前端响应。
