协议配置 · 使用指南

传输层配置中哪些字段要随 WebSocket 或 gRPC 切换

VMess、VLESS、Trojan 接受的承载方式各有范围。先让 network 与选项对象匹配,再核对 TLS、路由与高级参数。

  • network
  • 同时检查 WebSocket 的路径与头部
  • HTTP/2
  • 先匹配 gRPC 服务名
  • TLS
查看分节

先选 network 再填写对应选项

传输方式是出站配置的一部分,不能单独充当代理协议。先配齐 VMess、VLESS 或 Trojan 所需内容,再由 network 指定承载形式。

读取 *-opts 的前提是 network 与它同名。选择 WebSocket、gRPC 或 XHTTP 并不会自动开启 TLS、Reality、UDP 或认证;这些内容仍需在顶层配置。XHTTP 可通过 download-settings 为下行另设 TLS 与 Reality。

network选择器
负责指定承载方式;未填写或给出该协议不接受的值,内核会回落为 TCP。
*-opts满足条件后有效
network 必须匹配对象名称;例如 ws-opts 仅在 network: ws 时被读取。
tls / reality-opts需独立配置
这组设置负责传输安全,应与对端配套;XHTTP 的 download-settings 可为下行另设覆盖值。
udp / packet-encodingVMess / VLESS
这是 VMess、VLESS 的 UDP 能力与包编码选项,不属于 Trojan 的传输字段,也不会随 network 自动启用。

按协议核对承载类型

先确认协议接受哪些 network,再参照表内取值填写,不能跨协议照抄。

VMess、VLESS 与 Trojan 的传输层支持
代理类型接受的 network 值未匹配时的处理
VMesstcp, ws, http, h2, grpc, mkcp, mekya未填或不匹配时采用 tcp
VLESStcp, ws, http, h2, grpc, xhttp未填或不匹配时采用 tcp
Trojantcp, ws, grpc未填或不匹配时采用 tcp

HTTP 与 H2 分别使用各自选项

http 与 h2 要分别填写对应的 opts。两者都要求路径、Host 与对端路由匹配,但并非同一种 network。

http-opts.methodHTTP
按对端接受的方式指定 HTTP 方法。
http-opts.pathHTTP
提供与远端路由相匹配的 HTTP 路径列表。
http-opts.headersHTTP
按反向代理规则填写 Host、Connection 等附加头部。
h2-opts.hostHTTP/2
提供主机名列表;有多个候选时随机选取,远端仍会验证所选名称。
h2-opts.pathHTTP/2
填写远端接受的 HTTP/2 请求路径。

先匹配 gRPC 服务名

启用 gRPC 需要同时提供 network: grpc 与 grpc-opts。应先确认服务名一致,再按对端能力及并发需求考虑连接数、流数量设置。

grpc-opts.grpc-service-name与对端配套
填写与远端完全匹配的 gRPC 服务名。
grpc-opts.grpc-user-agent需要时设置
用于改写 gRPC User-Agent,没有特别需求可省略。
grpc-opts.ping-interval需要时设置
以秒为单位设置心跳周期,未启用时不发送此类心跳。
grpc-opts.max-connections需要时设置
底层连接数量上限默认为 1,不能与 max-streams 并用。
grpc-opts.min-streams需要时设置
达到此复用流下限后才考虑新建连接,与 max-streams 互斥。
grpc-opts.max-streams需要时设置
控制新建连接前允许的复用流上限,不能与 max-connections、min-streams 同用。

同时检查 WebSocket 的路径与头部

采用 WebSocket 时填写 network: ws 及 ws-opts。经过 CDN 或反向代理时,还应确保它们接受该路径和 Host。

ws-opts.path与对端配套
请求路径应能匹配远端服务或反向代理的路由。
ws-opts.headers需要时设置
提供额外头部,例如 Host;它与 TLS 的 servername 各有作用。
ws-opts.max-early-data需要时设置
设置 Early Data 的首包长度边界,远端没有支持时不要开启。
ws-opts.early-data-header-name需要时设置
指定用于传递 Early Data 的头部名称,需与对端约定一致。
ws-opts.v2ray-http-upgrade需要时设置
启用 HTTP Upgrade 承载的前提是对端实现也支持此方式。
ws-opts.v2ray-http-upgrade-fast-open需要时设置
需要前一项及对端配合,才能为 HTTP Upgrade 打开 Fast Open。

VMess 专属的 mKCP 与 Mekya

mKCP、Mekya 只能用于 VMess。换成 VLESS 或 Trojan 后,应重新核对承载选项,不能继续保留这些配置。

