Vole/docs/vless.md

VLESS 出站

outbound-vless 使用共享 Dialer、上游图及 TLS/REALITY/JLS，不创建独立 socket 或系统 DNS。 本文定义选定能力集，不承诺上游所有扩展；字段与版本以 config.yaml 为准。

配置与传输

type: vless，server、非零 port 和字符串 uuid 必填。UUID 接受标准、紧凑、花括号或 URN 表示；其他字符串按 UUIDv5(nil, 原始 UTF-8) 映射，不 trim，与 VMess 共用转换。udp 默认 false；network 默认 tcp，tls 默认 false。encryption 省略、空或 none 关闭该层；其他值见下文。flow 省略、null 或空串时关闭，也接受 xtls-rprx-vision。其余不接受 null 的字段、未知字段、错型或不匹配的传输选项失败，不隐式迁移配置。

• TCP/WS/gRPC/HTTP 首包伪装/legacy H2 可明文或标准 TLS。TLS 支持 1.2/1.3，TCP 默认不发送 ALPN，WS 默认 [http/1.1]，gRPC/H2 默认 [h2]。有序 ALPN 保留且必须包含传输要求值；标准 TLS 检查协商结果。servername 优先显式值、WS Host 去端口、server；不会改变拨号地址。TLS 关闭时禁止安全选项。
• 标准 TLS 支持 skip-cert-verify、SHA-256 fingerprint、独立 name-cert-verify；沿用共享证书验证器的叶 pin / 非叶信任锚优先级。certificate / private-key 接受配对的内联 PEM 或文件路径，相对路径从数据目录解析，解析或密钥不匹配在网络 IO 前失败。REALITY 不能混用这些标准证书策略。
• client-fingerprint 使用 TLS 指纹的命名模板，适用于 TCP 上的标准 TLS/REALITY（含 Vision 和 XHTTP H1/H2），与证书 pin 独立；none / 空串关闭，H3 拒绝已启用的 profile。
• WS 的 ED 支持默认头、自定义头或路径。path 的 ?ed=N 覆盖显式 ED 配置并删除 ed 参数；实际早数据按当前请求剩余的16KiB头预算限制，不按配置上限预分配。v2ray-http-upgrade 开启升级后裸流；v2ray-http-upgrade-fast-open 必须与前者一起启用，只允许默认 ED 头。fast-open 提前发协议首包但仍等待合法 101，拒绝不返回连接成功。
• gRPC 与 Trojan/VMess 共用配置：省略或空 grpc-service-name 默认 GunService，普通名映射 /name/Tun，/ 开头使用完整路径；省略或空 grpc-user-agent 默认 grpc-go/1.36.0。ping-interval 为带符号秒数，0 不主动 PING，负值明确拒绝；三项池阈值接受带符号整数，负阈值禁用相应分支。空闲连接总是复用；max-connections>0 时按连接上限/min-streams 扩容，否则按 max-streams 复用阈值扩容。三项池阈值省略或字面全零时归一为4/0/0，Mihomo为1/0/0；显式 max-connections=1 或2保留各自策略。正 max-connections 优先于 max-streams。阈值不是硬流数上限。物理连接归节点所有，关闭逻辑流不会杀死兄弟流；复用不重选上游组。
• gRPC 不新增业务流/建链数量额度；每个物理连接一个自有驱动，每个等待调用只保留自身 future、取消与原期限，不派生队列任务。每节点最多保留 4 条空闲连接，多余空闲连接退役且不影响活动流。空闲 PING 等待 ACK 最多 15 秒，节点 Stop 取消并 join 所有驱动。
• gRPC 在原建链期限内等待有效 HTTP/2 SETTINGS 并提交完整 VLESS 请求；提交后可持续上传，等待 HTTP 响应不再消耗建链期限。延迟响应仍须通过原状态、内容类型及协议校验，Stop 取消并唤醒活动读写。
• gRPC authority 使用非空显式 servername，否则使用 server:port；name-cert-verify 只改变证书验证名称。legacy H2 的 host 省略或为空列表时使用 www.example.com，path 省略或为空时使用 /。
• network: xhttp 支持 H1/H2 明文、TLS1.3、REALITY、JLS 或 ShadowTLS v3，H3 仅标准 TLS1.3。请求字段、独立下载腿、池与版本选择见 XHTTP。H3 的物理 UDP 仍由原 Dialer/上游图创建。
• 公共节点 smux 以独立的 h2mux/smux v1/yamux 承载逻辑 TCP/UDP；VLESS 只提供正常 TCP 到约定目标，不拥有第二个 mux 池。它不是 XUDP；only-tcp、调度及关闭边界见 通用 sing-mux。
• Vision 仅允许 network: tcp，要求 TLS 1.3/REALITY 或 Encryption；UDP 仅 XUDP，packet-encoding: none 同样归一为 XUDP。启用 Encryption 后外层 TLS 可省略，存在时仍保持独立认证。配置阶段拒绝 WS/gRPC/HTTP/H2/XHTTP、packetaddr、sing-mux 与 Vision 的组合，包括未启用业务 UDP 但显式选错编码。ECH 和附加安全封装仍拒绝。
• Vision 请求不自动降级；对端用户不支持 Vision 时业务失败。Mihomo 服务端允许为 Vision 用户显式配置空 flow，这属于普通 VLESS 模式，不是错误 flow 的拒绝用例。

