proxy_cache_bypass是Nginx跳过缓存读取的核心指令，需在启用proxy_cache的location中配合proxy_no_cache使用；变量值非空且不为"0"/"off"即触发绕过，任一条件满足即直连后端且不写缓存。

proxy_cache_bypass 是 Nginx 实现“跳过读取缓存”的核心指令，它让满足条件的请求不查缓存、直接转发给后端。注意：它本身不阻止响应被缓存，所以必须配合 proxy_no_cache 才算真正绕过整个缓存流程。

配置 proxy_cache_bypass 的关键前提

• 必须在已启用缓存的 location 块中使用（即该 location 里有 proxy_cache mycache;）
• mycache 名称需与 proxy_cache_path 中定义的 keys_zone 完全一致
• 指令值为变量，不能是字面量路径或正则（如 proxy_cache_bypass /admin/ 是非法的）
• 变量只要满足“非空且不等于 "0" 或 "off"”，即触发绕过

常用变量来源与写法示例

• 自定义请求头（推荐，安全可控）
  前端或 curl 加 -H "X-Bypass-Cache: 1"

  proxy_cache_bypass $http_x_bypass_cache;

• URL 查询参数（适合快速测试）
  访问 /api/data?nocache=1

  proxy_cache_bypass $arg_nocache;

• Cookie 字段（适合登录态识别）
  用户 Cookie 中含 dev_mode=1

  proxy_cache_bypass $cookie_dev_mode;

• Authorization 头（适合管理接口）
  请求带 Authorization: Bearer xxx

  proxy_cache_bypass $http_authorization;

• 多个条件任意满足即可（用空格分隔）

  proxy_cache_bypass $http_x_bypass_cache $arg_nocache $cookie_dev_mode;

必须同步配置 proxy_no_cache 防止污染

仅靠 proxy_cache_bypass，后端返回的响应仍可能被缓存（尤其当状态码匹配 proxy_cache_valid 时）。为避免调试数据、敏感内容误入缓存池，务必配对使用：

proxy_cache_bypass $http_x_bypass_cache;
proxy_no_cache $http_x_bypass_cache;

两者变量完全一致，才能确保：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 请求不读缓存（bypass）
• 响应不写缓存（no_cache）

如何验证是否生效

开启日志记录和响应头标识：

log_format cache_log '$remote_addr - $upstream_cache_status ...';
access_log /var/log/nginx/cache.log cache_log;

add_header X-Cache-Status $upstream_cache_status;

发起绕过请求（如 curl -H "X-Bypass-Cache: 1" https://example.com/api），检查：

• 响应头中 X-Cache-Status: BYP
• 日志中 $upstream_cache_status 字段为 BYP
• 普通请求仍显示 HIT 或 MISS，说明策略未影响正常流量

不复杂但容易忽略