实现安全私有文件下载需采用“鉴权在前、透传在后”的两段式链路：proxy_pass 将请求转发至可信后端校验权限并返回 X-Accel-Redirect 响应头，internal location 仅响应 Nginx 内部跳转，屏蔽外部直连，配合 alias、防绕过配置及轻量加固措施确保安全。

要实现极为安全的私有文件下载，核心不是靠 proxy_pass 做鉴权，而是用它配合 internal location 构建“鉴权在前、透传在后”的两段式链路——proxy_pass 负责把请求交给可信后端做校验，internal location 则像一道物理闸门，只认 Nginx 自己发来的内部跳转，彻底屏蔽外部直连。

对外入口：用 proxy_pass 转发鉴权请求

用户访问的路径（如 /api/download?file=2026-report.pdf）必须走普通 location，不带 internal，且通过 proxy_pass 转发给后端服务：

• 后端收到请求后，校验登录态、权限、签名或时效性，确认合法才继续
• 后端不读文件、不吐流，只返回 HTTP 响应头：
  X-Accel-Redirect: /_private/2026-report.pdf
Content-Disposition: attachment; filename="2026-report.pdf"
• 关键点：这里 proxy_pass 的目标是可信内部服务（如 127.0.0.1:8000），不能指向公网或不可控后端

对内透传：internal location 只响应内部跳转

对应 X-Accel-Redirect 中的路径，必须配置一个明确标记 internal 的 location：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 路径需严格匹配，例如 location /_private/ { internal; alias /var/www/private/; }
• alias 末尾必须带斜杠，且与 location 末尾一致，否则文件路径拼接错误
• 该 location 内禁止出现 proxy_pass 到外部服务——它只应直接读磁盘，或仅 proxy_pass 到内部静态文件服务（如另一个 Nginx 实例）
• 客户端若尝试直连 GET /_private/2026-report.pdf，Nginx 立即返回 404，不暴露任何存在性信息

防绕过细节：避免常见失效陷阱

很多配置看似正确却失效，问题往往出在衔接环节：

• 后端返回 302 重定向（比如跳到 /files/xxx.pdf）会完全绕过 internal——因为这是浏览器行为，不是 Nginx 内部跳转
• 如果用了 auth_request，它的子请求 location（如 location = /_auth）也必须加 internal，否则可被直接调用绕过主入口
• 不要在 internal location 中写 root；alias 更可控，root 容易因路径拼接导致越界访问
• 上传目录和下载目录必须物理隔离，且上传路径（如 /api/upload）绝不能映射到 alias 或 root 下，防止文件被意外下载执行

增强防护：轻量但有效的加固项

在基础链路之上，加几行就能显著提升安全性：

• 为 /_private/ location 加上 expires 1m;，防止下载链接长期有效被滥用
• 添加 add_header X-Content-Type-Options nosniff;，阻止浏览器 MIME 类型嗅探引发的 XSS 风险
• 搭配 limit_conn 或 limit_req 控制单 IP 下载频次，防暴力枚举
• 若需按用户隔离路径，后端返回的 X-Accel-Redirect 可动态构造，如 /_private/user_123/report.pdf，Nginx 无需改配置