> For the complete documentation index, see [llms.txt](https://www.axisnow.io/zh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.axisnow.io/zh/docs/edge/policies/real-ip.md).

# 真实客户端 IP

识别真实客户端 IP 并传递给源站

边缘前面有 CDN、七层代理或四层负载均衡时，到达边缘的连接地址是它们的出口地址，全部访客在边缘看来都来自少数几个地址。真实客户端 IP 插件从请求头或 Proxy Protocol 中读出真实地址，供后续插件、日志和洞察使用，并按所选方式传给源站。

## 两个动作 <a href="#actions" id="actions"></a>

<table data-search="false"><thead><tr><th width="100">动作</th><th>作用</th><th width="160">默认规则</th></tr></thead><tbody><tr><td><a href="#get">获取</a></td><td>真实 IP 的来源</td><td>连接地址</td></tr><tr><td><a href="#forward">转发</a></td><td>传给源站的方式</td><td>X-Real-IP</td></tr></tbody></table>

它是[多动作配置类插件](/zh/docs/edge/policies/rules.md#rulesets)。内置一条不可修改的默认规则排在最后：条件为**任意**，获取用连接地址，转发用 X-Real-IP，客户端直连边缘的 HTTP 站点不需要配置。TCP 转发端点不适用 X-Real-IP，默认原样透传客户端连接自带的 Proxy Protocol 头，没有则不传。

部分选项只适用于 HTTP 或只适用于 TCP，类型不符的端点命中后按未配置处理，不再落到默认规则；同时有两类端点时用 域、TCP 或 标签 条件限定。

## 获取 <a href="#get" id="get"></a>

读出的地址取代连接地址，作为本次请求的客户端 IP：后续插件条件中的「客户端 IP 地址」「客户端 IP 区域」「客户端 IP ASN」、IP 封禁、访问日志与洞察均以它为准。

<table data-search="false"><thead><tr><th width="150">方式</th><th>取值</th><th width="220">适用</th></tr></thead><tbody><tr><td>连接地址</td><td>TCP 连接的对端地址</td><td>客户端直连边缘</td></tr><tr><td>X-Forwarded-For</td><td>请求头中的一个值。默认取最后一个，即边缘前一跳代理追加的值；也可指定从左数第 1 到 10 个</td><td>前面是 CDN 或七层代理</td></tr><tr><td>其他请求头</td><td>指定请求头的值，例如 CDN 专用的 <code>CF-Connecting-IP</code>、<code>True-Client-IP</code></td><td>CDN 提供专用头时</td></tr><tr><td>Proxy Protocol</td><td>连接开头的 Proxy Protocol 头，v1、v2 自动识别</td><td>前面的四层负载均衡或 TCP 代理不透传源地址</td></tr></tbody></table>

* 值必须是单个 IPv4 或 IPv6 地址。请求头缺失或值不合法时回退到 Proxy Protocol 地址，没有则回退到连接地址。
* 请求头和 Proxy Protocol 头都可以伪造。本插件的条件在读取之前求值，条件里的「客户端 IP 地址」仍是连接地址，边缘可被直接访问时用它把规则限定在代理的出口网段，见[配置场景](/zh/docs/edge/policies/real-ip/use-cases.md#trust)。

## 转发 <a href="#forward" id="forward"></a>

<table data-search="false"><thead><tr><th width="150">方式</th><th>传递内容</th><th width="220">适用</th></tr></thead><tbody><tr><td>X-Real-IP</td><td>请求头 <code>X-Real-IP</code>，值为真实 IP</td><td>HTTP 源站</td></tr><tr><td>其他请求头</td><td>指定名称的请求头，值为真实 IP</td><td>源站程序读取固定的请求头</td></tr><tr><td>Proxy Protocol</td><td>回源连接开头附加 v1 或 v2 头，源站需开启接收</td><td>TCP 转发端点</td></tr><tr><td>TOA</td><td>真实 IP 和端口放在 TCP 选项中，源站需<a href="/zh/docs/edge/policies/real-ip/toa.md">加载 TOA 内核模块</a>，应用无需改动</td><td>TCP 转发端点</td></tr></tbody></table>

HTTP 请求不论选哪种，`X-Forwarded-For` 都会追加到达边缘的连接地址后转发给源站，源站能看到完整的代理链；`X-Forwarded-Proto` 固定为客户端到边缘的协议。

## 最佳实践 <a href="#best-practices" id="best-practices"></a>

* **前置代理必须配置本插件**：边缘前面有 CDN、七层代理或不透传源地址的四层负载均衡而没有配置获取规则时，全部访客在边缘看来共用代理的少数出口 IP：按 IP 计数的速率控制把所有请求计入同一来源，IP 封禁封掉的是代理出口，地区、ASN 条件和 IP 白名单全部失准。接入代理时同步配好规则。
* **真实 IP 来自请求头或 Proxy Protocol 时不用 IP 封禁**：这两种方式下连接来自 CDN 或负载均衡，封禁作用在真实 IP 上，网络层的丢弃不会命中，仅触发封禁的那一次请求被中断，没有持续封禁。[通用访问控制](/zh/docs/edge/policies/access-control/how-it-works.md#ban-details)和[速率控制](/zh/docs/edge/policies/rate-limiting/how-it-works.md#ip-ban-details)的 IP 封禁动作、挑战的自动封禁都是如此，改用阻断或挑战。透传源地址的四层负载均衡不受影响。
* **边缘能被直连时只信任代理网段的头**：边缘的公网 IP 可达时，读请求头或 Proxy Protocol 的规则要带上 客户端 IP 地址 在对象中 的条件，否则绕过代理直连并伪造头的请求可以冒充任意地址，IP 白名单、限速和封禁都会失效。边缘不对公网暴露的部署不需要这个条件，见[配置场景](/zh/docs/edge/policies/real-ip/use-cases.md#trust)。
* **专用头优先**：CDN 专用头只有一个值、由 CDN 覆盖写入；X-Forwarded-For 是客户端可以预先写入的列表，只有最后一个值是前一跳代理追加的可信值，仅当边缘前恰好一跳可信代理时才等于真实 IP。从左数第 N 个取的是客户端侧的值，除非前置代理会清除客户端自带的 X-Forwarded-For，否则不应使用。
* **源站读 X-Real-IP**：边缘转发时在 X-Forwarded-For 末尾追加到达边缘的连接地址，有前置代理时最后一个值是代理的出口地址而不是客户端；X-Real-IP 始终是还原后的真实 IP。

## 下一步 <a href="#next-steps" id="next-steps"></a>

<table data-search="false"><thead><tr><th width="160">页面</th><th>内容</th></tr></thead><tbody><tr><td><a href="/zh/docs/edge/policies/real-ip/use-cases.md">配置场景</a></td><td>条件是否限定来源，以及七层代理、四层负载均衡、TCP 转发端点三种拓扑的配置</td></tr><tr><td><a href="/zh/docs/edge/policies/real-ip/toa.md">安装 TOA 内核模块</a></td><td>源站侧的编译、加载与验证</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.axisnow.io/zh/docs/edge/policies/real-ip.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.