proxy_cache_bypass的作用是让特定请求跳过缓存查找直接回源，需与proxy_cache共存于同一location，变量命名严格小写加下划线，值非空且不为"0"/"off"即触发，须配合proxy_no_cache防止缓存污染。

proxy_cache_bypass 的作用不是“处理动态请求”，而是让特定请求**跳过缓存查找环节，直接回源**。它不改变缓存本身，也不刷新旧内容，只控制单次请求是否绕开缓存。要让它生效，必须满足三个基础条件：启用缓存、变量写对、值判准。

必须和 proxy_cache 共存于同一 location

单独配置 proxy_cache_bypass 没有效果。Nginx 会直接忽略它，除非对应 location 中明确启用了缓存：

• 必须有 proxy_cache mycache（名称需与 proxy_cache_path 中 keys_zone 一致）
• 建议搭配 proxy_cache_valid 定义哪些响应可缓存
• 不能把 proxy_cache_bypass 放在 http 或 server 块里指望全局生效；它只在启用缓存的 location 内起作用

变量命名和取值规则要严格匹配

客户端发送的请求头（如 X-No-Cache: 1），Nginx 内部对应变量是 $http_x_no_cache，不是 $http_X_No_Cache 或 $http_xnocache：

FastAPI Flask Proxy

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

下载

• 全部小写
• 短横线 - 替换为下划线 _
• 前缀固定为 $http_
• 值只要非空，且不等于 "0" 或 "off"（不区分大小写），即触发绕过

例如这些都有效：X-No-Cache: true、X-No-Cache: T、X-No-Cache: force；而 X-No-Cache: 0 或缺失该头则无效。

多条件组合与业务逻辑解耦

单一变量不够灵活时，推荐用 map 提前定义判断逻辑，再统一驱动 bypass 和 no_cache：

• 按路径跳过：map $request_uri $skip_cache { ~*^/admin/ 1; default 0; }
• 按角色跳过：map $http_x_user_role $skip_cache_by_role { "admin" 1; default 0; }
• 按 Cookie 判断：map $cookie_sessionid $skip_cache_by_login { ~. 1; default 0; }
• 在 location 中同时启用：proxy_cache_bypass $skip_cache $skip_cache_by_role $skip_cache_by_login; 和 proxy_no_cache $skip_cache $skip_cache_by_role $skip_cache_by_login;

务必配合 proxy_no_cache 防止缓存污染

proxy_cache_bypass 只跳过读缓存，但默认仍会把响应写入缓存。如果带认证头或用户私有数据的请求绕过缓存后被缓存，后续无权限用户可能命中并泄露信息：

• 必须用相同变量同步配置 proxy_no_cache
• 二者配合才能实现“既不读旧缓存，也不存新响应”
• 上线后通过 add_header X-Cache-Status $upstream_cache_status; 和日志字段 $upstream_cache_status 验证是否真正生效（BYPASS 表示成功绕过）