OpenResty 官方博客 ·

OpenResty Edge 客户端真实 IP 全链路传递指南

💡 原文中文，约9500字，阅读约需23分钟。

📝

内容提要

本文介绍了OpenResty Edge处理客户端真实IP的四种方案：Proxy Protocol、X-Forwarded-For、X-Real-IP和自定义头。每种方案适用于不同的代理拓扑，文中详细说明了配置步骤和安全注意事项，以确保准确还原用户真实IP，支持访问控制和限速等功能。

🎯

在引入前置代理、CDN 或四层负载均衡后，网关收到的客户端地址往往变成代理服务器的 IP，导致基于用户真实 IP 的限速、访问控制和审计日志失效。
OpenResty Edge 支持四种真实 IP 还原方案：Proxy Protocol、X-Forwarded-For、X-Real-IP 和自定义头，适用于不同的代理拓扑和协议层。
Proxy Protocol 适用于四层 TCP/UDP Stream 代理，前置代理在建立 TCP 连接时注入一行标准化的 PROXY 头，网关解析该头部以提取真实 IP。
X-Real-IP 方案适用于前置代理负责将真实客户端 IP 写入该头的场景，但不同上游代理的实现行为存在差异。
X-Forwarded-For 方案适用于多级 HTTP 代理链路，每经过一个代理节点，该节点将入站 IP 追加至 X-Forwarded-For 头末尾。
自定义头方案允许运维人员指定任意 HTTP 头字段名称作为真实 IP 来源，适用于内部系统已有私有 IP 传递规范的场景。
在 OpenResty Edge 中，必须在端口级别启用 proxy protocol 支持，并在全局配置中选择实际使用的方案。
配置可信来源 IP 列表，以确保只有来自可信地址的请求头中的真实 IP 会被采信并更新 client-addr。
通过 curl 等工具可以验证不同方案的效果，确保真实 IP 的传递和还原正确。
OpenResty Edge 还支持在回源请求中通过自定义请求头将真实客户端 IP 透传给后端服务器。

🔎

在现代网络架构中，准确还原客户端的真实 IP 地址对于实施访问控制、限速和审计日志至关重要。若未能正确获取真实 IP，可能导致安全漏洞和资源滥用。因此，选择合适的 IP 传递方案是确保系统安全和性能的基础。

OpenResty Edge 提供的四种真实 IP 还原方案各有其适用场景。Proxy Protocol 适合四层代理，而 X-Forwarded-For 和 X-Real-IP 更适用于 HTTP 代理链。运维人员需根据具体的代理拓扑和需求选择合适的方案，以确保系统的稳定性和安全性。

在配置真实 IP 还原方案时，设置可信来源 IP 列表是防止伪造头部的重要步骤。只有来自可信地址的请求头中的真实 IP 才会被采信，这样可以有效抵御潜在的安全威胁，确保系统的正常运行和数据的准确性。

❓

OpenResty Edge 支持四种方案：Proxy Protocol、X-Forwarded-For、X-Real-IP 和自定义头，适用于不同的代理拓扑和协议层。

Proxy Protocol 在建立 TCP 连接时注入一行标准化的 PROXY 头，网关解析该头部以提取真实 IP。

X-Forwarded-For 适用于多级 HTTP 代理链路，每经过一个代理节点，该节点将入站 IP 追加至该头末尾。

在 Global Config 页面中输入前置代理服务器的 IP 地址，只有在此列表中的 IP 才会被采信并更新 client-addr。

可以通过 curl 携带不同的头部，如 X-Forwarded-For、X-Real-IP 等，来验证真实 IP 的传递和还原是否正确。

自定义头方案适用于内部系统已有私有 IP 传递规范的场景，允许运维人员指定任意 HTTP 头字段名称作为真实 IP 来源。

🏷️