# 详解 Nginx 获取客户端真实 IP

写这类文章，我更关注能快速落地的配置与踩坑规避。你会看到清晰的架构图景、配置“即插即用”的范式、验证与日志、以及在复杂场景（CDN、负载均衡、K8s）下的稳妥实践。

## 场景与核心概念

#### 常见流量路径

- 直连：
	 客户端 → Nginx（无代理）。
	- **真实 IP 来源：** `$remote_addr`。
- 单层代理：
	 客户端 → 反向代理/CDN/ELB → Nginx。
	- **真实 IP 来源：** 来自上游的 `X-Forwarded-For` 或 `Forwarded` 头，需启用 `real_ip` 模块。
- 多层代理：
	 客户端 → 多级代理链 → Nginx。
	- **真实 IP 来源：** `X-Forwarded-For` 列表的第一个非信任代理插入的地址；需开启递归解析并谨慎设置信任边界。

#### 关键变量与头部

- **$remote_addr：** Nginx 接收到的直连对端 IP（通常是最后一跳代理的 IP）。
- **$http_x_forwarded_for：** 原样读取请求头 `X-Forwarded-For` 的值（未经校验）。
- **$realip_remote_addr：** 启用 real_ip 模块后解析出的“客户端真实 IP”（基于信任代理和递归规则）。
- **Forwarded 头：** 标准化头（RFC 7239），如 `Forwarded: for=203.0.113.1; proto=https; host=example.com`。


## 标准配置范式与即插即用示例

#### 单层代理或 CDN 的基本范式

- **目标：** 使用上游写入的 `X-Forwarded-For` 或供应商头（如 `CF-Connecting-IP`）替换真实 IP。
- 配置要点：
	- **声明信任源：** 只信任上游代理的出口 IP 段。
	- **指定头来源：** 优先标准头；CDN场景用供应商专用头。
	- **开启递归：** 多级链路时需要，单层可选。

```
# http 块内
# 1) 声明信任的上游代理/负载均衡出口网段
set_real_ip_from  10.0.0.0/8;
set_real_ip_from  192.168.0.0/16;
set_real_ip_from  203.0.113.0/24; &nbsp; # 举例外部负载均衡出口段
​
# 2) 选择解析的头（优先标准头；或供应商头）
real_ip_header &nbsp; &nbsp;X-Forwarded-For; &nbsp; # 标准链路
# real_ip_header  CF-Connecting-IP; # Cloudflare 场景
​
# 3) 多级代理时启用递归
real_ip_recursive on;
server {
 &nbsp;listen 80;
 &nbsp;# 规范化代理链：下游继续传递真实 IP
 &nbsp;location / {
 &nbsp; &nbsp;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 &nbsp; &nbsp;proxy_set_header X-Forwarded-Proto $scheme;
 &nbsp; &nbsp;proxy_set_header X-Forwarded-Host $host;
 &nbsp; &nbsp;proxy_pass http://upstream_app;
  }
}
```#### Cloudflare 的专用范式

- **要点：** 使用 `CF-Connecting-IP`，并将 Cloudflare 官方出口网段加入信任列表（需定期同步）。

```
set_real_ip_from  173.245.48.0/20;
set_real_ip_from  103.21.244.0/22;
# ...（完整列表自行同步）
real_ip_header &nbsp; &nbsp;CF-Connecting-IP;
real_ip_recursive on;
```#### AWS 负载均衡与 K8s Ingress

- **ALB/NLB：** ALB 会写 `X-Forwarded-For`，需把 ALB 子网段加入 `set_real_ip_from`。
- **Kubernetes：** 通过 Ingress Controller（如 NGINX Ingress）通常已代管 `X-Forwarded-*`，你需要在工作负载侧继续信任 Ingress 的 Pod/Node 出口网段；或直接在 Ingress 层开启 Real IP。


----
## 日志与验证

#### 推荐 log_format 模板

```
log_format realip_combined
 &nbsp;'$remote_addr - $realip_remote_addr - $http_x_forwarded_for '
 &nbsp;'"$request" $status $body_bytes_sent '
 &nbsp;'"$http_referer" "$http_user_agent" '
 &nbsp;'rt=$request_time uct=$upstream_connect_time urt=$upstream_response_time';
​
access_log /var/log/nginx/access.log realip_combined;
```- 解读：
	- **$remote_addr：** 你实际连接到的对端（多半是代理）。
	- **$realip_remote_addr：** 解析后“真实客户端 IP”。
	- **$http_x_forwarded_for：** 原始头部，便于对比与审计。

#### 本地验证步骤

- **抓包对照：** tcpdump 观察 Nginx 收到的对端 vs 日志解析出的真实 IP。
- curl 模拟：
	- **直连：** `curl -H 'X-Forwarded-For: 1.2.3.4' http://your-nginx`（不在信任段时不应被采信）。
	- **代理内网：** 从信任网段主机发起同样请求，应看到 `$realip_remote_addr=1.2.3.4`。


## 常见坑与安全边界

- 信任边界配置错位：
	- **风险：** 任意客户端可伪造 `X-Forwarded-For`，导致伪造 IP 被采信。
	- **对策：** 仅将“你控制的、已知的出口代理网段”加入 `set_real_ip_from`。外网不在信任列表。
- 未递归导致取值错误：
	- **表现：** 多级代理时 `$realip_remote_addr`仍为倒数第二跳。
	- **对策：** `real_ip_recursive on;`。
- 头来源不统一：
	- **表现：** 混用供应商专用头与标准头，解析顺序不明确。
	- **对策：** 明确场景选择一个头；如 Cloudflare 用 `CF-Connecting-IP`，其他用 `X-Forwarded-For`。