mkcp-opts.mtumKCP
根据链路 MTU 设置最大传输单元。
mkcp-opts.ttimKCP
用毫秒表示发送之间的时间间隔。
mkcp-opts.uplink-capacitymKCP
以 MB/s 表达向外发送的容量。
mkcp-opts.downlink-capacitymKCP
以 MB/s 表达接收方向的容量。
mkcp-opts.congestionmKCP
用此开关决定是否进行拥塞控制。
mkcp-opts.seedmKCP
AES-GCM 认证使用该种子;没有指定则采用默认认证行为。
mkcp-opts.headermKCP
可选的包头外观包括 none、srtp、utp、wechat-video、dtls、wireguard。
mekya-opts.urlMekya
填写远端实际提供的 Mekya 接入 URL。
mekya-opts.max-write-delayMekya
首包发送后允许聚合等待的最长时间,以毫秒填写。
mekya-opts.max-request-sizeMekya
限制每个 HTTP 请求可携带的负载字节数。
mekya-opts.polling-interval-initialMekya
设定空轮询开始时的等待时间,计量单位是毫秒。
mekya-opts.h2-pool-sizeMekya
限制 HTTP/2 连接池的规模。
mekya-opts.kcpMekya
此对象设置 Mekya 内部 KCP,含义可参照 mkcp-opts。

逐步配置 VLESS 的 XHTTP

VLESS 的 XHTTP 默认采用 H2。选择 H3 必须提供 tls: true 及 alpn: [h3],且不能使用 Reality、ShadowTLS、Restls、JLS。若要采用 HTTP/1.1,则填 alpn: [http/1.1]。

顶层仍需填写 UUID、VLESS Encryption。TLS 与 Reality 可放在顶层,而 xhttp-opts.download-settings 能单独覆盖下行的 TLS、Reality、ECH、SNI 等值。

先确认服务端和反向代理的基础路由,再配置 path、host 与默认模式。拆分、填充、会话及复用属于高级行为,没有配套要求时不宜全部启用。

xhttp-opts.path与对端配套
选择能与对端或反向代理路由匹配的请求路径。
xhttp-opts.host与对端配套
此项填写 HTTP Host,TLS 名称使用另一个字段 servername。
xhttp-opts.mode需要时设置
模式可选择 auto、stream-one、stream-up、packet-up。
xhttp-opts.headers需要时设置
需要额外的 HTTP 头部时在此配置。
xhttp-opts.no-grpc-header需要时设置
决定 stream-up、stream-one 上传时是否省略用于 gRPC 外观的 Content-Type。
xhttp-opts.x-padding-bytes需要时设置
指定请求头的填充长度区间,未改动时为 100-1000。
xhttp-opts.x-padding-obfs-mode需要时设置
以 false 作为兼容性的初始设置,需要填充混淆时再启用。
xhttp-opts.uplink-http-method需要时设置
POST、PUT、PATCH、DELETE 等带请求体的方法,需被远端及中间网络接受后才能用于上传。
xhttp-opts.session-placement需要时设置
会话标识支持置于 path、query、cookie、header。
xhttp-opts.seq-placement需要时设置
序列号应遵守会话位置的配套规则;会话位于 path 时,序列号也要放在 path。
xhttp-opts.uplink-data-placementpacket-up
packet-up 模式下,用它指定拆分后的上传数据放置位置。
xhttp-opts.uplink-chunk-size满足条件后有效
当上传数据不在 body 中时,限制每块的字节上限;该值不能低于 64 字节。
xhttp-opts.reuse-settings需要时设置
控制 XHTTP 的连接复用;没有预设值,省略整组便不启用。
xhttp-opts.reuse-settings.max-concurrency择一设置
限制每条底层连接的并发请求上限,不能同时设置 max-connections。
xhttp-opts.reuse-settings.max-connections择一设置
限制同时建立的连接数量,不能与 max-concurrency 并用。
xhttp-opts.download-settings需要时设置
下行可另设 TLS、Reality、ECH、SNI、ALPN 及客户端指纹;未覆盖的字段继续取上行值。
  • VMess、Trojan 不接受 xhttp,需改用各自支持的承载方式。
  • XHTTP 的 reuse-settings 与通用 smux 应择一配置,避免重复叠加复用。
  • 先让路径、Host、ALPN 和模式匹配对端,再排查高级选项。
  • uplink-http-method: GET 未列在此处接受的上传方法内,不应直接套用。
YAML
proxies:
  - name: vless-xhttp-h2
    type: vless
    server: edge.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000001
    encryption: ""
    udp: true
    tls: true
    servername: origin.example.com
    alpn:
      - h2
    client-fingerprint: chrome
    network: xhttp
    xhttp-opts:
      path: /xhttp
      host: origin.example.com
      mode: auto