log_subrequest指令用于启用Nginx子请求日志记录，默认关闭，需在http块中配置log_subrequest on并配合含$subrequest变量的自定义日志格式，以区分主请求与子请求，便于安全审计与问题排查。
在 Nginx 中，log_subrequest 指令用于控制是否将内部子请求（subrequest）的访问日志写入 access log。默认情况下，Nginx 不记录子请求（例如由 auth_request、include、add_after_body 或 Lua 的 ngx.location.capture 等触发的内部请求），这会导致认证、鉴权等关键环节“隐身”，难以排查问题或审计行为。
为什么需要开启 log_subrequest？
子请求常用于安全增强场景，比如：
-
auth_request /auth：将请求转发到后端认证服务（如 OAuth2 Proxy、自研 Auth API）进行校验 - 动态 header 注入、权限检查、灰度路由决策等依赖子请求逻辑
若不记录这些子请求，你看到的 access log 只有主请求（如 GET /api/user），而真正决定放行/拒绝的 POST /auth 完全不可见——无法判断是认证超时、返回 401 还是后端异常。
如何启用 log_subrequest？
该指令为全局配置项，只能出现在 http 块中，且需配合自定义日志格式使用（否则子请求日志会混在主请求里，无区分标识）：
注意：log_subrequest 是布尔开关，没有 on/off 参数，直接写指令即启用。
http {
log_subrequest on; # ✅ 启用子请求日志
<pre class="brush:php;toolbar:false;">log_format subreq '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'rt=$request_time uct="$upstream_connect_time" '
'uht="$upstream_header_time" urt="$upstream_response_time" '
'subreq=$subrequest;'; # 自定义字段标识是否为子请求
access_log /var/log/nginx/access.log subreq;}
关键点：
-
log_subrequest on必须放在http块顶层，不能在 server 或 location 内设置 - 使用
$subrequest变量（Nginx 1.7.5+ 支持）可在日志中明确标记：值为yes表示该条日志来自子请求，no为主请求 - 推荐搭配
$upstream_*_time字段，便于分析子请求耗时瓶颈
验证子请求是否被记录
以常见 auth_request 配置为例：
location /api/ {
auth_request /auth;
proxy_pass http://backend;
}
<p>location = /auth {
proxy_pass <a href="https://www.php.cn/link/8ab9523c37d8f410f7f35e270ce14369">https://www.php.cn/link/8ab9523c37d8f410f7f35e270ce14369</a>;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}</p>
当用户访问 /api/data 时，Nginx 会先发起子请求到 /auth。此时 access.log 中应出现两条记录：
- 一条
subreq=no：主请求GET /api/data（状态码取决于 /auth 结果） - 一条
subreq=yes：子请求GET /auth（真实调用 auth-service，含上游耗时）
可通过 tail -f /var/log/nginx/access.log | grep subreq=yes 实时观察子请求流量。
注意事项与常见问题
-
性能影响轻微但存在：每个子请求多一次日志写入，高并发下建议使用 buffer 和 flush 控制（如
access_log ... buffer=64k flush=5s;） -
不记录嵌套子请求：若 /auth 内部又发起子请求（如 Lua 中再调
ngx.location.capture('/check')），只有第一层子请求会被标记subreq=yes - 日志轮转需同步处理：子请求日志量可能突增（尤其认证失败风暴），确保 logrotate 配置覆盖并避免磁盘打满
-
旧版本兼容性：Nginx $subrequest 变量，可改用
$request_filename或自定义 header 辅助识别
