当前位置：首页 > news >正文

Nginx Embedded Variables 嵌入式变量解析(2)

news 来源：原创 2025/5/8 1:48:24

Nginx Embedded Variables 嵌入式变量解析(2)

相关链接

一、目录

1.1 变量目录

1.1.3 ngx_http_browser_module

$ancient_browser
$modern_browser
$msie

1.1.4 ngx_http_fastcgi_module

$fastcgi_path_info
$fastcgi_script_name

1.1.5 ngx_http_geoip_module

$geoip_area_code
$geoip_city
$geoip_city_continent_code
$geoip_city_country_code
$geoip_city_country_code3
$geoip_city_country_name
$geoip_country_code
$geoip_country_code3
$geoip_country_name
$geoip_dma_code
$geoip_latitude
$geoip_longitude
$geoip_org
$geoip_postal_code
$geoip_region
$geoip_region_name

1.1.6 ngx_http_gzip_module

$gzip_ratio

1.1.7 ngx_http_limit_conn_module

$limit_conn_status

1.1.8 ngx_http_limit_req_module

$limit_req_status

1.1.9 ngx_http_log_module

$bytes_sent
$connection
$connection_requests
$msec
$pipe
$request_length
$request_time
$status
$time_iso8601
$time_local

1.1.10 ngx_http_memcached_module

$memcached_key

1.1.11 ngx_http_proxy_module

$proxy_add_x_forwarded_for
$proxy_host
$proxy_port

1.1.12 ngx_http_proxy_protocol_vendor_module

$proxy_protocol_tlv_aws_vpce_id
$proxy_protocol_tlv_azure_pel_id
$proxy_protocol_tlv_gcp_conn_id

1.1.13 ngx_http_realip_module

$realip_remote_addr
$realip_remote_port

1.1.14 ngx_http_secure_link_module

$secure_link
$secure_link_expires

1.1.15 ngx_http_session_log_module

$session_log_binary_id
$session_log_id

1.1.16 ngx_http_slice_module

$slice_range

1.1.17 ngx_http_ssi_module

$date_gmt
$date_local

二、解释

2.3 ngx_http_browser_module

2.3.1 变量列表

$ancient_browser

功能：如果浏览器被识别为古老浏览器，则返回由ancient_browser_value指令设置的值。

描述：用于区分是否是古老浏览器，便于针对不同类型的浏览器应用不同的配置或逻辑。

示例：

ancient_browser_value "Ancient";
if ($ancient_browser) {
    return 403; # 或者重定向到兼容页面
}

如果用户使用的是古老浏览器，可能会返回403禁止访问或重定向到兼容页面。

$modern_browser

功能：如果浏览器被识别为现代浏览器，则返回由modern_browser_value指令设置的值。

描述：用于区分是否是现代浏览器，便于针对不同类型的浏览器应用不同的配置或逻辑。

示例：

modern_browser_value "Modern";
if ($modern_browser) {
    add_header X-Browser-Type $modern_browser;
}

如果用户使用的是现代浏览器，响应头将包含X-Browser-Type: Modern。

$msie

功能：如果浏览器被识别为任何版本的MSIE（Microsoft Internet Explorer），则返回“1”。

描述：用于检测用户是否使用了MSIE浏览器，便于针对IE浏览器进行特定配置或逻辑处理。

示例：

if ($msie) {
    rewrite ^/oldpage$ /newpage break;
}

如果用户使用的是MSIE浏览器，请求/oldpage将会被重写为/newpage。

2.4 ngx_http_fastcgi_module

2.4.1 变量列表

$fastcgi_path_info

功能：返回由fastcgi_split_path_info指令设置的第二个捕获值。此变量可用于设置PATH_INFO参数。

描述：用于获取URL中的路径信息部分，便于在FastCGI环境中正确解析和处理请求。

示例：

location ~ [^/]\.php(/|$) {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_split_path_info ^(.+?\.php)(/.*)$;
    fastcgi_param PATH_INFO $fastcgi_path_info;
}

