如何利用 $upstream_http_x_cache_lookup 追踪多级缓存链路的详细透传路径-Nginx-PHP中文网

$upstream_http_x_cache_lookup并非nginx官方变量，需各层主动注入x-cache等响应头并用$upstream_http_x_*读取，结合add_header与统一日志格式实现多级缓存链路追踪。

如何利用 $upstream_http_x_cache_lookup 追踪多级缓存链路的详细透传路径

$upstream_http_x_cache_lookup 并不是 Nginx 官方内置变量，它不存在于标准 Nginx 中。你看到的这个变量名，很可能是对 $upstream_http_* 系列变量的误写或混淆，或者是某家自研 CDN/代理中间件（如阿里云全站加速、腾讯云 CDN、或内部定制 Nginx）添加的私有响应头解析变量。

我们来厘清关键事实，并给出真正可行的多级缓存链路追踪方案：

什么是 `$upstream_http_*` 变量？

Nginx 提供一类变量，形如
$upstream_http_<header_name></header_name>，
用于读取 upstream（后端服务器）返回的某个 HTTP 响应头的值。
例如：

若上游返回 X-Cache: HIT from cdn-node-a，那么 $upstream_http_x_cache 的值就是 HIT from cdn-node-a；
但 $upstream_http_x_cache_lookup —— 只要上游没返回名为 X-Cache-Lookup 的响应头，该变量就为空，且 Nginx 不会自动构造它。

所以，想靠这个变量“自动追踪多级缓存路径”，前提必须是：
✅ 每一级缓存节点（边缘 CDN、POP 节点、反向代理层、源站前置缓存）都主动在响应中注入自己的缓存状态和节点标识，比如：

X-Cache: HIT
X-Cache-Lookup: MISS; edge-shanghai-03
X-Cache-From: pop-beijing-01
X-Cache-Hierarchy: EDGE → POP → ORIGIN

否则，这个变量毫无意义。

如何真实实现多级缓存链路透传与可观测？

你需要逐层约定 + 主动注入 + 日志串联，而非依赖某个神奇变量：

Upload audio to AIOZ Stream

快速上传音频至 AIOZ Stream API。支持默认或自定义编码配置创建音频对象，上传文件并完成处理后返回音频链接。

下载

每级代理必须显式记录并透传自身缓存行为
在每一级 Nginx（或 CDN 节点）的 location 或 upstream 配置中，用 add_header 注入本层信息：

# 边缘节点（EDGE）
add_header X-Cache "$upstream_cache_status from edge-hangzhou-01";
add_header X-Cache-Hit "$upstream_cache_status";

# 区域节点（POP），收到请求后也覆盖/追加
add_header X-Cache "$upstream_cache_status from pop-nanjing-02";
add_header X-Cache-Prev "$sent_http_x_cache";  # 透传上一层的 X-Cache

用 proxy_set_header 向下透传链路标记（非必须，但利于日志关联）
如果你想让源站也知道自己被哪几层缓存过，可把关键头向下传递（注意避免环路）：
```
proxy_set_header X-Cache-Upstream $upstream_http_x_cache;
proxy_set_header X-Cache-Hierarchy "$sent_http_x_cache, $upstream_http_x_cache";
```

统一日志格式，把多级缓存状态打到 access_log
在 http 或 server 块中定义日志格式：

log_format cache_chain 
  '$remote_addr - $remote_user [$time_local] '
  '"$request" $status $body_bytes_sent '
  '"$http_referer" "$http_user_agent" '
  'edge="$upstream_cache_status" '
  'pop="$upstream_http_x_cache" '
  'origin="$upstream_http_x_cache_status" '
  'hierarchy="$sent_http_x_cache_hierarchy"';

这样一条日志就能横向对比各层命中状态。

CDN 多级架构下的典型响应头链路示例
用户请求经过：
浏览器 → 边缘节点（EDGE）→ 区域节点（POP）→ 源站 Nginx（ORIGIN）
最终响应头可能为：
```
X-Cache: HIT from edge-shenzhen-05  
X-Cache-From: pop-guangzhou-02  
X-Cache-Origin: MISS  
X-Cache-Hierarchy: EDGE(HIT) → POP(MISS) → ORIGIN  
X-Request-ID: a1b2c3d4-...
```
这些字段全部由对应层级的 Nginx 或 CDN 控制台配置注入，不是自动生成的。