要让特定请求跳过缓存并防止响应被缓存，必须在启用 proxy_cache 的 location 块中同时配置 proxy_cache_bypass 和 proxy_no_cache，且两者使用相同变量（如 $http_x_bypass_cache），并添加 add_header x-cache-status $upstream_cache_status 验证状态为 byp。

要让特定请求跳过缓存、直接读取源站，核心是正确配置 proxy_cache_bypass，但它不能单独生效——必须和 proxy_cache 在同一个 location 块中启用，且需配合 proxy_no_cache 防止响应被错误缓存。

必须共用 location 并启用缓存

只写 proxy_cache_bypass 不起作用。Nginx 会忽略它，除非该 location 已明确启用缓存：

• 确保已定义缓存区（如 proxy_cache_path /path/ keys_zone=my_cache:10m;）
• 在目标 location 中必须包含：
  proxy_cache my_cache;
proxy_cache_valid 200 5m;
• proxy_cache_bypass 必须出现在同一块内，例如：

location /api/ {
  proxy_pass http://backend;
  proxy_cache my_cache;
  proxy_cache_valid 200 5m;
  proxy_cache_bypass $http_x_bypass_cache;
}

设置绕过条件：用变量控制触发逻辑

该指令接收一个或多个变量，只要任一变量值为非空字符串且不等于 "0" 或 "off"，就跳过缓存查找：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 用自定义请求头识别开发请求：proxy_cache_bypass $http_x_bypass_cache;（前端加 -H "X-Bypass-Cache: 1"）
• 用查询参数快速验证：proxy_cache_bypass $arg_nocache;（访问 /api/data?nocache=1）
• 用 Cookie 区分内部用户：proxy_cache_bypass $cookie_dev_mode;（浏览器设置 dev_mode=1）
• 用 Authorization 头识别管理员：proxy_cache_bypass $http_authorization;（适用于带 Token 的管理接口）

防止缓存污染：必须配对 proxy_no_cache

proxy_cache_bypass 只跳过读缓存，不阻止响应写入缓存。若不加限制，管理员请求返回的敏感数据可能被缓存并泄露给普通用户：

• 使用完全相同的变量，同步配置：
  proxy_no_cache $http_x_bypass_cache;
proxy_no_cache $arg_nocache;
proxy_no_cache $cookie_dev_mode;
• 两个指令必须同 location、同变量，才能实现“不读 + 不存”的原子效果
• 避免写 proxy_no_cache 1 这类静态值，它会导致所有请求都不缓存

验证是否真正绕过

上线前务必实测，不能只看配置：

• 添加响应头便于观察：add_header X-Cache-Status $upstream_cache_status;
• 绕过成功时，响应头中 X-Cache-Status 应为 BYP，不是 HIT 或 MISS
• 检查 Nginx 日志中 $upstream_cache_status 字段是否为 BYP
• 对比无绕过参数的请求，确认普通流量仍能稳定命中 HIT