XUDP 协议

XUDP 扩展了 Mux 协议以支持逐包寻址的 UDP，从而在单个传输连接上实现 Full-Cone NAT 行为。它被 VLESS、VMess 及其他协议用于代理 UDP 流量。

源码：common/xudp/xudp.go

为什么需要 XUDP？

标准 Mux 为每个目的地址创建一个会话。对于 UDP：

客户端发送到 Server_A → 会话 1
客户端发送到 Server_B → 会话 2
Server_A 响应 → 会话 1 ✓
Server_C 响应 → 没有对应会话！ ✗

XUDP 通过以下方式解决这个问题：

对来自同一源的所有 UDP 流量使用单个会话
在每个数据包中包含目的地址（而非仅在会话头部）
支持来自任意地址的响应（Full-Cone NAT）

线路格式

首个数据包（新会话）

+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Meta Len  | Session=0 | Status=New | Opt=Data      |
| (2B BE)   | (2B: 0x00)| (1B: 0x01) | (1B: 0x01)  |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Network=UDP | Port    | AddrType | Address         |
| (1B: 0x02)  | (2B BE) | (1B)     | (var)          |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| GlobalID (8 bytes)                                  |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Data Len  | UDP Payload                             |
| (2B BE)   | (var)                                   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

后续数据包（保持会话）

+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Meta Len  | Session=0 | Status=Keep | Opt=Data     |
| (2B BE)   | (2B: 0x00)| (1B: 0x02)  | (1B: 0x01) |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Network=UDP | Port    | AddrType | Address         |
| (1B: 0x02)  | (2B BE) | (1B)     | (var)          |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Data Len  | UDP Payload                             |
| (2B BE)   | (var)                                   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

与标准 Mux 的关键区别：

Session ID 始终为 0（XUDP 使用单个会话）
Keep 帧包含目的地址（逐包寻址）
GlobalID 仅在首个（New）帧中发送

PacketWriter

type PacketWriter struct {
    Writer   buf.Writer       // underlying mux/transport writer
    Dest     net.Destination  // initial destination
    GlobalID [8]byte          // connection identity
}

func (w *PacketWriter) WriteMultiBuffer(mb buf.MultiBuffer) error {
    for _, b := range mb {
        eb := buf.New()
        eb.Write([]byte{0, 0, 0, 0})  // meta len placeholder + session ID=0

        if w.Dest.Network == net.Network_UDP {
            // First packet: New session
            eb.WriteByte(1)  // Status: New
            eb.WriteByte(1)  // Option: Data
            eb.WriteByte(2)  // Network: UDP
            AddrParser.WriteAddressPort(eb, w.Dest.Address, w.Dest.Port)
            if b.UDP != nil {
                eb.Write(w.GlobalID[:])  // 8-byte GlobalID
            }
            w.Dest.Network = net.Network_Unknown  // switch to Keep for next packet
        } else {
            // Subsequent packets: Keep session
            eb.WriteByte(2)  // Status: Keep
            eb.WriteByte(1)  // Option: Data
            if b.UDP != nil {
                eb.WriteByte(2)  // Network: UDP
                AddrParser.WriteAddressPort(eb, b.UDP.Address, b.UDP.Port)
            }
        }

        // Write meta length
        l := eb.Len() - 2
        eb.SetByte(0, byte(l>>8))
        eb.SetByte(1, byte(l))

        // Write data length + data
        eb.WriteByte(byte(length >> 8))
        eb.WriteByte(byte(length))
        eb.Write(b.Bytes())

        mb2Write = append(mb2Write, eb)
    }
    return w.Writer.WriteMultiBuffer(mb2Write)
}

PacketReader

type PacketReader struct {
    Reader io.Reader
    cache  []byte  // 2-byte buffer for length reads
}

func (r *PacketReader) ReadMultiBuffer() (buf.MultiBuffer, error) {
    for {
        // Read meta length (2 bytes)
        io.ReadFull(r.Reader, r.cache)
        l := int32(r.cache[0])<<8 | int32(r.cache[1])

        // Read metadata
        b := buf.New()
        b.ReadFullFrom(r.Reader, l)

        switch b.Byte(2) {  // Status byte
        case 2:  // Keep
            if l > 4 && b.Byte(4) == 2 {  // Has UDP address
                b.Advance(5)
                addr, port, _ := AddrParser.ReadAddressPort(nil, b)
                b.UDP = &net.Destination{
                    Network: net.Network_UDP,
                    Address: addr,
                    Port:    port,
                }
            }
        case 4:  // KeepAlive (discard)
            discard = true
        default:  // End
            return nil, io.EOF
        }

        // Read data length + payload
        b.Clear()
        if b.Byte(3) == 1 {  // Option: Data
            io.ReadFull(r.Reader, r.cache)
            length := int32(r.cache[0])<<8 | int32(r.cache[1])
            b.ReadFullFrom(r.Reader, length)
            if !discard {
                return buf.MultiBuffer{b}, nil
            }
        }
    }
}

GlobalID

GlobalID 标识客户端的 UDP "连接"，用于服务端的 Full-Cone NAT：

