nginx access_log是http请求全链路的文本化快照，核心在于理解各字段对应处理阶段及生效条件：$remote_addr默认为代理ip，需配合$http_x_forwarded_for获取真实客户端ip；$time_local是请求头解析完成时刻；$request保留原始编码uri；$status为nginx最终返回码，$upstream_status才反映后端真实状态；$request_time含全程耗时，$upstream_response_time仅计上游交互；$upstream_addr为空表明upstream失联；空字段具诊断意义，如$upstream_response_time为空多因连接超时；日志在请求结束后写入，buffer/flush设置影响实时性。
NGINX 的 access_log 不是简单记下“谁来了、干了什么”，而是把一次 HTTP 请求从 TCP 握手到响应关闭的完整链路，压缩成一行可解析的文本。真正用好它，关键不在字段数量，而在理解每个变量背后代表的处理阶段、生效前提和常见陷阱。
核心字段：谁、何时、请求什么、结果如何
这些是日志的骨架，几乎每条记录都稳定出现：
-
$remote_addr：TCP 连接发起方的 IP。注意——若前端有代理（如 CDN、LB、另一层 Nginx），这里默认是代理的 IP，不是真实用户。要获取真实客户端 IP，必须配合
$http_x_forwarded_for，且要求上游代理正确设置了该 Header。 -
$time_local：请求头被 Nginx 解析完成时的本地服务器时间，格式为
[29/Dec/2022:10:17:14 +0000]。它不等于请求到达内核 socket 的时间，也不等于响应发出的时间，而是进入 HTTP 解析阶段的时刻。 -
$request：原始请求行，例如
"GET /api/v1/user?id=123 HTTP/1.1"。它未经解码，保留原始 URI（含编码字符如%20），也包含协议版本。不能直接用于统计路径，需先 decode 和 normalize。 -
$status：Nginx 最终返回给客户端的 HTTP 状态码。它可能来自 Nginx 自身（如 404、413）、上游服务（502、504）或 rewrite 规则（301、302）。注意：它不反映 upstream 实际返回的状态（那是
$upstream_status的职责）。 - $body_bytes_sent：实际发送给客户端响应体的字节数（不含响应头）。若响应被截断、连接中断或启用 gzip 压缩，该值可能小于后端返回的原始 body 大小。
性能与链路字段：耗时在哪？谁在响应？
这些变量对排查慢请求、定位瓶颈至关重要，但它们的值依赖于具体配置和请求路径：
-
$request_time：从接收到客户端第一个字节开始，到发送完最后一个响应字节为止的总耗时（单位：秒，精度毫秒）。它包含 DNS 解析（如果用了
resolver）、upstream 建连、等待 upstream 响应、Nginx 自身处理、网络传输等全部环节。即使 upstream 返回很快，若客户端上传慢（如大文件 POST），$request_time也会拉长。 -
$upstream_response_time：仅计算 Nginx 与 upstream 交互的时间——从向 upstream 发出请求开始，到收完 upstream 的全部响应头为止。它不包括 upstream 处理业务逻辑的时间（那属于 upstream 内部），也不包括响应体传输时间（除非启用了
proxy_buffering off）。多个 upstream（如负载均衡）会以逗号分隔，如0.012, 0.008。 -
$upstream_addr：实际通信的 upstream 地址，如
10.1.2.3:8000或unix:/var/run/backend.sock。当发生 502 错误且 upstream 不可用时，该字段为空字符串，而非-——这是判断 upstream 是否失联的关键信号。 -
$upstream_status：upstream 返回的实际状态码。与
$status对比，能快速区分是 Nginx 层问题（如 500）还是 upstream 问题（如 upstream 返回 500 而 Nginx 转发为 500）。若 upstream 未响应，此字段为空。
上下文与安全字段：来源、身份、协议细节
这些字段补充业务上下文，但需注意其生效条件和潜在伪造风险：
-
$http_x_forwarded_for：由上游代理添加，通常包含真实客户端 IP 和中间代理 IP 链（如
203.0.113.5, 198.51.100.2）。Nginx 默认不校验其真实性，因此不可直接用于权限控制。生产环境应结合set_real_ip_from和real_ip_header X-Forwarded-For指令，只信任可信代理传来的值。 - $http_user_agent：客户端声明的 UA 字符串。易被篡改，仅适合做统计或初步识别（如爬虫过滤），不可用于安全决策。
-
$scheme 和 $server_name：分别表示请求使用的协议（
http或https）和匹配的 server 块的server_name。后者在泛域名或多站点配置中尤其有用，能明确知道请求命中了哪个虚拟主机。 -
$request_method 和 $request_uri：将
$request拆解为方法（GET/POST/PUT）和 URI（含 query string）。相比$request，它们更便于按方法类型或路径前缀做聚合分析，且$request_uri是已 decode 的，更适合路径匹配。
容易被忽略但很关键的细节
几个看似简单、实则影响诊断准确性的点：
-
空字段不等于“无值”：比如
$upstream_addr为空，大概率说明 upstream 根本没连上；$upstream_response_time为空，往往意味着 upstream 连接超时或拒绝连接（111 错误），而非处理慢。 -
时间字段的精度差异：
$request_time和$upstream_response_time默认精度为毫秒（如0.123），但若需更高精度（微秒），需在编译 NGINX 时启用--with-http_stub_status_module并配置log_format使用$request_completion_time等扩展变量（需第三方模块支持）。 - 日志写入时机：access log 在请求完全结束（connection close 或 keepalive timeout）后才写入。这意味着正在传输大文件或长轮询的请求，在日志中会延迟出现，甚至因 worker 进程异常而丢失。
-
buffer 与 flush 设置：使用
buffer=64k flush=5s可减少磁盘 I/O，但会带来最多 5 秒的日志延迟。调试阶段建议关闭 buffer（或设为极小值），确保日志实时可见。
