proxy_store是“首次拉取+本地落盘+直接读取”的镜像机制，非缓存：需同时配置proxy_store on、root路径、proxy_store_access权限、if (!-e $request_filename)判断及proxy_pass回源。
proxy_store 不是缓存，而是“首次拉取 + 本地落盘 + 直接读取”的镜像机制。它不依赖 proxy_cache 模块，也不处理响应头中的缓存策略，只管把后端返回的静态资源按 URL 路径结构原样保存到磁盘，并在后续请求中跳过 upstream，直接由 Nginx 读文件返回。
必须同时满足的四个核心条件
缺一不可，否则会持续回源、无法落盘或返回 404：
-
启用存储功能：在 location 块内写
proxy_store on; -
指定根路径映射：用
root /path/to/mirror;，该路径将作为 URL 路径的前缀。例如请求/css/app.css，Nginx 会尝试读取/path/to/mirror/css/app.css -
确保文件系统权限：Nginx 工作进程（如 www-data 或 nginx 用户）需对 root 目录有读写权限。推荐配置：
proxy_store_access user:rw group:rw all:rw;，再执行chmod -R a+rw /path/to/mirror -
显式控制回源时机：必须用
if (!-e $request_filename) { proxy_pass http://backend; }判断本地文件是否存在；只有不存在时才触发回源
典型安全配置示例（仅镜像静态资源）
避免误将 HTML 页面或 POST 接口也镜像，应严格限制匹配范围：
（以下配置适用于图片、字体、JS、CSS 等纯静态资源）
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2|ttf|eot|webp)$ {
root /data/mirror;
proxy_store on;
proxy_store_access user:rw group:rw all:rw;
<pre class="brush:php;toolbar:false;"># 只有本地无文件时才回源
if (!-e $request_filename) {
proxy_pass https://origin.example.com;
proxy_set_header Host origin.example.com;
proxy_set_header User-Agent "nginx-mirror";
proxy_set_header Accept-Encoding "";
}
expires 30d;
add_header X-Cached-By "proxy_store";
add_header Cache-Control "public, immutable";}
关键注意事项与避坑点
- 不能用于动态内容：proxy_store 不解析响应体，也不校验状态码——即使后端返回 500 或 302，只要响应体非空，就会照单全收并落盘。务必限制 location 匹配范围，避开 API 和 HTML
- 不支持 POST/PUT 等非幂等方法：Nginx 默认拒绝用 proxy_store 处理非 GET/HEAD 请求。若需兼容，可加 error_page 405 转为 GET，但语义已改变，慎用
-
路径一致性很重要：root 路径 + URI 路径必须能拼出真实文件路径。例如 root 是
/data/mirror，请求/v1.2.0/js/main.js，则落盘路径为/data/mirror/v1.2.0/js/main.js - 不自动清理过期文件：proxy_store 不识别 Last-Modified 或 ETag，也不会删除旧文件。需配合外部脚本定期清理，例如用 find 命令按修改时间清理：
find /data/mirror -type f -mtime +90 -delete
和 proxy_cache 的本质区别
两者目标相似，但机制完全不同：
- proxy_cache：基于内存+磁盘的缓存系统，受缓存键、过期策略、验证逻辑（If-Modified-Since）驱动，支持 stale、revalidate、purge，适合通用反向代理场景
- proxy_store：无缓存逻辑，纯文件系统映射；不关心 HTTP 语义，只做“拉一次、存下来、下次直接读”，轻量、确定性强，适合构建只读静态镜像站或边缘预热节点
