要在 Nginx 中记录详细的缓存命中状态日志，核心是使用内置变量 $upstream_cache_status，并确保它在启用 proxy_cache 的上下文中被正确捕获和输出；需配置 proxy_cache_path、在含 proxy_pass 的 location 中启用 proxy_cache，再于 log_format 中加入该变量，日志中即可显示 HIT、MISS、EXPIRED、BYPASS 等状态值。
要在 Nginx 中记录详细的缓存命中状态日志，核心是使用内置变量 $upstream_cache_status，并确保它在启用 proxy_cache 的上下文中被正确捕获和输出。
配置缓存区域与启用缓存
只有在真正启用 proxy_cache 的 location 中，$upstream_cache_status 才会输出有效值（如 HIT、MISS、EXPIRED 等）。否则日志中显示为破折号 -。
- 在
http块中定义缓存路径和共享内存区：proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:50m inactive=1h max_size=2g; - 在目标
location中启用缓存并设置有效期：proxy_cache my_cache;<br>proxy_cache_valid 200 302 10m;<br>proxy_cache_valid 404 1m;
- 确认该 location 包含
proxy_pass，因为该变量只在代理请求时生效
在日志格式中加入缓存状态
将 $upstream_cache_status 直接写入 log_format，就能在每条访问日志末尾看到真实缓存行为。
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 在
http块中定义带状态的日志格式：log_format cache_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_cache_status" $request_time $upstream_response_time'; - 在
server或location中启用该格式：access_log /var/log/nginx/cache.log cache_log; - 重启 Nginx 后，日志行类似：
192.168.1.100 - - [01/Oct/2026:10:20:30 +0000] "GET /style.css HTTP/1.1" 200 1245 "-" "curl/7.68.0" "HIT" 0.002 0.001
理解常见状态含义，辅助排查
日志中出现的值不是随机字符串，而是 Nginx 缓存引擎的真实执行结果：
- HIT：响应直接来自缓存，未向后端发起请求
- MISS：缓存未命中，Nginx 向后端获取并缓存了响应
- EXPIRED：缓存存在但已过期，Nginx 重新验证或拉取
-
BYPASS：因
proxy_cache_bypass规则（如含特定 cookie 或参数）跳过读缓存 -
STALE：缓存已过期，但配置了
proxy_cache_use_stale，仍返回旧内容 - UPDATING：缓存过期且后台正在更新，当前返回旧副本
快速分析日志中的缓存分布
无需额外工具，用 Linux 命令即可统计命中率和定位瓶颈：
- 查看各状态出现次数：
awk '{print $12}' /var/log/nginx/cache.log | sort | uniq -c | sort -nr - 找出最常 MISS 的 URI：
grep "MISS" /var/log/nginx/cache.log | awk '{print $7}' | sort | uniq -c | sort -nr | head -10 - 检查 BYPASS 是否集中出现在带
?nocache=1或登录态请求中，判断是否规则误配