REALITY

reality-opts.support-x25519mlkem768 为非 null 布尔值，默认 false。true 允许同次握手 协商真实混合或经典 TLS 密钥交换，可用于主连接和 XHTTP 独立下载连接。 chrome 和未命名 profile 提供混合/X25519 双 share，其余 TLS1.3 模板保留真实经典 share； 不改写模板、重试握手或放宽 REALITY 认证。模板及下载继承约束见 TLS 指纹。

JLS

共享凭据身份认证仍使用完整原生 TLS 1.3，不是 skip 或失败后裸流回退。

配置

• 对象出现即启用，两项必须都是非空字符串，各 1–65,535 个 UTF-8 字节，不 trim。 主连接不接受空对象；未知字段、null、错型、缺项及超限在 IO 前拒绝。
• 必须 tls: true。同一腿不能混用 REALITY、标准证书策略或客户端证书； ECH、其他安全封装、Vision 和 HTTP/3 也不属于此组合。
• servername、有序 ALPN、传输必需 ALPN 与具备 TLS1.3 能力的命名模板 client-fingerprint 沿用共享配置，不增加全局默认或别名。
• download-settings.jls-opts 缺省继承整个身份；非空对象必须完整替换两项， {} 清除，不能按叶继承另一个身份的密码。其他下载字段独立覆盖。
• 切换下载安全模式须显式清除旧身份及冲突证书策略；设置新对象不会自动删除旧对象。 两腿仍必须汇入同一个原生 XHTTP handler 的会话表。

认证与所有权

锁定的自有 boring JLS hook 认证实际 ClientHello/ServerHello，由原生 TLS 完成 transcript、CertificateVerify、Finished 和记录保护。共享凭据替代 WebPKI 身份，但不会跳过握手签名或 Finished。普通 TLS 证书、错误凭据、篡改握手、 TLS 1.2 和 HRR 都不能满足 JLS；失败不发伪装 HTTP 探测、不重发业务、不回退 DIRECT。 模板保留 TLS 1.2 的声明下限，实际成功协商始终必须 TLS 1.3。

每条腿的连接器身份不可变；不启用 TLS 恢复、PSK 或 early data。自有凭据副本 使用清零容器，原生临时材料按握手/失败清理；不宣称擦除所有配置 String 副本。 连接器只包装既有 Dialer/上游交付的受控 IO，不创建 resolver、socket、后台任务 或额外连接池。建链期限、取消、ALPN 检查和同步 Stop 继承现有运行时。

JLS 继续承载 TLS 记录，CloseWrite 沿用共享 TLS 有界关闭；XHTTP 保持整流关闭。 Encryption 位于外层传输内，身份彼此独立，不能由单层成功推断组合验收。

ECH

静态 ECHConfigList 或运行时 HTTPS 记录来源保护内层 ClientHello 名称， 不隐藏 IP、外层名称或流量形态。VMess/Trojan/AnyTLS/Hysteria2 共用此配置和失败契约。

配置

ech-opts:
  enable: true
  # config: "<服务端提供的标准 Base64 ECHConfigList>" # 非空时优先，不查询 DNS
  # query-server-name: query.example # 只覆盖 DNS 查询名；省略时查询 servername

