配置 proxy_cache_key 的本质是让 nginx 准确识别哪些请求该共用一份缓存；需精简变量、清洗干扰参数、添加业务前缀、避免敏感信息明文、并实测验证 key 生效。

配置 proxy_cache_key 的本质，是让 Nginx 准确识别“哪些请求该共用一份缓存”。键值写不准，轻则缓存命中率低，重则用户看到别人的数据、移动端加载 PC 页面、带登录态的内容被公开缓存。

只保留真正影响响应内容的变量

每个加进 key 的字段，都会成倍增加缓存碎片。必须逐个确认：这个字段变了，后端返回的内容真的会不同吗？

• 设备类型用 $device（需提前用 map 提取 desktop/mobile/tablet），别直接塞 $http_user_agent
• 登录用户可加 $cookie_user_id，未登录统一设为 "guest"，避免匿名用户生成海量小缓存
• 语言地区取主语言（如 zh 或 en），而不是全量 $http_accept_language；若需细化区域，再叠加 $geoip_country_code
• 绝对不要包含 $request_time、$msec、$date_gmt 这类每次请求都变的变量，否则缓存永远不命中

主动清洗干扰性查询参数

UTM、时间戳、随机数等参数不影响实际响应，却会让同一接口产生上千个 key。不能简单拼接 $args，要预处理：

FastAPI Flask Proxy

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

下载

• 在 http 块中定义 map 清洗参数串，例如剔除 utm_*、v=、t=、_t=
• 示例：map $args $clean_args { ~^(.*&)?(utm_source|v|t|_t)=[^&]+(&.*)?$ "$1$2"; default $args; }
• 在 proxy_cache_key 中使用 $clean_args，而非原始 $args
• 若后端对参数顺序不敏感（如 ?a=1&b=2 和 ?b=2&a=1 返回相同结果），Nginx 不支持自动排序，建议仅对明确需区分参数的路径启用缓存

结构清晰 + 加业务前缀便于管理

自定义 key 上线后，刷新和排查都依赖可读性和可识别性：

• 开头加业务标识，例如："api_v2:$scheme://$host$request_uri:$device:$lang"
• 含 Cookie 或 Header 的 key 无法用“按 URL 刷新”，必须按 Cache Key 清理，有前缀才好批量识别
• 推荐用冒号 : 或下划线 _ 分隔层级，避免斜杠或空格引发解析歧义
• 避免明文放入敏感字段，如需用户标识，优先哈希后使用：md5($cookie_user_id)

验证 key 是否真实生效

配置写完不等于 key 按预期生成，必须实测确认：

• 添加日志格式：log_format cache '$cache_key - $upstream_cache_status';，再在 access_log 中启用该格式
• 用 curl -I 观察响应头中的 X-Cache-Status（需配 add_header X-Cache-Status $upstream_cache_status;）和 Age 字段变化
• 临时把 key 设为固定字符串（如 "debug_key"），看多个不同请求是否全部命中 HIT，快速验证配置是否加载成功