3x-ui/docs/panel-guide/09-xray-protocol-reference.md

09. Xray Protocol Reference for 3x-ui

Scope

This document captures protocol-level understanding relevant to 3x-ui operations and implementation decisions.

Important:

• It is an operator-focused reference, not full wire-spec replacement for each protocol.
• Always validate against current upstream Xray docs before major production migrations.

Protocols supported in current model/constants

From database/model/model.go protocol constants:

• vmess
• vless
• trojan
• shadowsocks
• http
• mixed
• tunnel
• wireguard

Concept model

In Xray/3x-ui, configuration is split into:

1. Protocol/auth layer (vless/vmess/trojan/ss/etc)
2. Transport/stream layer (tcp, ws, grpc, etc)
3. Security layer (none, tls, reality)
4. Routing/DNS policy layer

Most operator mistakes happen when these layers are mixed conceptually.

VLESS

Characteristics:

• Modern lightweight protocol (common choice with Reality).
• Client identity via UUID (id) and optional flow in specific TLS/XTLS contexts.

Typical production pairings:

• vless + tcp + reality
• vless + ws + tls
• vless + grpc + tls

Operational notes:

• Treat UUID/flow/security migration as coordinated change.
• Reality key material/shortIds are break-sensitive.

VMESS

Characteristics:

• Legacy/common protocol with UUID identity and security parameters.

Operational notes:

• Can still work well, but many modern deployments prefer VLESS.
• Migration VMESS->VLESS should be staged as full client profile replacement.

Trojan

Characteristics:

• Password-based identity model.
• Often used with TLS-like camouflage patterns.

3x-ui key behavior:

• Client key for updates/deletes is password for trojan path in service logic.

Shadowsocks

Characteristics:

• Cipher/password model.
• Includes classic and 2022-style cipher handling paths in Xray integration.

3x-ui key behavior:

• Email plays tracking role in panel logic even for SS clients.
• For SS, client-key handling differs from UUID-based protocols.

WireGuard / Tunnel / HTTP / Mixed

These exist in model support and can appear in inbound definitions depending on build/version/UI exposure.

Operational recommendation:

• Use these only when your use-case explicitly requires them.
• Keep your mainstream user path on one well-tested protocol family.

Reality

Reality is a security/camouflage mode (commonly with VLESS TCP).

Key operator concerns:

• Public key/private key, shortIds, destination/serverName consistency.
• Any mismatch causes hard connect failures.
• Keep a fallback inbound during rotations.

XHTTP / HTTP-style obfuscation context

In this session context, “xhttp-like/client-similar behavior” referred to HTTP header camouflage over TCP-style transport.

Implemented test pattern:

• vless-tcp-http-18080-test
• Request header host and path set for camouflage testing.

Guidance:

• Keep obfuscation experiments in clearly marked test inbounds.
• Do not blend experimental obfuscation into main production inbound without staged rollout.

Routing and DNS interplay (critical)

Protocol success can still fail at policy layer due to:

• DNS resolver split policies
• Domain/IP route overrides
• Direct/proxy exceptions

Always validate:

1. Inbound reaches server
2. Auth/security valid
3. DNS route correct
4. Outbound path available

Practical compatibility checklist before creating a new inbound type

1. Confirm protocol support in current panel build.
2. Confirm client app supports same protocol+transport+security combo.
3. Create isolated test inbound first.
4. Add one test client and verify handshake/traffic.
5. Roll out with explicit naming and fallback path.

Naming convention reminder

Use descriptive remarks to prevent operator error:

• <protocol>-<transport>-<security>-<port>-<role>

Examples used in session:

• vless-reality-tcp-443-main
• vless-reality-tcp-8443-alt
• vless-tcp-http-18080-test

Where to cross-check in codebase

• Protocol constants: database/model/model.go
• Inbound/client update logic: web/service/inbound.go
• Xray add/remove user and inbound operations: xray/api.go
• Xray config assembly: web/service/xray.go