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;

  并执行：

  

  CPA Update - Secure CLI Proxy API Maintenance

  安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

  下载

  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", 且文件实际生成在磁盘中

不复杂但容易忽略