proxy_store是一种按需落盘+本地服务的静态资源镜像机制：首次请求从源站拉取并保存到磁盘，后续直接读取本地文件返回，不经过upstream；需同时满足启用落盘、声明root路径、权限可写、if判断触发回源四个条件。
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 响应不会写入
与 proxy_cache 的关键区别
别把 proxy_store 当缓存用：
- 无过期机制：文件一旦写入，永久存在，除非手动清理或被覆盖（默认不覆盖）
- 无内存索引或并发保护：多请求同时写同一文件可能冲突，不适合高频更新资源
- 不校验一致性：上游文件更新后，本地镜像不会自动同步，需人工介入或脚本刷新
- 路径由 URI 映射生成：不支持 key 自定义，也不支持 purge 接口
适合场景：CDN 回源压力大、源站稳定性差、资源更新频率低（如文档站点、老版本前端包）。
