proxy_cache_bypass 是缓存绕过指令，需与 proxy_cache 和 proxy_cache_valid 同在 location 块中启用，变量名严格为 $http_x_refresh（小写、短横变下划线），值非空且不为 "0" 或 "off" 才触发绕过，并须配对 proxy_no_cache 防污染，生效时响应头显示 x-cache-status: byp。

proxy_cache_bypass 不是清理缓存，而是让特定请求不查缓存、直接回源。要让它真正起作用，必须满足几个关键前提，否则配置写得再全也等于没写。

必须和 proxy_cache 在同一 location 中启用

只在 server 或 http 块里写 proxy_cache_bypass，Nginx 完全忽略。它必须和以下指令共存于同一个 location 块：

• proxy_cache my_cache（名称需与 proxy_cache_path 中 keys_zone 一致）
• proxy_cache_valid 200 302 10m（定义哪些响应可缓存）

变量命名必须严格规范

客户端发送 X-Refresh: 1，Nginx 内部对应变量只能是 $http_x_refresh：

• 全部小写
• 短横线 - 替换为下划线 _
• 固定前缀 $http_
• 错写成 $http_X_Refresh 或 $http_xrefresh 都无效

值判断逻辑要记准

只要变量展开后满足以下任一条件，就触发绕过：

• 值非空（如 "1"、"true"、"force"、"debug"）
• 值不等于 "0"（不区分大小写）
• 值不等于 "off"（不区分大小写）

例如：curl -H "X-Refresh: true" https://site.com/api 有效；curl -H "X-Refresh: 0" 或不带该头则不绕过。

FastAPI Flask Proxy

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

下载

务必搭配 proxy_no_cache 防污染

proxy_cache_bypass 只控制“不读缓存”，默认仍会把这次响应存入缓存（只要状态码匹配 proxy_cache_valid）。管理员带权限头请求的数据若被缓存，后续普通用户可能误命中。

推荐配对使用：

• proxy_cache_bypass $http_x_refresh;
• proxy_no_cache $http_x_refresh;

两个指令共用同一变量，确保既不读旧缓存，也不存新响应。

验证是否生效，不能只看配置。实测时检查响应头中是否有 X-Cache-Status: BYP，或日志中 $upstream_cache_status 字段是否为 BYP，而非 HIT 或 MISS。