proxy_store 是按需落盘+本地服务的静态资源镜像机制：首次请求从后端拉取并存盘，后续直接读本地文件绕过上游；需同时满足 proxy_store on、root 路径配置、worker 可写权限、if (!-e $request_filename) 回源逻辑四个条件。
proxy_store 不是缓存，而是一种“按需落盘 + 本地服务”的镜像机制：首次请求时从后端拉取资源并保存到磁盘，后续相同请求直接读取本地文件返回，完全绕过上游。它轻量、无需额外模块，适合图片、CSS、JS 等静态资源的被动镜像分发。
必须同时满足的四个基础条件
缺一不可，否则 proxy_store 不会写入文件或无法命中本地服务：
-
启用落盘：在 location 块中明确写
proxy_store on; -
声明根路径：用
root /path/to/mirror;指定本地目录；该路径将与请求 URI 拼接生成实际落盘位置（如请求/img/logo.png，则写入/path/to/mirror/img/logo.png） -
确保权限可写：Nginx worker 进程需对 root 目录有写权限；推荐配置
proxy_store_access user:rw group:r all:r;，再执行chown -R nginx:nginx /path/to/mirror && chmod 755 /path/to/mirror -
触发回源逻辑：必须用
if (!-e $request_filename) { proxy_pass http://backend; }判断文件是否存在；仅当本地缺失时才发起代理请求并落盘
推荐的 location 配置结构
避免使用裸 location / 直接套用 proxy_store，应分离“本地服务”和“回源落盘”两个阶段：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 用
try_files $uri @mirror;优先尝试本地文件；命中则直接返回，不走任何代理 - 未命中时跳转到
@mirror块，在其中配置proxy_pass、proxy_store on及相关头信息（如proxy_set_header Host） - 注意：
root必须定义在能被$request_filename解析的 location 中（通常放在外层或@mirror同级），不能只放在@mirror内部
关键行为与限制说明
理解它的“非智能”特性，才能避免踩坑：
- 只在 upstream 返回 200/201/206 等成功状态码时才落盘；4xx/5xx 响应不会保存
- 目标目录（如
/path/to/mirror/img/）必须提前存在；Nginx 不自动创建父目录 - 不会覆盖已有同名文件（除非系统权限允许且无锁竞争）；也不校验内容一致性，上游更新后本地不会自动同步
- 不管理过期、不支持 purge、无并发写保护——本质是静态快照，适合内容稳定、更新频率低的资源
简单验证是否生效
部署后可通过三步快速确认：
- 首次请求一个不存在的图片 URL（如
/static/test.jpg），观察 Nginx error log 是否出现proxy_store: "/path/to/mirror/static/test.jpg" created - 检查对应路径下文件是否生成，且大小与响应体一致
- 再次请求同一 URL，观察 access log 中 status 是否为 200 且无 upstream 连接日志（如
upstream_addr字段为空）
