proxy_store 是 Nginx 轻量级磁盘缓存指令，将上游成功响应原样落盘为静态文件，适用于降级兜底、高成本资源固化及只读镜像站；需配合 alias 和双 location（读/写分离）实现静态化分发闭环。
proxy_store 是 Nginx 的一个模块级指令，用于将上游（后端）响应的内容自动缓存到本地磁盘，并以静态文件形式落盘。它不同于 proxy_cache（内存+磁盘的完整缓存系统），而是更轻量、更直接地“镜像”后端资源到指定路径，适合构建静态化分发节点或边缘缓存镜像站。
要真正用好 proxy_store，关键不是加一行配置，而是理解它的行为边界和配套机制。
proxy_store 的核心作用与适用场景
- 它不主动预热、不自动校验过期、不支持缓存清理策略（如
proxy_cache_purge）； - 每次请求触发一次后端回源，并把响应体原样写入本地文件（路径由
alias或root+ URI 决定）； - 仅对 200、201、206、301、302 等成功状态码生效（默认），且要求响应头中不含
Cache-Control: no-store； - 适合：
- 后端服务不稳定，需降级为静态资源兜底；
- 静态资源生成成本高（如 PDF 渲染、图片缩略图），希望首次生成后永久复用；
- 构建只读镜像站点（如文档中心、API 参考页），内容更新频次低但访问量大。
基础配置结构与关键细节
以下是一个典型配置片段（放在 location 块内）：
location /api/docs/ {
proxy_pass https://backend.example.com/;
proxy_store on;
proxy_store_access user:rw group:rw all:r;
alias /var/www/mirror/docs/;
}
说明要点：
-
proxy_pass必须带结尾/，否则 URI 拼接会出错； -
alias指定本地存储根路径，Nginx 会将请求 URI（如/api/docs/v2/index.html）去掉前缀/api/docs/后，拼到alias路径下，即最终写入/var/www/mirror/docs/v2/index.html； - 若用
root替代alias，则路径拼接逻辑不同（会保留完整 URI），容易误写入深层嵌套，推荐统一用alias； -
proxy_store_access控制生成文件的权限，避免因权限不足导致写入失败（常见于 SELinux 或容器环境）； - 不需要额外开启
proxy_buffering off——proxy_store默认已绕过缓冲区直写磁盘。
⚠️ 注意：
proxy_store不会自动创建父目录。确保/var/www/mirror/docs/目录存在且 Nginx worker 进程有写权限。
实现“静态化分发”的闭环逻辑
单纯开启 proxy_store 只完成“写”，还需配合“读”才能形成静态分发能力。推荐采用 双 location 分离策略：
# 【写】首次请求时回源并落盘
location ~ ^/api/docs/(?<relpath>.*)$ {
proxy_pass https://backend.example.com/$relpath;
proxy_store on;
proxy_store_access user:rw group:rw all:r;
alias /var/www/mirror/docs/;
}
# 【读】后续请求优先走本地静态文件（命中即返回，不 upstream）
location /docs/ {
alias /var/www/mirror/docs/;
# 可选：启用内置静态文件处理优化
sendfile on;
tcp_nopush on;
expires 1y;
}</relpath>
这样：
- 外部请求
/api/docs/v2/index.html→ 触发回源 + 落盘 → 存为/var/www/mirror/docs/v2/index.html； - 后续可直接访问
/docs/v2/index.html，Nginx 将跳过代理，直接sendfile返回本地文件； - 实现了「动态生成 → 静态固化 → 高速分发」的完整链路。
生产环境注意事项
-
无并发写保护：多个相同请求可能同时触发多次回源并写同一文件。可通过
limit_req限流或前端加幂等控制缓解； -
不校验后端变更：一旦文件落地，即使后端内容更新，本地镜像也不会自动刷新。如需更新，需手动删除对应文件或加版本号路径（如
/api/docs/v2.1/）； -
日志与监控建议：在
log_format中加入$upstream_http_content_length和$status，便于识别哪些请求走了回源、哪些命中了本地文件； -
容器部署时注意挂载：若运行在 Docker 中，确保
/var/www/mirror/docs/目录挂载为 volume，避免容器重启后镜像丢失。
Nginx 的 proxy_store 是一条低调但实用的路径——它不炫技，但足够可靠。只要理清“谁来写、写哪、怎么读”，就能低成本搭建出具备镜像能力的静态分发层。
