解读Nginx变量字段大全_阿里

nginx 的变量系统功能强大，能够捕获请求、响应和服务器状态的各种信息。

以下是常用的 nginx 变量分类整理：

一、请求信息变量

变量名	描述
$host	请求中的主机名（如example.com），优先使用请求行的主机名，否则使用 server_name。
$request_method	http 请求方法（如get、post）。
$request_uri	完整的请求 uri（如/path?query=string）。
$uri	解码后的请求 uri，可能在处理过程中被修改（如/path）。
$args	请求中的查询字符串（如query=string）。
$query_string	同$args。
$request_body	请求体内容，需在location中启用proxy_pass或fastcgi_pass。
$content_type	请求的 content-type 头（如application/json）。
$content_length	请求的 content-length 头。
$request	记录请求的url和http协议
$request_length	用于记录客户端请求的总大小（以字节为单位）。这个变量包含了整个 http 请求的所有部分：请求行、请求头和请求体。它在日志分析、流量监控和安全防护等场景中非常有用。

二、客户端信息变量

变量名	描述
$remote_addr	客户端 ip 地址。
$remote_port	客户端端口号。
$http_user_agent	客户端 user-agent 头（如浏览器信息）。
$http_referer	客户端 referer 头（来源页面）。
$http_cookie	客户端 cookie 头。

三、服务器信息变量

变量名	描述
$server_addr	服务器 ip 地址。
$server_port	服务器端口号。
$server_name	匹配请求的 server_name。
$scheme	请求协议（http或https）。
$server_protocol	请求协议版本（如http/1.1）。

四、响应信息变量

变量名	描述
$status	响应状态码（如200、404）。
$body_bytes_sent	发送给客户端的响应体字节数（不包含响应头）。
$bytes_sent	用于记录发送给客户端的总字节数，包括响应头和响应体。这个变量在日志记录、流量统计和性能监控中非常有用。
$sent_http_*	自定义响应头（如$sent_http_content_type）。

五、时间相关变量

变量名	描述
$request_time	请求处理时间（单位：秒，精确到毫秒）。
$msec	当前时间（单位：秒，精确到毫秒）。
$time_iso8601	iso 8601 格式的时间（如2023-01-01t12:00:00+08:00）。
$time_local	本地时间（如01/jan/2023:12:00:00 +0800）。

六、连接相关变量

变量名	描述
$connection	连接序列号。
$connection_requests	当前连接上的请求数量。
$keepalive_requests	持久连接上的请求数量。
$pipe	用于指示请求的处理方式是通过管道（piped）还是缓冲（buffered）。这个变量主要用于调试和性能分析，特别是在处理大文件或代理请求时。

七、nginx 内置变量

变量名	描述
$arg_*	获取请求参数（如$arg_name获取?name=value中的value）。
$cookie_*	获取 cookie 值（如$cookie_session）。
$http_*	获取任意请求头（如$http_accept）。
$sent_http_*	设置响应头（如add_header cache-control $sent_http_cache_control）。

八、高级变量

变量名	描述
$upstream_addr	上游服务器地址（如代理后端的 ip: 端口）。
$upstream_response_time	上游服务器响应时间（多个上游时用逗号分隔）。
$uri_filename	uri 中的文件名部分（如/path/file.txt中的file.txt）。
$request_id	生成唯一请求 id（用于日志追踪）。
$upstream_connect_time	nginx与后游服务器建立连接所消耗的时间，其中包含连接握手的时间，单位为秒。
$upstream_header_time	接收到后端服务器响应头花费的时间。
$upstream_queue_time	请求保留在upstream队列中的时间。队列:如果在处理请求时无法立即选择upstream服务器，则该请求将被放入队列中。如果队列已满，或者在timeout参数指定的时间段内无法选择将请求传递给的服务器，则会将502（错误网关）错误返回给客户端。
$http_x_forwarded_for	用于获取客户端的真实 ip 地址。在经过代理服务器（如负载均衡器、cdn）转发的请求中，客户端的原始 ip 会被记录在 x-forwarded-for 请求头中，而非 $remote_addr（它记录的是直接连接到 nginx 的客户端或代理服务器的 ip）。
$remote_user	用于获取通过 http 基础认证（basic authentication）验证的用户名。它在需要用户身份验证的场景中非常有用，但在使用时需要注意其生效条件和安全问题。
$http_authorization	用于获取客户端发送的 authorization 请求头。这个变量在处理身份验证（如 basic auth、bearer token、oauth 等）时非常重要。

九、自定义变量

通过set指令定义：

set $my_var "custom_value";

使用示例

在配置中引用变量：

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;

location /proxy {
    proxy_pass http://backend;
    proxy_set_header host $host;
    proxy_set_header x-real-ip $remote_addr;
}