fix(nodes): resolve agent public address from master-observed source IP

NAT'd agents (cloud 1:1 EIP) only ever report their private
interface address in heartbeat telemetry, so the node list showed
an unusable RFC1918 address. The master now records the source
address of every authenticated agent request (CF-Connecting-IP,
else first X-Forwarded-For hop, else RemoteAddr; change-only
writes) on the agent row as seen_ipv4/seen_ipv6, and the node
list resolves the displayed pair via service.ResolveAgentAddresses:
public telemetry wins, else a public observed source, else the
reported address as-is. CGNAT 100.64/10 observed addresses are
never promoted. Telemetry values are kept verbatim; resolution
is read-time only, and agents need no changes.

internal/web/service/agent_address.go

@@ -0,0 +1,92 @@
+package service
+
+import (
+	"net"
+	"strings"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+// Public-address resolution for agent nodes.
+//
+// An agent reports the addresses of its own network interfaces in its
+// heartbeat telemetry (P13). On a host behind 1:1 NAT (typical cloud
+// EIP setups) the public address is mapped in the provider's network
+// and never assigned to a local interface, so the agent can only ever
+// report its private address — the node list then shows an unusable
+// RFC1918 address for such nodes. The master, however, observes the
+// source address of every authenticated agent request (recorded on the
+// agent row as SeenIPv4/SeenIPv6 by AgentController.captureSeenIP).
+// ResolveAgentAddresses combines both views into the address pair a
+// client can actually connect to.
+
+// IsPublicIPLiteral reports whether s is an IP literal that is globally
+// routable: not loopback, link-local, multicast, unspecified, RFC1918,
+// ULA, or the CGNAT shared range 100.64.0.0/10 (RFC 6598 — not private,
+// but not publicly routable either). Go's IsGlobalUnicast alone is not
+// sufficient for this: it counts RFC1918 addresses as global unicast.
+//
+// Exported for reuse by the subscription/export chain.
+func IsPublicIPLiteral(s string) bool {
+	ip := net.ParseIP(strings.TrimSpace(s))
+	if ip == nil {
+		return false
+	}
+	if ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() ||
+		ip.IsMulticast() || ip.IsUnspecified() || ip.IsPrivate() {
+		return false
+	}
+	if v4 := ip.To4(); v4 != nil && v4[0] == 100 && v4[1]&0xC0 == 0x40 {
+		return false // 100.64.0.0/10, CGNAT shared address space
+	}
+	return true
+}
+
+// familyLiteral returns s normalized as an IP literal of the wanted
+// family, or "" when s is not a valid literal of that family.
+func familyLiteral(s string, want4 bool) string {
+	ip := net.ParseIP(strings.TrimSpace(s))
+	if ip == nil {
+		return ""
+	}
+	if want4 {
+		if v4 := ip.To4(); v4 != nil {
+			return v4.String()
+		}
+		return ""
+	}
+	if ip.To4() != nil {
+		return ""
+	}
+	return ip.String()
+}
+
+// resolveAddressFamily picks the externally usable address of one
+// family: the agent-reported address when it is public; otherwise the
+// master-observed source address when IT is public; otherwise the
+// reported address as-is (a private telemetry address still beats
+// nothing, e.g. for LAN-only deployments). A non-public observed
+// address is never promoted over the reported one.
+func resolveAddressFamily(reported, seen string, want4 bool) string {
+	rep := familyLiteral(reported, want4)
+	if IsPublicIPLiteral(rep) {
+		return rep
+	}
+	if sn := familyLiteral(seen, want4); IsPublicIPLiteral(sn) {
+		return sn
+	}
+	return rep
+}
+
+// ResolveAgentAddresses returns the externally usable IPv4/IPv6 pair
+// for an agent binding, resolved from its telemetry addresses and the
+// source addresses the master observed on its requests. This is the
+// single resolution point shared by the node list (agent row address)
+// and the subscription/export chain (advertised connect address).
+func ResolveAgentAddresses(ag *model.AgentNode) (ipv4, ipv6 string) {
+	if ag == nil {
+		return "", ""
+	}
+	return resolveAddressFamily(ag.IPv4, ag.SeenIPv4, true),
+		resolveAddressFamily(ag.IPv6, ag.SeenIPv6, false)
+}

internal/web/service/agent_address_test.go

@@ -0,0 +1,164 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+// Public-address resolution: the node list must show the address a
+// client can actually connect to. An agent behind 1:1 NAT only ever
+// reports its private interface address; the master-observed source
+// address (SeenIPv4/SeenIPv6) is the public side. Resolution order per
+// family: public telemetry > public observed > telemetry as-is.
+
+func TestIsPublicIPLiteral(t *testing.T) {
+	cases := map[string]bool{
+		"8.8.8.8":             true,
+		"111.91.29.150":       true,
+		"203.0.113.7":         true, // documentation range: not excluded (codebase treats it as public)
+		"2602:f32b:1:310f::1": true,
+		"2001:db8::7":         true,
+		"10.0.0.1":            false, // RFC1918
+		"172.31.2.240":        false, // RFC1918 (the HWSG case)
+		"192.168.1.1":         false, // RFC1918
+		"100.64.1.2":          false, // CGNAT shared space
+		"100.127.255.254":     false, // CGNAT shared space, top edge
+		"127.0.0.1":           false, // loopback
+		"169.254.1.1":         false, // link-local
+		"fd00::1":             false, // ULA
+		"fe80::1":             false, // link-local v6
+		"::1":                 false,
+		"::":                  false,
+		"224.0.0.1":           false, // multicast
+		"":                    false,
+		"not-an-ip":           false,
+		"999.1.1.1":           false,
+	}
+	for in, want := range cases {
+		if got := IsPublicIPLiteral(in); got != want {
+			t.Errorf("IsPublicIPLiteral(%q) = %v, want %v", in, got, want)
+		}
+	}
+}
+
+func TestResolveAgentAddresses(t *testing.T) {
+	cases := []struct {
+		name         string
+		ag           *model.AgentNode
+		want4, want6 string
+	}{
+		{
+			name:  "telemetry public wins over seen public",
+			ag:    &model.AgentNode{IPv4: "140.235.229.19", SeenIPv4: "8.8.8.8"},
+			want4: "140.235.229.19",
+		},
+		{
+			name:  "NAT: private telemetry, public seen",
+			ag:    &model.AgentNode{IPv4: "172.31.2.240", SeenIPv4: "111.91.29.150"},
+			want4: "111.91.29.150",
+		},
+		{
+			name:  "both private: telemetry fallback",
+			ag:    &model.AgentNode{IPv4: "172.31.2.240", SeenIPv4: "192.168.0.8"},
+			want4: "172.31.2.240",
+		},
+		{
+			name:  "no telemetry yet, public seen",
+			ag:    &model.AgentNode{SeenIPv4: "111.91.29.150"},
+			want4: "111.91.29.150",
+		},
+		{
+			name:  "CGNAT seen is not trusted",
+			ag:    &model.AgentNode{IPv4: "172.31.2.240", SeenIPv4: "100.64.1.2"},
+			want4: "172.31.2.240",
+		},
+		{
+			name:  "v6 only, telemetry public",
+			ag:    &model.AgentNode{IPv6: "2602:f32b:1:310f::1"},
+			want6: "2602:f32b:1:310f::1",
+		},
+		{
+			name:  "v6 ULA telemetry, public seen",
+			ag:    &model.AgentNode{IPv6: "fd00::1", SeenIPv6: "2401:1da0:22:148::a"},
+			want6: "2401:1da0:22:148::a",
+		},
+		{
+			name:  "garbage telemetry ignored",
+			ag:    &model.AgentNode{IPv4: "not-an-ip", SeenIPv4: "111.91.29.150"},
+			want4: "111.91.29.150",
+		},
+		{
+			name:  "families resolve independently",
+			ag:    &model.AgentNode{IPv4: "140.235.229.19", IPv6: "fd00::9", SeenIPv6: "2401:1da0:22:148::a"},
+			want4: "140.235.229.19",
+			want6: "2401:1da0:22:148::a",
+		},
+		{
+			name: "nothing known",
+			ag:   &model.AgentNode{},
+		},
+		{
+			name: "nil agent",
+			ag:   nil,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			v4, v6 := ResolveAgentAddresses(tc.ag)
+			if v4 != tc.want4 || v6 != tc.want6 {
+				t.Fatalf("ResolveAgentAddresses(%+v) = (%q, %q), want (%q, %q)",
+					tc.ag, v4, v6, tc.want4, tc.want6)
+			}
+		})
+	}
+}
+
+// Display: the node list row address comes from ResolveAgentAddresses,
+// including for an agent that has not reported telemetry yet.
+func TestAnnotateAgentTelemetryResolvedAddress(t *testing.T) {
+	setupConflictDB(t)
+	db := database.GetDB()
+
+	natNode := &model.Node{Id: 7501, Name: "nat-agent-node", Address: ""}
+	preNode := &model.Node{Id: 7502, Name: "pre-telemetry-agent-node", Address: ""}
+	for _, n := range []*model.Node{natNode, preNode} {
+		if err := db.Create(n).Error; err != nil {
+			t.Fatalf("create node %d: %v", n.Id, err)
+		}
+	}
+	nat := &model.AgentNode{
+		TokenHash: "hash-nat", Name: "nat-agent-node", NodeID: &natNode.Id,
+		AgentVersion: "A1.0.0", XrayVersion: "26.6.27", TelemetryAt: 1700000000000,
+		IPv4: "172.31.2.240", SeenIPv4: "111.91.29.150",
+	}
+	pre := &model.AgentNode{
+		TokenHash: "hash-pre", Name: "pre-telemetry-agent-node", NodeID: &preNode.Id,
+		SeenIPv4: "203.0.113.55", SeenIPAt: 1700000000000,
+	}
+	for _, ag := range []*model.AgentNode{nat, pre} {
+		if err := db.Create(ag).Error; err != nil {
+			t.Fatalf("create agent row: %v", err)
+		}
+	}
+
+	views := toNodeViews([]*model.Node{natNode, preNode})
+	annotateNodeTypes(views)
+	annotateAgentTelemetry(views)
+	byID := map[int]*NodeView{}
+	for _, v := range views {
+		byID[v.Id] = v
+	}
+
+	if got := byID[7501].Ipv4; got != "111.91.29.150" {
+		t.Fatalf("NAT node address = %q, want observed public 111.91.29.150 (view %+v)", got, byID[7501])
+	}
+	if got := byID[7502].Ipv4; got != "203.0.113.55" {
+		t.Fatalf("pre-telemetry node address = %q, want observed 203.0.113.55 (view %+v)", got, byID[7502])
+	}
+	// The pre-telemetry overlay must not invent other fields.
+	if pv := byID[7502]; pv.XrayVersion != "" || pv.UptimeSecs != 0 || pv.PanelVersion != "" {
+		t.Fatalf("pre-telemetry view picked up telemetry fields: %+v", pv)
+	}
+}

