proxy_cache_key的核心作用是定义缓存键以决定哪些请求共用同一份缓存，需按业务逻辑精准设计区分维度，如多端适配、登录态隔离、多语言支持、子域隔离，并清洗无关参数，最后验证配置生效且缓存机制整体就绪。
proxy_cache_key 的核心作用是告诉 Nginx：“哪些请求该共用同一份缓存”。配置不是拼凑变量，而是按业务逻辑精准表达“内容是否相同”的判断依据。
明确缓存区分维度
默认值 $scheme$proxy_host$request_uri 只考虑协议、主机和路径，但实际场景常需更多区分：
- 多端适配：加入
$http_x_requested_with（值为XMLHttpRequest或空）比依赖$http_user_agent更稳定，避免因 UA 微小差异导致缓存碎片 - 登录态隔离：用
md5($cookie_user_id)替代明文$cookie_user_id，既保证用户间不串缓存，又规避敏感信息泄露风险 - 多语言支持：若后端通过
Accept-Language或自定义头HTTP_X_LANG返回不同内容，需将其纳入 key，如$http_accept_language - 子域隔离：用
$host替代$proxy_host，确保www.example.com和api.example.com不共享缓存
精简无关参数，减少缓存膨胀
UTM 参数、时间戳、随机数等不影响内容输出，却会让同一资源生成大量 key。不能直接拼 $args，应预处理：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 在 http 块中定义 map 清洗参数：
map $args $clean_args {<br> default "";<br> ~^(.*)(?:&|&?)(?:utm_[^&]*|ts=\d+|random=[^&]*)(?:&.*)?$ "$1";<br>} - key 中使用清洗后变量：
proxy_cache_key "$scheme$host$request_uri$is_args$clean_args|$lang|$device";
验证 key 是否按预期生成
配置写完必须验证，否则无法确认是否生效：
- 添加日志格式：
log_format cache '$cache_key - $upstream_cache_status';，并在 access_log 中启用 - 响应头中输出状态：
add_header X-Cache-Status $upstream_cache_status;，用 curl -I 查看 HIT/MISS - 临时设 key 为固定字符串（如
"debug"），观察多个请求是否全部命中 HIT，快速确认配置已加载
确保缓存机制整体就绪
proxy_cache_key 再准确，缺以下任一条件也无法工作：
- http 块中已声明
proxy_cache_path，路径存在且 Nginx 进程有读写权限 - 对应 location 中启用了
proxy_cache zone_name，且 zone_name 与 proxy_cache_path 中 keys_zone 名称一致 - 后端响应含有效缓存控制头（如
Cache-Control: public, max-age=3600），或 Nginx 侧用proxy_cache_valid强制指定状态码缓存策略
