nginx反向代理缓存需精准设计proxy_cache_key，仅纳入影响响应内容的业务维度：设备类型、登录态标识、主语言、协议路径，并清洗utm等干扰参数，加业务前缀便于管理与清理。

要让 Nginx 的反向代理缓存真正“懂业务”，关键不是堆字段，而是让 proxy_cache_key 精准反映哪些维度实际影响响应内容。加错一个参数，缓存就分裂；漏掉一个业务标识，不同设备或语言的用户可能拿到错误内容。

必须纳入的业务维度

只保留真正导致后端返回不同结果的变量，避免无意义区分：

• 设备类型：用 $device（需提前用 map 提取 desktop / mobile / tablet），别直接用 $http_user_agent——后者千变万化，极易造成缓存碎片
• 登录态标识：已登录用户用 $cookie_user_id；未登录统一设为 "guest"，防止匿名用户各自生成独立缓存项
• 主语言：提取 zh、en 这类一级语言码，而非完整 $http_accept_language；高阶场景可叠加 $geoip_country_code 构成 zh-CN 或 en-US
• 请求协议与路径：$scheme、$host、$request_uri 是基础骨架，必须保留

示例：

map $http_user_agent $device {
    ~*iPad|iPhone|iPod  mobile;
    ~*Android.*Mobile  mobile;
    ~*Tablet  tablet;
    default  desktop;
}
map $http_accept_language $lang {
    ~^zh  zh;
    ~^en  en;
    default  en;
}

必须剔除的干扰参数

UTM、分享追踪、埋点类参数（如 utm_source、v、t、_t）不改变内容，却会让同一 URL 生成几十个缓存副本：

FastAPI Flask Proxy

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

下载

• 在 http 块中定义清洗逻辑：

  map $args $clean_args {
    ~^(.*&)?(utm_source|v|t|_t)=[^&]+(&.*)?$ "$1$2";
    default $args;
  }

• proxy_cache_key 中引用 $clean_args，而非原始 $args

加业务前缀，便于管理与清理

缓存键开头加上可读性强的业务标识，比如 api_v2、blog_static、user_feed：

proxy_cache_key "api_v2:$scheme://$host$request_uri:$device:$lang:$cookie_user_id";

好处很明显：

• 清理缓存时能按前缀批量操作（如 purge api_v2:*）
• 日志里一眼识别缓存归属，排查问题更快
• 避免和其它项目缓存键冲突

配合行为控制，防止误命中

• 含 Cookie 或 Header 的缓存无法靠 URL 刷新，必须支持按 Cachekey 清理，提前确认你用的缓存清理工具（如 nginx-purge 或自研接口）支持该方式
• 开启 proxy_ignore_headers Set-Cookie，避免因后端返回 Set-Cookie 导致缓存被自动跳过
• 调试时用 proxy_cache_bypass $arg_nocache，加 ?nocache=1 就绕过缓存，方便验证

不复杂但容易忽略