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 刷新”功能批量清理
