proxy_store 是请求触发、文件落地、本地直读的静态资源镜像机制，不缓存、不校验过期、不自动更新，仅对200/201/206响应落盘，要求root、proxy_store on、if(!-e $request_filename)、proxy_pass等配置缺一不可，适用于URL稳定、内容静态的场景。
proxy_store 不是缓存，而是“请求触发 + 文件落地 + 本地直读”的镜像机制。它不依赖内存索引、不校验过期、不自动更新，但结构简单、路径透明、可被 rsync 或脚本直接管理，特别适合静态资源（如图片、CSS、JS、HTML）的轻量级自动化同步。
明确适用范围和前提条件
只对成功响应（200/201/206）落盘；不处理 POST/PUT 等非幂等请求；不支持动态内容（如带 Session 的 HTML、API 返回体）；必须确保源站资源 URL 稳定、路径可预测、内容不变或极少变更。
- 适合场景：官网静态页、文档站点、产品图库、CDN 备份节点、内网离线镜像站
- 不适合场景：登录页、用户仪表盘、实时数据接口、含时间戳参数的资源（如 ?v=1678901234）
- 关键前提：目标目录已存在、Nginx worker 用户（如 nginx）对该目录有读写权限、目录本身有执行（x）权限（Linux 下访问子路径必需）
基础配置要点（缺一不可）
以下要素必须同时配置，否则 proxy_store 不生效或报 Permission denied / File not found：
- root 指令：定义本地文件系统根路径，也是 $request_filename 的解析基准。例如 root /data/mirror;，则 /img/logo.png 将映射为 /data/mirror/img/logo.png
- proxy_store on：显式启用落盘行为
- proxy_store_access：设最小权限，推荐 user:rw group:r all:r；避免 all:rw 引发安全风险
- if (!-e $request_filename)：仅当本地无对应文件时才回源，这是触发镜像的关键判断
- proxy_pass：指向完整协议+域名的上游地址，如 https://cdn.example.com；注意 Host 头需匹配源站要求（常需 proxy_set_header Host $host;）
推荐的 location 配置模式
按资源类型精确匹配，避免误镜像动态接口：
location ~* \.(jpg|jpeg|png|gif|webp|svg|css|js|woff2|ttf|html)$ {
root /data/mirror;
expires 30d;
add_header X-Mirror-Status "hit-by-store";
<pre class="brush:php;toolbar:false;">proxy_store on;
proxy_store_access user:rw group:r all:r;
if (!-e $request_filename) {
proxy_pass https://origin.example.com;
proxy_set_header Host origin.example.com;
proxy_set_header User-Agent "nginx-mirror/1.0";
proxy_set_header Accept-Encoding "";
}
}
- 用正则限定后缀，排除 .php、.json、.api 等高危路径
- 添加 expires 和自定义 header，便于前端调试与命中识别
- 关闭 Accept-Encoding 可避免 gzip 响应导致落盘失败（部分 Nginx 版本对压缩响应落盘支持不稳定）
自动化同步与维护建议
proxy_store 本身不提供主动拉取或定时刷新能力，但因其文件路径与 URL 严格一一对应，可轻松接入外部工具实现可控同步：
- 用 curl + while 循环预热常用路径：
cat urls.txt | xargs -I{} curl -s -o /dev/null http://localhost/{} - 用 find + rsync 向其他节点分发：
rsync -avz --delete /data/mirror/ user@backup:/data/mirror/ - 用 crontab 定期清理过期文件（如 90 天未访问）：
find /data/mirror -type f -mtime +90 -delete - 若需强制刷新某资源，直接删除本地对应文件即可，下次请求自动重拉
