fix(inbounds): serve fresh client UUIDs for list and allLinks (#6458)

* fix(inbounds): serve fresh client UUIDs for list and allLinks (#6436)

Resolve clients from the clients table in inboundLinks and
backfillClientStats so /inbounds/list ClientStats and allLinks match
the running Xray identity when embedded settings JSON is stale.

* fix(sub): keep WG/AWG settings identity in link exports (#6436)

clientsForLinkExport uses the clients table for UUID-bearing protocols and
the inbound settings JSON for WireGuard/AmneziaWG so allLinks and per-client
QR links stay consistent without collapsing per-inbound tunnel keys.

* fix(sub): fall back to settings clients for link export (#6458)

Prefer ListClientsForInbound for UUID protocols, but when the clients
table is empty or unavailable fall back to GetClients so settings-only
inbounds (and share-link unit tests) still produce links. Keep WG/AWG
on settings identity.

---------

Co-authored-by: mrchatam <[email protected]>
Co-authored-by: mrchatam <[email protected]>

internal/sub/export_all_links_test.go

@@ -1,11 +1,14 @@
 package sub
 
 import (
+	"encoding/base64"
+	"net/url"
 	"strings"
 	"testing"
 
 	"github.com/mhsanaei/3x-ui/v3/internal/database"
 	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	wgutil "github.com/mhsanaei/3x-ui/v3/internal/util/wireguard"
 )
 
 // inboundLinks (the "Export all inbound links" path) must render the remark
@@ -23,6 +26,16 @@ func TestInboundLinks_RemarkTemplateClientTokens(t *testing.T) {
 	if err := db.Create(ib).Error; err != nil {
 		t.Fatalf("seed inbound: %v", err)
 	}
+	client := &model.ClientRecord{
+		Email: "john@e", SubID: "subABC", UUID: "11111111-2222-4333-8444-000000000001",
+		Enable: true, Comment: "vip", TgID: 777,
+	}
+	if err := db.Create(client).Error; err != nil {
+		t.Fatalf("seed client: %v", err)
+	}
+	if err := db.Create(&model.ClientInbound{ClientId: client.Id, InboundId: ib.Id}).Error; err != nil {
+		t.Fatalf("seed client_inbound: %v", err)
+	}
 
 	svc := NewSubService("{{INBOUND}}-{{EMAIL}}-{{COMMENT}}-{{SUB_ID}}-{{TELEGRAM_ID}}-{{SHORT_ID}}|📊{{TRAFFIC_LEFT}}|⏳{{DAYS_LEFT}}D")
 	svc.PrepareForRequest("req.example.com")
@@ -41,3 +54,170 @@ func TestInboundLinks_RemarkTemplateClientTokens(t *testing.T) {
 		t.Fatalf("display mode must drop the traffic/expiry segments: %s", frag)
 	}
 }
+
+// inboundLinks must use the clients-table UUID when the inbound settings JSON
+// still embeds a stale id (#6436).
+func TestInboundLinks_UsesClientsTableUUIDWhenSettingsStale(t *testing.T) {
+	seedSubDB(t)
+	db := database.GetDB()
+	stale := "11111111-1111-1111-1111-111111111111"
+	fresh := "22222222-2222-2222-2222-222222222222"
+	settings := `{"clients":[{"id":"` + stale + `","email":"stale@e","subId":"subStale","enable":true}],"decryption":"none"}`
+	ib := &model.Inbound{
+		UserId: 1, Tag: "stale-uuid", Enable: true, Listen: "203.0.113.5", Port: 4432,
+		Protocol: model.VLESS, Remark: "Stale", Settings: settings,
+		StreamSettings: `{"network":"tcp","security":"none","tcpSettings":{"header":{"type":"none"}}}`,
+	}
+	if err := db.Create(ib).Error; err != nil {
+		t.Fatalf("seed inbound: %v", err)
+	}
+	client := &model.ClientRecord{Email: "stale@e", SubID: "subStale", UUID: fresh, Enable: true}
+	if err := db.Create(client).Error; err != nil {
+		t.Fatalf("seed client: %v", err)
+	}
+	if err := db.Create(&model.ClientInbound{ClientId: client.Id, InboundId: ib.Id}).Error; err != nil {
+		t.Fatalf("seed client_inbound: %v", err)
+	}
+
+	svc := NewSubService("{{EMAIL}}")
+	svc.PrepareForRequest("req.example.com")
+	links := svc.inboundLinks(ib)
+	if len(links) != 1 {
+		t.Fatalf("links = %d, want 1: %v", len(links), links)
+	}
+	if !strings.Contains(links[0], fresh) {
+		t.Fatalf("link missing fresh UUID %q: %s", fresh, links[0])
+	}
+	if strings.Contains(links[0], stale) {
+		t.Fatalf("link still carries stale settings UUID %q: %s", stale, links[0])
+	}
+}
+
+// inboundLinks must still emit a VLESS link when clients exist only in the
+// inbound settings JSON (no clients / client_inbounds rows) — ListClientsForInbound
+// returns empty and clientsForLinkExport falls back to GetClients (#6458).
+func TestInboundLinks_SettingsOnlyVLESSProducesLink(t *testing.T) {
+	seedSubDB(t)
+	db := database.GetDB()
+	uuid := "33333333-3333-3333-3333-333333333333"
+	settings := `{"clients":[{"id":"` + uuid + `","email":"settings@e","subId":"subSettings","enable":true}],"decryption":"none"}`
+	ib := &model.Inbound{
+		UserId: 1, Tag: "settings-only", Enable: true, Listen: "203.0.113.5", Port: 4434,
+		Protocol: model.VLESS, Remark: "SettingsOnly", Settings: settings,
+		StreamSettings: `{"network":"tcp","security":"none","tcpSettings":{"header":{"type":"none"}}}`,
+	}
+	if err := db.Create(ib).Error; err != nil {
+		t.Fatalf("seed inbound: %v", err)
+	}
+
+	svc := NewSubService("{{EMAIL}}")
+	svc.PrepareForRequest("req.example.com")
+	links := svc.inboundLinks(ib)
+	if len(links) != 1 {
+		t.Fatalf("links = %d, want 1: %v", len(links), links)
+	}
+	if !strings.Contains(links[0], "vless://") {
+		t.Fatalf("link = %q, want vless:// prefix", links[0])
+	}
+	if !strings.Contains(links[0], uuid) {
+		t.Fatalf("link missing settings UUID %q: %s", uuid, links[0])
+	}
+}
+
+// inboundLinks must keep each WireGuard/AmneziaWG inbound's own tunnel address
+// and private key when the same email is attached to both — those fields live
+// only in the per-inbound settings JSON, not the shared clients.wg_* columns.
+func TestInboundLinks_PreservesPerInboundWireGuardIdentity(t *testing.T) {
+	seedSubDB(t)
+	db := database.GetDB()
+
+	serverPriv, serverPub, err := wgutil.GenerateWireguardKeypair()
+	if err != nil {
+		t.Fatalf("server keypair: %v", err)
+	}
+	wgPriv, _, err := wgutil.GenerateWireguardKeypair()
+	if err != nil {
+		t.Fatalf("wg client keypair: %v", err)
+	}
+	awgPriv, _, err := wgutil.GenerateWireguardKeypair()
+	if err != nil {
+		t.Fatalf("awg client keypair: %v", err)
+	}
+	// Shared clients row deliberately holds the *other* tunnel's key/address
+	// (last sync wins) — the failure mode ListClientsForInbound alone would export.
+	mergedPriv, _, err := wgutil.GenerateWireguardKeypair()
+	if err != nil {
+		t.Fatalf("merged keypair: %v", err)
+	}
+
+	email := "dual@e"
+	wgSettings := `{"secretKey":"` + serverPriv + `","clients":[{"email":"` + email + `","privateKey":"` + wgPriv + `","allowedIPs":["10.0.0.5/32"],"enable":true}]}`
+	awgSettings := `{"server":{"privateKey":"` + serverPriv + `","publicKey":"` + serverPub + `","mtu":1420},` +
+		`"clients":[{"email":"` + email + `","privateKey":"` + awgPriv + `","allowedIPs":["10.8.1.5/32"],"enable":true}]}`
+
+	wgIb := &model.Inbound{
+		UserId: 1, Tag: "wg-dual", Enable: true, Listen: "203.0.113.7", Port: 51820,
+		Protocol: model.WireGuard, Remark: "WG", Settings: wgSettings,
+	}
+	awgIb := &model.Inbound{
+		UserId: 1, Tag: "awg-dual", Enable: true, Listen: "203.0.113.8", Port: 443,
+		Protocol: model.AmneziaWG, Remark: "AWG", Settings: awgSettings,
+	}
+	for _, ib := range []*model.Inbound{wgIb, awgIb} {
+		if err := db.Create(ib).Error; err != nil {
+			t.Fatalf("create inbound %s: %v", ib.Tag, err)
+		}
+	}
+	rec := &model.ClientRecord{
+		Email: email, SubID: "subDual", Enable: true,
+		PrivateKey: mergedPriv, AllowedIPs: "10.9.9.9/32",
+	}
+	if err := db.Create(rec).Error; err != nil {
+		t.Fatalf("create client: %v", err)
+	}
+	for _, ib := range []*model.Inbound{wgIb, awgIb} {
+		if err := db.Create(&model.ClientInbound{ClientId: rec.Id, InboundId: ib.Id}).Error; err != nil {
+			t.Fatalf("create client_inbound %s: %v", ib.Tag, err)
+		}
+	}
+
+	svc := NewSubService("{{EMAIL}}")
+	svc.PrepareForRequest("req.example.com")
+
+	wgLinks := svc.inboundLinks(wgIb)
+	if len(wgLinks) != 1 {
+		t.Fatalf("wg links = %d, want 1: %v", len(wgLinks), wgLinks)
+	}
+	wu, err := url.Parse(wgLinks[0])
+	if err != nil {
+		t.Fatalf("wg link parse: %v (%s)", err, wgLinks[0])
+	}
+	if wu.User.Username() != wgPriv {
+		t.Fatalf("wg private key = %q, want inbound settings key %q (not merged %q)", wu.User.Username(), wgPriv, mergedPriv)
+	}
+	if got := wu.Query().Get("address"); got != "10.0.0.5/32" {
+		t.Fatalf("wg address = %q, want 10.0.0.5/32 (not merged 10.9.9.9/32)", got)
+	}
+
+	awgLinks := svc.inboundLinks(awgIb)
+	if len(awgLinks) != 1 {
+		t.Fatalf("awg links = %d, want 1: %v", len(awgLinks), awgLinks)
+	}
+	if !strings.HasPrefix(awgLinks[0], "vpn://") {
+		t.Fatalf("awg link = %q, want vpn:// prefix", awgLinks[0])
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(strings.TrimPrefix(awgLinks[0], "vpn://"))
+	if err != nil {
+		t.Fatalf("awg link decode: %v (%s)", err, awgLinks[0])
+	}
+	textCfg := string(raw)
+	if !strings.Contains(textCfg, "PrivateKey = "+awgPriv) {
+		t.Fatalf("awg config missing inbound private key %q:\n%s", awgPriv, textCfg)
+	}
+	if !strings.Contains(textCfg, "Address = 10.8.1.5/32") {
+		t.Fatalf("awg config missing inbound address 10.8.1.5/32:\n%s", textCfg)
+	}
+	if strings.Contains(textCfg, mergedPriv) || strings.Contains(textCfg, "10.9.9.9/32") {
+		t.Fatalf("awg config leaked merged clients-table tunnel identity:\n%s", textCfg)
+	}
+}

internal/sub/links_test.go

@@ -5,6 +5,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
 	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
 )
 
@@ -59,3 +60,40 @@ func TestLinksForClient_UsesHostEndpoints(t *testing.T) {
 		t.Fatalf("link = %q, want the host endpoint proxy.example.com:443", links[0])
 	}
 }
+
+// LinksForClient (per-client QR / links API) must use the clients-table UUID
+// when the inbound settings JSON still embeds a stale id — same source as
+// /inbounds/list and allLinks (#6436).
+func TestLinksForClient_UsesClientsTableUUIDWhenSettingsStale(t *testing.T) {
+	seedSubDB(t)
+	db := database.GetDB()
+	stale := "11111111-1111-1111-1111-111111111111"
+	fresh := "22222222-2222-2222-2222-222222222222"
+	settings := `{"clients":[{"id":"` + stale + `","email":"stale@e","subId":"subStale","enable":true}],"decryption":"none"}`
+	ib := &model.Inbound{
+		UserId: 1, Tag: "stale-uuid-qr", Enable: true, Listen: "203.0.113.5", Port: 4433,
+		Protocol: model.VLESS, Remark: "StaleQR", Settings: settings,
+		StreamSettings: `{"network":"tcp","security":"none","tcpSettings":{"header":{"type":"none"}}}`,
+	}
+	if err := db.Create(ib).Error; err != nil {
+		t.Fatalf("seed inbound: %v", err)
+	}
+	client := &model.ClientRecord{Email: "stale@e", SubID: "subStale", UUID: fresh, Enable: true}
+	if err := db.Create(client).Error; err != nil {
+		t.Fatalf("seed client: %v", err)
+	}
+	if err := db.Create(&model.ClientInbound{ClientId: client.Id, InboundId: ib.Id}).Error; err != nil {
+		t.Fatalf("seed client_inbound: %v", err)
+	}
+
+	links := NewLinkProvider().LinksForClient("req.example.com", ib, "stale@e")
+	if len(links) != 1 {
+		t.Fatalf("links = %d, want 1: %v", len(links), links)
+	}
+	if !strings.Contains(links[0], fresh) {
+		t.Fatalf("link missing fresh UUID %q: %s", fresh, links[0])
+	}
+	if strings.Contains(links[0], stale) {
+		t.Fatalf("link still carries stale settings UUID %q: %s", stale, links[0])
+	}
+}

internal/sub/service.go

@@ -142,8 +142,10 @@ func (s *SubService) primeLinkClients(inboundId int, clients []model.Client, com
 }
 
 // clientForLink resolves one client of an inbound by email for link
-// generation: from the per-request cache when primed, otherwise by parsing
-// the settings JSON once and caching every client from it.
+// generation: from the per-request cache when primed, otherwise via
+// clientsForLinkExport (clients-table UUID identity with settings-JSON
+// fallback for share-link protocols; settings JSON for WireGuard/AmneziaWG
+// tunnel fields) and caches the list.
 func (s *SubService) clientForLink(inbound *model.Inbound, email string) (model.Client, bool) {
 	if m, ok := s.clientsByInbound[inbound.Id]; ok {
 		if c, hit := m[email]; hit {
@@ -153,7 +155,7 @@ func (s *SubService) clientForLink(inbound *model.Inbound, email string) (model.
 			return model.Client{}, false
 		}
 	}
-	clients, err := s.inboundService.GetClients(inbound)
+	clients, err := s.clientsForLinkExport(inbound)
 	if err != nil {
 		return model.Client{}, false
 	}
@@ -166,6 +168,29 @@ func (s *SubService) clientForLink(inbound *model.Inbound, email string) (model.
 	return model.Client{}, false
 }
 
+// clientsForLinkExport returns the clients used to build share / QR / allLinks
+// exports for one inbound. UUID-bearing protocols prefer the normalized clients
+// table so the link matches the running Xray identity when settings JSON is
+// stale (#6436). When that list is empty or unavailable (settings-only inbounds,
+// unsynced rows, unit tests without a DB), fall back to GetClients so links
+// still generate from the embedded settings JSON (#6458). WireGuard and
+// AmneziaWG always keep the inbound's own settings JSON: private key,
+// AllowedIPs, and related tunnel fields are deliberately per-inbound there,
+// while the shared clients.wg_* columns collapse to whichever tunnel inbound
+// synced last (see TunnelAllowedIPsByInbound / amneziaWGClientAddresses).
+func (s *SubService) clientsForLinkExport(inbound *model.Inbound) ([]model.Client, error) {
+	if inbound.Protocol == model.WireGuard || inbound.Protocol == model.AmneziaWG {
+		return s.inboundService.GetClients(inbound)
+	}
+	if database.GetDB() != nil {
+		clients, err := s.inboundService.ListClientsForInbound(inbound.Id)
+		if err == nil && len(clients) > 0 {
+			return clients, nil
+		}
+	}
+	return s.inboundService.GetClients(inbound)
+}
+
 // linkSettings returns the inbound's settings decoded once per request with
 // the clients array left out — the link generators read only inbound-level
 // fields from it and resolve clients via clientForLink. The shallow
@@ -461,10 +486,12 @@ func (s *SubService) getSubs(subId string) ([]string, []string, int64, xray.Clie
 // inboundLinks builds the share links for every distinct client of one inbound
 // the same way getSubs does — managed Host endpoints win over the plain link so
 // {{HOST}} and per-host variants render — but across all clients rather than a
-// single subId. Dedups duplicate client JSON entries by email (#5134). Backs the
-// panel's "Export all inbound links" so it matches the client/QR pages.
+// single subId. Resolves clients via clientsForLinkExport so UUID-bearing
+// protocols match the running Xray config (#6436) while WireGuard/AmneziaWG
+// keep per-inbound tunnel identity from settings. Dedups by email (#5134).
+// Backs the panel's "Export all inbound links" and matches client/QR pages.
 func (s *SubService) inboundLinks(inbound *model.Inbound) []string {
-	clients, err := s.inboundService.GetClients(inbound)
+	clients, err := s.clientsForLinkExport(inbound)
 	if err != nil {
 		return nil
 	}

internal/web/service/inbound.go

@@ -573,6 +573,14 @@ func (s *InboundService) GetClientsBySubId(inboundId int, subId string) ([]model
 	return s.clientService.ListForInboundBySubId(nil, inboundId, subId)
 }
 
+// ListClientsForInbound returns every client attached to the inbound from the
+// normalized clients tables — the same source the running Xray config uses —
+// instead of parsing the embedded settings JSON, which can hold a stale UUID
+// after a client identity change (#6436).
+func (s *InboundService) ListClientsForInbound(inboundId int) ([]model.Client, error) {
+	return s.clientService.ListForInbound(nil, inboundId)
+}
+
 func (s *InboundService) GetAllEmails() ([]string, error) {
 	db := database.GetDB()
 	var emails []string

internal/web/service/inbound_clients.go

@@ -24,10 +24,12 @@ type CopyClientsResult struct {
 	Errors  []string `json:"errors"`
 }
 
-// enrichClientStats parses each inbound's clients once, fills in the
-// UUID/SubId fields on the preloaded ClientStats, and tops up rows owned by
-// a sibling inbound (shared-email mode — the row is keyed on email so it
-// only preloads on its owning inbound).
+// enrichClientStats resolves each inbound's clients from the clients table
+// once, fills in the UUID/SubId fields on the preloaded ClientStats, and tops
+// up rows owned by a sibling inbound (shared-email mode — the row is keyed on
+// email so it only preloads on its owning inbound). Reading identity from the
+// clients table keeps /inbounds/list in sync with the running Xray config
+// when the embedded settings JSON is stale (#6436).
 func (s *InboundService) enrichClientStats(db *gorm.DB, inbounds []*model.Inbound) {
 	if len(inbounds) == 0 {
 		return
@@ -55,13 +57,14 @@ func (s *InboundService) enrichClientStats(db *gorm.DB, inbounds []*model.Inboun
 // backfillClientStats tops up each inbound's preloaded ClientStats with rows
 // owned by a sibling inbound: client_traffics is keyed on email, so a client
 // attached to several inbounds has one row that only preloads on the inbound
-// it was created on. Returns the parsed clients per inbound for reuse.
+// it was created on. Returns the clients-table clients per inbound for reuse
+// (not the embedded settings JSON, which can lag the live UUID — #6436).
 func (s *InboundService) backfillClientStats(db *gorm.DB, inbounds []*model.Inbound) [][]model.Client {
 	clientsByInbound := make([][]model.Client, len(inbounds))
 	seenByInbound := make([]map[string]struct{}, len(inbounds))
 	missing := make(map[string]struct{})
 	for i, inbound := range inbounds {
-		clients, _ := s.GetClients(inbound)
+		clients, _ := s.clientService.ListForInbound(db, inbound.Id)
 		clientsByInbound[i] = clients
 		seen := make(map[string]struct{}, len(inbound.ClientStats))
 		for _, st := range inbound.ClientStats {

internal/web/service/inbound_clients_stale_uuid_test.go

@@ -0,0 +1,57 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+// GetInbounds must enrich ClientStats.UUID from the clients table, not the
+// embedded inbound settings JSON, when the two diverge (#6436).
+func TestEnrichClientStats_UsesClientsTableUUIDWhenSettingsStale(t *testing.T) {
+	setupBulkDB(t)
+	db := database.GetDB()
+	stale := "11111111-1111-1111-1111-111111111111"
+	fresh := "22222222-2222-2222-2222-222222222222"
+
+	ib := &model.Inbound{
+		UserId: 1, Tag: "stale-uuid-list", Enable: true, Listen: "0.0.0.0", Port: 8443,
+		Protocol: model.VLESS, Remark: "stale",
+		Settings:       `{"clients":[{"id":"` + stale + `","email":"stale@e","subId":"sub1","enable":true}],"decryption":"none"}`,
+		StreamSettings: `{"network":"tcp","security":"none"}`,
+	}
+	if err := db.Create(ib).Error; err != nil {
+		t.Fatalf("create inbound: %v", err)
+	}
+	rec := &model.ClientRecord{Email: "stale@e", SubID: "sub1", UUID: fresh, Enable: true}
+	if err := db.Create(rec).Error; err != nil {
+		t.Fatalf("create client: %v", err)
+	}
+	if err := db.Create(&model.ClientInbound{ClientId: rec.Id, InboundId: ib.Id}).Error; err != nil {
+		t.Fatalf("create client_inbound: %v", err)
+	}
+	if err := db.Create(&xray.ClientTraffic{InboundId: ib.Id, Email: "stale@e", Enable: true}).Error; err != nil {
+		t.Fatalf("create client_traffics: %v", err)
+	}
+
+	svc := &InboundService{}
+	inbounds, err := svc.GetInbounds(1)
+	if err != nil {
+		t.Fatalf("GetInbounds: %v", err)
+	}
+	if len(inbounds) != 1 {
+		t.Fatalf("inbounds = %d, want 1", len(inbounds))
+	}
+	if len(inbounds[0].ClientStats) != 1 {
+		t.Fatalf("ClientStats = %d, want 1", len(inbounds[0].ClientStats))
+	}
+	got := inbounds[0].ClientStats[0].UUID
+	if got != fresh {
+		t.Fatalf("ClientStats.UUID = %q, want fresh %q (settings still had stale %q)", got, fresh, stale)
+	}
+	if got == stale {
+		t.Fatalf("ClientStats.UUID still carries stale settings value %q", stale)
+	}
+}