func GetGlobalID(ctx context.Context) (globalID [8]byte) {
    // Only generate for cone mode
    if cone := ctx.Value("cone"); cone == nil || !cone.(bool) {
        return  // zero ID: no cone NAT
    }

    // Only for supported inbounds
    inbound := session.InboundFromContext(ctx)
    if inbound != nil && inbound.Source.Network == net.Network_UDP &&
        (inbound.Name == "dokodemo-door" ||
         inbound.Name == "socks" ||
         inbound.Name == "shadowsocks" ||
         inbound.Name == "tun") {

        // BLAKE3 hash of source address
        h := blake3.New(8, BaseKey)
        h.Write([]byte(inbound.Source.String()))
        copy(globalID[:], h.Sum(nil))
    }
    return
}

GlobalID 工作原理

客户端 A（源地址=10.0.0.1:5000）发送 UDP → 服务器对 "10.0.0.1:5000" 计算哈希 → GlobalID abc123
服务器创建以 GlobalID abc123 为键的 cone 会话
任何携带 GlobalID abc123 的返回 UDP 数据包都被路由回 10.0.0.1:5000
不同的客户端 B（源地址=10.0.0.2:3000）→ 不同的 GlobalID → 独立的会话

BaseKey

BLAKE3 密钥在启动时随机生成：

BaseKey = make([]byte, 32)
rand.Read(BaseKey)

或通过环境变量 XRAY_XUDP_BASEKEY 配置（用于可复现的行为，例如跨重启场景）。

VLESS 出站中的 XUDP

当 VLESS 出站处理带有 Cone NAT 的 UDP 时：

// Convert UDP to mux+XUDP
if command == UDP && (flow == XRV || cone) {
    request.Command = Mux
    request.Address = "v1.mux.cool"
    request.Port = 666  // magic port: indicates XUDP
}

// Wrap writer with XUDP framing
serverWriter = xudp.NewPacketWriter(serverWriter, target, xudp.GetGlobalID(ctx))

// Wrap reader with XUDP deframing
serverReader = xudp.NewPacketReader(conn)

服务端的 XUDP 检测

VLESS 入站通过检查首个 Mux 帧来检测 XUDP：

func isMuxAndNotXUDP(request, first) bool {
    if request.Command != Mux { return false }
    if first.Len() < 7 { return true }  // assume regular mux

    firstBytes := first.Bytes()
    // XUDP: session=0 (bytes 2,3), network=UDP (byte 6)
    return !(firstBytes[2] == 0 &&
             firstBytes[3] == 0 &&
             firstBytes[6] == 2)
}

如果检测到 XUDP，服务器使用支持 XUDP 的数据包读取器，而非常规的 Mux 服务端 worker。

数据流示例

客户端发送 DNS 查询到 8.8.8.8:53：

PacketWriter 写入：
  [00 0C]             # meta length = 12
  [00 00]             # session ID = 0
  [01]                # status = New
  [01]                # option = Data
  [02]                # network = UDP
  [00 35]             # port = 53
  [01]                # addr type = IPv4
  [08 08 08 08]       # address = 8.8.8.8
  [a1 b2 c3 d4 e5 f6 g7 h8]  # GlobalID (8 bytes)
  [00 2A]             # data length = 42
  [... DNS query ...]  # payload

来自 8.8.8.8:53 的响应到达：

PacketReader 读取：
  [00 0C]             # meta length
  [00 00]             # session ID = 0
  [02]                # status = Keep
  [01]                # option = Data
  [02]                # network = UDP
  [00 35]             # port = 53
  [01 08 08 08 08]    # addr = 8.8.8.8
  [00 XX]             # data length
  [... DNS response ...]
  → b.UDP = {Network: UDP, Address: 8.8.8.8, Port: 53}

实现要点

Session ID 0 是特殊的：在 XUDP 中，session ID 始终为 0。常规 Mux 的 session ID 从 1 开始。
GlobalID 按源地址生成：每个客户端源地址获得唯一的 GlobalID。服务器使用它来维护每个客户端的 Cone NAT 状态。
逐包寻址：每个 Keep 帧可以有不同的目的地址。这正是实现 Full-Cone NAT 的关键——响应可以来自任意地址。
Buffer.UDP 传播：Buffer.UDP 字段贯穿整个管道：XUDP 读取器设置它，pipe 保留它，XUDP 写入器读取它。绝不要去除此字段。
Cone 模式可配置：上下文中的 cone 值（来自配置）控制是否使用 XUDP。禁用时，每个 UDP 目的地获得单独的 Mux 会话（Symmetric NAT 行为）。
BLAKE3 用于哈希：8 字节哈希提供了足够的唯一性，同时保持紧凑。BaseKey 防止客户端猜测彼此的 GlobalID。

XUDP 协议 ​

为什么需要 XUDP？ ​

线路格式 ​

首个数据包（新会话） ​

后续数据包（保持会话） ​

PacketWriter ​

PacketReader ​

GlobalID ​

GlobalID 工作原理 ​

BaseKey ​

VLESS 出站中的 XUDP ​

服务端的 XUDP 检测 ​

数据流示例 ​

实现要点 ​