• 仅标准 TLS，内层 servername 必须是 DNS 名，实际只协商 TLS 1.3。 同腿不能与 REALITY、JLS 或 Vision 混用；可与 VLESS Encryption、证书策略、 mTLS 和既有传输组合。命名指纹仍只用于 TCP TLS，H3 仍拒绝命名指纹。
• enable 默认 false，关闭时忽略 config/query-server-name。启用且 config 为空或省略时， 每条新物理 TLS/QUIC 连接通过节点 DNS 角色查询 HTTPS (65)，消费第一个含二进制 ECH key 5 参数的有效记录；沿用有界 wire cache 和 singleflight。静态 config 优先。
• query-server-name 只覆盖查询名，不改实际拨号目标、SNI、证书验证名、ALPN 或端口。 不查询 SVCB (64) 后备，不按服务优先级重排，不自行跟随 AliasMode。 DNS 启用时使用 proxy-server-nameserver 角色；关闭 DNS 和 node-only measureDelay 时 使用原 Dialer 的物理 system DNS 元数据。平台来源不可用则失败，无额外公共 DNS 后备。
• config 是标准带填充 Base64，不是 URL、文件路径或 PEM。解码后的完整 ECHConfigList 最多 65,537 字节，仍受整份配置 8 MiB 上限限制。
• ECH 版本为 0xfe0d。按实际 后端算法 选取第一个兼容条目， 保留其原始编码；下载腿切换后端时按完整来源重新选择。未知版本或不兼容条目可跳过， 无兼容条目、畸形长度、非法 public_name 或不支持的必需扩展失败，不能依赖 BoringSSL 静默忽略。
• public_name 要求多标签 LDH 名称；Rustls 的名称类型另限制每标签 63 字节并拒绝纯数值末段， Boring 命名指纹还拒绝十六进制 IP lookalike。这里保留真实后端限制，不能宣称任意 Go DNS 名称均兼容。
• {} / {enable: false} 清除 ECH。null、未知字段、错型均拒绝；诊断不回显配置或查询名。

xhttp-opts.download-settings.ech-opts 缺省继承整个主腿对象；出现时整对象替换， 不逐字段合并，替换密钥须同时写 enable: true。显式 {} 可仅清除下载腿 ECH。 切换到 REALITY/JLS/明文必须显式清除继承的 ECH，以及其他冲突的证书身份。 两腿仍须汇聚到同一原生 XHTTP handler；各自独立建立和认证外层安全连接。

后端与失败边界

无指纹 TCP TLS 与 XHTTP H3 的 Quinn 使用官方 rustls + ring，通过公开 HPKE trait 接入官方 hpke；命名指纹使用锁定的同一 boring ECH 接口。XHTTP H3 保留 rustls 的完整 ECH 算法范围；Boring 命名指纹限定 X25519/HKDF-SHA256，加 AES128/256-GCM 或 ChaCha20-Poly1305。 切换下载腿时按完整静态来源和实际后端重新选择，动态来源也按实际后端解析； 没有兼容配置就失败。动态来源只获取配置，不扩大后端算法范围。

两后端都必须真正接受 ECH 才交出业务连接。rustls QUIC 的 ECH 拒绝作为原生 握手错误传播，XHTTP H3 还检查实际 ALPN，通过前不发送 HTTP 请求。 TCP 同样检查 accepted 状态。 不把 GREASE 当真实 ECH，不自动采用 retry config，不重拨、不回放业务，也不 降级为未加密 ClientHello 的成功连接。静态旧密钥需宿主更新配置；动态新连接随 DNS 缓存有效期取得来源。

ECH 连接禁用 TLS 会话恢复和 0-RTT；XHTTP/gRPC 的已认证物理连接仍可在 原节点内复用。不同节点、主/下载腿、配置替换和后续运行实例不会共享 TLS 票据。 本层只包装调用方提供的 IO；DNS 查询由原建链期限和解析上下文取消拥有， 只弱引用运行时 DNS，不创建独立 resolver、socket、后台刷新任务或全局可变缓存。

正常 ECH 接受后沿用内层证书名称、pin 和 mTLS 策略。拒绝分支不返回业务成功， 也不能发送客户端证书。boring 使用原生 outer-name override，按外层名称和默认 WebPKI 验证拒绝连接，不沿用内层 pin/skip。rustls 的公共 verifier 没有独立的 ECH-rejection 回调：沿用配置的证书策略后仍由原生状态机强制失败；不获取或使用 retry config。该拒绝证书路径不宣称与 Mihomo 完全相同，但不放宽业务成功门槛。

Encryption

mlkem768x25519plus.{native,xorpub,random}.{1rtt,0rtt}.<key>[.<key>…][.<padding>…]。 key 为无填充 URL-safe Base64，解码后 32 字节 X25519 或 1184 字节 ML-KEM-768 公开密钥，可组成有序链；非法 ML-KEM 编码在 IO 前拒绝，X25519 低阶共享密钥 在握手失败关闭。最多 16 个 key、128 个 padding 三元组和 65,536 字节配置串。

