需自定义log_format并启用proxy_cache后在server或location块中配置access_log，$upstream_cache_status才有效；其值如hit、miss等仅在proxy_pass执行完毕且缓存启用时生成。
要在 Nginx 的全量审计日志中记录 $upstream_cache_status，关键不是“开启审计”，而是**自定义 log_format 并确保该变量在请求生命周期中可用**。这个变量仅在使用 proxy_cache（或类似缓存模块）且完成 upstream 交互后才被赋值，因此必须将它写入 access_log 的 format 中，并确保日志指令作用于处理完 upstream 的阶段（通常是 location 或 server 块中）。
确认缓存已启用且变量可访问
$upstream_cache_status 是 Nginx 内置变量，但它的值只在以下条件下有效：
- 当前请求匹配了配置了
proxy_cache的 location； - 实际执行了 proxy_pass 并完成了与 upstream 的通信（包括缓存命中/未命中/绕过等）；
- 没有在 upstream 执行前就返回（如被 rewrite、return 或 auth_request 拦截）。
如果日志中该字段始终为空或“-”，先检查是否漏配 proxy_cache 或 proxy_cache_valid，并确认请求确实走到了缓存逻辑分支。
定义含 cache_status 的 log_format
在 http 块中定义一个新格式，例如：
log_format audit_log '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'$upstream_cache_status '
'$upstream_addr $request_time $upstream_response_time';注意：$upstream_cache_status 可直接使用，无需额外模块；它可能的值包括 HIT、MISS、BYPASS、EXPIRED、STALE、UPDATING、REVALIDATED、MISS_FROM_UPSTREAM 等（取决于 Nginx 版本和缓存配置）。
在合适位置启用该日志格式
不能只在 http 块定义 format 就生效，还需在具体作用域（如 server 或 location）中调用 access_log：
- 若需全局审计，放在
server块内：
access_log /var/log/nginx/audit.log audit_log; - 若只对缓存路径审计，放在启用了
proxy_cache的location块更精准：
location /api/ {
proxy_cache my_cache;
proxy_pass http://backend;
access_log /var/log/nginx/cache_audit.log audit_log;
}
避免在未启用缓存的 location 中使用该 format，否则 $upstream_cache_status 恒为“-”，造成日志冗余。
验证与排查建议
- 修改配置后运行
nginx -t确认语法正确，再nginx -s reload； - 发起几次缓存相关请求（如首次访问触发 MISS，再次访问应 HIT），然后查看日志文件是否出现对应状态；
- 若仍为空，可在 location 中临时加
add_header X-Cache-Status $upstream_cache_status;，用 curl -I 验证变量是否真实生成； - 注意：该变量不适用于纯静态文件服务（如 root + try_files），除非你用 proxy_cache 缓存静态内容。
