Nginx 中访问日志如何记录服务响应的完整报文头部信息

作者：袖梨 2026-08-25

必须显式定义log_format并使用$sent_http_*变量按需记录响应头，或借助headers-more-nginx-module模块捕获全部原始响应头；前者推荐生产环境使用，后者仅适用于临时审计。

要让 Nginx 的 access_log 记录服务响应的完整报文头部信息，不能依赖默认配置，必须显式定义日志格式并引用响应头变量。Nginx 本身不提供“一键记录所有响应头”的内置变量，但可通过两种方式实现：一种是按需提取关键响应头（推荐、稳定、无需额外模块），另一种是借助 headers-more-nginx-module 模块聚合全部原始响应头（适合临时审计，但有性能和解析成本）。

按需记录指定响应头（推荐，生产环境首选）

这是最常用、兼容性最好、无需编译安装第三方模块的方式。核心是使用 $sent_http_* 变量，变量命名规则为：响应头名称转小写，短横线（-）替换为下划线（_）。该变量只在响应头已发送后才可读取，且仅对当前请求有效。

在 http 块中定义日志格式，例如：

log_format resp_headers '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" "$http_user_agent" ' '"$sent_http_content_type" "$sent_http_x_request_id" "$sent_http_etag" "$sent_http_cache_control"';

在 server 或 location 块中启用：

access_log /var/log/nginx/response.log resp_headers;

常见映射示例：

Content-Type → $sent_http_content_type

ETag → $sent_http_etag

X-Request-ID → $sent_http_x_request_id

Cache-Control → $sent_http_cache_control

若上游未返回某头，对应字段为空字符串，不会导致日志写入失败

记录全部原始响应头（需 headers-more-nginx-module）

当需要完整捕获所有响应头（包括动态生成或未知名称的头）时，需提前编译安装 headers-more-nginx-module，再通过其指令聚合输出。

启用模块后，在配置中添加：

more_set_headers 'All-Response-Headers: $sent_http_headers';

log_format all_resp '[$time_local] $remote_addr "$request" $status "$sent_http_content_type" "Response-Headers: $more_set_headers_all_response_headers"';

该方式输出类似："Response-Headers: Content-Type: application/json, ETag: W/"abc123", X-Content-Type-Options: nosniff"
优点：不遗漏任何响应头；缺点：日志体积显著增大、结构松散、难以用标准工具解析、增加磁盘 I/O 和存储压力
仅建议用于短期安全审计、合规检查或深度调试，不作为长期线上标配