feat(tuic): implement native in-process Go TUIC v5 server (#6577)

* feat(tuic): implement native in-process Go TUIC v5 server

- Implement native TUIC v5 protocol server on pure Go using quic-go
- Bridge decrypted TCP/UDP traffic into Xray-core via loopback SOCKS5 inbound
- Support full Xray routing rules (geosite/geoip) and cascading outbounds
- Implement atomic per-client traffic accounting with TotalGB and ExpiryTime
- Add automatic legacy cleanup for older Rust tuic-server binaries, configs, and orphaned processes
- Eliminate external Rust tuic-server downloads from install/CI scripts

* fix(tuic): address traffic accounting, client reload, and socket lifecycle issues

* fix(service): update checkTuicSocksReverseConflict to use bindAddr for listenOverlaps

* fix(tuic): resolve traffic double-accounting, UDP fragmentation, and socket lifecycle issues

* feat(tuic): complete native Go integration and address audit findings

- Integrate an isolated QUIC fork pinned to a specific commit
- Preserve original QUIC dependencies for Xray, Hysteria and Gin
- Apply BBR, CUBIC and Reno to server connections and exported client profiles
- Bridge Xray BBR with correct monotonic time and congestion type conversions
- Handle congestion sender recreation after PMTU changes
- Update congestion control for new connections without restarting the listener
- Preserve existing connections and their selected congestion controller
- Apply per-inbound log levels through the shared panel logger
- Add lifecycle, authentication and TCP/UDP relay events without exposing secrets
- Rate-limit repeated authentication and relay warnings
- Support native and QUIC UDP relay modes on the same listener
- Recover UDP associations after relay worker failures
- Fix TCP relay cancellation, idle shutdown and half-close handling
- Close active sessions when client credentials are revoked or disabled
- Track traffic by immutable client statistics IDs across email and UUID changes
- Prevent ambiguous accounting and duplicate UUIDs within TUIC inbounds
- Persist pending traffic in a durable shutdown journal
- Replay journal batches transactionally without duplicate accounting
- Report server shutdown failures through the shared logger
- Preserve legacy flat and nested TUIC settings compatibility
- Normalize congestion controller values consistently across backend and frontend
- Preserve controller, UDP mode and SNI in client links and subscriptions
- Separate client profile options from server settings in the TUIC form
- Keep certificate path autofill explicit when changing client SNI
- Align UDP packet size validation with protocol limits
- Simplify and localize TUIC field hints and certificate autofill messages
- Add controller, TCP/UDP, logging and live settings update tests
- Add accounting identity, journal replay and shutdown regression tests
- Add relay recovery, session revocation and legacy frontend form tests

* fix(service): alias the TUIC duplicate-UUID subquery for PostgreSQL < 16

syncInboundClients runs a COUNT(*) FROM (subquery) for every client sync,
whatever the protocol. PostgreSQL before 16 rejects a FROM subquery with
no alias, so on the distro PostgreSQL install.sh provisions (14 on Ubuntu
22.04, 15 on Debian 12) every client add or edit failed with SQLSTATE
42601. Reproduced against postgres:15 with the new env-gated test.

* fix(database): create tuic_traffic_receipts through the model migration

AddTuicTrafficBatch issued CREATE TABLE IF NOT EXISTS at runtime, a schema
change outside db.go. The table was invisible to allModels and
migrationModels, so x-ui migrate-db dropped the receipts and a retained
journal could be counted twice after a SQLite to PostgreSQL move. It is
now a GORM model in both lists, and the insert uses OnConflict DoNothing.

* chore(tuic): skip the ICMP-dependent relay test on Windows, drop dead collectors

Go disables SIO_UDP_CONNRESET on Windows, so a dead UDP bridge never fails
a read there and TestAudit3UDPAssociationMustRecoverAfterBridgeReadFailure
was red on every Windows run. Server.CollectTotalTraffic and
Manager.CollectTraffic had no caller.

* refactor(tuic): serve TUIC on apernet/quic-go instead of a personal fork

The native server depended on github.com/poise52/quic-go, a personal fork
of apernet/quic-go patched only to pick the congestion controller before
the handshake. That put a second QUIC/TLS stack in the binary that no
upstream security fix reaches. apernet/quic-go is already in the graph
through xray-core and exposes SetCongestionControl, so BBR is now installed
on each accepted connection with Xray's own congestion.UseBBR; the
cross-module BBR adapter is gone.

apernet ships New Reno as its only built-in sender, so a cubic setting is
served as new_reno server-side (clients still get cubic in their profile).
The test inspectors now read the sender under congestionMutex, which the
post-handshake install writes under.

Linux loopback, single stream through Xray: 2428 -> 3383 Mbit/s (bbr).

---------

Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
This commit is contained in:
Egor
2026-10-03 05:56:02 +05:00
committed by GitHub
parent 40ca2cd72f
commit 0054e671f8
100 changed files with 7942 additions and 1467 deletions
+57 -30
View File
@@ -1,6 +1,7 @@
package job
import (
"fmt"
"time"
"github.com/mhsanaei/3x-ui/v3/internal/logger"
@@ -18,6 +19,13 @@ func NewTuicJob() *TuicJob {
}
func (j *TuicJob) Run() {
tuicJournalMu.Lock()
journalErr := j.replayTuicJournal()
tuicJournalMu.Unlock()
if journalErr != nil {
logger.Warning("tuic job: recover traffic journal failed:", journalErr)
}
desired, err := j.inboundService.DesiredTuicInstances()
if err != nil {
logger.Warning("tuic job: get desired instances failed:", err)
@@ -32,41 +40,18 @@ func (j *TuicJob) Run() {
mgr := tuic.GetManager()
mgr.Reconcile(desired)
deltas := mgr.CollectTraffic()
_, clientDeltas := mgr.CollectAllTraffic()
onlineEmails, _ := mgr.GetActiveClients(30 * time.Second)
inboundUp := make(map[string]int64)
inboundDown := make(map[string]int64)
for _, d := range deltas {
inboundUp[d.Tag] += d.Up
inboundDown[d.Tag] += d.Down
}
clientTraffics := aggregateTuicClientTraffic(clientDeltas, onlineEmails)
traffics := make([]*xray.Traffic, 0, len(inboundUp))
for tag, up := range inboundUp {
traffics = append(traffics, &xray.Traffic{
IsInbound: true,
Tag: tag,
Up: up,
Down: inboundDown[tag],
})
}
// Build zero-byte client traffic entries for active clients so adjustTraffics can
// activate delayed-start expiryTime for TUIC clients without inflating traffic.
clientTraffics := make([]*xray.ClientTraffic, 0, len(onlineEmails))
for _, email := range onlineEmails {
clientTraffics = append(clientTraffics, &xray.ClientTraffic{
Email: email,
Up: 0,
Down: 0,
})
}
if len(traffics) > 0 || len(clientTraffics) > 0 {
needRestart, _, err := j.inboundService.AddTraffic(traffics, clientTraffics)
// Inbound total traffic is already metered through the loopback SOCKS relay
// by xray_traffic_job (matching mtproto); only per-client deltas are submitted here.
if len(clientTraffics) > 0 {
needRestart, _, err := j.inboundService.AddTraffic(nil, clientTraffics)
if err != nil {
logger.Warning("tuic job: add traffic failed:", err)
mgr.RequeueClientTraffic(clientDeltas)
} else if needRestart {
if desired, err := j.inboundService.DesiredTuicInstances(); err == nil {
mgr.Reconcile(desired)
@@ -82,3 +67,45 @@ func (j *TuicJob) Run() {
j.inboundService.RefreshLocalOnlineClients(onlineEmails, activeTags)
}
// FlushStoppedTraffic persists counters drained when the TUIC manager stops its
// listeners. Call it after scheduled jobs have stopped and before the traffic
// writer shuts down.
func (j *TuicJob) FlushStoppedTraffic() error {
return j.flushTuicJournal()
}
func aggregateTuicClientTraffic(clientDeltas []tuic.ClientTrafficDelta, onlineEmails []string) []*xray.ClientTraffic {
clientTrafficMap := make(map[string]*xray.ClientTraffic, len(clientDeltas)+len(onlineEmails))
for _, cd := range clientDeltas {
key := cd.Email
if cd.TrafficID > 0 {
key = fmt.Sprintf("traffic:%d", cd.TrafficID)
}
if cd.TrafficID == 0 && cd.InboundID > 0 && cd.UUID != "" {
key = fmt.Sprintf("tuic:%d:%s", cd.InboundID, cd.UUID)
}
traffic := clientTrafficMap[key]
if traffic == nil {
traffic = &xray.ClientTraffic{Email: cd.Email, TuicTrafficID: cd.TrafficID, TuicUUID: cd.UUID, TuicInboundId: cd.InboundID}
clientTrafficMap[key] = traffic
}
traffic.Up += cd.Up
traffic.Down += cd.Down
}
for _, email := range onlineEmails {
if _, exists := clientTrafficMap[email]; !exists {
clientTrafficMap[email] = &xray.ClientTraffic{
Email: email,
Up: 0,
Down: 0,
}
}
}
clientTraffics := make([]*xray.ClientTraffic, 0, len(clientTrafficMap))
for _, ct := range clientTrafficMap {
clientTraffics = append(clientTraffics, ct)
}
return clientTraffics
}
+182
View File
@@ -0,0 +1,182 @@
package job
import (
"crypto/rand"
"crypto/rsa"
"crypto/x509"
"crypto/x509/pkix"
"encoding/pem"
"fmt"
"math/big"
"net"
"path/filepath"
"testing"
"time"
"github.com/mhsanaei/3x-ui/v3/internal/database"
"github.com/mhsanaei/3x-ui/v3/internal/database/model"
"github.com/mhsanaei/3x-ui/v3/internal/tuic"
"github.com/mhsanaei/3x-ui/v3/internal/xray"
)
func generateTestCertForJob(t *testing.T) (certPEM, keyPEM []byte) {
t.Helper()
priv, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
t.Fatalf("rsa.GenerateKey: %v", err)
}
template := x509.Certificate{
SerialNumber: big.NewInt(1),
Subject: pkix.Name{CommonName: "localhost"},
NotBefore: time.Now().Add(-time.Hour),
NotAfter: time.Now().Add(time.Hour),
IPAddresses: []net.IP{net.ParseIP("127.0.0.1")},
}
der, err := x509.CreateCertificate(rand.Reader, &template, &template, &priv.PublicKey, priv)
if err != nil {
t.Fatalf("CreateCertificate: %v", err)
}
certPEM = pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
keyPEM = pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: x509.MarshalPKCS1PrivateKey(priv)})
return
}
func TestTuicJob_TrafficAccounting(t *testing.T) {
if err := database.InitDB(filepath.Join(t.TempDir(), "tuic_job.db")); err != nil {
t.Fatalf("database.InitDB failed: %v", err)
}
t.Cleanup(func() { _ = database.CloseDB() })
certPEM, keyPEM := generateTestCertForJob(t)
pc, err := net.ListenPacket("udp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
port := pc.LocalAddr().(*net.UDPAddr).Port
_ = pc.Close()
email := "tuic-user@example.com"
settings := fmt.Sprintf(`{
"certificate": %q,
"private_key": %q,
"congestion_control": "bbr",
"alpn": ["h3"],
"udp_relay_mode": "native",
"zero_rtt_handshake": false,
"clients": [
{
"uuid": "a0000000-0000-0000-0000-000000000001",
"password": "password123",
"email": %q,
"enable": true
}
]
}`, string(certPEM), string(keyPEM), email)
inbound := &model.Inbound{
Id: 42,
Tag: "tuic-in-42",
Protocol: model.TUIC,
Listen: "127.0.0.1",
Port: port,
Enable: true,
Settings: settings,
}
if err := database.GetDB().Create(inbound).Error; err != nil {
t.Fatalf("create inbound failed: %v", err)
}
clientTraffic := &xray.ClientTraffic{
InboundId: inbound.Id,
Email: email,
Up: 0,
Down: 0,
Enable: true,
}
if err := database.GetDB().Create(clientTraffic).Error; err != nil {
t.Fatalf("create clientTraffic failed: %v", err)
}
mgr := tuic.GetManager()
t.Cleanup(mgr.StopAll)
job := NewTuicJob()
// Initial run reconciles desired instances and starts the server
job.Run()
// Add test traffic to the running client
const wantUp = int64(1024)
const wantDown = int64(2048)
if !mgr.AddTestTraffic(inbound.Id, email, wantUp, wantDown) {
t.Fatalf("failed to add test traffic for %s on inbound %d", email, inbound.Id)
}
// Second run collects and writes traffic to database
job.Run()
// Verify client traffic in database
var dbClient xray.ClientTraffic
if err := database.GetDB().Where("inbound_id = ? AND email = ?", inbound.Id, email).First(&dbClient).Error; err != nil {
t.Fatalf("find client traffic in DB failed: %v", err)
}
if dbClient.Up != wantUp || dbClient.Down != wantDown {
t.Fatalf("client traffic mismatch: got up=%d down=%d, want up=%d down=%d", dbClient.Up, dbClient.Down, wantUp, wantDown)
}
// Verify inbound total traffic in database: TuicJob leaves inbound total
// accounting to xray_traffic_job (metered on the SOCKS relay tag, matching mtproto),
// preventing double-counting.
var dbInbound model.Inbound
if err := database.GetDB().First(&dbInbound, inbound.Id).Error; err != nil {
t.Fatalf("find inbound in DB failed: %v", err)
}
if dbInbound.Up != 0 || dbInbound.Down != 0 {
t.Fatalf("expected inbound traffic to remain 0 in TuicJob (metered by Xray bridge), got up=%d down=%d", dbInbound.Up, dbInbound.Down)
}
}
func TestAggregateTuicClientTrafficSumsAcrossInbounds(t *testing.T) {
got := aggregateTuicClientTraffic([]tuic.ClientTrafficDelta{
{Email: "shared@example.test", Up: 100, Down: 200},
{Email: "shared@example.test", Up: 300, Down: 400},
{Email: "other@example.test", Up: 5, Down: 6},
}, []string{"shared@example.test", "online-only@example.test"})
byEmail := make(map[string]struct{ up, down int64 }, len(got))
for _, traffic := range got {
byEmail[traffic.Email] = struct{ up, down int64 }{traffic.Up, traffic.Down}
}
if shared := byEmail["shared@example.test"]; shared.up != 400 || shared.down != 600 {
t.Fatalf("shared client traffic = %+v, want (400, 600)", shared)
}
if other := byEmail["other@example.test"]; other.up != 5 || other.down != 6 {
t.Fatalf("other client traffic = %+v, want (5, 6)", other)
}
if online, ok := byEmail["online-only@example.test"]; !ok || online.up != 0 || online.down != 0 {
t.Fatalf("online-only client traffic = %+v, present=%v", online, ok)
}
if len(got) != 3 {
t.Fatalf("got %d aggregated clients, want 3", len(got))
}
}
func TestAggregateTuicClientTrafficPreservesStableIdentityAcrossEmailRename(t *testing.T) {
const (
inboundID = 82
clientUUID = "a0000000-0000-0000-0000-000000000082"
)
got := aggregateTuicClientTraffic([]tuic.ClientTrafficDelta{
{Email: "old@example.test", UUID: clientUUID, InboundID: inboundID, Up: 10, Down: 20},
{Email: "old@example.test", UUID: clientUUID, InboundID: inboundID, Up: 30, Down: 40},
}, nil)
if len(got) != 1 {
t.Fatalf("aggregate returned %d records, want 1", len(got))
}
if got[0].Email != "old@example.test" || got[0].TuicUUID != clientUUID || got[0].TuicInboundId != inboundID {
t.Fatalf("aggregate lost retired TUIC identity: %+v", got[0])
}
if got[0].Up != 40 || got[0].Down != 60 {
t.Fatalf("aggregate counters = (%d,%d), want (40,60)", got[0].Up, got[0].Down)
}
}
+135
View File
@@ -0,0 +1,135 @@
package job
import (
"encoding/json"
"fmt"
"os"
"path/filepath"
"runtime"
"sync"
"time"
"github.com/google/uuid"
"github.com/mhsanaei/3x-ui/v3/internal/config"
"github.com/mhsanaei/3x-ui/v3/internal/tuic"
)
var tuicJournalMu sync.Mutex
type tuicTrafficBatch struct {
ID string `json:"id"`
Deltas []tuic.ClientTrafficDelta `json:"deltas"`
}
func tuicJournalDir() string { return filepath.Join(config.GetDBFolderPath(), "tuic-traffic-journal") }
func syncJournalDir(dir string) error {
if runtime.GOOS == "windows" {
return nil
}
file, err := os.Open(dir)
if err != nil {
return err
}
defer file.Close()
return file.Sync()
}
func storeTuicBatch(batch tuicTrafficBatch) (string, error) {
dir := tuicJournalDir()
if err := os.MkdirAll(dir, 0o700); err != nil {
return "", err
}
if err := syncJournalDir(filepath.Dir(dir)); err != nil {
return "", err
}
data, err := json.Marshal(batch)
if err != nil {
return "", err
}
file, err := os.CreateTemp(dir, ".pending-")
if err != nil {
return "", err
}
tmp := file.Name()
defer os.Remove(tmp)
if _, err := file.Write(data); err != nil {
file.Close()
return "", err
}
if err := file.Sync(); err != nil {
file.Close()
return "", err
}
if err := file.Close(); err != nil {
return "", err
}
path := filepath.Join(dir, batch.ID+".json")
if err := os.Rename(tmp, path); err != nil {
return "", err
}
return path, syncJournalDir(dir)
}
func (j *TuicJob) replayTuicJournal() error {
entries, err := os.ReadDir(tuicJournalDir())
if os.IsNotExist(err) {
return nil
}
if err != nil {
return err
}
for _, entry := range entries {
if entry.IsDir() || filepath.Ext(entry.Name()) != ".json" {
continue
}
path := filepath.Join(tuicJournalDir(), entry.Name())
data, err := os.ReadFile(path)
if err != nil {
return err
}
var batch tuicTrafficBatch
if err := json.Unmarshal(data, &batch); err != nil {
return fmt.Errorf("TUIC journal %s: %w", entry.Name(), err)
}
if batch.ID+".json" != entry.Name() {
return fmt.Errorf("TUIC journal batch ID mismatch")
}
if err := j.inboundService.AddTuicTrafficBatch(batch.ID, aggregateTuicClientTraffic(batch.Deltas, nil)); err != nil {
return err
}
if err := os.Remove(path); err != nil {
return err
}
if err := syncJournalDir(tuicJournalDir()); err != nil {
return err
}
}
return nil
}
func (j *TuicJob) flushTuicJournal() error {
tuicJournalMu.Lock()
defer tuicJournalMu.Unlock()
manager := tuic.GetManager()
_, deltas := manager.CollectAllTraffic()
if len(deltas) > 0 {
if path, err := storeTuicBatch(tuicTrafficBatch{ID: uuid.NewString(), Deltas: deltas}); err != nil {
if path == "" {
manager.RequeueClientTraffic(deltas)
}
return fmt.Errorf("persist TUIC shutdown journal: %w", err)
}
}
var err error
for attempt := 0; attempt < 3; attempt++ {
if err = j.replayTuicJournal(); err == nil {
return nil
}
if attempt < 2 {
time.Sleep(100 * time.Millisecond)
}
}
return fmt.Errorf("TUIC traffic retained in durable journal: %w", err)
}
+67
View File
@@ -0,0 +1,67 @@
package job
import (
"os"
"path/filepath"
"testing"
"github.com/mhsanaei/3x-ui/v3/internal/database"
"github.com/mhsanaei/3x-ui/v3/internal/database/dbtest"
"github.com/mhsanaei/3x-ui/v3/internal/tuic"
"github.com/mhsanaei/3x-ui/v3/internal/xray"
)
func TestTuicShutdownJournalSurvivesDatabaseFailureAndReplaysOnce(t *testing.T) {
dir := t.TempDir()
t.Setenv("XUI_DB_FOLDER", dir)
dbtest.InitDB(t, filepath.Join(dir, "x-ui.db"))
db := database.GetDB()
row := xray.ClientTraffic{Email: "journal@x", Enable: true}
if err := db.Create(&row).Error; err != nil {
t.Fatal(err)
}
batch := tuicTrafficBatch{ID: "shutdown-batch", Deltas: []tuic.ClientTrafficDelta{{Email: row.Email, TrafficID: row.Id, Up: 123, Down: 456}}}
path, err := storeTuicBatch(batch)
if err != nil {
t.Fatal(err)
}
if err := db.Exec(`CREATE TRIGGER fail_tuic_write BEFORE UPDATE ON client_traffics BEGIN SELECT RAISE(FAIL, 'disk fault'); END`).Error; err != nil {
t.Fatal(err)
}
job := NewTuicJob()
if err := job.FlushStoppedTraffic(); err == nil {
t.Fatal("failed traffic update must return an error")
}
if _, err := os.Stat(path); err != nil {
t.Fatalf("durable recovery file missing: %v", err)
}
var receipts int64
if err := db.Table("tuic_traffic_receipts").Count(&receipts).Error; err == nil && receipts != 0 {
t.Fatal("failed transaction committed a receipt")
}
if err := db.Exec("DROP TRIGGER fail_tuic_write").Error; err != nil {
t.Fatal(err)
}
// A new job has no knowledge of the previous process's in-memory deltas.
recovered := NewTuicJob()
if err := recovered.replayTuicJournal(); err != nil {
t.Fatal(err)
}
// Recreate a stale file, as if file removal was lost after DB commit.
if _, err := storeTuicBatch(batch); err != nil {
t.Fatal(err)
}
if err := recovered.replayTuicJournal(); err != nil {
t.Fatal(err)
}
if err := db.Where("id = ?", row.Id).First(&row).Error; err != nil {
t.Fatal(err)
}
if row.Up != 123 || row.Down != 456 {
t.Fatalf("replay billed %d/%d", row.Up, row.Down)
}
entries, err := os.ReadDir(tuicJournalDir())
if err != nil || len(entries) != 0 {
t.Fatalf("journal not drained: %v %v", entries, err)
}
}