假设请求为/script.php/path/to/resource，则$fastcgi_path_info将等于/path/to/resource。

$fastcgi_script_name

功能：请求URI或在URI以斜杠结尾时，附加由fastcgi_index指令配置的索引文件名。此变量可用于设置SCRIPT_FILENAME和PATH_TRANSLATED参数，以确定PHP脚本名称。

描述：用于动态生成脚本路径，便于在FastCGI环境中正确执行PHP脚本。

示例：

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
}

对于请求/info/，假设fastcgi_index设置为index.php，则SCRIPT_FILENAME参数将等于/home/www/scripts/php/info/index.php。

2.5 ngx_http_geoip_module

2.5.1 变量列表

$geoip_area_code

功能：返回电话区号（仅限美国）。

描述：表示客户端IP地址对应的美国电话区号。注意，该变量可能包含过时的信息，因为相应的数据库字段已弃用。

示例：

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

$geoip_city

功能：城市名称，例如“Moscow”，“Washington”。

描述：提供客户端IP地址对应的城市名称。这可以帮助你根据用户的地理位置来定制内容或进行访问控制。

示例：

if ($geoip_city = "New York") {
    add_header X-City-Specific-Content "Welcome to New York!";
}

$geoip_city_continent_code

功能：返回两位字母的大陆代码。

描述：表示客户端IP地址对应的大陆代码。例如，“EU”代表欧洲，“NA”代表北美洲。

示例：

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

$geoip_city_country_code

功能：返回两位字母的国家代码（城市级精度）。

描述：表示客户端IP地址对应的城市级别精度的两位字母国家代码。例如，“RU”代表俄罗斯，“US”代表美国。

示例：

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

$geoip_city_country_code3

功能：返回三位字母的国家代码（城市级精度）。

描述：表示客户端IP地址对应的城市级别精度的三位字母国家代码。例如，“RUS”代表俄罗斯，“USA”代表美国。

示例：

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

$geoip_city_country_name

功能：返回国家名称（城市级精度）。

描述：表示客户端IP地址对应的城市级别精度的国家名称。例如，“Russian Federation”代表俄罗斯，“United States”代表美国。

示例：

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

$geoip_country_code

功能：返回两位字母的国家代码。

描述：表示客户端IP地址对应的国家代码。例如，“RU”代表俄罗斯，“US”代表美国。此变量依赖于GeoIP数据库。

示例：

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

$geoip_country_code3

功能：返回三位字母的国家代码。

描述：表示客户端IP地址对应的三位字母国家代码。例如，“RUS”代表俄罗斯，“USA”代表美国。同样依赖于GeoIP数据库。

示例：

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

$geoip_country_name

功能：返回国家名称。

描述：表示客户端IP地址对应的国家名称。例如，“Russian Federation”代表俄罗斯，“United States”代表美国。

示例：

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

$geoip_dma_code

功能：返回DMA区域代码（美国）。

描述：表示客户端IP地址对应的美国DMA（指定市场区域）代码，也称为“metro code”，用于Google AdWords API中的地理定位。

示例：

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

$geoip_latitude

功能：返回纬度。

描述：表示客户端IP地址对应的地理纬度坐标。可用于更精确的地理位置分析。

示例：

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

$geoip_longitude

功能：返回经度。

描述：表示客户端IP地址对应的地理经度坐标。与纬度一起使用，可以精确确定客户端的大致位置。

示例：

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

$geoip_org

功能：组织名称，例如“The University/XMLSchema-Identifier=0”。

描述：提供客户端IP地址对应的组织名称。这对于识别来自特定组织的流量，并根据这些信息进行访问控制或统计分析非常有用。

示例：

if ($geoip_org = "The University of Melbourne") {
    add_header X-Academic-Network "Welcome, University of Melbourne!";
}

$geoip_postal_code

功能：邮政编码。

描述：提供客户端IP地址对应的邮政编码。这对于需要基于邮政编码进行个性化内容展示或物流配送的应用非常有用。

示例：