padding 采用 Mihomo 的 概率-下界-上界 三元组，交替表示字节长度、毫秒间隔。 首组概率至少 100、两端至少 35；长度上界累计不超过 65,553。 概率按 Mihomo 的包含边界比较，区间上界排除；相等/倒序端点允许。 缺省为 100-111-1111.75-0-111.50-0-3333，等待受原建链期限及取消控制。

所有密钥交换、AEAD 和 CTR 使用既有官方原语，AES-256-GCM / ChaCha20-Poly1305 根据 CPU 选择，不增加用户算法选项。每节点一个恢复票据；1rtt 不复用， 0rtt 在票据有效时恢复，过期改为新握手。错误票据/认证失败不会自动重发业务。 节点缓存互相隔离，旧连接失败不清除新一代票据，Stop 清空缓存且禁止再次插入。

该层位于外层传输内、VLESS 请求头外；WS/HTTPUpgrade/HTTP 的 initial data 是 Encryption 握手字节，不能提前发送明文 VLESS 请求头。XHTTP 主/下载腿汇聚为 一条逻辑流后只执行一次 Encryption。普通 Encryption 关闭与 Mihomo CommonConn 一致，flush 后关闭整条逻辑流，不承诺半关闭尾包；不关闭复用池中的兄弟流。

Vision 在独立的 Encryption 记录边界切换：先排空已认证明文，再绕过 AEAD； 已有外层 TLS 保留，random 模式保留记录头 CTR，不重置计数器。 进入 direct 后，native/xorpub 继承底层 CloseWrite 并保留读取方向；random 对齐 Mihomo 不可替换的 XorConn，仍整流关闭。未进入 direct 时三种外观均整流关闭。 验收只覆盖实际列举的组合，不由单层成功推断整个组合或设备通过。

Vision

Vision padding、TLS 记录过滤和读写切换状态独立管理。内层非 TLS / TLS 1.2 只结束 padding，保持外层加密；识别支持的内层 TLS 1.3 协商后，分别发送/接收 direct 标记才切到裸流。每次发送最多暂存 8 KiB 一帧，接收逐段处理 u16 长度，不按声明长度无限分配。非法 UUID/命令或截断关闭 IO；取消读取保留帧进度。

外层 TLS 使用公开 rustls 或 boring 接口及同一记录边界适配器；每次最多读一个 TLS 记录，不在识别切换标记前吞入后续裸流。切换读取前排空已解密明文，切换写入前 flush 外层密文；Vole 不访问 TLS 私有内存布局。direct 关闭不向裸流插入外层 close-notify；未切换时保留共享 TLS 的有界关闭语义。

UDP

packet-encoding 默认 xudp，none 与 xudp 使用相同编码：

配置	线上语义	目标
省略 / xudp / none	VLESS CommandMux + 共享 XUDP 帧	每包携带 IP / 域名
packetaddr / packet	CommandUDP 到原生约定地址，长度帧内再带地址	IP-only，域名经受控 ResolutionContext 解析

packetaddr 的原生约定地址不做本地 DNS。UDP 443 不额外过滤。

VLESS 不发送非零 XUDP GlobalID，不请求服务端跨载体继承 UDP 关联。同一来源可能同时拥有 不同节点、资源代际、域名隔离或退役后仍服务兄弟目标的通道；这些通道保持独立，不能仅按 来源生成相同 GlobalID。当前关联失败后关闭，不自动重连或恢复服务端原有 UDP 出口映射。

packetaddr 每关联只拥有一个已建流，首次发送前已固定物理上游选择和建链期限；等待首包不会重新选择组或重启期限。packetaddr 不调用系统 resolver：运行期使用本 Running Session DNS，独立测速使用受控 bootstrap。

收发预算独立与调用方预算取交集。XUDP payload 受 u16 上限约束，packetaddr 另扣 IPv4 7 / IPv6 19 字节地址头（未解析域名按较大开销预检）。packetaddr 接收 wire 最多 65,537 字节，逐段读取，合法超接收预算的整包丢弃。对端可能有更小容量，原生夹具预算不能冒充生产协议上限。

