缓存未命中根因是请求本该命中却反复走后端，需同步验证日志（$upstream_cache_status）、响应头（cache-control/set-cookie）、缓存文件落盘情况及proxy_cache_key稳定性。

缓存未命中引发后端穿透，关键不是“没配缓存”，而是请求本该命中却反复走后端。必须从运行时证据出发，同步验证日志、响应头、缓存文件和请求特征四方面，才能准确定位根因。

看 $upstream_cache_status 日志确认真实状态

这是最直接的判断依据，不能依赖 curl 或主观猜测：

• 在 http 块中定义带缓存状态的日志格式：log_format cache '$remote_addr - $upstream_cache_status $time_local "$request" $status $body_bytes_sent';
• 在对应 location 中启用该日志：access_log /var/log/nginx/cache.log cache;
• 重启 Nginx 后观察日志字段值：HIT 表示命中，MISS 是首次未命中，EXPIRED 表示缓存存在但已过期，BYPASS 表示被规则主动跳过（如含 Cookie、no-cache 头）
• 若大量出现 EXPIRED 或 BYPASS，说明缓存有生成，但被绕过或刷新太快，不是“没缓存”，而是“没用上”

检查响应头是否实际允许缓存

后端返回的响应头会覆盖 Nginx 缓存策略，常被忽略：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 用 curl -I 请求目标 URL，重点看：Cache-Control、Expires、Set-Cookie、Vary
• 只要出现 Cache-Control: no-store / private / no-cache 或任意 Set-Cookie:，Nginx 默认不缓存（除非显式配置 proxy_ignore_headers Set-Cookie）
• 若后端无法改，可在 Nginx 层强制覆盖：proxy_cache_valid 200 302 10m;（优先级高于响应头），并隐藏干扰头：proxy_hide_header Set-Cookie;

确认缓存文件是否真实写入磁盘

配置正确但没落盘，等于没缓存：

• 进入 proxy_cache_path 指定目录（如 /var/cache/nginx/），执行：find . -type f | head -10
• 若无任何文件，检查：目录权限（Nginx 进程用户是否可写）、proxy_temp_path 是否同文件系统且可写、磁盘空间是否充足
• 若有文件，用 stat 查看修改时间，对比请求时间——若频繁刷新，说明 proxy_cache_key 不稳定或 inactive 设置过短

分析 proxy_cache_key 是否引入动态干扰

Key 设计不合理，会让同一资源生成无数个缓存副本：

• 默认 proxy_cache_key $scheme$host$request_uri; 风险很高：URI 带随机参数（如 ?t=1698765432）或用户标识（如 $cookie_user_id）会导致 key 每次都不同
• 应精简 key，剔除无关变量：例如只保留路径和必要参数，用 map 归一化 UA 或设备类型，避免 Vary: User-Agent 直接参与 key
• 对含分页、排序等参数的接口，可考虑在 proxy_pass 前用 set $args 清理非关键 query string