log_format custom '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$geoip_postal_code"';
access_log /var/log/nginx/access.log custom;

$geoip_region

功能：两个符号的国家区域代码（地区、领土、州、省、联邦土地等），例如“48”，“DC”。

描述：提供客户端IP地址对应的国家区域代码。这对于基于地理位置进行内容定制或访问控制非常有用。

示例：

log_format custom '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$geoip_region"';
access_log /var/log/nginx/access.log custom;

$geoip_region_name

功能：国家区域名称（地区、领土、州、省、联邦土地等），例如“Moscow City”，“District of Columbia”。

描述：提供客户端IP地址对应的国家区域名称。对于需要展示或记录用户所在地理区域的应用场景非常有用。

示例：

if ($geoip_region_name = "California") {
    rewrite ^/content/(.*)$ /content/ca/$1 break;
}

2.6 ngx_http_gzip_module

2.6.1 变量列表

$gzip_ratio

功能：表示实现的压缩比率，计算方法是原始响应大小与压缩后响应大小的比率。

描述：这个变量对于监控和优化Nginx的Gzip压缩效率非常有用。它可以帮助了解哪些响应被有效地压缩了，从而节省带宽和提高加载速度。

示例：

log_format custom '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$gzip_ratio"';
access_log /var/log/nginx/access.log custom;

在此配置中，$gzip_ratio将被记录在访问日志中，帮助分析压缩效果。

2.7 ngx_http_limit_conn_module

2.7.1 变量列表

$limit_conn_status

功能：保存限制连接数的结果（从1.17.6版本开始）。

可能值：PASSED（通过），REJECTED（拒绝），REJECTED_DRY_RUN（模拟运行时拒绝）。

描述：用于跟踪是否成功应用了连接限制策略。这对于调试和监控限流规则特别有用。

示例：

limit_conn_zone $binary_remote_addr zone=addr:10m;
server {
    location /download/ {
        limit_conn addr 1;
        return 200 'Limit connection status: $limit_conn_status';
    }
}

当请求到达/download路径时，返回当前连接限制的状态。

2.8 ngx_http_limit_req_module

2.8.1 变量列表

$limit_req_status

功能：保存限制请求处理速率的结果（从1.17.6版本开始）。

可能值：PASSED（通过），DELAYED（延迟），REJECTED（拒绝），DELAYED_DRY_RUN（模拟运行时延迟），REJECTED_DRY_RUN（模拟运行时拒绝）。

描述：用于监控请求速率限制的效果，有助于了解请求是否被接受、延迟或拒绝。

示例：

limit_req_zone $binary_remote_addr zone=req_limit:10m rate=1r/s;
server {
    location /api/ {
        limit_req zone=req_limit burst=5;
        return 200 'Limit request status: $limit_req_status';
    }
}

此配置展示了如何设置并查看请求速率限制的状态。

2.9 ngx_http_log_module

2.9.1 变量列表

$bytes_sent

$connection

$connection_requests

$msec

$pipe

$request_length

$request_time

$status

$time_iso8601

$time_local

2.10 ngx_http_memcached_module

2.10.1 变量列表

$memcached_key

功能：定义用于从Memcached服务器获取响应的键。

描述：此变量允许您动态生成一个键值，该键值用于从Memcached缓存中检索数据。这对于缓存机制非常有用，可以显著提高性能。

示例：

location / {
    set $memcached_key $request_uri;
    memcached_pass localhost:11211;
}

在这个例子中，$memcached_key被设置为请求的URI，以便根据请求的路径从Memcached服务器中获取缓存的数据。

2.11 ngx_http_proxy_module

2.11.1 变量列表

$proxy_add_x_forwarded_for

功能：返回客户端请求头字段“X-Forwarded-For”加上$remote_addr变量，用逗号分隔。如果客户端请求头中没有“X-Forwarded-For”字段，则该变量等于$remote_addr。

描述：此变量用于保留客户端的真实IP地址，尤其是在通过多个代理服务器时。它有助于追踪请求的来源。

示例：

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://backend.example.com;
}

