proxy_cache_bypass 实现“条件绕过”，即满足条件时跳过缓存直连后端，需配合 proxy_cache、proxy_cache_valid 等指令生效；支持按请求头、参数、cookie、ip 等变量组合判断，变量值非空且不为 "0"/"off" 即触发；绕过请求仍携带条件头，便于后端返回 304 或更新缓存。

proxy_cache_bypass 不是做“缓存分流”，而是实现“条件绕过”：它让满足特定条件的请求跳过缓存查找，直连后端；其余请求照常走缓存。关键在于“不查缓存”，而非把流量分到不同缓存池或后端集群。

必须配齐缓存基础才能生效

单独写 proxy_cache_bypass 没用，它依赖完整的缓存上下文：

• 所在 location 必须启用缓存：proxy_cache mycache（名称需与 proxy_cache_path 的 keys_zone 一致）
• 必须定义可缓存的响应：proxy_cache_valid 200 302 5m 等
• 若想避免调试响应污染缓存，要同步配置 proxy_no_cache $http_x_debug

常见条件组合方式

变量之间用空格分隔，任意一个为真即触发绕过：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• 按请求头控制：proxy_cache_bypass $http_x_preview $http_x_refresh（带 X-Preview 或 X-Refresh 头即绕过）
• 按参数+Cookie混合判断：proxy_cache_bypass $arg_nocache $cookie_admin（URL 含 ?nocache=1 或含 admin Cookie）
• 按 IP 白名单限制：proxy_cache_bypass $http_x_admin $remote_addr ~^(192\.168\.10\.)（仅内网管理员可绕过）

变量命名和值判断有严格规则

Nginx 内部变量名不是随便写的：

• Header X-Preview-Cache → 变量名是 $http_x_preview_cache（全小写，短横变下划线，前缀固定）
• 值只要非空、且不等于 "0" 或 "off"（不区分大小写），就触发绕过
• 有效值示例："1"、"true"、"force"、"T"
• 无效值示例：""（Header 缺失）、"0"、"OFF"、"false"

配合后端校验头提升智能性

绕过之后的请求会携带标准条件头（如 If-None-Match）给后端：

• 后端返回 304 Not Modified，Nginx 自动返回本地缓存副本
• 后端返回新内容（如 200 + 新 ETag），Nginx 更新缓存并返回新响应
• 这样既保证实时性，又避免无谓的全量传输