proxy_cache_background_update 要生效，必须配套启用 proxy_cache_use_stale updating、明确定义 proxy_cache_valid 过期时间、开启 proxy_cache_lock 防击穿，并确保 proxy_cache_key 与 proxy_cache_path keys_zone 严格一致。

要让 proxy_cache_background_update 在缓存失效时真正触发后台异步刷新，不能只打开这个开关，必须确保它所依赖的“响应决策链”完整打通。它的本质是：当缓存已过期、但用户请求又来了，Nginx 不卡住等回源，而是秒回旧内容，同时在后台静默拉新——前提是它被明确授权这么做。

必须启用 proxy_cache_use_stale updating

这是整个机制的启动前提。没有它，Nginx 遇到过期缓存默认会阻塞等待回源，根本不会返回旧内容，后台更新也就无从发起。

• 务必显式包含 updating：例如 proxy_cache_use_stale updating error timeout http_500 http_502 http_503 http_504;
• 仅写 updating 不够健壮；加上错误类参数，才能覆盖回源失败时仍可用旧缓存的场景
• 如果这行缺失或漏掉 updating，即使开了 background_update，用户也收不到旧缓存，后台子请求永远不会出发

必须明确定义 proxy_cache_valid 过期时间

没有有效期，就没有“失效”概念，也就谈不上“失效后是否允许返回旧内容+后台更新”。

FastAPI Flask Proxy

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

下载

• 为常见状态码设有效期，例如：proxy_cache_valid 200 302 30s;
• API 类接口建议 10s～2m；带哈希的静态资源（如 app.a1b2c3.js）可设 1h 或更长
• 一定要单独控制 404：proxy_cache_valid 404 10s;，避免无效响应长期占位、挤占缓存空间

推荐开启 proxy_cache_lock 防并发击穿

多个请求同时命中同一失效 key，若不加锁，可能瞬间触发几十次重复回源，反而压垮上游服务。

• proxy_cache_lock on;：只允许一个请求真正回源，其余请求直接走 stale 路径
• proxy_cache_lock_timeout 5s;：锁等待超时后，立刻返回旧缓存，不卡主响应
• 可选加固：proxy_cache_lock_age 15s;，锁释放后 15 秒内禁止再次更新，防抖动

确保缓存基础配置稳定一致

后台子请求能否成功更新缓存，取决于它是否能精准复用原有缓存项的 key 和存储位置。

• proxy_cache_path 中定义的 keys_zone 名称，必须与 location 中 proxy_cache 的值严格匹配
• proxy_cache_key 推荐使用稳定组合，例如：$scheme$host$request_uri$is_args$args
• 避免混入易变字段：如未过滤的 Cookie、时间戳、随机数等，否则会导致 key 不一致，后台更新写入新条目而非覆盖旧条目
• 确认后端能接受无认证的后台子请求（不带敏感 header 或 session），否则更新可能失败且无提示