proxy_store是一种“首次拉取+本地落盘+直接读取”的静态资源镜像机制，非传统缓存；必须同时满足proxy_store on、root路径、worker可写权限、if (!-e $request_filename)回源判断四个条件。
proxy_store 实现的不是传统缓存，而是一种静态资源物理盘镜像：首次请求时从后端拉取并完整写入磁盘指定路径，后续请求直接由 Nginx 读文件返回，完全不经过 upstream。它轻量、无需额外模块，适合图片、字体、JS、CSS 等内容稳定、更新极少的静态资源。
必须同时满足的四个硬性条件
缺一不可，否则会静默失败（比如始终回源、文件写不进磁盘、或命中不了本地）：
-
proxy_store on;明确开启落盘行为（只在需要镜像的 location 中配置） -
root /path/to/mirror;声明本地根目录；Nginx 会把请求 URI 拼接到该路径后生成落盘位置（如请求/js/app.js→ 写入/path/to/mirror/js/app.js） - Nginx worker 进程对
root目录有写权限；推荐显式设置：proxy_store_access user:rw group:rw all:r;
并执行：
FastAPI Flask Proxy下载FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
mkdir -p /path/to/mirror && chown -R nginx:nginx /path/to/mirror && chmod 755 /path/to/mirror
- 用
if (!-e $request_filename)控制回源时机：仅当本地文件不存在时才proxy_pass，否则直接 serve 文件
推荐的 location 结构（读写分离，避免误覆盖）
不要把 proxy_store on 和 proxy_pass 放在同一个无判断逻辑的块里。应拆成两层：
location ~* \.(js|css|png|jpg|jpeg|gif|webp|svg|woff2|ttf|eot)$ {
root /data/mirror;
# 先尝试读本地
try_files $uri @mirror;
}
# 回源+落盘专用块
location @mirror {
proxy_pass https://origin.example.com;
proxy_store on;
proxy_set_header Host $host;
proxy_set_header User-Agent "nginx-mirror";
proxy_set_header Accept-Encoding ""; # 防止 gzip 内容被乱码写入
}⚠️ 注意：root 必须定义在能被 $request_filename 解析的位置（即外层或与 @mirror 同级），不能只写在 @mirror 块内部。
只对静态资源启用，防止污染镜像目录
- 避免
location / { proxy_store on; }这类宽泛配置，否则 HTML 页面、API 响应甚至 404 都会被原样写入，导致路径混乱或安全风险 - 按后缀精准匹配，例如：
- 图片类：
location ~* \.(png|jpg|jpeg|gif|webp|ico|svg)$ - 字体与脚本：
location ~* \.(woff2|ttf|eot|js|css)$
- 图片类：
- 若需镜像文档页（如
/docs/*.html），可单独加一条：location ~* ^/docs/.+\.html$ { root /data/mirror; try_files $uri @mirror_docs; } location @mirror_docs { proxy_pass https://docs-origin; proxy_store on; # …其他同上 }
补充实用配置提升可用性
- 加客户端缓存头，减少重复请求：
expires 30d; add_header Cache-Control "public, immutable";
- 打标记便于排查是否走镜像：
add_header X-Cached-By "proxy_store";
- 提前建好常见子目录（
proxy_store不自动创建父级）：mkdir -p /data/mirror/{js,css,img,fonts,docs} - 验证是否生效：访问一个本地尚不存在的资源（如
/img/test.png），检查 Nginx error log 是否出现proxy_store: "/data/mirror/img/test.png", 且文件实际生成在磁盘中
不复杂但容易忽略
