From d89dfc96f43b8e45f5640dba5563f3dc04adcb5b Mon Sep 17 00:00:00 2001 From: Meow <197331664+Meo597@users.noreply.github.com> Date: Sun, 17 May 2026 06:49:13 +0800 Subject: [PATCH] Sockopt: Add `trustedXForwardedFor` --- docs/config/transports/sockopt.md | 26 +++++++++++++++++++++++++- docs/en/config/transports/sockopt.md | 26 +++++++++++++++++++++++++- docs/ru/config/transports/sockopt.md | 26 +++++++++++++++++++++++++- 3 files changed, 75 insertions(+), 3 deletions(-) diff --git a/docs/config/transports/sockopt.md b/docs/config/transports/sockopt.md index 87f6dadb..b43ab907 100644 --- a/docs/config/transports/sockopt.md +++ b/docs/config/transports/sockopt.md @@ -16,7 +16,7 @@ Sockopt 用于配置底层网络行为。 // ... "streamSettings": { "sockopt": { - // [!code focus:18] + // [!code focus:19] "mark": 0, "tcpMaxSeg": 1440, "tcpFastOpen": false, @@ -25,6 +25,7 @@ Sockopt 用于配置底层网络行为。 "happyEyeballs": {}, "dialerProxy": "", "acceptProxyProtocol": false, + "trustedXForwardedFor": [], "tcpKeepAliveInterval": 0, "tcpKeepAliveIdle": 300, "tcpUserTimeout": 10000, @@ -156,6 +157,29 @@ Sockopt 用于配置底层网络行为。 填写 `true` 时，最底层 TCP 连接建立后，请求方必须先发送 PROXY protocol v1 或 v2，否则连接会被关闭。 +> `trustedXForwardedFor`: [ string ] + +仅用于 `XHTTP`、`WebSocket`、`HTTPUpgrade` 这三个基于 HTTP 的 inbound。 + +用于限制何时信任请求头里的 `X-Forwarded-For`，并用它覆写 `SourceIP`。 + +默认不设置时，仍保持旧行为：只要请求中带有 `X-Forwarded-For`，Xray 就会读取它。 + +设置后，数组中的每一项都表示一个额外要求存在的请求头名。只有当请求中存在其中任意一个头时，Xray 才会信任 `X-Forwarded-For`；这些头的值无所谓，只检查键是否存在。 + +::: details 示例与用途 + +```json +"sockopt": { + "trustedXForwardedFor": ["ABCDEF", "XYZ"] +} +``` + +这表示请求中必须额外出现 `ABCDEF` 或 `XYZ` 这两个头里的任意一个，Xray 才会接受同一请求中的 `X-Forwarded-For` 作为来源 IP。 + +通常可以让 CDN、Nginx 等你自己信任的 HTTP 反代额外注入一个只有服务端知道的自定义请求头，以避免客户端伪造来源 IP。 +::: + > `tcpKeepAliveIdle`: number TCP 空闲时间阈值，单位为秒。当 TCP 连接空闲时间达到这个阈值时，将开始发送 Keep-Alive 探测包。 diff --git a/docs/en/config/transports/sockopt.md b/docs/en/config/transports/sockopt.md index c10a769d..38792500 100644 --- a/docs/en/config/transports/sockopt.md +++ b/docs/en/config/transports/sockopt.md @@ -16,7 +16,7 @@ It can be used to tune transparent proxying, DNS resolution strategy, and many o // ... "streamSettings": { "sockopt": { - // [!code focus:18] + // [!code focus:19] "mark": 0, "tcpMaxSeg": 1440, "tcpFastOpen": false, @@ -25,6 +25,7 @@ It can be used to tune transparent proxying, DNS resolution strategy, and many o "happyEyeballs": {}, "dialerProxy": "", "acceptProxyProtocol": false, + "trustedXForwardedFor": [], "tcpKeepAliveInterval": 0, "tcpKeepAliveIdle": 300, "tcpUserTimeout": 10000, @@ -151,6 +152,29 @@ Common reverse proxies such as HAProxy and Nginx can be configured to send it, a When set to `true`, the peer must send PROXY protocol v1 or v2 immediately after the underlying TCP connection is established, otherwise the connection is closed. +> `trustedXForwardedFor`: [ string ] + +Only applies to the three HTTP-based inbounds: `XHTTP`, `WebSocket`, and `HTTPUpgrade`. + +It controls when Xray trusts `X-Forwarded-For` and uses it to overwrite `SourceIP`. + +If left unset, the old behavior remains: as long as the request contains `X-Forwarded-For`, Xray reads it. + +After setting this field, each array item is treated as an additional required header name. Xray trusts `X-Forwarded-For` only when the request also contains at least one of those headers. The header values do not matter; only the presence of the key is checked. + +::: details Example and use case + +```json +"sockopt": { + "trustedXForwardedFor": ["ABCDEF", "XYZ"] +} +``` + +This means the request must additionally contain either `ABCDEF` or `XYZ`, otherwise Xray will not accept the `X-Forwarded-For` value from that same request as the source IP. + +In practice, you can have a trusted HTTP reverse proxy such as a CDN or Nginx inject a custom header known only to the server side, which helps prevent clients from forging the source IP. +::: + > `tcpKeepAliveIdle`: number TCP idle threshold in seconds. Once a TCP connection has been idle for this long, Keep-Alive probes begin. diff --git a/docs/ru/config/transports/sockopt.md b/docs/ru/config/transports/sockopt.md index 040c4cd8..fb5bc9d4 100644 --- a/docs/ru/config/transports/sockopt.md +++ b/docs/ru/config/transports/sockopt.md @@ -16,7 +16,7 @@ Sockopt используется для настройки низкоуровн // ... "streamSettings": { "sockopt": { - // [!code focus:18] + // [!code focus:19] "mark": 0, "tcpMaxSeg": 1440, "tcpFastOpen": false, @@ -25,6 +25,7 @@ Sockopt используется для настройки низкоуровн "happyEyeballs": {}, "dialerProxy": "", "acceptProxyProtocol": false, + "trustedXForwardedFor": [], "tcpKeepAliveInterval": 0, "tcpKeepAliveIdle": 300, "tcpUserTimeout": 10000, @@ -149,6 +150,29 @@ Sockopt используется для настройки низкоуровн Если значение равно `true`, после установления TCP-соединения удаленная сторона обязана сразу отправить PROXY protocol v1 или v2, иначе соединение будет закрыто. +> `trustedXForwardedFor`: [ string ] + +Применяется только к трем HTTP-ориентированным inbound: `XHTTP`, `WebSocket` и `HTTPUpgrade`. + +Позволяет ограничить, в каких случаях Xray будет доверять заголовку `X-Forwarded-For` и использовать его для подмены `SourceIP`. + +Если поле не задано, сохраняется старое поведение: если в запросе есть `X-Forwarded-For`, Xray его читает. + +После настройки этого поля каждый элемент массива рассматривается как имя дополнительного заголовка, которое должно присутствовать в запросе. Xray будет доверять `X-Forwarded-For` только если в запросе есть хотя бы один из этих заголовков. Их значения не важны, проверяется только наличие самого ключа. + +::: details Пример и сценарий использования + +```json +"sockopt": { + "trustedXForwardedFor": ["ABCDEF", "XYZ"] +} +``` + +Это означает, что в запросе дополнительно должен присутствовать либо `ABCDEF`, либо `XYZ`, иначе Xray не примет `X-Forwarded-For` из этого же запроса как исходный IP-адрес. + +На практике доверенный HTTP reverse proxy, например CDN или Nginx, может дополнительно подставлять специальный заголовок, известный только серверной стороне. Это помогает защититься от подделки исходного IP клиентом. +::: + > `tcpKeepAliveIdle`: number Порог простоя TCP в секундах. После такого времени бездействия начинают отправляться Keep-Alive пакеты.