处理多级代理日志变量需准确提取客户端信息与跳转路径,并通过请求头注入、变量映射和日志格式协同实现;核心是用X-Forwarded-For链式传递+realip模块还原真实IP,配合X-Forwarded-By等自定义头标记转发节点,再用map构建语义化路径与角色标签统一记录。

处理多级代理转发中的自定义日志变量,关键在于两点:一是准确提取原始客户端信息与中间跳转路径,二是让变量在各层 Nginx 实例中可传递、可识别、可记录。它不是简单拼几个内置变量,而是需要请求头注入 + 变量映射 + 日志格式协同设计。
用 X-Forwarded-For 链式追加 + $realip_remote_addr 提取真实 IP
多级代理下,$remote_addr 只是上一跳的 IP,不可靠。应结合请求头和 realip 模块还原源头:
- 确保每级 Nginx 都配置
set_real_ip_from和real_ip_header X-Forwarded-For,并启用real_ip_recursive on,这样$realip_remote_addr才能稳定拿到最外层客户端 IP - 在入口 Nginx 中用
proxy_set_header X-Forwarded-For "$proxy_add_x_forwarded_for"—— 它自动追加当前$remote_addr,形成逗号分隔链(如203.0.113.5, 192.168.10.2, 172.16.0.3) - 若需单独记录首跳 IP(即用户真实出口),可用
map提前解析:
map $http_x_forwarded_for $client_first_ip {
"" $remote_addr;
"~^([0-9.]+),?" $1;
}
为每级代理注入唯一标识,并写入日志
仅记录 IP 不足以区分转发路径,必须标记“谁转发了谁”:
- 在每一级 Nginx 的
location或upstream块中,添加:
proxy_set_header X-Forwarded-By "$hostname";
proxy_set_header X-Proxy-Hop "$server_addr:$server_port";
这样下游服务或下一级 Nginx 就能读到本节点身份 - 在日志格式中直接引用这些头:
log_format proxy_chain
'$client_first_ip [$time_local] "$request" '
'$status $body_bytes_sent '
'"$http_x_forwarded_by" "$http_x_proxy_hop" '
'"$upstream_addr" $request_time'; - 注意:
$http_x_*变量会自动将请求头转为小写并把连字符换成下划线,所以X-Forwarded-By对应$http_x_forwarded_by
用 map 构建语义化转发路径标签
单纯记录 IP 和主机名仍难快速定位问题,建议抽象出业务路径维度:
- 在
http块顶层定义路径类型标签:
map $host:$request_uri $proxy_route {
"api.example.com/api/v2/users" "edge→auth→user-service";
"api.example.com/health" "edge→health-check";
default "unknown-route";
} - 再定义节点角色标签(如边缘网关、区域 LB、服务网关):
map $hostname $proxy_role {
"gw-edge-prod-01" "edge";
"lb-region-us" "region-lb";
"svc-gw-api" "service-gw";
default "unknown";
} - 把这些变量统一放进日志格式,就能一眼看出“谁在哪条路径上做了什么”:
log_format full_trace
'$client_first_ip $proxy_role "$proxy_route" '
'[$time_local] "$request" $status '$upstream_response_time';
验证与调试要点
多级代理日志容易因变量未就绪或顺序错乱而丢失字段:
-
log_format必须定义在http块内,且早于所有access_log引用;map同样只能在http块顶层声明 - 像
$upstream_addr这类变量只在proxy_pass执行后才有效,不能在 rewrite 阶段使用;若需前置判断,改用$proxy_host或map映射 - 测试时用
curl -H "X-Forwarded-For: 203.0.113.5" http://your-nginx/模拟多级头,再tail -f /var/log/nginx/access.log实时观察输出 - 如果某变量始终为空,检查是否拼写错误(如
$http_x_forwarded_for写成$http_x_forwarded_for少个r),或请求头被忽略(确认未启用underscores_in_headers on)











