nginx默认proxy_cache_key包含全部请求信息导致缓存命中率低，应精简为仅含影响响应的变量；静态资源用$scheme$host$uri，api保留lang/region等业务参数，剔除utm/t等跟踪参数；通过map预处理args和cookie生成干净key；配合proxy_cache_bypass和proxy_no_cache实现动态穿透；需添加x-cache-status响应头及cache_log日志验证效果。

直接用默认 proxy_cache_key，Nginx 会把整个请求 URI（含所有 query 参数、Cookie、Header）原样拼进去。结果就是同一接口，因带了 utm_source=weibo、_ga=GA1.2.xxxx 或随机 t=1678901234 就生成完全不同的缓存项——命中率暴跌，磁盘白占，回源压力不降反升。

只保留真正影响响应的参数

缓存键不是越“全”越好，而是越“准”越好。核心原则是：只有导致后端返回不同内容的变量，才放进 key。

• 静态资源（JS/CSS/图片）通常只需 $scheme$host$uri —— 路径不变，内容就不该变
• API 接口若按 lang=zh 或 region=us 返回不同数据，就只保留这两个参数；剔除 utm_*、ref=、v=、t= 等纯跟踪或防缓存参数
• 登录态接口若需区分用户，只取关键字段如 $cookie_user_id，未登录时统一设为 "guest"，避免空值或缺失导致 key 不一致

用 map 预处理，让 key 干净可控

别在 proxy_cache_key 行内写正则或复杂逻辑。推荐用 map 提前清洗参数：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• 剥离无关 query 参数：
  map $args $cache_args {
    ~^(?:(?!lang|region|id|theme).)*$ ""; # 全都不匹配时为空
    ~(lang=[^&]+|region=[^&]+|id=[^&]+|theme=[^&]+) $1;
  }
• 提取指定 Cookie 值：
  map $http_cookie $cache_user_id {
    ~user_id=([^;]+) $1;
    default "guest";
  }
• 最终 key 示例：
  proxy_cache_key "$scheme$host$uri|$cache_args|$cache_user_id";

配合 bypass 和 no_cache 实现动态穿透

精准 key 解决了“该缓存什么”，而 proxy_cache_bypass 和 proxy_no_cache 决定“什么时候不缓存”：

• 调试时加 ?nocache=1：proxy_cache_bypass $arg_nocache;，跳过缓存直连后端
• 敏感操作（如提交表单、修改设置）可设 proxy_no_cache $arg_action;，只要含 action=save 就不缓存
• 灰度流量用 Header 控制：proxy_cache_bypass $http_x_abtest_flag;，带特定 header 就绕过缓存

上线前验证与可观测性

改完 key 后必须确认是否生效：

• 配置响应头：add_header X-Cache-Status $upstream_cache_status;，观察 HIT/MISS 分布
• 用 log_format 记录真实 key：log_format cache_log "$upstream_cache_status $cache_key";，抽样检查是否符合预期
• 注意：一旦 key 中含 Cookie 或自定义 header，就无法用“按 URL 刷新”，需改用“按 Cachekey 刷新”功能批量清理