Xray-core: внутреннее устройство

Русский

English
简体中文
العربية

Русский

English
简体中文
العربية

Appearance

Протокол 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 решает это:

  1. Использует единую сессию для всего UDP-трафика от одного источника
  2. Включает адрес назначения в каждый пакет (не только в заголовок сессии)
  3. Поддерживает ответы с любого адреса (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:

  • ID сессии всегда 0 (XUDP использует единую сессию)
  • Кадры Keep включают адрес назначения (адресация для каждого пакета)
  • GlobalID отправляется только в первом (New) кадре

PacketWriter ​

go
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 ​

go
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:

go
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 ​

  1. Клиент A (source=10.0.0.1:5000) отправляет UDP → сервер хеширует "10.0.0.1:5000" → GlobalID abc123
  2. Сервер создаёт cone-сессию по ключу GlobalID abc123
  3. Любой возвратный UDP-пакет с GlobalID abc123 маршрутизируется обратно на 10.0.0.1:5000
  4. Другой клиент B (source=10.0.0.2:3000) → другой GlobalID → отдельная сессия

BaseKey ​

Ключ BLAKE3 генерируется случайным образом при запуске:

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

Или настраивается через переменную окружения XRAY_XUDP_BASEKEY (для воспроизводимого поведения, например, при перезапусках).

XUDP в исходящем VLESS ​

Когда исходящее соединение VLESS обрабатывает UDP с cone NAT:

go
// 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 обнаруживает XUDP, проверяя первый mux-кадр:

go
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, сервер использует packet reader с поддержкой XUDP вместо обычного mux server 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}

Замечания по реализации ​

  1. ID сессии 0 — особый: В XUDP ID сессии всегда 0. Обычный mux начинает ID сессий с 1.

  2. GlobalID — для каждого источника: Каждый адрес источника клиента получает уникальный GlobalID. Сервер использует его для поддержания состояния cone NAT для каждого клиента.

  3. Адресация для каждого пакета: Каждый Keep-кадр может иметь различный адрес назначения. Это то, что обеспечивает Full-Cone NAT — ответ может прийти с любого адреса.

  4. Распространение Buffer.UDP: Поле Buffer.UDP проходит через весь конвейер: XUDP reader устанавливает его, pipe сохраняет, XUDP writer считывает. Никогда не удаляйте это поле.

  5. Режим cone настраивается: Значение cone в контексте (из конфигурации) управляет использованием XUDP. При отключении каждый UDP-адрес назначения получает отдельную mux-сессию (поведение Symmetric NAT).

  6. BLAKE3 для хеширования: 8-байтовый хеш обеспечивает достаточную уникальность при компактности. BaseKey предотвращает угадывание клиентами GlobalID друг друга.

Технический анализ для целей повторной реализации.