- 缺少下游继续传递：
	- **表现：** 应用服务器只看到最后一跳。
	- **对策：** `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`。
- IPv6 忽视：
	- **表现：** 仅配置 IPv4 信任段，IPv6 入口未被识别。
	- **对策：** 追加 IPv6 段到 `set_real_ip_from`，并在日志中记录 IPv6。
- Forwarded 标准头未适配：
	- **建议：** 有条件时同步解析 `Forwarded`，但保持单一权威来源。


## 进阶场景与模块

#### stream 层的真实 IP（TCP/UDP）

- **场景：** 四层代理（如 TLS 透传、MySQL 直连）需在 `stream` 中识别真实 IP。
- **方法：** 使用 `proxy_protocol`（如 HAProxy、ELB 支持）。在 Nginx `stream` 配置启用 `proxy_protocol` 并解析。

```
stream {
 &nbsp;server {
 &nbsp; &nbsp;listen 3306 proxy_protocol;
 &nbsp; &nbsp;proxy_protocol on;
 &nbsp; &nbsp;set_real_ip_from 10.0.0.0/8;
 &nbsp; &nbsp;real_ip_header proxy_protocol;
 &nbsp; &nbsp;proxy_pass mysql_backend:3306;
  }
}
```#### gRPC 与 HTTP/2

- **要点：** 与 HTTP 类似，确保上游代理传递 `X-Forwarded-For`，Nginx 侧正常解析即可。

#### 应用层透传与安全审计

- **建议：** 将 `$realip_remote_addr` 透传到应用层（例如入库、审计日志），同时保留原始 `X-Forwarded-For` 供取证。


----
## 可复制的配置清单与模板

#### 通用 http 模板

```
# http
set_real_ip_from  10.0.0.0/8;
set_real_ip_from  192.168.0.0/16;
set_real_ip_from  172.16.0.0/12;
# 外部 LB 出口段（示例）
set_real_ip_from  203.0.113.0/24;
​
# 选择一个权威头
real_ip_header &nbsp; &nbsp;X-Forwarded-For;
real_ip_recursive on;
​
log_format realip_combined
 &nbsp;'$remote_addr - $realip_remote_addr - $http_x_forwarded_for '
 &nbsp;'"$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
access_log /var/log/nginx/access.log realip_combined;
​
server {
 &nbsp;listen 80;
 &nbsp;location / {
 &nbsp; &nbsp;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 &nbsp; &nbsp;proxy_set_header X-Forwarded-Proto $scheme;
 &nbsp; &nbsp;proxy_set_header X-Forwarded-Host $host;
 &nbsp; &nbsp;proxy_pass http://upstream_app;
  }
}
```#### Cloudflare 专用模板

```
# 按官方列表维护出口网段
set_real_ip_from  173.245.48.0/20;
set_real_ip_from  103.21.244.0/22;
# ... 其余段请同步更新
real_ip_header &nbsp; &nbsp;CF-Connecting-IP;
real_ip_recursive on;
```#### AWS ALB 模板

```
# 将 ALB 子网/出口段加入信任
set_real_ip_from  10.0.0.0/8; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;# 你的 VPC 网段
set_real_ip_from  198.51.100.0/24; &nbsp; &nbsp; # 举例：ALB 公网出口段
real_ip_header &nbsp; &nbsp;X-Forwarded-For;
real_ip_recursive on;
```

----
## 运维排查清单与自动化要点

- 信任网段核对：
	- **动作：** 收集并白名单化所有代理出口段（CDN、ELB、Ingress、边缘节点）。
	- **自动化：** 订阅供应商网段变更，定期拉取与渲染 Nginx 片段。
- 头部一致性：
	- **动作：** 统一权威头；下游统一 `proxy_set_header`。
	- **自动化：** lint 检查 Nginx 配置中是否混用多头来源。
- 日志验证：
	- **动作：** 对比 `$remote_addr` 与 `$realip_remote_addr` 差异分布。
	- **自动化：** 定时统计异常比例，触发告警。
- 多级链路递归：
	- **动作：** 启用 `real_ip_recursive`，并验证 XFF 列表首元素是否为公网客户端。
	- **自动化：** 在灰度环境强制注入测试 IP，校验解析结果。
- IPv6 支持：
	- **动作：** 增加 IPv6 信任段与日志字段。
	- **自动化：** 双栈探测脚本与告警。


----
## 结语

获取“真实 IP”不是把某个变量换个名字，而是设置信任边界与解析规则。把信任网段管住、权威头统一、递归开启、日志对齐，这事就稳了。需要我把上述模板整理成 Ansible 角色或一键脚本吗？我可以按你的环境（CDN/ALB/K8s）出定制版本。

写这类文章，我更关注能快速落地的配置与踩坑规避。你会看到清晰的架构图景、配置“即插即用”的范式、验证与日志、以及在复杂场景（CDN、负载均衡、K8s）下的稳妥实践。

详解 Nginx 获取客户端真实 IP

网络与通信

后端

运维

Nginx获取客户端真实IP配置指南：详解单层/多层代理场景下的real_ip模块使用，提供Cloudflare、ALB、Kubernetes等场景的即用配置模板。包含信任网段设置、递归解析、日志验证等关键步骤，以及常见安全风险规避方案。适用于CDN、负载均衡等复杂网络环境，确保准确获取客户端真实IP。

负载均衡

安全审计

Kubernetes

服务器

MySQL

CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

详解 Nginx 获取客户端真实 IP-腾讯云开发者社区-腾讯云

详解 Nginx 获取客户端真实 IP

详解 Nginx 获取客户端真实 IP

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