Nginx 内部变量及其示例值一览

七月 07, 2023 16361

一、前言

平时在配置nginx时，时不时需要使用一些内置变量，如 $scheme 变量可以判断请求是 http 还是 https。然而大多数人也只知道几个变量，而对Nginx的其他变量知之甚少，就算看到文档说明也不明觉厉，不知道符不符合自己的需求。于是乎我打算对 Nginx 的大部分变量进行列举与获取它的示例值。

二、变量一览

1. 标准示例

通过查阅文档得出 Nginx 大致包含了下面的变量，包括了 标准示例值和变量说明。

英文名 中文名 示例值 变量说明
$arg_name 请求参数名 color=red 获取请求URL中的某个特定参数及其值。
$args 请求参数 color=red&size=large 提供整个请求URL中“?”后面的所有参数及其值。
$binary_remote_addr 二进制远程地址 0x0A0B0C0D 客户端IP地址的二进制表示形式。
$body_bytes_sent 发送的响应主体字节数 12345 已发送到客户端的响应主体的总字节数。
$bytes_sent 发送的总字节数 12345 包括响应头和主体在内的已发送到客户端的总字节数。
$connection 连接ID 12345 当前连接的唯一标识符。
$connection_requests 连接请求数 10 在当前连接上处理的请求数量。
$connection_time 连接持续时间（秒） 123.456 从建立连接到当前时刻的持续时间（以秒为单位）。
$content_length 请求内容长度 12345 请求主体的预期长度（如果存在）。
$content_type 请求内容类型 application/json 请求中“Content-Type”头字段指定的内容类型。
$cookie_name cookie名 user_session=abc123 获取请求中名为“name”的特定cookie及其值。
$document_root 文档根目录 /var/www/example.com 与当前请求匹配的location块中配置的文档根目录。
$document_uri 请求URI /index.html 完整的请求URI，不包括查询字符串。
$host 主机头 example.com 客户端在“Host”头字段中提供的主机名。
$hostname 服务器主机名 webserver01 Nginx服务器的主机名。
$http_name 请求头字段 Accept-Language: en-US,en;q=0.5 获取请求中名为“name”的特定HTTP头字段及其值。
$http_host 完整主机头 example.com:80 “Host”请求头的完整值，可能包含端口号
$http_HEADER 请求头信息 $http_referer 客户端发送的特定请求头信息，例如$http_referer表示referer请求头
$http_upgrade HTTP升级头 upgrade 若存在HTTP Upgrade请求头，则显示其值
$http_user_agent 用户代理 Mozilla/5.0… 客户端浏览器信息
$https 是否HTTPS连接 on 表示是否为HTTPS连接（“on”或“off”）。
$is_args 存在参数标记 ? 如果请求包含参数，则为“?”；否则为空字符串。
$limit_rate 限速速率 100k 为响应设置的最大传输速率（如：100k）。
$msec 当前时间（毫秒） 1649671538.567 从Nginx启动开始到当前时刻的毫秒数。
$nginx_version Nginx版本 1.18.0 Nginx服务器的版本号。
$pid 进程ID 1234 处理当前请求的Nginx工作进程的进程ID。
$pipe 是否管道连接 p 如果请求通过管道传输，则为“p”；否则为空字符串。
$proxy_protocol_addr PROXY协议源地址 192.0.2.42 使用PROXY协议时，客户端的实际源IP地址。
$proxy_protocol_port PROXY协议源端口 49152 使用PROXY协议时，客户端的实际源端口号。
$proxy_protocol_server_addr PROXY协议目的地址 198.51.100.1 使用PROXY协议时，Nginx监听的服务器地址。
$proxy_protocol_server_port PROXY协议目的端口 80 使用PROXY协议时，Nginx监听的服务器端口号。
$proxy_protocol_tlv_name PROXY协议TLV字段名 AWS_VPCE_ID 获取PROXY协议中的特定TLV字段名及其值。
$query_string 查询字符串 color=red&size=large 请求URI中的查询字符串部分（不包括问号“?”）。
$realpath_root 绝对路径文档根目录 /var/www/example.com 文档根目录的绝对路径。
$remote_addr 远程地址 192.0.2.42 客户端的IP地址。
$remote_port 远程端口 49152 客户端的端口号。
$remote_user 远程用户 john.doe 已经经过身份验证的用户名（如：基本认证）。
$request 请求行 GET /index.html HTTP/1.1 完整的请求行，包括方法、URI和协议版本。
$request_body 请求主体 {"key": "value"} 客户端发送的请求主体数据。
$request_body_file 请求主体临时文件路径 /tmp/nginx_upload_12345 存储大请求主体的临时文件路径。
$request_completion 请求完成状态 OK 请求处理的完成状态。
$request_filename 请求文件路径 /var/www/example.com/index.html 根据请求URI映射到的实际文件系统路径。
$request_id 请求ID 123e4567-e89b-12d3-a456-426655440000 为每个请求生成的唯一标识符。
$request_length 请求长度 12345 整个请求（包括头和主体）的长度。
$request_method 请求方法 GET 客户端使用的HTTP请求方法（如：GET、POST等）。
$request_time 请求处理时间（秒） 0.123 从接收请求到发送响应头的时间（以秒为单位）。
$request_uri 请求URI /index.html?color=red 完整的原始请求URI，包括查询字符串。
$scheme 协议 http 请求使用的协议（http或https）。
$sent_http_name 发送的响应头字段 Content-Type: application/json 发送到客户端的特定响应头字段及其值。
$sent_trailer_name 发送的响应尾部字段 X-Trailer: Value 发送到客户端的特定响应尾部字段及其值。
$server_addr 服务器地址 198.51.100.1 Nginx服务器监听的IP地址。
$server_name 服务器名 example.com 与当前请求匹配的server块的名称。
$server_port 服务器端口 80 Nginx服务器监听的端口号。
$server_protocol 服务器协议 HTTP/1.1 客户端使用的HTTP协议版本。
$status 响应状态码 200 响应给客户端的HTTP状态码。
$tcpinfo_rtt TCP往返时间 0.050 与客户端的TCP连接的往返时间（RTT）。
$tcpinfo_rttvar TCP往返时间变化 0.010 TCP往返时间的变化（RTT variance）。
$tcpinfo_snd_cwnd 发送方拥塞窗口 10000 TCP连接的发送方拥塞窗口大小。
$tcpinfo_rcv_space 接收方缓冲区空间 8192 TCP连接的接收方缓冲区可用空间。
$time_iso8601 ISO 8601时间戳 2022-0¼-20T14:35:38+00:00 当前时间的ISO 8601格式时间戳。
$time_local 本地时间戳 20/Apr/2022:14:35:38 +0000 当前时间的本地格式时间戳。
$uri 请求URI /index.html 不包括查询字符串的请求URI。
$jwt_header_name JWT头部字段名 Authorization: Bearer eyJhbG... 获取请求中JWT令牌的特定头部字段及其值。
$jwt_claim_name JWT声明字段名 sub: john.doe 获取JWT令牌中特定声明字段及其值。
$jwt_payload JWT有效载荷 { "sub": "john.doe", "exp": 16.png" JWT令牌的完整有效载荷对象（JSON格式）。
$fastcgi_script_name FastCGI脚本名 /index.php 当前FastCGI请求的脚本名。
$fastcgi_path_info FastCGI路径信息 /path/to/resource FastCGI请求中与脚本名后跟的额外路径信息。
$gzip_ratio 压缩比率 0..jpg 压缩响应后的实际压缩比率（如：0.5表示压缩了50%）。
$limit_conn_status 连接限制状态 200 如果请求因连接限制被拒绝，则返回拒绝状态码；否则为当前响应状态码。
$limit_req_status 速率限制状态 429 如果请求因速率限制被拒绝，则返回拒绝状态码；否则为当前响应状态码。
$memcached_key Memcached键 product_123 对于Memcached代理模块，当前请求使用的Memcached键。
$proxy_host 代理主机名 backend.example.com 向其转发请求的代理服务器的主机名。
$proxy_port 代理端口 8080 向其转发请求的代理服务器的端口号。
$proxy_add_x_forwarded_for X-Forwarded-For头 client_ip, proxy1_ip, proxy2_ip 更新或设置“X-Forwarded-For”头字段，包含客户端及所有上游代理的IP地址。
$proxy_protocol_tlv_aws_vpce_id AWS VPC终端节点ID vpce-1234567890abcdef 从PROXY协议TLV中获取AWS VPC终端节点ID。
$proxy_protocol_tlv_azure_pel_id Azure PEL ID pel-0123456789ABCDEF 从PROXY协议TLV中获取Azure PEL（Platform Endpoint Layer）ID。
$proxy_protocol_tlv_gcp_conn_id GCP连接ID gcp-conn-1234567890abcdef 从PROXY协议TLV中获取GCP连接ID。
$realip_remote_addr 真实远程地址 192.0.2.42 根据RealIP模块解析的客户端真实IP地址。
$realip_remote_port 真实远程端口 49152 根据RealIP模块解析的客户端真实端口号。
$invalid_referer 引用头有效性 0 根据referer有效性检查返回的结果（0表示有效，非0表示无效）。
$secure_link 加密链接值 bS9pbmRleC5odG1sOjEyMzQ= Secure Link模块生成的加密链接值。
$secure_link_expires 加密链接过期时间 164967.png Secure Link模块生成的加密链接过期时间戳。
$session_log_id 会话日志ID 1234567890abcdef 会话日志模块为当前请求生成的唯一会话ID。
$session_log_binary_id 二进制会话日志ID 0x1234567890ABCDEF 会话日志模块为当前请求生成的二进制会话ID。
$slice_range 数据切片范围 bytes=0-1023 范围请求中的数据切片范围。
$date_local 本地日期时间 20/Apr/2022:14:35:38 +0000 当前本地日期时间。
$date_gmt GMT日期时间 20/Apr/2022:14:35:38 +0000 当前格林尼治标准时间（GMT）日期时间。
$ssl_alpn_protocol ALPN协商协议 h2 TLS连接上通过ALPN协商选定的应用层协议。
$ssl_cipher 当前SSL/TLS密码套件 ECDHE-RSA-AES256-GCM-SHA384 当前SSL/TLS连接使用的密码套件。
$ssl_ciphers 允许的SSL/TLS密码套件 HIGH:!aNULL:!MD5 服务器配置中允许的SSL/TLS密码套件列表。
$ssl_client_escaped_cert 客户端证书（URL编码） %30%82... 客户端证书的URL编码表示形式。
$ssl_client_cert 客户端证书 -----BEGIN CERTIFICATE-----\nMIID... 客户端提供的PEM格式X.509证书。
$ssl_client_fingerprint 客户端证书指纹 SHA1:AB:CD:EF:GH:IJ:KL:M... 客户端证书的指纹（如：SHA1）。
$ssl_client_i_dn 客户端证书issuer DN CN=Example CA, O=Example Org, C=US 客户端证书颁发者的DN（Distinguished Name）。
$ssl_client_i_dn_legacy 客户端证书issuer DN（旧版） /CN=Example CA/O=Example Org/C=US 客户端证书颁发者的DN（旧版格式）。
$ssl_client_raw_cert 客户端证书原始数据 0x30820122300D06092A8648... 客户端证书的原始二进制数据。
$ssl_client_s_dn 客户端证书subject DN CN=John Doe, OU=Engineering, O=Example Inc., C=US 客户端证书主题的DN。
$ssl_client_s_dn_legacy 客户端证书subject DN（旧版） /CN=John Doe/OU=Engineering/O=Example Inc./C=US 客户端证书主题的DN（旧版格式）。
$ssl_client_serial 客户端证书序列号 1234567890ABCDEF 客户端证书的序列号。
$ssl_client_v_end 客户端证书有效期结束 2024-01-01 客户端证书的有效期结束日期。
$ssl_client_v_remain 客户端证书剩余有效期（秒） 315360000 客户端证书剩余的有效期（以秒为单位）。
$ssl_client_v_start 客户端证书有效期开始 2022-01-01 客户端证书的有效期开始日期。
$ssl_client_verify 客户端证书验证结果 SUCCESS 客户端证书验证的结果（如：SUCCESS、FAILED等）。
$ssl_curve 选择的ECDH曲线 prime256v1 TLS连接上选择的ECDH曲线。
$ssl_curves 支持的ECDH曲线 prime256v1, secp384r1, secp521r1 服务器支持的ECDH曲线列表。
$ssl_early_data 是否使用0-RTT数据 on 表示是否使用TLS 1.3早期数据（0-RTT）。
$ssl_protocol SSL/TLS协议版本 TLSv1.2 当前SSL/TLS连接使用的协议版本。
$ssl_server_name SNI主机名 example.com 客户端在Server Name Indication (SNI)扩展中提供的主机名。
$ssl_session_id SSL会话ID 0123456789ABCDEF 当前SSL会话的ID。
$ssl_session_reused 是否重用SSL会话 0 表示当前连接是否重用了之前建立的SSL会话（0表示否，非零表示是）。
$time_iso8601 ISO 8601时间戳 2022-0.jpg 当前时间的ISO 8601格式时间戳。
$time_local 本地易读时间戳 14/Mar/2022:13:37:05 -0700 当前时间的本地易读格式时间戳。
$upstream_addr 上游服务器地址 192.0.2.100:8080, 192.0.2.101:8080 与请求关联的上游服务器的地址和端口列表，按请求顺序排列。
$upstream_bytes_sent 发送给上游的字节数 12345 发送给上游服务器的总字节数（不包括HTTP头）。
$upstream_cache_status 缓存命中状态 HIT 缓存模块返回的缓存状态（如：HIT、MISS、EXPIRED等）。
$upstream_connect_time 与上游建立连接耗时 0.001 与上游服务器建立连接所花费的时间（以秒为单位，精确到毫秒）。
$upstream_header_time 接收上游响应头耗时 0.002 从开始到接收完上游服务器响应头所花费的时间（以秒为单位，精确到毫秒）。
$upstream_http_
 上游HTTP响应头 Content-Type: text/html 上游服务器返回的特定HTTP响应头（替换<header>为实际头部名称）。
$upstream_response_length 上游响应长度 1234 上游服务器返回的响应主体长度（不包括HTTP头）。
$upstream_response_time 接收上游完整响应耗时 0.003 从开始到接收完上游服务器完整响应（包括头和主体）所花费的时间（以秒为单位，精确到毫秒）。
$upstream_status 上游响应状态码 200 上游服务器返回的HTTP状态码。
$uri 请求URI /path/to/resource?query=param 请求的统一资源标识符（URI），包括查询字符串。
$uri_args URI查询参数 query=param 请求URI中的查询参数部分。
$uri_hash 请求URI哈希 e3b0c44298fc1c149afbf4c899... 请求URI的SHA-256哈希值。
$uri_path 请求URI路径 /path/to/resource 请求URI中的路径部分，不包括查询字符串。
$uwsgi_app_id uWSGI应用ID 1 uWSGI应用程序的ID。
$uwsgi_body_bytes_sent 发送至uWSGI的字节数 12345 发送给uWSGI服务器的总字节数（不包括HTTP头）。
$uwsgi_chunked uWSGI响应是否分块 0 uWSGI响应是否采用分块编码（0表示否，非0表示是）。
$uwsgi_headers uWSGI响应头 Status: 200、Content-Length: 1234 uWSGI服务器返回的所有HTTP响应头，格式化为多个“Name: Value”行。
$uwsgi_modifier1 uWSGI修饰符1 0 uWSGI传递给worker的修饰符1值。
$uwsgi_modifier2 uWSGI修饰符2 0 uWSGI传递给worker的修饰符2值。
$uwsgi_num_packets uWSGI包数量 10 与请求关联的uWSGI数据包总数。
$uwsgi_packet_size uWSGI包大小 4096 uWSGI数据包的大小（字节）。
$uwsgi_pid uWSGI进程ID 1234 处理请求的uWSGI工作进程的PID。
$uwsgi_response_code uWSGI响应状态码 200 uWSGI服务器返回的HTTP状态码。
$uwsgi_status uWSGI状态信息 200 OK uWSGI服务器返回的HTTP状态信息。
$uwsgi_thread_id uWSGI线程ID 1 处理请求的uWSGI线程ID（如果适用）。
$uwsgi_to uWSGI响应耗时 0.001 从开始到接收完uWSGI服务器响应所花费的时间（以秒为单位，精确到毫秒）。
$uwsgi_txid uWSGI事务ID 0123456789ABCDEF uWSGI事务的唯一标识符。

请注意，这些变量可能需要特定的模块或配置启用才能在实际环境中使用。在编写Nginx配置或日志格式时，请确保已正确配置和启用所需模块，并参考Nginx官方文档以获取最新和最准确的信息。

2. 实际获取值

很多时候，文档说是这样，但是实际使用时却有偏差，于是我对变量进行实际测试获取。

英文名 中文名 实际获取值
$pid 进程ID 100
$uri 请求URI /api/backtest
$scheme 请求协议 https
$request_uri 完整请求URI /api/backtest?tradeId=1688653270906431
$status 响应状态码 000
$args 查询字符串 tradeId=1688653270906431
$host 主机头 temp.frp.scwang90.cn
$hostname 主机名 77f1aa4ae276 [docker容器hostname]
$http_host 完整主机头 temp.frp.scwang90.cn
$http_HEADER 请求头信息 [空]
$http_upgrade HTTP升级头 [空]
$http_user_agent 用户代理 Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.67
$request_body 请求主体 [空]
$request_filename 真实文件路径 /etc/nginx/html/api/backtest
$request_method 请求方法 GET
$request_time 请求处理时间 0.000
$content_type 内容类型 [空]
$content_length 内容长度 [空]
$arg_PARAMETER 请求参数 [空]
$query_string 查询字符串 tradeId=1688653270906431
$bytes_sent 已发送字节数 0
$body_bytes_sent 已发送正文字节数 0
$connection 连接相关信息 27554
$connection_requests 连接请求数 4
$cookie_COOKIE cookie值 [空]
$document_root 文档根目录 /etc/nginx/html
$document_uri 文档URI /api/backtest
$limit_rate 限速速率 0
$remote_addr 客户端IP地址 111.121.67.127
$remote_port 客户端端口 12882
$server_addr 服务器IP地址 172.17.0.8
$server_name 服务器名 *.frp.scwang90.cn
$server_port 服务器端口 443
$server_protocol 服务器协议 HTTP/1.1
$date_gmt GMT日期 Friday, 07-Jul-2023 02:55:28 GMT
$date_local 本地日期 Friday, 07-Jul-2023 10:55:28 CST
$time_local 本地时间 07/Jul/2023:10:55:28 +0800
$time_iso8601 ISO 8601时间 2023-07-07T10:55:28+08:00
$realpath_root 解析后的文档根目录 [空]
$nginx_version Nginx版本 1.23.3
$binary_remote_addr 二进制远程地址 [开启解析出错]
$proxy_host 代理主机 httpbin.org
$proxy_port 代理端口 443
$proxy_protocol_addr 代理协议地址 [空]
$proxy_protocol_port 代理协议端口 [空]
$proxy_protocol_tlv_name 代理协议 TLV 名称 [空]
$proxy_protocol_tlv_gcp_conn_id 代理协议 TLV GCP 连接 ID [空]
$proxy_protocol_tlv_aws_vpce_id 代理协议 TLV AWS VPCE ID [空]
$proxy_protocol_tlv_azure_pel_id 代理协议 TLV Azure PEL ID [空]
$proxy_protocol_server_addr 代理协议服务器地址 [空]
$proxy_protocol_server_port 代理协议服务器端口 [空]
$proxy_add_x_forwarded_for 添加 X-Forwarded-For 头部 58.16.12.182

这个实际获取值与上面的标准示例综合对比会对实际应用中有所帮助

三、获取方法

通过 proxy_set_header 把变量添加到 http Header 中，然后在被代理的服务后端读取出 对应的 Header 值即可获得变量的实际值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

server {
    # 标准配置 ....

    # 变量抓取

    proxy_set_header   Refit-pid                    "=$pid";                
    proxy_set_header   Refit-uri                    "=$uri";                
    proxy_set_header   Refit-scheme                 "=$scheme";             
    proxy_set_header   Refit-request_uri            "=$request_uri";        
    proxy_set_header   Refit-status                 "=$status";             
    proxy_set_header   Refit-args                   "=$args";               
    proxy_set_header   Refit-host                   "=$host";               
    proxy_set_header   Refit-hostname               "=$hostname";           
    proxy_set_header   Refit-http_host              "=$http_host";          
    proxy_set_header   Refit-http_HEADER            "=$http_HEADER";        
    proxy_set_header   Refit-http_upgrade           "=$http_upgrade";       
    proxy_set_header   Refit-http_user_agent        "=$http_user_agent";    
    proxy_set_header   Refit-request_body           "=$request_body";       
    proxy_set_header   Refit-request_filename       "=$request_filename";   
    proxy_set_header   Refit-request_method         "=$request_method";     
    proxy_set_header   Refit-request_time           "=$request_time";       
    proxy_set_header   Refit-content_type           "=$content_type";       
    proxy_set_header   Refit-content_length         "=$content_length";     
    proxy_set_header   Refit-arg_parameter          "=$arg_PARAMETER";      
    proxy_set_header   Refit-query_string           "=$query_string";       
    proxy_set_header   Refit-bytes_sent             "=$bytes_sent";         
    proxy_set_header   Refit-body_bytes_sent        "=$body_bytes_sent";    
    proxy_set_header   Refit-connection             "=$connection";         
    proxy_set_header   Refit-connection_requests    "=$connection_requests";
    proxy_set_header   Refit-cookie_COOKIE          "=$cookie_COOKIE";      
    proxy_set_header   Refit-document_root          "=$document_root";      
    proxy_set_header   Refit-document_uri           "=$document_uri";       
    proxy_set_header   Refit-limit_rate             "=$limit_rate";         
    proxy_set_header   Refit-remote_addr            "=$remote_addr";        
    proxy_set_header   Refit-remote_port            "=$remote_port";        
    proxy_set_header   Refit-server_addr            "=$server_addr";        
    proxy_set_header   Refit-server_name            "=$server_name";        
    proxy_set_header   Refit-server_port            "=$server_port";        
    proxy_set_header   Refit-server_protocol        "=$server_protocol";    
    proxy_set_header   Refit-date_gmt               "=$date_gmt";           
    proxy_set_header   Refit-date_local             "=$date_local";         
    proxy_set_header   Refit-time_local             "=$time_local";         
    proxy_set_header   Refit-time_iso8601           "=$time_iso8601";       
    proxy_set_header   Refit-realpath_root          "=$realpath_root";      
    proxy_set_header   Refit-nginx_version          "=$nginx_version";      
    proxy_set_header   Refit-binary_remote_addr     "=$binary_remote_addr"; 

    proxy_set_header   Refit-proxy_host                         "=$proxy_host";
    proxy_set_header   Refit-proxy_port                         "=$proxy_port";
    proxy_set_header   Refit-proxy_protocol_addr                "=$proxy_protocol_addr";
    proxy_set_header   Refit-proxy_protocol_port                "=$proxy_protocol_port";
    proxy_set_header   Refit-proxy_protocol_tlv_name            "=$proxy_protocol_tlv_name";
    proxy_set_header   Refit-proxy_protocol_tlv_gcp_conn_id     "=$proxy_protocol_tlv_gcp_conn_id";
    proxy_set_header   Refit-proxy_protocol_tlv_aws_vpce_id     "=$proxy_protocol_tlv_aws_vpce_id";
    proxy_set_header   Refit-proxy_protocol_tlv_azure_pel_id    "=$proxy_protocol_tlv_azure_pel_id";
    proxy_set_header   Refit-proxy_protocol_server_addr         "=$proxy_protocol_server_addr";
    proxy_set_header   Refit-proxy_protocol_server_port         "=$proxy_protocol_server_port";
    proxy_set_header   Refit-proxy_add_x_forwarded_for          "=$proxy_add_x_forwarded_for";
}