如何通过 log_subrequest 开启子请求日志以深度追踪 SSI 嵌套环境下的缓存逻辑-Nginx-PHP中文网

log_subrequest on可使nginx将ssi、auth_request等子请求写入access log，需nginx≥1.19.2、配置含$subrequest/$request_id的日志格式，并在http/server块中启用，以实现缓存与转发链路的精准追踪。

如何通过 log_subrequest 开启子请求日志以深度追踪 ssi 嵌套环境下的缓存逻辑

log_subrequest 是 Nginx 的一个调试型指令，用于将子请求（subrequest）的处理过程写入 access log，对分析 SSI（Server Side Includes）嵌套、FastCGI 缓存、proxy_cache 与内部重定向交互等复杂场景非常关键。它本身不改变请求逻辑，只增加日志维度——但开启后能清晰看到每个 SSI include 是如何触发子请求、是否命中缓存、是否走上游、响应状态及耗时等信息。

确认 Nginx 版本与模块支持

该指令自 Nginx 1.19.2 起正式引入（此前为实验性），且仅在 http 或 server 块中生效，不支持 location 级别。需确保：

使用 Nginx ≥ 1.19.2（推荐 ≥ 1.21.0，修复了早期 subrequest 日志中 $status 不准确等问题）
编译时未禁用 --without-http-subs-module（SSI 依赖此模块）
启用了 access_log，并配置了包含子请求变量的日志格式

配置 log_subrequest 并扩展日志格式

默认 access_log 不记录子请求。需显式开启并定义能区分主/子请求的日志字段：

log_format subreq '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   'req_id="$request_id" '
                   'subreq="$subrequest" '        # 关键：标识是否为子请求
                   'upstream_cache_status="$upstream_cache_status" '
                   'upstream_http_x_cache="$upstream_http_x_cache" '
                   'rt=$request_time uct="$upstream_connect_time" '
                   'uht="$upstream_header_time" urt="$upstream_response_time"';
<p>access_log /var/log/nginx/ssi_debug.log subreq;
log_subrequest on;  # 必须放在 http/server 块中，全局或按需启用
</p>

其中 $subrequest 变量在子请求中值为 "yes"，主请求为 "-"；搭配 $upstream_cache_status（proxy_cache）或 $upstream_http_x_cache（FastCGI 自定义头）可定位缓存行为。

结合 SSI 使用时的关键验证点

SSI 页面中每条  都会触发一次子请求。开启 log_subrequest 后，你将看到：

同一客户端 IP 在极短时间内连续多条日志，request 字段显示子请求路径（如 "/fragment.html"），而非原始 URI
子请求日志中的 $upstream_cache_status 显示 HIT/MISS/EXPIRED/BYPASS，可确认 fragment 是否独立缓存
若 fragment 使用 proxy_pass 到后端，其 urt（upstream_response_time） 与主请求 rt 明显不同，说明缓存未穿透或后端延迟
注意：SSI 默认不继承主请求的 proxy_cache_key，子请求 key 由自身 location 决定——这是缓存失效常见原因

排查典型缓存异常的实操线索

当 SSI 页面整体缓存正常，但某 fragment 总是 MISS 或返回过期内容，通过日志可快速定位：

查子请求日志中 "$upstream_cache_status" 字段是否恒为 MISS → 检查该 fragment 对应 location 是否漏配 proxy_cache / proxy_cache_valid
发现子请求 $upstream_http_x_cache: "HIT from upstream" 但内容陈旧 → 后端未正确设置 Cache-Control / Expires，导致 Nginx 无法刷新本地缓存
子请求日志中 status=502/504 频发 → SSI fragment 后端不稳定，Nginx 默认不缓存错误响应（需 proxy_cache_use_stale 配合）
主请求 rt 很小（如 5ms），但某子请求 urt 达 800ms → 该 fragment 未命中缓存且后端慢，需优化其缓存策略或降级逻辑

不复杂但容易忽略：log_subrequest 本身无性能开销，但日志量会显著上升，建议仅在调试环境或临时开启，配合 logrotate 控制体积。