代理协议 · 配置文档

VMess 的用户标识、兼容模式与连接加密怎样对应

从基础身份信息开始,逐层核对 VMess 的兼容模式、加密、承载方式和安全连接,遇到错误再定位具体差异。

  • uuid
  • alterId
  • cipher
  • TLS
  • WebSocket
章节索引

建立 VMess 出站的起点

在 proxies 中声明 VMess 后,需按远端配置分别检查身份凭据、承载方式与 TLS;某一项相符,并不代表整条连接已经匹配。

先填通用连接信息与协议必需项,再决定是否补充 UDP、TLS 及其他承载选项;这些能力取决于远端的部署。

name必填
为这项出站指定不重复的引用名。
type必填
此处类型值应为 vmess。
server必填
使用远端 VMess 主机的域名或者 IP。
port必填
目标端口应取远端实际监听值。

凭据、兼容模式与加密

这里列出的 uuid、alterId 和 cipher 均需提供;各自承担不同作用,填了其中某项也不能省略其他项。

uuid必填
按远端分配结果填写该用户的 ID。
alterId必填
旧兼容模式由此值区分;0 用于所列新式配置,只有远端仍明确要求时才使用非零值。
cipher必填
此项接受 auto、none、zero、aes-128-gcm 及 chacha20-poly1305,使用时需与远端对应。
global-padding可选
全局填充会带来额外流量,应确认远端要求与兼容性后再启用。
authenticated-length可选
长度块是否加密由此项控制,通信双方必须具备相应能力。

先放行 UDP 再选封装

UDP 能否通过,以及数据包如何包装,是彼此独立的设置;仅改其中一项不足以确定可用性。

udp可选
初始状态是 false;需要使用 UDP 时置为 true,并核对远端能力。
packet-encoding可选
默认沿用原始封装;另可显式选择 packetaddr 或 xudp,但要获得远端支持。

让承载方式对齐远端

network 用来指定连接承载。留空或填入无法识别的名称都会走 TCP,因此错误未必出现在配置加载时,也可能表现为后续连接等待超时。

承载名称与附加设置
network关联参数用途提示
tcp不另设专用 opts未指定时采用 TCP
wsws-opts指定 WebSocket 的 Early Data、Host 与路径
httphttp-opts指定 HTTP 路径、请求头及方法
h2h2-opts指定 HTTP/2 的路径和 Host
grpcgrpc-opts指定 gRPC 连接参数及服务名称
mkcpmkcp-opts对应 VMess 的 mKCP 承载
mekyamekya-opts对应 VMess 的 Mekya 承载

把连接安全单独核对

加入 TLS 或 Reality 后,uuid、alterId 与 cipher 仍各自承担原有职责。连接安全层应依据远端实际方案选填。

tls可选
true 表示启用 TLS;远端未提供该能力时,不应自行打开。
servername可选
这是握手所用的 SNI;默认取 server,存在 WebSocket Host 请求头时则优先采用该 Host。
alpn可选
协商列表中的协议及其排列,应同远端承载设置对应。
client-fingerprint可选
这是 uTLS 客户端握手特征,chrome 为可用示例,含义不同于证书摘要。
fingerprint可选
此处要求服务端证书的 SHA-256 摘要;client-fingerprint 所描述的并非同一对象。
reality-opts可选
对象非空即选择 Reality,需检查 public-key 与 short-id,再配合 tls: true 及 servername 设置。
skip-cert-verify谨慎
取消证书检查会削弱身份确认,排查连接问题后应修正原因并恢复验证。

从 WebSocket 示例看字段层级

示例按 VMess、WebSocket、TLS 展示配置关系;使用前应将 UUID、证书名称、主机和路径替换成远端提供的信息。

YAML
proxies:
  - name: vmess-ws-tls
    type: vmess
    server: edge.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000001
    alterId: 0
    cipher: auto
    udp: true
    packet-encoding: xudp
    tls: true
    servername: origin.example.com
    network: ws
    ws-opts:
      path: /vmess
      headers:
        Host: origin.example.com

依次找出参数差异

无法建立连接时,先和远端逐项比对;每次只调整明确不一致的设置。

  • network 若误填 xhttp 等未支持项,连接会回到 TCP,因而无法对应远端承载方式。
  • 对照远端是否要求 alterId: 0,避免继续沿用旧配置里的兼容模式值。
  • 使用 WebSocket 反向代理时,检查 path 与 Host 是否落在对应路由。
  • TLS 场景要检查 servername 所用名称,避免直接填 IP 后与证书或 Reality 目标不符。