internal/web/service/node_contract.go

@@ -33,10 +33,11 @@ type NodeView struct {
 	// panel UI annotate it via annotateNodeTypes. Empty on views built
 	// outside those paths.
 	NodeType string `json:"nodeType,omitempty" example:"traditional"`
-	// Ipv4/Ipv6 carry the agent-reported host addresses for agent nodes
-	// (P13). The nodes page renders them as plain text on agent rows
-	// instead of the panel-URL link used for traditional nodes. Empty for
-	// traditional nodes and for agents that never reported telemetry.
+	// Ipv4/Ipv6 carry the resolved externally usable host addresses for
+	// agent nodes (P13 telemetry, public-address resolution on top).
+	// The nodes page renders them as plain text on agent rows instead
+	// of the panel-URL link used for traditional nodes. Empty for
+	// traditional nodes and for agents with no known address yet.
 	Ipv4          string  `json:"ipv4,omitempty" example:"203.0.113.7"`
 	Ipv6          string  `json:"ipv6,omitempty" example:"2001:db8::7"`
 	// Agent one-click update bookkeeping (item 20), agent nodes only:
@@ -171,9 +172,12 @@ func annotateNodeTypes(views []*NodeView) {
 // annotateAgentTelemetry overlays the latest heartbeat telemetry reported
 // by each node's bound agent onto its view (P13): xray version, the
 // "agent <version>" panel-version label, host uptime, node->master latency,
-// CPU/memory percentages and the host IPv4/IPv6 pair. Views for traditional
-// nodes (and agent nodes whose agent never reported telemetry) are left
-// exactly as built. Must run after annotateNodeTypes.
+// CPU/memory percentages and the host IPv4/IPv6 pair. The address pair is
+// the resolved externally usable one (ResolveAgentAddresses), not the raw
+// telemetry — a NAT'd agent only ever reports its private interface
+// address. Views for traditional nodes (and agent nodes whose agent never
+// reported telemetry) are left exactly as built. Must run after
+// annotateNodeTypes.
 func annotateAgentTelemetry(views []*NodeView) {
 	if len(views) == 0 {
 		return
@@ -198,7 +202,14 @@ func annotateAgentTelemetry(views []*NodeView) {
 			continue
 		}
 		ag, ok := byNode[v.Id]
-		if !ok || ag.TelemetryAt == 0 {
+		if !ok {
+			continue
+		}
+		// Address resolution applies to every bound agent, even before
+		// its first telemetry report: an agent that has only registered
+		// already has a master-observed source address.
+		v.Ipv4, v.Ipv6 = ResolveAgentAddresses(ag)
+		if ag.TelemetryAt == 0 {
 			continue
 		}
 		if ag.XrayVersion != "" {
@@ -221,8 +232,6 @@ func annotateAgentTelemetry(views []*NodeView) {
 		v.LatencyMs = ag.LatencyMs
 		v.CpuPct = ag.CpuPct
 		v.MemPct = ag.MemPct
-		v.Ipv4 = ag.IPv4
-		v.Ipv6 = ag.IPv6
 	}
 }