XUDP 在既有单帧字节预算内读取已就绪字节，消费当前帧后保留后续帧的尾部；不等待凑批， 也不为每个长度或地址字段分别进入底层 TLS/HTTP 接收。 省略回复目标仅在关联始终使用同一目标时可恢复；多目标关联收到无目标回复会关闭，避免串流交付。 无 VLESS Encryption 的 H1/H2/H3 XHTTP 由自有驱动独立推进已接受的写入，XUDP 首包保留建链 flush， 后续帧交给既有有界发送队列；其它传输仍逐帧 flush。 packetaddr 在同一适用范围保留 VLESS 请求头与首个 DATA 帧的强制 flush，首个 DATA 仍受原建链绝对期限约束。后续完整帧被既有有界 writer 接纳后即可返回，不额外逐帧等待 packet-up 的 POST 响应；容量不足时仍沿原背压等待。timer／IO 驱动独立推进末帧， 不依赖下一次收发。启用 VLESS Encryption 或非 XHTTP 路径仍逐帧 flush。 返回成功表示接纳，不代表远端确认；显式 close／Stop 可以取消尚未确认的 UDP， 不承诺排空这些帧。来源隔离、目标地址恢复、部分发送取消及原有 TCP FIN／XHTTP 整流关闭合同保持。

packetaddr 和 XUDP 在关联中最多保留一个待写帧及偏移；取消发送后，下次收发先完成该帧与必要的 flush，再处理新包，保持共享通道边界。packetaddr 在发布关联前完成固定魔法目的的传输准备，首次报文仍受原建链期限约束，不因取消重置。相同来源、相同具体节点且无需地址恢复的 IP 目标可共享一条 packetaddr wire；每包回包地址用于分发，域名、fake-IP 与嗅探覆盖路径仍保留独立 wire。最后所有者关闭可直接终止未完成帧，不在其中插入 END 帧。接收取消保留帧进度。非法帧或响应头关闭关联，不切换编码、不回退 DIRECT。显式 close 后不能恢复收发。

关闭和期限

VLESS 响应头允许延迟到业务响应前；TCP 不等待它才允许发送请求。传输握手及请求头写入、flush 共用原建链期限，请求头成功提交后结束该期限；响应头随后按需读取、校验，持续上传不因缺少下行响应被原建链期限中断。业务等待由调用者期限、取消、EOF及运行时停止控制，格式错误仍释放IO。UUID 和业务目标不进入 Debug/诊断。

HTTP 首包伪装在完整请求前导提交后按需解析首响应，不为该响应保留旧建链期限； VLESS Encryption 等仍未完成的协议握手继续受原建链期限约束，不从 HTTP 前导提交推定完成。

普通 TCP/TLS 按底层 CloseWrite 语义工作；HTTP 首包伪装没有 Mihomo CloseWrite，shutdown 释放整个逻辑流并唤醒读侧。gRPC/H2 结束当前逻辑流，gRPC 的兄弟流与节点池不受影响。XHTTP 上传 EOF/shutdown 关闭整条逻辑连接，包括下载腿；需要完整响应时在关闭前读完。验收检查正常数据完整性、与支持对端的互通，以及 Vole 声明的关闭、取消和 Stop 契约，不要求所有传输半关闭后都收到尾包。

验证边界

所有服务端、原站、DNS 和对照入口遵守隔离规则。 ignored 未执行不计通过；精确组合与源/对端身份在当次报告记录，不拼接旧成绩。 HTTPUpgrade/fast-open 与 sing-mux 的未列举组合不从单层结果推导。

静态 ECH 的 H3 使用 Xray，packetaddr/sing-mux 使用明确标注的 XHTTP → Mihomo 解码。 HTTP/H2/扩展 WS 可用 Xray TLS 网关 → V2Ray transport；需 UDP/Encryption 时另由 Mihomo 解码。网关使用官方 XRAY_BUF_SPLICE=disable，避免下行 raw splice 绕过 TLS； 不代表 V2Ray 直接支持 ECH。无指纹 JLS/gRPC 及 Safari ECH/gRPC 的官方对照缺口采用 明确标注的 Chrome 关闭参照；Vole 原配置的数据面单独验证，不声称同配置差分。 VLESS 的 shadow-tls-opts 仅接已有 TCP 承载传输及 XHTTP H1/H2，包含独立下载腿； 须 tls: true、显式 version 3 和 password，不能与 Vision/JLS/REALITY/ECH 同腿混用。 cover 的证书策略与 mTLS 独立于业务身份，行为见 流式安全身份。

REALITY 只接流式 TLS 消费路径；普通 WS、HTTPUpgrade 及其 fast-open 与 REALITY 的组合在配置期拒绝。