Nginx反向代理获取真实IP的完整解决方案

一、核心问题解析
当请求经过Nginx反向代理时，默认情况下后端服务只能获取到Nginx服务器的本地IP。要获取客户端真实IP，需通过以下方式实现：

二、技术实现原理
1. HTTP头传递机制
通过 X-Forwarded-For和 X-Real-IP两个标准头字段，将客户端真实IP传递给后端服务。
2. 内置变量解析
Nginx提供了以下关键变量：

$remote_addr：客户端直接连接Nginx的IP地址
$proxy_add_x_forwarded_for：自动追加IP的特殊变量（推荐使用）


三、配置方法与示例
方案1：基础配置（推荐）
location /api {
    proxy_pass http://backend_server;
    proxy_set_header X-Real-IP $remote_addr;       # 直接记录客户端IP
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 自动处理IP追加
}
​
代码解释：

X-Real-IP：直接记录客户端首次连接的IP地址
X-Forwarded-For：标准格式记录完整的代理链IP（如：客户端IP, NginxIP, 其他代理IP）
$proxy_add_x_forwarded_for：特殊变量，自动在原有值后追加当前客户端IP，避免重复写入


方案2：多级代理场景
当存在多层代理时，需确保每层代理正确传递IP：
# 第一层Nginx配置
proxy_set_header X-Forwarded-For $remote_addr;

# 第二层Nginx配置
proxy_set_header X-Forwarded-For $http_x_forwarded_for, $remote_addr;
​
重要说明：

第一层代理需将原始IP写入 X-Forwarded-For
后续代理需将当前客户端IP追加到现有值末尾（用逗号分隔）


方案3：IP白名单验证（安全增强）
# 验证客户端IP是否来自可信代理
if ($http_x_forwarded_for ~ "^(.*)?, (可信IP地址),(.*)$") {
    set $valid_ip 1;
}
if ($valid_ip != 1) {
    return 403;
}
​

四、关键参数分析表



参数名称
作用描述
示例值
⚠️注意事项




X-Real-IP
直接记录客户端首次连接的IP地址
192.168.1.100
仅记录单个IP，不保留代理链


X-Forwarded-For
标准的IP链记录格式（逗号分隔）
192.168.1.100, 10.0.0.1
需配合 $proxy_add_x_forwarded_for使用


$remote_addr
客户端直接连接Nginx的IP地址
192.168.1.100
可能被伪造，需结合白名单验证


$proxy_add_x_forwarded_for
自动处理 X-Forwarded-For的追加逻辑，避免重复写入
自动计算
必须确保后端解析器支持此格式




五、配置验证方法
1. 命令行测试
curl -H "Host:yourdomain.com" -I http://localhost/api
​
检查响应头中是否包含：
X-Real-IP: 192.168.1.100
X-Forwarded-For: 192.168.1.100
​
2. 后端服务验证
在后端代码中输出请求头：
# Python示例
print(request.headers.get("X-Real-IP"))
print(request.headers.get("X-Forwarded-For"))
​

六、安全增强建议
1. IP白名单校验
# 仅允许来自10.0.0.0/8的代理请求
if ($http_x_forwarded_for !~ "^(.*?, )?10\.[0-9.]+(.*)$") {
    return 403;
}
​
2. 禁用客户端伪造
# 移除客户端自定义的X-Forwarded-For
proxy_set_header X-Forwarded-For "";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
​

七、常见问题解答
Q：为什么后端收到的IP是Nginx本地IP？
A：未正确配置 proxy_set_header，需确保在 proxy_pass同级块中设置。
Q：多层代理时IP顺序如何？
A：IP按 客户端→代理1→代理2的顺序，逗号分隔显示在 X-Forwarded-For中。
Q：如何防止IP伪造？
A：结合白名单验证和 $proxy_add_x_forwarded_for，仅信任可信代理链。

通过以上配置方法，可确保后端服务准确获取客户端真实IP，同时兼顾安全性与灵活性。建议在生产环境启用访问日志记录IP信息，便于后续审计分析。