proxy_store是静态资源镜像落地机制，非缓存——响应原样写磁盘，本地文件存在则直接返回，无校验、不过期、不压缩；需配置proxy_store on、proxy_store_path、root/alias及if(!-e $request_filename) proxy_pass。
proxy_store 不是缓存机制，而是一种“静态资源镜像落地”方式——它把从后端拉取的响应原样写入本地磁盘指定路径，并在后续请求中直接由 Nginx 读取该文件返回，不经过缓存校验、不自动过期、不压缩重写，完全由你控制生命周期。
核心配置要点
要实现真正持久化的静态资源镜像，需满足三个条件：路径可写、命中逻辑可靠、本地文件优先于代理回源。关键指令如下：
- proxy_store on; —— 启用响应落盘功能（必须放在 location 块内）
- proxy_store_path /path/to/mirror; —— 指定根存储目录（注意：Nginx 会按 URI 自动创建子目录结构）
- root /path/to/mirror; 或 alias 配合路径映射 —— 让 Nginx 能正确定位已落盘的文件
- if (!-e $request_filename) { proxy_pass http://backend; } —— 仅当本地文件不存在时才回源，这是镜像行为的关键判断
推荐的 root 模式配置（适合全站镜像）
适用于将整个站点（如 /images/、/css/、/js/）完整镜像到本地目录，URI 路径与磁盘路径严格对齐：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
location / {
root /data/mirror;
proxy_store on;
proxy_store_path /data/mirror;
proxy_store_access user:rw group:rw all:rw;
if (!-e $request_filename) {
proxy_pass http://origin.example.com;
proxy_set_header Host origin.example.com;
}
}
说明：当请求 /images/logo.png 时，Nginx 先检查 /data/mirror/images/logo.png 是否存在；若不存在，则向后端发起请求，并把响应体写入该路径；下次再请求，直接读取本地文件返回。
推荐的 alias 模式配置（适合子路径镜像）
当你只想镜像某一段路径（例如只镜像视频切片），且希望存储路径与 URL 路径解耦时使用：
location ^~ /video/hls/ {
alias /data/hls/;
proxy_store on;
proxy_store_path /data/hls;
proxy_store_access user:rw group:rw all:rw;
if (!-e $request_filename) {
proxy_pass http://origin.example.com/video/hls/;
}
}
说明：请求 /video/hls/2026/06/stream.m3u8 会被映射为读取 /data/hls/2026/06/stream.m3u8；若文件缺失，Nginx 向后端 http://origin.example.com/video/hls/2026/06/stream.m3u8 拉取并保存。
运维注意事项
- 无自动过期机制：proxy_store 不识别 Last-Modified、ETag 或 Cache-Control，一旦落盘即永久存在，需自行定期清理（如用 find + cron 删除 30 天前的文件）
- 权限必须匹配：确保 Nginx worker 进程用户（如 www-data）对 proxy_store_path 目录有读写权限，否则写入失败且静默降级为纯代理
- 不支持范围请求（Range）自动续传：若后端返回 206 Partial Content，proxy_store 仍会完整写入整个响应体，不适合断点续传场景
- 避免与 proxy_cache 混用：二者逻辑冲突，同一 location 中不应同时启用
