如何利用 proxy_store 实现简单的镜像文件按需存储与加速指南-Nginx-PHP中文网

proxy_store是一种按需落盘+本地服务的静态资源镜像机制：首次请求从源站拉取并保存到磁盘，后续直接读取本地文件返回，不经过upstream；需同时满足启用落盘、声明root路径、权限可写、if判断触发回源四个条件。

如何利用 proxy_store 实现简单的镜像文件按需存储与加速指南

proxy_store 不是缓存模块，而是一种“按需落盘 + 本地服务”的静态资源镜像机制：首次请求时从源站拉取并保存到磁盘，后续请求直接读取本地文件返回，不经过 upstream。它轻量、无需额外编译模块，适合图片、CSS、JS 等静态资源的快速分发。

必须同时满足的四个基础条件

缺一不可，否则会静默失败或始终回源：

启用落盘：配置 proxy_store on;
声明根路径：用 root /path/to/mirror; 指定本地目录，该路径将作为 URL 路径的映射基准（如请求 /img/bg.jpg，Nginx 尝试读取 /path/to/mirror/img/bg.jpg）
权限可写：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 https://upstream; } ——只有本地文件不存在时才拉取，否则直接 serve

推荐的 location 配置结构

避免用泛匹配 location /，优先按资源类型精确匹配，减少误判和磁盘写入：

只对图片、字体、JS、CSS 启用镜像：
location ~* \.(gif|jpg|jpeg|png|webp|ico|woff2?|ttf|eot|js|css)$ {
设置本地根目录与过期头：
```
root /data/mirror;<br>expires 30d;
```

先查本地，不存在则代理拉取：

if (!-e $request_filename) {<br>  proxy_pass https://origin.example.com;<br>  proxy_store on;<br>  proxy_store_access user:rw group:r all:r;<br>  proxy_set_header Host origin.example.com;<br>}

注意：try_files $uri @mirror + location @mirror 是更健壮的替代写法，可避免 if 在某些上下文中的限制。

aperture: the L402 aware reverse proxy

安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

常见问题与排查要点

出错时通常不报明显错误，而是持续回源或返回 404/500。重点检查：

目录是否真实存在且可写：Nginx 不自动创建父目录，/data/mirror/img/ 不存在时，/img/logo.png 无法落盘
权限是否完整：目录需有执行（x）权限才能进入子路径；文件需有读权限才能返回；写权限缺失会导致 open() ... failed (13: Permission denied)
proxy_store_access 是否生效：若设为 all:rw，任意本地账户都可篡改缓存，存在投毒风险；生产环境应坚持最小权限
响应状态码是否允许落盘：proxy_store 只在 200、201、206 等成功状态时保存，4xx/5xx 响应不会写入