如果客户端的真实IP是192.168.1.1，且请求经过了一个代理服务器10.0.0.1，则最终的“X-Forwarded-For”头将包含192.168.1.1, 10.0.0.1。

$proxy_host

功能：返回代理服务器的名称和端口，如在proxy_pass指令中指定的那样。

描述：此变量包含代理服务器的主机名和端口号，便于在配置中引用或记录。

示例：

location /backend/ {
    proxy_pass http://backend.example.com:8080;
    add_header X-Proxy-Host $proxy_host;
}

如果代理服务器是backend.example.com:8080，则响应头将包含X-Proxy-Host: backend.example.com:8080。

$proxy_port

功能：返回代理服务器的端口，如在proxy_pass指令中指定的那样；如果没有指定，则返回协议的默认端口。

描述：此变量包含代理服务器的端口号，便于在配置中引用或记录。

示例：

location /api/ {
    proxy_pass http://api.example.com;
    add_header X-Proxy-Port $proxy_port;
}

如果代理服务器是api.example.com（没有指定端口），则响应头将包含X-Proxy-Port: 80（HTTP协议的默认端口）。

2.12 ngx_http_proxy_protocol_vendor_module

2.12.1 变量列表

$proxy_protocol_tlv_aws_vpce_id

功能：从PROXY Protocol头中提取的TLV（Type-Length-Value）值，表示AWS VPC终端节点的ID。

描述：此变量用于获取通过PROXY Protocol传递的特定于AWS VPC终端节点的信息，通常用于网络连接管理和安全策略。

示例：

location / {
    proxy_pass http://backend.example.com;
    log_format custom '$remote_addr - $proxy_protocol_tlv_aws_vpce_id';
    access_log /var/log/nginx/access.log custom;
}

如果请求中包含PROXY Protocol头并指定了AWS VPC终端节点ID，则日志条目将包含该ID。

$proxy_protocol_tlv_azure_pel_id

功能：从PROXY Protocol头中提取的TLV值，表示Azure私有端点的LinkID。

描述：此变量用于获取通过PROXY Protocol传递的特定于Azure私有端点的信息，通常用于网络连接管理和安全策略。

示例：

location / {
    proxy_pass http://backend.example.com;
    log_format custom '$remote_addr - $proxy_protocol_tlv_azure_pel_id';
    access_log /var/log/nginx/access.log custom;
}

如果请求中包含PROXY Protocol头并指定了Azure私有端点的LinkID，则日志条目将包含该ID。

$proxy_protocol_tlv_gcp_conn_id

功能：从PROXY Protocol头中提取的TLV值，表示Google Cloud PSC（Private Service Connect）连接ID。

描述：此变量用于获取通过PROXY Protocol传递的特定于Google Cloud PSC连接的信息，通常用于网络连接管理和安全策略。

示例：

location / {
    proxy_pass http://backend.example.com;
    log_format custom '$remote_addr - $proxy_protocol_tlv_gcp_conn_id';
    access_log /var/log/nginx/access.log custom;
}

如果请求中包含PROXY Protocol头并指定了Google Cloud PSC连接ID，则日志条目将包含该ID。

2.13 ngx_http_realip_module

2.13.1 变量列表

$realip_remote_addr

功能：保持原始客户端地址。

描述：该变量保存了请求的原始客户端IP地址。在使用反向代理或负载均衡器时，此变量可以帮助获取真实的客户端IP地址，而不是代理服务器的IP地址。自Nginx版本1.9.7起可用。

示例：

set_real_ip_from 192.168.1.0/24;
real_ip_header X-Real-IP;
log_format custom '$realip_remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent"';

在这个例子中，即使使用了set_real_ip_from和real_ip_header指令来处理代理IP，$realip_remote_addr仍然会记录原始客户端IP。

$realip_remote_port

功能：保持原始客户端端口。

描述：该变量保存了请求的原始客户端端口号。这对于调试和记录详细的连接信息非常有用。自Nginx版本1.11.0起可用。

示例：

