在 nginx 中配置缓存失效日志,核心做法是在 `http` 或 `server` 块中使用 `log_format` 定义包含 `$upstream_cache_status` 变量的日志格式,并通过 `access_log` 指令将该格式应用到指定路径。这样配置后,nginx 会在每次请求处理结束时记录缓存状态(如 hit、miss、expired),从而直观地监控缓存命中与失效情况。

如何定义包含缓存状态的日志格式
要实现这一功能,首先需要自定义日志格式。默认的 `combined` 格式并不包含缓存状态信息,因此必须使用 `log_format` 指令创建一个新的格式名称,并在其中加入 `$upstream_cache_status` 变量。该变量会返回当前请求的缓存状态,常见的值包括 `HIT`(命中)、`MISS`(未命中,需回源)、`EXPIRED`(已过期,需回源刷新)以及 `BYPASS`(绕过缓存)。定义好格式后,只需在 `location` 块或 `server` 块中通过 `access_log` 指向该格式即可生效。

log_format cache_status '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'cache_status=$upstream_cache_status';
server {
listen 80;
server_name example.com;
location /static/ {
proxy_cache my_cache;
proxy_pass http://backend;
access_log /var/log/nginx/cache_access.log cache_status;
}
}
上述代码展示了完整的配置片段。首先定义了名为 cache_status 的日志格式,它包含了标准的请求信息以及末尾的 cache_status 字段。接着在 location 块中,将 proxy_cache 启用,并将 access_log 指向新定义的格式。重启 Nginx 服务后,访问静态资源,即可在 /var/log/nginx/cache_access.log 中看到类似 cache_status=HIT 或 cache_status=MISS 的记录。若需排查特定资源的缓存问题,可直接 grep 该日志文件进行分析。
不同缓存状态对日志记录的影响及排查策略
理解日志中的具体状态值是排查缓存问题的关键。HIT 表示请求直接从缓存中获取,响应速度快且后端压力小;MISS 表示缓存中没有该资源,Nginx 向后端发起请求并缓存结果;EXPIRED 表示缓存条目已过期,Nginx 需要重新向后端验证或获取新内容。在实际运维中,如果观察到大量的 MISS,可能意味着缓存时间设置过短或缓存键设计不合理;而大量的 EXPIRED 则可能表明业务逻辑需要更频繁的更新,或者缓存生命周期配置不符合预期。

# 假设后端返回 200 OK # 第一次请求:cache_status=MISS (缓存未命中,回源) # 第二次请求:cache_status=HIT (缓存命中) # 等待过期时间后第三次请求:cache_status=EXPIRED (缓存过期,再次回源)
为了验证上述行为,可以编写一个简单的测试脚本或使用 curl 命令模拟请求。例如,设置 proxy_cache_valid 为较短的时间(如 1s),然后连续发送请求。第一次请求会记录为 MISS,随后的请求在有效期内会记录为 HIT,一旦超过有效期,下一个请求将记录为 EXPIRED。这种模式有助于确认缓存是否按预期工作,以及失效机制是否触发。通过分析这些日志,可以调整 proxy_cache_key 或 proxy_cache_valid 参数,以优化缓存命中率并减少不必要的后端负载。
当 upstream_cache_status 显示 BYPASS 时意味着什么
当日志中出现 BYPASS 状态时,意味着请求被明确配置为绕过缓存层,直接由后端服务器处理。这通常发生在使用了 proxy_cache_bypass 或 proxy_no_cache 指令的情况下。例如,当用户登录或执行写操作时,系统可能配置为跳过缓存以确保数据实时性。此时,即使缓存中存在该资源的旧版本,Nginx 也不会返回缓存内容,而是直接向后端发起请求。这种行为在日志中体现为 cache_status=BYPASS,它与 MISS 不同,MISS 是缓存缺失导致的回源,而 BYPASS 是策略性的主动绕过。











