mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-06 14:12:09 +03:00
Egor
aacfaebab8
* fix(tuic): restore client speed and certificate layout * docs(tuic): clarify native runtime and protocol behavior * fix(websocket): preserve traffic updates from independent sources * fix(docs): sync websocket traffic schema and drop restating TUIC tests docs/public/openapi.json still described the old traffic event, without clientTrafficSource/clientTrafficIntervalMs or the TUIC oneOf branch, so the docs site showed a payload the panel no longer sends. No check covers that copy. The TUIC certificate layout test and the TUIC speed payload test only read back the literals the code writes, so neither could fail on a real regression. Both are removed, along with the className that existed only for the layout test. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
113 lines
5.6 KiB
Plaintext
113 lines
5.6 KiB
Plaintext
---
|
||
title: TUIC
|
||
description: Set up a TUIC inbound in 3x-ui — QUIC congestion control, 0-RTT handshakes, and multi-user authentication.
|
||
icon: Zap
|
||
---
|
||
|
||
**TUIC** (v5) is a proxy protocol built directly on top of the **QUIC** (HTTP/3) transport
|
||
layer. It uses 0-RTT handshakes, connection multiplexing without head-of-line blocking,
|
||
and custom congestion control algorithms to maintain stable connections over lossy or
|
||
unstable networks.
|
||
|
||
<Callout type="info">
|
||
TUIC runs as an **in-process native Go server** inside 3x-ui. Decrypted traffic is bridged into Xray-core via a loopback SOCKS5 tunnel, enabling full Xray routing rules, cascading outbounds (e.g. TUIC → VLESS / WARP), per-client traffic quotas (`totalGB`), and zero-downtime hot user updates without restarting the port.
|
||
</Callout>
|
||
|
||
## Key settings
|
||
|
||
### Server, QUIC & client-profile parameters
|
||
|
||
| Field | Description |
|
||
| --- | --- |
|
||
| **Port** | UDP port for incoming client QUIC connections. |
|
||
| **Certificate & Key** | Full TLS certificate chain and private key. QUIC mandates TLS encryption; self-signed certificates or valid Let's Encrypt / ACME certs are supported. |
|
||
| **SNI** | Client-profile Server Name Indication. Set it to the domain covered by the server certificate; this field does not configure the listener certificate. |
|
||
| **Congestion Control** | QUIC congestion control algorithm used in the server setting and exported client profile: `bbr`, `cubic`, or `new_reno`. The server runs BBR or New Reno; when CUBIC is selected, the client profile keeps CUBIC while this server currently falls back to New Reno. |
|
||
| **ALPN** | Application-Layer Protocol Negotiation tokens (default: `h3`). |
|
||
| **UDP Relay Mode** | Client-profile packet mode: `native` (QUIC datagrams) or `quic` (unidirectional streams). The server accepts both modes regardless of this exported preference. |
|
||
| **Zero-RTT Handshake** | Enables 0-RTT connection resumption to eliminate initial handshake round-trips for returning clients. |
|
||
| **Authentication Timeout** | Maximum time (seconds) allowed for client authentication before disconnecting (default: `3s`). |
|
||
| **Max Idle Time** | Inactivity timeout (seconds) before closing idle QUIC connections (default: `15s`). |
|
||
| **Max Packet Size** | Maximum UDP relay packet size in bytes (default: `1500`). |
|
||
|
||
## Set it up in the panel
|
||
|
||
<Steps>
|
||
|
||
<Step>
|
||
### Add an inbound
|
||
|
||
Create a new inbound and choose protocol **TUIC**. Assign a UDP port (e.g. `8443` or `443`).
|
||
</Step>
|
||
|
||
<Step>
|
||
### Select TLS certificate
|
||
|
||
Provide the certificate file path and private key file path (or paste their contents). Make sure the configured SNI matches the certificate domain.
|
||
</Step>
|
||
|
||
<Step>
|
||
### Configure QUIC options
|
||
|
||
The panel fills recommended defaults (`bbr`, `h3`, `native` UDP relay). Adjust timeouts or enable **Zero-RTT Handshake** if desired.
|
||
</Step>
|
||
|
||
<Step>
|
||
### Add clients
|
||
|
||
Each client requires an **Email** identifier, a **UUID** (token), and a **Password**. The panel automatically generates secure random credentials when creating clients.
|
||
</Step>
|
||
|
||
<Step>
|
||
### Export and connect
|
||
|
||
Copy the client's share link (`tuic://…`) or open the **QR modal** to download a ready-to-use **Clash / Mihomo YAML** configuration.
|
||
</Step>
|
||
|
||
</Steps>
|
||
|
||
## Client support & configuration
|
||
|
||
TUIC v5 is supported by modern proxy clients including **Clash Verge Rev**, **Mihomo**, **Flclash**, **sing-box**, and **v2rayN**.
|
||
|
||
### Clash / Mihomo configuration
|
||
|
||
The panel provides automatic YAML export for Clash/Mihomo in the client QR modal:
|
||
|
||
```yaml title="clash-tuic.yaml"
|
||
proxies:
|
||
- name: "3x-ui-tuic"
|
||
type: tuic
|
||
server: vpn.example.com
|
||
port: 8443
|
||
uuid: 8a47f2b1-5e8c-4a3d-9b1e-7f6c5d4a3b2a
|
||
password: secure-random-password
|
||
alpn:
|
||
- h3
|
||
sni: vpn.example.com
|
||
congestion-controller: bbr
|
||
udp-relay-mode: native
|
||
reduce-rtt: false
|
||
skip-cert-verify: false
|
||
```
|
||
|
||
### Share link format
|
||
|
||
TUIC share links use standard URI formatting:
|
||
|
||
```text
|
||
tuic://<uuid>:<password>@<host>:<port>?congestion_control=bbr&alpn=h3&sni=vpn.example.com&udp_relay_mode=native&allow_insecure=0#Remark
|
||
```
|
||
|
||
## Architecture & Features
|
||
|
||
<Callout type="info">
|
||
- **Native in-process Go engine**: TUIC v5 runs 100% natively in Go within the 3x-ui process. No external binaries or sidecars to download or maintain.
|
||
- **Full Xray routing & cascading**: Decrypted traffic passes directly through Xray's routing engine. Inbound tags (`in-<port>-udp`) work seamlessly with routing rules, domain/IP blocks, and cascading to any outbound proxy (VLESS, Shadowsocks, WARP, etc.).
|
||
- **Per-client traffic limits & expiration**: Individual traffic quotas (`totalGB`) and expiration timestamps (`expiryTime`) are tracked and enforced for each client.
|
||
- **Live speed & traffic totals**: Native TUIC client counters are sampled every 10 seconds and sent to the panel for per-client live speed. Xray meters inbound totals through the loopback relay; TUIC's client-speed event does not add inbound totals again.
|
||
- **UDP resource bounds**: Each QUIC connection can hold up to 256 active UDP associations. Idle associations are closed after five minutes. This is a per-connection limit, not a node-wide association cap. TUIC uses a reserved loopback SOCKS relay port in `64001–65000`; 3x-ui checks it against managed inbound and relay ports.
|
||
- **Zero-downtime client updates**: Adding, modifying, or disabling clients updates the in-memory user registry instantly without restarting the UDP port or interrupting existing client sessions.
|
||
- **Deployment**: A TUIC inbound can be created on, or cloned to, a sub-node. The node's own panel runs the TUIC server, so the node must run panel v3.8.0 or newer; the master refuses an older node.
|
||
</Callout>
|