log_format detailed '$realip_remote_addr:$realip_remote_port - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent"';

这个日志格式不仅记录了客户端的IP地址，还记录了客户端使用的端口号。

2.14 ngx_http_secure_link_module

2.14.1 变量列表

$secure_link

功能：链接检查的状态。

描述：该变量用于表示安全链接检查的结果状态。具体值取决于所选择的操作模式。通常与secure_link和secure_link_md5指令一起使用，以验证请求中的链接是否有效和未过期。

如果链接有效且未过期，变量值为1。
如果链接已过期，变量值为0。
如果链接无效（例如签名不匹配），变量值为空字符串。

示例：

location /protected {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "secret$uri$arg_expires";

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;
    }
}

在这个例子中，如果链接无效，返回403错误；如果链接已过期，返回410错误。

$secure_link_expires

功能：请求中传递的链接的有效期。

描述：该变量仅在使用secure_link_md5指令时有效，表示链接的有效期（即过期时间）。通常用于生成和验证带有过期时间的安全链接。

示例：

location /downloads {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "secret$uri$arg_expires";

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;
    }

    # 可以在这里使用 $secure_link_expires 来做进一步处理
    add_header X-Link-Expires $secure_link_expires;
}

在这个例子中，除了验证链接的有效性和过期时间外，还可以通过add_header指令将链接的过期时间添加到响应头中。

2.15 ngx_http_session_log_module

2.15.1 变量列表

$session_log_binary_id

功能：当前会话ID的二进制形式（16字节）。

描述：提供当前请求的会话ID的二进制表示形式，通常用于需要高效处理或存储会话ID的情况。

示例：

log_format custom_binary '$remote_addr - $remote_user [$time_local] "$request" '
                         '$status $body_bytes_sent "$http_referer" '
                         '"$http_user_agent" "$session_log_binary_id"';
access_log /var/log/nginx/access_binary.log custom_binary;

$session_log_id

功能：当前会话ID。

描述：提供当前请求的会话ID。这对于跟踪用户会话、分析用户行为或进行日志记录非常有用。

示例：

log_format custom '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$session_log_id"';
access_log /var/log/nginx/access.log custom;

2.16 ngx_http_slice_module

2.16.1 变量列表

$slice_range

功能：当前分片范围，以HTTP字节范围格式表示，例如bytes=0-1048575。

描述：提供当前请求的字节范围。这对于支持大文件下载时的分片传输非常有用，可以实现断点续传等功能。

示例：

location /downloads/largefile {
    slice 1m;
    proxy_cache my_cache;
    proxy_pass http://backend;
}

log_format slice_custom '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" "$slice_range"';
access_log /var/log/nginx/slice_access.log slice_custom;

2.17 ngx_http_ssi_module

2.17.1 变量列表

$date_gmt

功能：GMT时区的当前时间。格式由配置命令中的timefmt参数设置。

描述：提供当前时间的GMT时区表示，格式可以通过timefmt参数自定义。适用于需要记录协调世界时（UTC）的日志记录场景。

示例：

log_format custom_with_gmt_date '$remote_addr - $remote_user [$time_local] "$request" '
                                 '$status $body_bytes_sent "$http_referer" '
                                 '"$http_user_agent" "$date_gmt"';
access_log /var/log/nginx/access_with_gmt_date.log custom_with_gmt_date;

# 在nginx.conf中设置日期格式
config timefmt "%Y-%m-%d %H:%M:%S";

$date_local

功能：本地时区的当前时间。格式由配置命令中的timefmt参数设置。

描述：提供当前时间的本地时区表示，格式可以通过timefmt参数自定义。适用于需要记录本地时间的日志记录场景。

示例：

log_format custom_with_date '$remote_addr - $remote_user [$time_local] "$request" '
                            '$status $body_bytes_sent "$http_referer" '
                            '"$http_user_agent" "$date_local"';
access_log /var/log/nginx/access_with_date.log custom_with_date;

# 在nginx.conf中设置日期格式
config timefmt "%Y-%m-%d %H:%M:%S";