feat: update agents.md and add a feat (#128)

* docs(agents): update knowledge base with encryption, API envelope, and build conventions

Add comprehensive documentation of project conventions including:
- Encryption patterns (AES with node secret PSK)
- API envelope structure (code, msg, data, ts)
- Build peculiarities (minify: false, rolldown-vite, UPX compression)
- Unique styles (flat monorepo, asymmetric Go layout, hybrid frontend mode)
- Module boundaries and anti-patterns
- Large file hotspots and code map references

Updated 7 AGENTS.md files across root and submodules.

* test(backend): add comprehensive dual-stack IP preference test suite

Added 43 tests covering:
- Core IP selection logic (selectTunnelDialHost)
- Node capability detection (nodeSupportsV4/V6)
- Address picker functions
- API contract tests for create/update/list
- Database compatibility (SQLite + PostgreSQL)

Fixed pre-existing broken test in federation_runtime_test.go

go-backend/internal/http/handler/dual_stack_test.go

@@ -0,0 +1,377 @@
+package handler
+
+import (
+	"testing"
+)
+
+// ---------------------------------------------------------------------------
+// nodeSupportsV4 / nodeSupportsV6
+// ---------------------------------------------------------------------------
+
+func TestNodeSupportsV4_Nil(t *testing.T) {
+	if nodeSupportsV4(nil) {
+		t.Fatal("nil node must not support v4")
+	}
+}
+
+func TestNodeSupportsV6_Nil(t *testing.T) {
+	if nodeSupportsV6(nil) {
+		t.Fatal("nil node must not support v6")
+	}
+}
+
+func TestNodeSupportsV4_ExplicitV4(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1"}
+	if !nodeSupportsV4(n) {
+		t.Fatal("explicit server_ip_v4 must support v4")
+	}
+}
+
+func TestNodeSupportsV6_ExplicitV6(t *testing.T) {
+	n := &nodeRecord{ServerIPv6: "2001:db8::1"}
+	if !nodeSupportsV6(n) {
+		t.Fatal("explicit server_ip_v6 must support v6")
+	}
+}
+
+func TestNodeSupportsV4_OnlyV6Set(t *testing.T) {
+	n := &nodeRecord{ServerIPv6: "2001:db8::1"}
+	if nodeSupportsV4(n) {
+		t.Fatal("node with only v6 should not support v4")
+	}
+}
+
+func TestNodeSupportsV6_OnlyV4Set(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1"}
+	if nodeSupportsV6(n) {
+		t.Fatal("node with only v4 should not support v6")
+	}
+}
+
+func TestNodeSupportsV4_DualStack(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1", ServerIPv6: "2001:db8::1"}
+	if !nodeSupportsV4(n) {
+		t.Fatal("dual-stack node must support v4")
+	}
+}
+
+func TestNodeSupportsV6_DualStack(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1", ServerIPv6: "2001:db8::1"}
+	if !nodeSupportsV6(n) {
+		t.Fatal("dual-stack node must support v6")
+	}
+}
+
+func TestNodeSupportsV4_LegacyV4Only(t *testing.T) {
+	n := &nodeRecord{ServerIP: "192.168.1.1"}
+	if !nodeSupportsV4(n) {
+		t.Fatal("legacy v4 ip in server_ip must support v4")
+	}
+	if nodeSupportsV6(n) {
+		t.Fatal("legacy v4 ip in server_ip must not support v6")
+	}
+}
+
+func TestNodeSupportsV6_LegacyV6Only(t *testing.T) {
+	n := &nodeRecord{ServerIP: "2001:db8::1"}
+	if !nodeSupportsV6(n) {
+		t.Fatal("legacy v6 ip in server_ip must support v6")
+	}
+	if nodeSupportsV4(n) {
+		t.Fatal("legacy v6 ip in server_ip must not support v4")
+	}
+}
+
+func TestNodeSupportsV4_EmptyNode(t *testing.T) {
+	n := &nodeRecord{}
+	if nodeSupportsV4(n) {
+		t.Fatal("empty node must not support v4")
+	}
+	if nodeSupportsV6(n) {
+		t.Fatal("empty node must not support v6")
+	}
+}
+
+func TestNodeSupportsV4_LegacyBracketed(t *testing.T) {
+	n := &nodeRecord{ServerIP: "[::1]"}
+	if nodeSupportsV4(n) {
+		t.Fatal("bracketed ipv6 must not support v4")
+	}
+	if !nodeSupportsV6(n) {
+		t.Fatal("bracketed ipv6 must support v6")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// pickNodeAddressV4 / pickNodeAddressV6
+// ---------------------------------------------------------------------------
+
+func TestPickNodeAddressV4_Nil(t *testing.T) {
+	if pickNodeAddressV4(nil) != "" {
+		t.Fatal("nil node must return empty")
+	}
+}
+
+func TestPickNodeAddressV6_Nil(t *testing.T) {
+	if pickNodeAddressV6(nil) != "" {
+		t.Fatal("nil node must return empty")
+	}
+}
+
+func TestPickNodeAddressV4_PreferExplicit(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1", ServerIP: "192.168.0.1"}
+	got := pickNodeAddressV4(n)
+	if got != "10.0.0.1" {
+		t.Fatalf("expected explicit v4 10.0.0.1, got %q", got)
+	}
+}
+
+func TestPickNodeAddressV4_FallbackLegacy(t *testing.T) {
+	n := &nodeRecord{ServerIP: "192.168.0.1"}
+	got := pickNodeAddressV4(n)
+	if got != "192.168.0.1" {
+		t.Fatalf("expected legacy 192.168.0.1, got %q", got)
+	}
+}
+
+func TestPickNodeAddressV6_PreferExplicit(t *testing.T) {
+	n := &nodeRecord{ServerIPv6: "2001:db8::1", ServerIP: "::1"}
+	got := pickNodeAddressV6(n)
+	if got != "2001:db8::1" {
+		t.Fatalf("expected explicit v6 2001:db8::1, got %q", got)
+	}
+}
+
+func TestPickNodeAddressV6_FallbackLegacy(t *testing.T) {
+	n := &nodeRecord{ServerIP: "::1"}
+	got := pickNodeAddressV6(n)
+	if got != "::1" {
+		t.Fatalf("expected legacy ::1, got %q", got)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// selectTunnelDialHost — core IP preference selection logic
+// ---------------------------------------------------------------------------
+
+func dualStackNode(name, v4, v6 string) *nodeRecord {
+	return &nodeRecord{
+		Name:       name,
+		ServerIPv4: v4,
+		ServerIPv6: v6,
+	}
+}
+
+func v4OnlyNode(name, v4 string) *nodeRecord {
+	return &nodeRecord{
+		Name:       name,
+		ServerIPv4: v4,
+	}
+}
+
+func v6OnlyNode(name, v6 string) *nodeRecord {
+	return &nodeRecord{
+		Name:       name,
+		ServerIPv6: v6,
+	}
+}
+
+func TestSelectTunnelDialHost_NilNodes(t *testing.T) {
+	_, err := selectTunnelDialHost(nil, nil, "")
+	if err == nil {
+		t.Fatal("expected error for nil nodes")
+	}
+	_, err = selectTunnelDialHost(dualStackNode("a", "1.1.1.1", "::1"), nil, "")
+	if err == nil {
+		t.Fatal("expected error for nil toNode")
+	}
+	_, err = selectTunnelDialHost(nil, dualStackNode("b", "1.1.1.1", "::1"), "")
+	if err == nil {
+		t.Fatal("expected error for nil fromNode")
+	}
+}
+
+func TestSelectTunnelDialHost_DualStack_DefaultPreference(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	host, err := selectTunnelDialHost(from, to, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// Default prefers v4 when both available
+	if host != "10.0.0.2" {
+		t.Fatalf("default preference should pick v4, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_DualStack_PreferV4(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("v4 preference should pick v4 address, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_DualStack_PreferV6(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("v6 preference should pick v6 address, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_V4Only_PreferV6Fallback(t *testing.T) {
+	from := v4OnlyNode("from", "10.0.0.1")
+	to := v4OnlyNode("to", "10.0.0.2")
+
+	// User prefers v6, but both nodes are v4-only — should fallback to v4
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("v6 preference on v4-only nodes should fallback to v4, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_V6Only_PreferV4Fallback(t *testing.T) {
+	from := v6OnlyNode("from", "2001:db8::1")
+	to := v6OnlyNode("to", "2001:db8::2")
+
+	// User prefers v4, but both nodes are v6-only — should fallback to v6
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("v4 preference on v6-only nodes should fallback to v6, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_Incompatible(t *testing.T) {
+	from := v4OnlyNode("from", "10.0.0.1")
+	to := v6OnlyNode("to", "2001:db8::2")
+
+	_, err := selectTunnelDialHost(from, to, "")
+	if err == nil {
+		t.Fatal("expected error for incompatible nodes (v4-only -> v6-only)")
+	}
+}
+
+func TestSelectTunnelDialHost_Incompatible_Reverse(t *testing.T) {
+	from := v6OnlyNode("from", "2001:db8::1")
+	to := v4OnlyNode("to", "10.0.0.2")
+
+	_, err := selectTunnelDialHost(from, to, "")
+	if err == nil {
+		t.Fatal("expected error for incompatible nodes (v6-only -> v4-only)")
+	}
+}
+
+func TestSelectTunnelDialHost_WhitespacePreference(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	// Whitespace should be trimmed, treated as "v6"
+	host, err := selectTunnelDialHost(from, to, "  v6  ")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("trimmed v6 preference should pick v6 address, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromDualToV4(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := v4OnlyNode("to", "10.0.0.2")
+
+	// v6 preferred, but target only has v4 — should succeed with v4
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("should fallback to v4 when target is v4-only, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromDualToV6(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := v6OnlyNode("to", "2001:db8::2")
+
+	// v4 preferred, but target only has v6 — should succeed with v6
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("should fallback to v6 when target is v6-only, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromV4ToDual(t *testing.T) {
+	from := v4OnlyNode("from", "10.0.0.1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	// v6 preferred, but from only has v4 — should use v4 (from can only reach v4 of target)
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("should use v4 when from is v4-only, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromV6ToDual(t *testing.T) {
+	from := v6OnlyNode("from", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	// v4 preferred, but from only has v6 — should use v6
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("should use v6 when from is v6-only, got %q", host)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// nodeDisplayName
+// ---------------------------------------------------------------------------
+
+func TestNodeDisplayName_Nil(t *testing.T) {
+	got := nodeDisplayName(nil)
+	if got != "node" {
+		t.Fatalf("nil node display name should be 'node', got %q", got)
+	}
+}
+
+func TestNodeDisplayName_Named(t *testing.T) {
+	n := &nodeRecord{ID: 42, Name: "hk-node"}
+	got := nodeDisplayName(n)
+	if got != "hk-node" {
+		t.Fatalf("expected 'hk-node', got %q", got)
+	}
+}
+
+func TestNodeDisplayName_Unnamed(t *testing.T) {
+	n := &nodeRecord{ID: 42}
+	got := nodeDisplayName(n)
+	if got != "node_42" {
+		t.Fatalf("expected 'node_42', got %q", got)
+	}
+}

go-backend/internal/http/handler/federation_runtime_test.go

@@ -56,14 +56,35 @@ func TestPickPeerSharePortUsesRuntimeReservations(t *testing.T) {
 	}
 }
 
-func TestApplyTunnelRuntimeSkipsRemoteNodes(t *testing.T) {
-	h := &Handler{}
+func TestApplyTunnelRuntimeSkipsRemoteChainAndOutNodes(t *testing.T) {
+	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "rt-skip.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer repo.Close()
+
+	h := &Handler{repo: repo}
+	now := time.Now().UnixMilli()
+	for _, n := range []struct {
+		id   int64
+		name string
+		ip   string
+	}{
+		{12, "remote-chain", "10.99.0.2"},
+		{13, "remote-out", "10.99.0.3"},
+	} {
+		if _, err := repo.DB().Exec(`
+			INSERT INTO node(id, name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx, is_remote, remote_url, remote_token)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, n.id, n.name, n.name+"-secret", n.ip, n.ip, "", "40000-40010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://remote-peer", "remote-token"); err != nil {
+			t.Fatalf("insert node %s: %v", n.name, err)
+		}
+	}
+
 	state := &tunnelCreateState{
 		TunnelID: 1,
 		Type:     2,
-		InNodes: []tunnelRuntimeNode{
-			{NodeID: 11, ChainType: 1, Protocol: "tls"},
-		},
+		InNodes:  []tunnelRuntimeNode{},
 		ChainHops: [][]tunnelRuntimeNode{
 			{
 				{NodeID: 12, ChainType: 2, Inx: 1, Port: 41000, Protocol: "tls", Strategy: "round"},
@@ -73,9 +94,8 @@ func TestApplyTunnelRuntimeSkipsRemoteNodes(t *testing.T) {
 			{NodeID: 13, ChainType: 3, Port: 42000, Protocol: "tls", Strategy: "round"},
 		},
 		Nodes: map[int64]*nodeRecord{
-			11: {ID: 11, Name: "remote-in", IsRemote: 1},
-			12: {ID: 12, Name: "remote-chain", IsRemote: 1},
-			13: {ID: 13, Name: "remote-out", IsRemote: 1},
+			12: {ID: 12, Name: "remote-chain", IsRemote: 1, ServerIPv4: "10.99.0.2"},
+			13: {ID: 13, Name: "remote-out", IsRemote: 1, ServerIPv4: "10.99.0.3"},
 		},
 	}
 
@@ -84,10 +104,10 @@ func TestApplyTunnelRuntimeSkipsRemoteNodes(t *testing.T) {
 		t.Fatalf("apply runtime: %v", err)
 	}
 	if len(chains) != 0 {
-		t.Fatalf("expected no local chains created, got %d", len(chains))
+		t.Fatalf("expected no local chains for remote-only nodes, got %d", len(chains))
 	}
 	if len(services) != 0 {
-		t.Fatalf("expected no local services created, got %d", len(services))
+		t.Fatalf("expected no local services for remote-only nodes, got %d", len(services))
 	}
 }
 

go-backend/internal/http/handler/mutations.go

@@ -497,6 +497,7 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 	status := asInt(req["status"], 1)
 	trafficRatio := asFloat(req["trafficRatio"], 1.0)
 	inIP := asString(req["inIp"])
+	ipPreference := asString(req["ipPreference"])
 	now := time.Now().UnixMilli()
 	inx := nextIndex(h.repo.DB(), "tunnel")
 
@@ -512,6 +513,7 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
+	runtimeState.IPPreference = ipPreference
 	if strings.TrimSpace(inIP) == "" {
 		inIP = buildTunnelInIP(runtimeState.InNodes, runtimeState.Nodes)
 	}
@@ -565,8 +567,8 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	tunnelID, err := tx.ExecReturningID(`INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-		name, trafficRatio, typeVal, "tls", flow, now, now, status, nullableText(inIP), inx)
+	tunnelID, err := tx.ExecReturningID(`INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx, ip_preference) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		name, trafficRatio, typeVal, "tls", flow, now, now, status, nullableText(inIP), inx, ipPreference)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
@@ -677,6 +679,7 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 
 	now := time.Now().UnixMilli()
 	typeVal := asInt(req["type"], 1)
+	ipPreference := asString(req["ipPreference"])
 
 	tx, err := h.repo.DB().Begin()
 	if err != nil {
@@ -691,6 +694,7 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	runtimeState.TunnelID = id
+	runtimeState.IPPreference = ipPreference
 
 	inIp := buildTunnelInIP(runtimeState.InNodes, runtimeState.Nodes)
 
@@ -703,8 +707,8 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 	}
 	applyTunnelPortsToRequest(req, runtimeState)
 
-	_, err = tx.Exec(`UPDATE tunnel SET name=?, type=?, flow=?, traffic_ratio=?, status=?, in_ip=?, updated_time=? WHERE id=?`,
-		asString(req["name"]), typeVal, asInt64(req["flow"], 1), asFloat(req["trafficRatio"], 1.0), asInt(req["status"], 1), nullableText(inIp), now, id)
+	_, err = tx.Exec(`UPDATE tunnel SET name=?, type=?, flow=?, traffic_ratio=?, status=?, in_ip=?, ip_preference=?, updated_time=? WHERE id=?`,
+		asString(req["name"]), typeVal, asInt64(req["flow"], 1), asFloat(req["trafficRatio"], 1.0), asInt(req["status"], 1), nullableText(inIp), ipPreference, now, id)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
@@ -838,14 +842,18 @@ func (h *Handler) reconstructTunnelState(tunnelID int64) (*tunnelCreateState, er
 		return nil, err
 	}
 
+	var ipPreference string
+	_ = h.repo.DB().QueryRow(`SELECT COALESCE(ip_preference, '') FROM tunnel WHERE id = ?`, tunnelID).Scan(&ipPreference)
+
 	state := &tunnelCreateState{
-		TunnelID:   tunnelID,
-		Type:       tunnel.Type,
-		InNodes:    make([]tunnelRuntimeNode, 0),
-		ChainHops:  make([][]tunnelRuntimeNode, 0),
-		OutNodes:   make([]tunnelRuntimeNode, 0),
-		Nodes:      make(map[int64]*nodeRecord),
-		NodeIDList: make([]int64, 0),
+		TunnelID:     tunnelID,
+		Type:         tunnel.Type,
+		IPPreference: ipPreference,
+		InNodes:      make([]tunnelRuntimeNode, 0),
+		ChainHops:    make([][]tunnelRuntimeNode, 0),
+		OutNodes:     make([]tunnelRuntimeNode, 0),
+		Nodes:        make(map[int64]*nodeRecord),
+		NodeIDList:   make([]int64, 0),
 	}
 
 	inNodes, chainHops, outNodes := splitChainNodeGroups(chainRows)
@@ -2145,13 +2153,14 @@ type tunnelRuntimeNode struct {
 }
 
 type tunnelCreateState struct {
-	TunnelID   int64
-	Type       int
-	InNodes    []tunnelRuntimeNode
-	ChainHops  [][]tunnelRuntimeNode
-	OutNodes   []tunnelRuntimeNode
-	Nodes      map[int64]*nodeRecord
-	NodeIDList []int64
+	TunnelID     int64
+	Type         int
+	IPPreference string // "" = auto, "v4" = prefer IPv4, "v6" = prefer IPv6
+	InNodes      []tunnelRuntimeNode
+	ChainHops    [][]tunnelRuntimeNode
+	OutNodes     []tunnelRuntimeNode
+	Nodes        map[int64]*nodeRecord
+	NodeIDList   []int64
 }
 
 func (h *Handler) prepareTunnelCreateState(tx *store.Tx, req map[string]interface{}, tunnelType int, excludeTunnelID int64) (*tunnelCreateState, error) {
@@ -2513,7 +2522,7 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState) ([]sqlite.Fed
 					h.releaseFederationRuntimeRefs(releaseRefs)
 					return nil, nil, errors.New("节点不存在")
 				}
-				host, hostErr := selectTunnelDialHost(node, targetNode)
+				host, hostErr := selectTunnelDialHost(node, targetNode, state.IPPreference)
 				if hostErr != nil {
 					h.releaseFederationRuntimeRefs(releaseRefs)
 					return nil, nil, hostErr
@@ -2669,7 +2678,7 @@ func (h *Handler) applyTunnelRuntime(state *tunnelCreateState) ([]int64, []int64
 		if len(state.ChainHops) > 0 {
 			targets = state.ChainHops[0]
 		}
-		chainData, err := buildTunnelChainConfig(state.TunnelID, inNode.NodeID, targets, state.Nodes)
+		chainData, err := buildTunnelChainConfig(state.TunnelID, inNode.NodeID, targets, state.Nodes, state.IPPreference)
 		if err != nil {
 			return createdChains, createdServices, err
 		}
@@ -2691,7 +2700,7 @@ func (h *Handler) applyTunnelRuntime(state *tunnelCreateState) ([]int64, []int64
 			if node := state.Nodes[chainNode.NodeID]; node != nil && node.IsRemote == 1 {
 				continue
 			}
-			chainData, err := buildTunnelChainConfig(state.TunnelID, chainNode.NodeID, nextTargets, state.Nodes)
+			chainData, err := buildTunnelChainConfig(state.TunnelID, chainNode.NodeID, nextTargets, state.Nodes, state.IPPreference)
 			if err != nil {
 				return createdChains, createdServices, err
 			}
@@ -2766,7 +2775,7 @@ func shouldDeferTunnelRuntimeApplyError(err error) bool {
 	return false
 }
 
-func buildTunnelChainConfig(tunnelID int64, fromNodeID int64, targets []tunnelRuntimeNode, nodes map[int64]*nodeRecord) (map[string]interface{}, error) {
+func buildTunnelChainConfig(tunnelID int64, fromNodeID int64, targets []tunnelRuntimeNode, nodes map[int64]*nodeRecord, ipPreference string) (map[string]interface{}, error) {
 	fromNode := nodes[fromNodeID]
 	if fromNode == nil {
 		return nil, errors.New("节点不存在")
@@ -2780,7 +2789,7 @@ func buildTunnelChainConfig(tunnelID int64, fromNodeID int64, targets []tunnelRu
 		if targetNode == nil {
 			return nil, errors.New("节点不存在")
 		}
-		host, err := selectTunnelDialHost(fromNode, targetNode)
+		host, err := selectTunnelDialHost(fromNode, targetNode, ipPreference)
 		if err != nil {
 			return nil, err
 		}
@@ -2853,7 +2862,7 @@ func buildTunnelChainServiceConfig(tunnelID int64, chainNode tunnelRuntimeNode,
 	return []map[string]interface{}{service}
 }
 
-func selectTunnelDialHost(fromNode, toNode *nodeRecord) (string, error) {
+func selectTunnelDialHost(fromNode, toNode *nodeRecord, ipPreference string) (string, error) {
 	if fromNode == nil || toNode == nil {
 		return "", errors.New("节点不存在")
 	}
@@ -2862,16 +2871,39 @@ func selectTunnelDialHost(fromNode, toNode *nodeRecord) (string, error) {
 	toV4 := nodeSupportsV4(toNode)
 	toV6 := nodeSupportsV6(toNode)
 
-	if fromV4 && toV4 {
-		host := pickNodeAddressV4(toNode)
-		if host != "" {
-			return host, nil
+	switch strings.TrimSpace(ipPreference) {
+	case "v6":
+		if fromV6 && toV6 {
+			if host := pickNodeAddressV6(toNode); host != "" {
+				return host, nil
+			}
 		}
-	}
-	if fromV6 && toV6 {
-		host := pickNodeAddressV6(toNode)
-		if host != "" {
-			return host, nil
+		if fromV4 && toV4 {
+			if host := pickNodeAddressV4(toNode); host != "" {
+				return host, nil
+			}
+		}
+	case "v4":
+		if fromV4 && toV4 {
+			if host := pickNodeAddressV4(toNode); host != "" {
+				return host, nil
+			}
+		}
+		if fromV6 && toV6 {
+			if host := pickNodeAddressV6(toNode); host != "" {
+				return host, nil
+			}
+		}
+	default:
+		if fromV4 && toV4 {
+			if host := pickNodeAddressV4(toNode); host != "" {
+				return host, nil
+			}
+		}
+		if fromV6 && toV6 {
+			if host := pickNodeAddressV6(toNode); host != "" {
+				return host, nil
+			}
 		}
 	}
 	return "", fmt.Errorf("节点链路不兼容：%s(v4=%t,v6=%t) -> %s(v4=%t,v6=%t)", nodeDisplayName(fromNode), fromV4, fromV6, nodeDisplayName(toNode), toV4, toV6)