proxy_store 仅在本地文件不存在时回源落盘且只写一次，不支持无条件持久化；需满足启用指令、正确根路径、worker可写权限、if判断触发四前提，并配合目录预建、精准匹配、权限控制等措施实现稳定镜像。
proxy_store 本身不支持“无条件持久化”——它天然是按需、有条件、只写一次的镜像机制。所谓“无条件”，容易误解为每次请求都强制回源并覆盖写入，但 proxy_store 的设计逻辑恰恰相反：只在本地文件不存在时才回源落盘，且成功写入后就不再触碰该文件。因此，“无条件持久化”不是它的行为，而是需要你明确理解其边界，并通过配套措施达成稳定、可靠、可维护的本地镜像效果。
下面从实操角度讲清楚怎么做：
必须满足的四个硬性前提
缺一不可，否则镜像不会落地或无法服务：
-
启用落盘指令：在对应 location 块中写
proxy_store on; -
声明映射根路径：用
root /data/mirror;（不能用alias替代，否则$request_filename解析失败） -
确保 worker 进程可写：Nginx 工作用户（如
nginx）对/data/mirror及其所有子目录有读写权限 -
显式触发回源判断：必须包裹在
if (!-e $request_filename) { proxy_pass http://upstream; }中
⚠️ 注意：
proxy_store不会自动创建父目录。比如请求/css/app.css，而/data/mirror/css/不存在，落盘就会静默失败，后续仍持续回源。务必提前建好常用目录结构：mkdir -p /data/mirror/{css,js,img,fonts,docs} chown -R nginx:nginx /data/mirror chmod 755 /data/mirror
精准匹配静态资源，避免误镜像
不要在 location / 下全局开启，否则 HTML 页面、API 接口甚至 404 响应都会被原样写入磁盘，造成路径污染或安全风险：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
location ~* \.(js|css|png|jpg|jpeg|gif|webp|svg|woff2|ttf|eot|ico)$ {
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，防止二进制乱码
}✅
try_files $uri @mirror是推荐结构：先查本地，命中即返回；未命中才跳转到@mirror回源+落盘。
❌ 别把root写在@mirror块里——$request_filename在那里解析不到正确路径。
权限与落盘行为要可控
proxy_store_access 控制生成文件的系统权限，不是 HTTP 权限：
proxy_store_access user:rw group:r all:r;
这表示：Nginx 自己可读写，同组用户只读，其他人也只读。比依赖系统 umask 更可靠，也更安全。
补充关键细节提升稳定性
光能落盘还不够，得让镜像真正可用、可查、可管：
-
加标识头方便排查：
add_header X-Cached-By "proxy_store"; -
设客户端缓存策略：
expires 30d; add_header Cache-Control "public, immutable"; -
验证是否生效：首次请求一个尚未存在的资源（如
/img/new-logo.png），检查 Nginx error log 是否出现proxy_store: "/data/mirror/img/new-logo.png", 并确认文件已生成
它不做的事，你得心里有数
- ❌ 不校验内容一致性：上游更新了，本地不会自动同步
- ❌ 不清理过期文件：没有 TTL、没有 purge 接口，靠运维脚本或 rsync 管理
- ❌ 不处理非 200 响应：4xx/5xx 不落盘，也不报错，只是跳过
- ❌ 不支持 POST/PUT：只对 GET/HEAD 类请求有效，且要求幂等
适合场景很明确：官网静态页、文档站点、图库、离线镜像站、CDN 备份节点——前提是 URL 稳定、内容静态、更新频率低。
不复杂但容易忽略
