XHTTP: Beyond REALITY

https://github.com/XTLS/Xray-core/discussions/4113
2026-10-10 08:18:10 +03:00 · 2024-12-13 10:47:12 +00:00
parent dcc39472dd
commit a6af837cb5
39 changed files with 300 additions and 1243 deletions
@@ -11,7 +11,7 @@
 不过目前的浏览器转发有以下缺点：
 * 用户需要手动开浏览器
 * 浏览器发出的连接必须直连 使用 tun 的用户需要特别注意容易形成死循环
-* 浏览器只能发出 HTTP 连接 所以目前仅支持 [WebSocket](../../transports/websocket.md) 与 [XHTTP](../../transports/splithttp.md) 传输方式
+* 浏览器只能发出 HTTP 连接 所以目前仅支持 [WebSocket](../../transports/websocket.md) 与 [XHTTP](https://github.com/XTLS/Xray-core/discussions/4113) 传输方式
 * 当浏览器从 `localhost:8080` 页面连接至代理服务端，需要考虑 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
 * 因为中间经过 JS 处理数据，会有一些性能损耗
 * 不能使用自定义 SNI 或者 Host，也就是说 `SNI == host == address`。自定义 HTTP 头以及其它 `tlsSettings` 项会被忽略
@@ -44,6 +44,6 @@

 <Badge text="v1.8.19+" type="warning"/>

-XHTTP 本身支持 QUIC，如果想使用浏览器自己的 QUIC 网络栈，Chrome 可以在 `chrome://flags` 中设定。其它浏览器也有相关选项。
+[XHTTP](https://github.com/XTLS/Xray-core/discussions/4113) 本身支持 QUIC，如果想使用浏览器自己的 QUIC 网络栈，Chrome 可以在 `chrome://flags` 中设定。其它浏览器也有相关选项。

 原理上说 `tlsSettings` 项会被忽略，使用哪个 HTTP 版本将完全由浏览器决定。
@@ -10,17 +10,16 @@

 ```json
 {
-  "network": "tcp",
+  "network": "raw",
  "security": "none",
  "tlsSettings": {},
  "realitySettings": {},
-  "tcpSettings": {},
-  "kcpSettings": {},
-  "wsSettings": {},
-  "httpSettings": {},
-  "grpcSettings": {},
-  "httpupgradeSettings": {},
+  "rawSettings": {},
  "xhttpSettings": {},
+  "kcpSettings": {},
+  "grpcSettings": {},
+  "wsSettings": {},
+  "httpupgradeSettings": {},
  "sockopt": {
    "mark": 0,
    "tcpMaxSeg": 1440,
@@ -42,16 +41,12 @@
 }
 ```

-> `network`: "raw" | "ws" | "h2" | "grpc" | "kcp" | "httpupgrade" | "xhttp"
+> `network`: "raw" | "xhttp" | "kcp" | "grpc" | "ws" | "httpupgrade"

-连接的数据流所使用的传输方式类型，默认值为 `"raw"`
+连接的数据流所使用的传输方式类型，默认值为 `"raw"`。

 ::: tip
-v24.9.30 版本后，为了更贴近实际行为，tcp传输方式已更名为raw, 为了兼容性，`"network": "raw"` 和 "network": "tcp", `rawSettings`和`tcpSettings` 互为别名
-:::
-
-::: tip
-"h2" 可以写成 "http"，"grpc" 可以写成 "gun"，"kcp" 可以写成 "mkcp"。
+v24.9.30 版本后，为了更贴近实际行为，TCP 传输方式已更名为 RAW。为了兼容性，`"network": "raw"` 和 `"network": "tcp"`，`rawSettings` 和 `tcpSettings` 互为别名。
 :::

 > `security`: "none" | "tls" | "reality"
@@ -75,34 +70,30 @@ Reality 是目前最安全的传输加密方案, 且外部看来流量类型和
 达到数倍甚至十几倍的性能提升。
 :::

-> `rawSettings`: [TcpObject](./transports/raw.md)
+> `rawSettings`: [RawObject](./transports/raw.md)

-当前连接的 raw 配置，仅当此连接使用 raw 时有效。
+当前连接的 RAW 配置，仅当此连接使用 RAW 时有效。
+
+> `xhttpSettings`: [XHTTP: Beyond REALITY](https://github.com/XTLS/Xray-core/discussions/4113)
+
+当前连接的 XHTTP 配置，仅当此连接使用 XHTTP 时有效。

 > `kcpSettings`: [KcpObject](./transports/mkcp.md)

 当前连接的 mKCP 配置，仅当此连接使用 mKCP 时有效。

+> `grpcSettings`: [GRPCObject](./transports/grpc.md)
+
+当前连接的 gRPC 配置，仅当此连接使用 gRPC 时有效。
+
 > `wsSettings`: [WebSocketObject](./transports/websocket.md)

 当前连接的 WebSocket 配置，仅当此连接使用 WebSocket 时有效。

-> `httpSettings`: [HttpObject](./transports/http.md)
-
-当前连接的 HTTP 配置，仅当此连接使用 HTTP 时有效。
-
-> `grpcSettings`: [GRPCObject](./transports/grpc.md)
-
-当前连接的 gRPC 配置，仅当此连接使用 gRPC 时有效。。
-
 > `httpupgradeSettings`: [HttpUpgradeObject](./transports/httpupgrade.md)

 当前连接的 HTTPUpgrade 配置，仅当此连接使用 HTTPUpgrade 时有效。

-> `xhttpSettings`: [XHttpObject](./transports/splithttp.md)
-
-当前连接的 XHTTP 配置，仅当此连接使用 XHTTP 时有效。
-
 > `sockopt`: [SockoptObject](#sockoptobject)

 透明代理相关的具体配置。
@@ -5,6 +5,10 @@
 它基于 HTTP/2 协议，理论上可以通过其它支持 HTTP/2 的服务器（如 Nginx）进行中转。
 gRPC（HTTP/2）内置多路复用，不建议使用 gRPC 与 HTTP/2 时启用 mux.cool。

+::: danger
+**推荐换用 [XHTTP](https://github.com/XTLS/Xray-core/discussions/4113)，其相较于 gRPC 的优势已在 STREAM-UP/ONE 小节中注明。**
+:::
+
 ::: warning ⚠⚠⚠

 - gRPC 不支持指定 Host。请在出站代理地址中填写 **正确的域名** ，或在 `(x)tlsSettings` 中填写 `ServerName`，否则无法连接。
@@ -0,0 +1,3 @@
+# HTTP/2
+
+See [XHTTP: Beyond REALITY](https://github.com/XTLS/Xray-core/discussions/4113)
@@ -1,87 +1,3 @@
 # HTTP

-基于 HTTP/2 或 HTTP/3 的传输方式。
-
-它完整按照 HTTP 标准实现，可以通过其它的 HTTP 服务器（如 Nginx）进行中转。
-
-客户端必须开启 TLS 才可以正常使用这个传输方式。
-
-HTTP/2和3 内置多路复用，不建议使用时启用 mux.cool。
-
-::: tip
-当前版本的 HTTP/2 的传输方式并不强制要求**入站**（**服务端**）有 TLS 配置.
-这使得可以在特殊用途的分流部署环境中，由外部网关组件完成 TLS 层对话，Xray 作为后端应用，网关和 Xray 间使用明文HTTP进行通讯。
-:::
-
-::: tip
-当alpn有且仅有 `h3` 时，该传输才会工作在h3模式。
-:::
-
-::: warning
- HTTP/2 和 HTTP/3 无法通过xray的回落 Path 进行分流，不建议使用回落分流。
-  :::
-
-## HttpObject
-
-`HttpObject` 对应传输配置的 `httpSettings` 项。
-
-```json
-{
-  "host": ["xray.com"],
-  "path": "/random/path",
-  "read_idle_timeout": 10,
-  "health_check_timeout": 15,
-  "method": "PUT",
-  "headers": {
-    "Header": ["value"]
-  }
-}
-```
-
-> `host`: \[string\]
-
-一个字符串数组，每一个元素是一个域名。
-
-客户端会随机从列表中选出一个域名进行通信，服务器会验证域名是否在列表中。
-
-::: tip
-若不写 `"httpSettings"` 或 `"host": []` 值留空时，会使用默认值 `"www.example.com"`，需要两端 `"host"` 值一致才能连接成功。`"host": [""]` 不是值留空。
-:::
-
-> `path`: string
-
-HTTP 路径，由 `/` 开头, 客户端和服务器必须一致。
-
-默认值为 `"/"`。
-
-> `read_idle_timeout`: number
-
-单位秒，当这段时间内没有接收到数据时，将会进行健康检查。
-
-健康检查默认**不启用**。
-
-::: tip
-**只需**在**出站**（**客户端**）配置。
-:::
-
-::: tip
-可能会解决一些“断流”问题。
-:::
-
-> `health_check_timeout`: number
-
-单位秒，健康检查的超时时间。如果在这段时间内没有完成健康检查，即认为健康检查失败。默认值为 `15`。
-
-::: tip
-**只需**在**出站**（**客户端**）配置。
-:::
-
-> `method`: string
-
-HTTP 方法。默认值为 `"PUT"`。
-
-设置时应参照[此处](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)列出值。
-
-> `headers`: map{ string: \[string\] }
-
-仅客户端，自定义 HTTP 头，一个键值对，每个键表示一个 HTTP 头名称，对应值为一个数组。
+See [XHTTP: Beyond REALITY](https://github.com/XTLS/Xray-core/discussions/4113)
@@ -3,6 +3,10 @@
 一个实现了类似于 WebSocket 进行 HTTP 1.1 升级请求和响应的协议，这使得它可以像 WebSocket 一样可以被CDN或者Nginx进行反代，但无需实现 WebSocket 协议的其他部分，所以具有更高的效率。
 其设计不推荐单独使用，而是和TLS等安全协议一起工作。

+::: danger
+**推荐换用 [XHTTP](https://github.com/XTLS/Xray-core/discussions/4113)，以避免 HTTPUpgrade “ALPN 是 http/1.1” 等显著流量特征。**
+:::
+
 ## HttpUpgradeObject

 `HttpUpgradeObject` 对应传输配置的 `httpupgradeSettings` 项。
@@ -0,0 +1,3 @@
+# QUIC
+
+See [XHTTP: Beyond REALITY](https://github.com/XTLS/Xray-core/discussions/4113)
@@ -1,8 +1,8 @@
 # RAW

-更名自曾经的tcp传输(原名称稍有歧义) RAW传输出站发送的原始数据，核心不使用其他协议(如 websocket)承载其流量。
+更名自曾经的 TCP 传输层（原名称有歧义），出站 RAW 传输层直接发送经代理协议包装后产生的 TCP、UDP 数据，核心不使用其它传输层（如 [XHTTP](https://github.com/XTLS/Xray-core/discussions/4113)）承载其流量。

-可以和各种协议有多种组合模式.
+可以和各种协议有多种组合模式。

 ## RawObject

@@ -1,265 +1,3 @@
-# XHTTP (SplitHTTP)
+# SplitHTTP

-<Badge text="v1.8.16+" type="warning"/>
-
-使用HTTP分块传输编码流式响应处理下载，使用多个 HTTP POST 请求（或者流式）进行上传。
-
-可以通过不支持WebSocket的CDN上，但仍有一些要求：
-
- CDN必须支持HTTP分块传输，且支持流式响应而不会缓冲，核心将会发送各种信息以告知CDN，但是需要CDN遵守。如果中间盒不支持流式响应而导致连接被挂起，则该传输很可能无法工作。
-
-目的与V2fly Meek相同，由于使用了流式响应处理下载，下行速率更为优秀，上行也经过优化但仍非常有限，也因此对 HTTP 中间盒要求更高（见上）。
-
-`XHTTP` 也接受 `X-Forwarded-For` header。
-
-## XHttpObject
-
-The `XHttpObject` 对应传输配置的 `xhttpSettings` 项。
-
-```json
-{
-  "mode": "auto",
-  "path": "/",
-  "host": "xray.com",
-  "headers": {
-    "key": "value"
-  },
-  "scMaxEachPostBytes": 1000000,
-  "scMaxConcurrentPosts": 100,
-  "scMinPostsIntervalMs": 30,
-  "noSSEHeader": false,
-  "xPaddingBytes": "100-1000",
-  "keepAlivePeriod": 45,
-  "xmux": {
-    "maxConcurrency": 0,
-    "maxConnections": 0,
-    "cMaxReuseTimes": 0,
-    "cMaxLifetimeMs": 0
-  },
-  "downloadSettings": {
-    "address": "example.com",
-    "port": 443,
-    "network": "xhttp",
-    "security": "none",
-    "tlsSettings": {},
-    "realitySettings": {},
-    "xhttpSettings": {
-      "path": "/" // must be the same
-    },
-    "sockopt": {
-      "dialerProxy": "" // just for example
-    }
-  },
-  "extra": {}
-}
-```
-
-> `mode`: string
-
-XHTTP 上行所使用的模式。默认值为 `"auto"`，客户端与 REALITY 搭配时采用流式上行，否则采用分包上行。服务端同时兼容两种模式。
-
-`"packet-up"`：两端使用分包上行。即将数据包包装为单个 HTTP POST 请求，在服务端重组。可以兼容任意 HTTP 中间盒。
-
-`"stream-up"`：两端使用流式上行。开启一个 HTTP 长连接发送上行数据包，与现有的 H2 / H3 / gRPC 类似。速度快但兼容性低。
-
-> `path`: string
-
-XHTTP 所使用的 HTTP 协议路径，默认值为 `"/"`。
-
-> `host`: string
-
-XHTTP 的HTTP请求中所发送的host，默认值为空。若服务端值为空时，不验证客户端发送来的host值。
-
-当在服务端指定该值，或在 ```headers``` 中指定host，将会校验与客户端请求host是否一致。
-
-客户端选择发送的host优先级 ```host``` >  ```headers``` > ```address```
-
-> `headers`: map \{string: string\}
-
-仅客户端，自定义 HTTP 头，一个键值对，每个键表示一个 HTTP 头的名称，对应的值是字符串。
-
-> `scMaxEachPostBytes`: int | string
-
-上传分块的最大大小，单位为字节，默认值为 1000000, 即 1MB.
-
-客户端设置的大小必须低于该值，否则当发送的 POST 请求大于服务端设置的值时，请求会被拒绝。
-
-这个值应该小于CDN或其他HTTP反向代理所允许的最大请求体，否则将抛出 HTTP 413 错误。
-
-也可以是字符串 "500000-1000000" 的形式，核心每次会在范围内随机选择一个值，以减少指纹。
-
-> `scMaxConcurrentPosts`: int | string
-
-单个连接上传post的最大并发数，默认为100.
-
-上传并发同时也受(也主要受) `scMinPostsIntervalMs` 控制，故该值仅做保险。
-
-客户端实际发起的数量必须低于服务端。(实际情况下由于上述很难达到上限，所以事实上客户端设置的值可以超过服务端，但不建议这么做)
-
-也可以是字符串 "50-100" 的形式，核心每次会在范围内随机选择一个值，以减少指纹。
-
-> `scMinPostsIntervalMs`: int | string
-
-仅客户端，发起POST上传请求的最小间隔。默认值为 30.
-
-也可以是字符串 "10-50" 的形式，核心每次会在范围内随机选择一个值，以减少指纹。
-
-> `noSSEHeader`: bool
-
-仅服务端，不发送 `Content-Type: text/event-stream` 响应头，默认 `false` (即会发送)
-
-> `xPaddingBytes` int | string
-
-设置请求（出站）和响应（入站）的填充大小，用于减少请求指纹。单位byte, 默认为 `"100-1000"` 每次会在该范围中随机选择一个数字。为 [Int32Range](../../development/intro/guide.md#int32range) 类型
-
-设置为 `-1` 将完全禁用填充
-
-> `keepAlivePeriod` int
-
-发送保活请求的时间间隔，单位秒，设置为 `-1` 代表禁用该功能。
-
-当使用 H2 和 H3 时分别对应 h2 ping 帧和 QUIC ping 帧。
-
-默认值为：使用 H2 时 45 秒(Chrome 默认值), 使用 H3 时 10 秒(quic-go 默认值)
-
-> `xmux`: [XmuxObject](#xmuxobject)
-
-## XmuxObject
-
-<Badge text="v24.9.19+" type="warning"/>
-
-仅客户端，允许用户对 XHTTP 在 h2 与 h3 中的多路复用行为进行控制。使用该功能时不要启用 mux.cool。
-
-```json
-{
-  "maxConcurrency": "16-32",
-  "maxConnections": 0,
-  "cMaxReuseTimes": "64-128",
-  "cMaxLifetimeMs": 0
-}
-```
-
-上为全设置为0或者不设置时核心会填入的默认值
-
-术语解释：
- 流会复用物理连接，像这样 连接1(流1,流2,流3) 连接2(流4,流5,流6) .. 以此类推 在其他地方你可能看到 连接-子连接 这样的描述，都是一样的东西。
- 下述所有字段类型均为 为 [Int32Range](../../development/intro/guide.md#int32range) 类型
-
-> `maxConcurrency`: int/string
-
-默认值为 0(即无限) 每个连接中复用的流的最大数量，连接中流的数量达到该值后核心会新建更多连接以容纳更多的流，类似于 mux.cool 的 concurrency.
-
-> `maxConnections`: int/string
-
-默认值为 0(即无限) 要打开的最大连接数，连接达到此值前核心会积极打开连接，对每一条流都新建一个连接，直到达到该值。然后核心会开始复用已经建立的连接。 与 `maxConcurrency` 冲突。
-
-> `cMaxReuseTimes`: int/string
-
-默认值为 0(即无限) 一个连接最多被复用几次，当达到该值后核心不会向该连接再分配流，其将在内部最后一条流关闭后断开。
-
-> `cMaxLifetimeMs`: int/string
-
-默认值为 0(即无限) 一个连接最多可以“存活”多久，当连接打开的时间超过该值后核心不会向该连接再分配流，其将在内部最后一条流关闭后断开。
-
-## downloadSettings
-
-用于拆分 XHTTP 下行所使用的连接（可选项，注意拆分的流量必须抵达服务端的同一个入站）
-
-`downloadSettings` 里面是嵌套的 [StreamSettingsObject](../transport.md#streamsettingsobject) ，可以使用 TLS 或者 REALITY 或者 `sockopt` 等各种选项。除此以外独有以下两个选项：
-
-> `address`: address
-
-下行服务端地址，支持域名、IPv4、IPv6。
-
-> `port`: number
-
-下行服务端端口。
-
-## extra
-
-```json
-{
-  "extra": {
-    "headers": {
-      "key": "value"
-    },
-    "scMaxEachPostBytes": 1000000,
-    "scMaxConcurrentPosts": 100,
-    "scMinPostsIntervalMs": 30,
-    "noSSEHeader": false,
-    "xPaddingBytes": "100-1000",
-    "xmux": {
-      "maxConcurrency": 0,
-      "maxConnections": 0,
-      "cMaxReuseTimes": 0,
-      "cMaxLifetimeMs": 0
-    },
-    "downloadSettings": {
-      "address": "example.com",
-      "port": 443,
-      "network": "xhttp",
-      "security": "none",
-      "tlsSettings": {},
-      "realitySettings": {},
-      "xhttpSettings": {
-        "path": "/" // must be the same
-      }
-    }
-  }
-}
-```
-
-`extra` 是嵌套的 `XHttpObject`，用来实现分享原始 Json。`extra` 里面的配置会覆盖外面的配置。
-
-目前以下选项在 `extra` 里面**不生效**:
-
-`host` `path` `mode` `downloadSettings->sockopt` `extra`
-
-## HTTP 版本
-
-### 客户端行为
-
-默认情况下，客户端将会默认在未启用 TLS 时使用 http/1.1, 启用 TLS 时，使用 h2.
-
-当启用 TLS 时，允许在 TLS 设置的 alpn 数组内设置 http/1.1 h2 h3 来指定具体的http版本(仅当该数组只有一个元素时生效，若填入多个元素则返回默认行为)
-
-### 服务端行为
-
-默认情况下，服务端将会默认监听 TCP, 此时可以处理 http/1.1 和 h2 流量。
-
-当启用 TLS 时，允许在 TLS 设置的 alpn 数组内设置 h3, 此时服务端将改为监听 UDP 端口, 处理 h3 流量。
-
-### 小提示
-
-由于该协议为标准的 HTTP 请求，所以对于 HTTP 版本的转换并不敏感，各种中间盒都可能转换 HTTP 版本。
-
-列如：你希望使用 h3 连接 Cloudflare, 但是Cloudflare 不会使用 h3 回源, 而是使用 http/1.1 或 h2 回源，此时客户端 alpn 应为 h3, 而服务端就不应为 h3, 因为发往服务端的请求不是 h3.
-
-## Browser Dialer
-
-如果使用HTTPS，该传输还支持 [Browser Dialer](../features/browser_dialer.md)
-
-## 协议细节
-
-讨论详见 [#3412](https://github.com/XTLS/Xray-core/pull/3412) 和 [#3462](https://github.com/XTLS/Xray-core/pull/3462) 以下是简述和简要兼容实现要求
-
-1. 使用 `GET /<UUID>` 开始下载。服务器立即回复 `200 OK` 和 `Transfer Encoding:chunked` , 并立即发送一个两字节的有效负载，以强制HTTP中间盒刷新标头。
-
-现阶段服务器会发送以下标头
-
-* `X-Accel-Buffering: no` 禁用缓冲
-* `Content-Type: text/event-stream` 在部分中间盒中禁用缓冲，可以使用 `"noSSEHeader"` 选项关闭
-* `Transfer-Encoding: chunked` 分块传输，仅在 HTTP/1.1 中使用
-* `Cache-Control: no-store` to disable any potential response caching. 禁用CDN的缓存
-
-2. 使用 `POST /<UUID>/<seq>` 开始发送上行数据. `seq` 作用类似于 TCP 序列号，从0开始，数据包可以被同时发送，服务端必须按序列号将数据重组。序列号不应重置。
-
-   客户端可以以任意决定打开上行与下行请求的顺序，任何一种都可以启动会话，但是必须要在30秒内打开 `GET` 连接，否则会话将被终止。
-
-3. `GET` 请求将一直保持在打开状态直到连接被终止，服务端和客户端都可以关闭连接。具体行为取决于HTTP版本。
-
-建议:
-
-* 不要期望CDN会正确传输所有标头，这个协议的目的是为了穿透不支持WS的CDN，而这些CDN的行为通常不怎么友好。
-
-* 应当假设所有HTTP连接都不支持流式请求，所以上行连接发送的的每个包的大小应该基于延迟、吞吐量以及中间盒本身的限制考虑(类似TCP的MTU与纳格算法)。
+See [XHTTP: Beyond REALITY](https://github.com/XTLS/Xray-core/discussions/4113)
@@ -1,3 +1,3 @@
 # TCP

-v24.9.30 版本后，为了更贴近实际行为，tcp传输方式已更名为[raw](./raw.md), 为了兼容性，`"network": "raw"` 和 "network": "tcp", `rawSettings`和`tcpSettings` 互为别名
+See [RAW](./raw.md)
@@ -4,6 +4,10 @@

 WebSocket 连接可以被其它 HTTP 服务器（如 Nginx）分流，也可以被 VLESS fallbacks path 分流。

+::: danger
+**推荐换用 [XHTTP](https://github.com/XTLS/Xray-core/discussions/4113)，以避免 WebSocket “ALPN 是 http/1.1” 等显著流量特征。**
+:::
+
 ::: tip
 Websocket 会识别 HTTP 请求的 X-Forwarded-For 头来覆写流量的源地址，优先级高于 PROXY protocol。
 :::
@@ -0,0 +1,3 @@
+# XHTTP: Beyond REALITY
+
+See [XHTTP: Beyond REALITY](https://github.com/XTLS/Xray-core/discussions/4113)