Nginx 缓存绕过怎么配置 proxy_bypass_cache 跳过读取缓存-Nginx-PHP中文网

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

nginx 缓存绕过怎么配置 proxy_bypass_cache 跳过读取缓存

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），检查：