fix(backend): migrate PostgreSQL traffic columns from int4 to bigint (#290)

## Summary

- Widens legacy PostgreSQL traffic/quota columns from `integer` to
`bigint` to prevent int4 overflow
- Fixes federation share creation failure when traffic limits exceed 2GB
(e.g., `536870912000` bytes = 500GB)
- Bumps schema version from 4 to 5 with auto-migration on backend
startup

## Affected Tables

- `user`: `flow`, `in_flow`, `out_flow`
- `forward`: `in_flow`, `out_flow`
- `statistics_flow`: `flow`, `total_flow`
- `tunnel`: `flow`
- `user_tunnel`: `flow`, `in_flow`, `out_flow`
- `peer_share`: `max_bandwidth`, `current_flow`

## Test Plan

- ✅ Unit tests added for migration execution and error handling
- ✅ Contract tests passed
- ✅ Repository tests passed

Commands:
```bash
cd go-backend && go test ./internal/store/repo/...
cd go-backend && go test ./tests/contract/...
```

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

@@ -527,15 +527,17 @@ func controlForwardServiceCommand(bases []string, commandType string, send func(
 }
 
 func deleteForwardServiceCandidates(bases []string, send func(name string) error) error {
-	handled, lastNotFoundErr, err := controlForwardServiceCommand(bases, "DeleteService", send)
-	if err != nil {
-		return err
-	}
-	if handled {
-		return nil
-	}
-	if lastNotFoundErr != nil {
-		return nil
+	for _, base := range bases {
+		for _, name := range append([]string{base + "_tcp", base + "_udp", base}, []string{}...) {
+			err := send(name)
+			if err == nil {
+				continue
+			}
+			if isNotFoundError(err) {
+				continue
+			}
+			return err
+		}
 	}
 	return nil
 }
@@ -1477,10 +1479,11 @@ func isAlreadyExistsMessage(message string) bool {
 	if msg == "" {
 		return false
 	}
-	if strings.Contains(msg, "address already in use") {
+	if isAddressAlreadyInUseMessage(msg) {
 		return false
 	}
-	return strings.Contains(msg, "already exists") || strings.Contains(msg, "已存在")
+	compact := compactErrorMessage(msg)
+	return strings.Contains(msg, "already exists") || strings.Contains(msg, "已存在") || strings.Contains(compact, "alreadyexists")
 }
 
 func isBindAddressInUseError(err error) bool {
@@ -1505,7 +1508,10 @@ func isAddressAlreadyInUseMessage(msg string) bool {
 	if msg == "" {
 		return false
 	}
-	return strings.Contains(msg, "address already in use")
+	if strings.Contains(msg, "address already in use") {
+		return true
+	}
+	return strings.Contains(compactErrorMessage(msg), "addressalreadyinuse")
 }
 
 func isCannotAssignRequestedAddressError(err error) bool {
@@ -1516,7 +1522,18 @@ func isCannotAssignRequestedAddressError(err error) bool {
 	if msg == "" {
 		return false
 	}
-	return strings.Contains(msg, "cannot assign requested address")
+	if strings.Contains(msg, "cannot assign requested address") {
+		return true
+	}
+	return strings.Contains(compactErrorMessage(msg), "cannotassignrequestedaddress")
+}
+
+func compactErrorMessage(msg string) string {
+	msg = strings.TrimSpace(msg)
+	if msg == "" {
+		return ""
+	}
+	return strings.Join(strings.Fields(strings.ToLower(msg)), "")
 }
 
 func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel *tunnelRecord, node *nodeRecord, port int, bindIP string, limiterID *int64, tunnelTLSProtocol bool) []map[string]interface{} {

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

@@ -180,6 +180,27 @@ func TestDeleteForwardServiceBasesOnNodeRetriesLegacyZeroResidue(t *testing.T) {
 	}
 }
 
+func TestDeleteForwardServiceCandidatesDeletesAllMatchingVariants(t *testing.T) {
+	bases := []string{"57_7_7", "57_7_0"}
+	called := make([]string, 0)
+	err := deleteForwardServiceCandidates(bases, func(name string) error {
+		called = append(called, name)
+		switch name {
+		case "57_7_7_tcp", "57_7_7_udp", "57_7_0_tcp", "57_7_0_udp":
+			return nil
+		default:
+			return errors.New("service " + name + " not found")
+		}
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := []string{"57_7_7_tcp", "57_7_7_udp", "57_7_7", "57_7_0_tcp", "57_7_0_udp", "57_7_0"}
+	if !reflect.DeepEqual(called, want) {
+		t.Fatalf("expected calls %v, got %v", want, called)
+	}
+}
+
 func TestValidateForwardPortAvailabilityRejectsOtherForwardOccupancy(t *testing.T) {
 	h := &Handler{repo: nil}
 	node := &nodeRecord{ID: 9, Name: "test-node"}
@@ -235,9 +256,15 @@ func TestIsAlreadyExistsMessage(t *testing.T) {
 	if !isAlreadyExistsMessage("服务已存在") {
 		t.Fatalf("expected Chinese already exists message to be tolerated")
 	}
+	if !isAlreadyExistsMessage("service demo alreadyexists") {
+		t.Fatalf("missing-space alreadyexists should be tolerated")
+	}
 	if isAlreadyExistsMessage("listen tcp [::]:10001: bind: address already in use") {
 		t.Fatalf("address already in use must not be treated as already exists")
 	}
+	if isAlreadyExistsMessage("create service 57_7_7_tcp failed: listen tcp4 0.0.0.0:46222: bind: address alreadyin use") {
+		t.Fatalf("alreadyin-use variant must not be treated as already exists")
+	}
 }
 
 func TestIsBindAddressInUseError(t *testing.T) {
@@ -259,6 +286,9 @@ func TestIsAddressAlreadyInUseError(t *testing.T) {
 	if !isAddressAlreadyInUseError(errors.New("listen tcp [::]:10001: bind: address already in use")) {
 		t.Fatalf("address already in use should be detected")
 	}
+	if !isAddressAlreadyInUseError(errors.New("create service 57_7_7_tcp failed: listen tcp4 0.0.0.0:46222: bind: address alreadyin use")) {
+		t.Fatalf("missing-space alreadyin-use variant should be detected")
+	}
 	if isAddressAlreadyInUseError(errors.New("listen tcp4 13.228.170.187:16765: bind: cannot assign requested address")) {
 		t.Fatalf("cannot assign requested address should not be treated as address-in-use")
 	}
@@ -268,11 +298,83 @@ func TestIsCannotAssignRequestedAddressError(t *testing.T) {
 	if !isCannotAssignRequestedAddressError(errors.New("listen tcp4 13.228.170.187:16765: bind: cannot assign requested address")) {
 		t.Fatalf("cannot assign requested address should be detected")
 	}
+	if !isCannotAssignRequestedAddressError(errors.New("listen tcp4 13.228.170.187:16765: bind: cannotassignrequestedaddress")) {
+		t.Fatalf("missing-space cannotassignrequestedaddress variant should be detected")
+	}
 	if isCannotAssignRequestedAddressError(errors.New("listen tcp [::]:10001: bind: address already in use")) {
 		t.Fatalf("address already in use should not be treated as cannot-assign")
 	}
 }
 
+func TestRetryTunnelServiceAddWithCleanupRetriesOnAddressInUse(t *testing.T) {
+	addCalls := 0
+	cleanupCalls := 0
+	err := retryTunnelServiceAddWithCleanup(
+		func() error {
+			addCalls++
+			if addCalls == 1 {
+				return errors.New("listen tcp 10.0.0.1:32000: bind: address already in use")
+			}
+			return nil
+		},
+		func() error {
+			cleanupCalls++
+			return nil
+		},
+		0,
+	)
+	if err != nil {
+		t.Fatalf("expected retry to succeed, got %v", err)
+	}
+	if addCalls != 2 {
+		t.Fatalf("expected 2 add attempts, got %d", addCalls)
+	}
+	if cleanupCalls != 1 {
+		t.Fatalf("expected 1 cleanup attempt, got %d", cleanupCalls)
+	}
+}
+
+func TestRetryTunnelServiceAddWithCleanupSkipsCleanupOnNonBindError(t *testing.T) {
+	addCalls := 0
+	cleanupCalls := 0
+	err := retryTunnelServiceAddWithCleanup(
+		func() error {
+			addCalls++
+			return errors.New("network timeout")
+		},
+		func() error {
+			cleanupCalls++
+			return nil
+		},
+		0,
+	)
+	if err == nil {
+		t.Fatalf("expected hard error")
+	}
+	if addCalls != 1 {
+		t.Fatalf("expected 1 add attempt, got %d", addCalls)
+	}
+	if cleanupCalls != 0 {
+		t.Fatalf("expected 0 cleanup attempts, got %d", cleanupCalls)
+	}
+}
+
+func TestRetryTunnelServiceAddWithCleanupReturnsCleanupError(t *testing.T) {
+	cleanupErr := errors.New("delete failed")
+	err := retryTunnelServiceAddWithCleanup(
+		func() error {
+			return errors.New("listen tcp 10.0.0.1:32000: bind: address already in use")
+		},
+		func() error {
+			return cleanupErr
+		},
+		0,
+	)
+	if !errors.Is(err, cleanupErr) {
+		t.Fatalf("expected cleanup error %v, got %v", cleanupErr, err)
+	}
+}
+
 func TestBuildForwardServiceConfigs_UsesBindIPForListen(t *testing.T) {
 	forward := &forwardRecord{RemoteAddr: "1.2.3.4:80", Strategy: "fifo", TunnelID: 7}
 	node := &nodeRecord{TCPListenAddr: "[::]", UDPListenAddr: "[::]"}

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

@@ -43,6 +43,19 @@ func TestBuildTunnelChainServiceConfig_UsesConnectIPForListen(t *testing.T) {
 	}
 }
 
+func TestBuildTunnelChainServiceConfig_FallsBackToNodeListenAddr(t *testing.T) {
+	node := &nodeRecord{TCPListenAddr: "10.8.0.5"}
+	chain := tunnelRuntimeNode{Protocol: "tls", Port: 21002}
+	services := buildTunnelChainServiceConfig(99, chain, node)
+	if len(services) != 1 {
+		t.Fatalf("expected 1 service, got %d", len(services))
+	}
+	addr, _ := services[0]["addr"].(string)
+	if addr != "10.8.0.5:21002" {
+		t.Fatalf("expected node listen addr 10.8.0.5:21002, got %q", addr)
+	}
+}
+
 func TestBuildTunnelChainServiceConfig_DefaultListenAddrWhenConnectIPEmpty(t *testing.T) {
 	node := &nodeRecord{TCPListenAddr: "[::]"}
 	chain := tunnelRuntimeNode{Protocol: "tls", Port: 21001}

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

@@ -571,7 +571,7 @@ func (h *Handler) userTunnelList(w http.ResponseWriter, r *http.Request) {
 			"userId":         t.UserID,
 			"tunnelId":       t.TunnelID,
 			"tunnelName":     t.TunnelName,
-			"status":         1,
+			"status":         t.Status,
 			"flow":           t.Flow,
 			"num":            t.Num,
 			"expTime":        t.ExpTime,

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

@@ -25,6 +25,8 @@ import (
 	"gorm.io/gorm"
 )
 
+const tunnelServiceBindRetryDelay = 150 * time.Millisecond
+
 func (h *Handler) userCreate(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
@@ -1277,13 +1279,13 @@ func (h *Handler) forwardUpdate(w http.ResponseWriter, r *http.Request) {
 	if strategy == "" {
 		strategy = forward.Strategy
 	}
-	if actorRole != 0 {
-		if speedIDVal, ok := req["speedId"]; ok && speedIDVal != nil {
-			response.WriteJSON(w, response.Err(-1, "普通用户无法修改限速规则"))
-			return
-		}
+	rawSpeedID, hasSpeedID := req["speedId"]
+	requestedSpeedID := asAnyToInt64Ptr(rawSpeedID)
+	if actorRole != 0 && hasSpeedID && requestedSpeedID != nil && !sameSpeedLimitSelection(forward.SpeedID, requestedSpeedID) {
+		response.WriteJSON(w, response.Err(-1, "普通用户无法修改限速规则"))
+		return
 	}
-	speedID := asAnyToInt64Ptr(req["speedId"])
+	speedID := requestedSpeedID
 	speedID, err = h.normalizeSpeedLimitReference(speedID)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
@@ -2584,7 +2586,7 @@ func (h *Handler) applyTunnelRuntime(state *tunnelCreateState) ([]int64, []int64
 			createdChains = append(createdChains, chainNode.NodeID)
 
 			serviceData := buildTunnelChainServiceConfig(state.TunnelID, chainNode, state.Nodes[chainNode.NodeID])
-			if _, err := h.sendNodeCommand(chainNode.NodeID, "AddService", serviceData, true, false); err != nil {
+			if err := h.addTunnelServiceOnNode(chainNode.NodeID, state.TunnelID, serviceData); err != nil {
 				return createdChains, createdServices, fmt.Errorf("转发链节点 %s 下发服务失败: %w", nodeDisplayName(state.Nodes[chainNode.NodeID]), err)
 			}
 			createdServices = append(createdServices, chainNode.NodeID)
@@ -2596,7 +2598,7 @@ func (h *Handler) applyTunnelRuntime(state *tunnelCreateState) ([]int64, []int64
 			continue
 		}
 		serviceData := buildTunnelChainServiceConfig(state.TunnelID, outNode, state.Nodes[outNode.NodeID])
-		if _, err := h.sendNodeCommand(outNode.NodeID, "AddService", serviceData, true, false); err != nil {
+		if err := h.addTunnelServiceOnNode(outNode.NodeID, state.TunnelID, serviceData); err != nil {
 			return createdChains, createdServices, fmt.Errorf("出口节点 %s 下发服务失败: %w", nodeDisplayName(state.Nodes[outNode.NodeID]), err)
 		}
 		createdServices = append(createdServices, outNode.NodeID)
@@ -2605,6 +2607,44 @@ func (h *Handler) applyTunnelRuntime(state *tunnelCreateState) ([]int64, []int64
 	return createdChains, createdServices, nil
 }
 
+func retryTunnelServiceAddWithCleanup(add func() error, cleanup func() error, wait time.Duration) error {
+	if add == nil {
+		return errors.New("invalid tunnel service add callback")
+	}
+	err := add()
+	if err == nil || !isAddressAlreadyInUseError(err) {
+		return err
+	}
+	if cleanup == nil {
+		return err
+	}
+	if cleanupErr := cleanup(); cleanupErr != nil {
+		return cleanupErr
+	}
+	if wait > 0 {
+		time.Sleep(wait)
+	}
+	return add()
+}
+
+func (h *Handler) addTunnelServiceOnNode(nodeID, tunnelID int64, serviceData []map[string]interface{}) error {
+	if h == nil {
+		return errors.New("invalid tunnel service context")
+	}
+	serviceName := fmt.Sprintf("%d_tls", tunnelID)
+	return retryTunnelServiceAddWithCleanup(
+		func() error {
+			_, err := h.sendNodeCommand(nodeID, "AddService", serviceData, true, false)
+			return err
+		},
+		func() error {
+			_, err := h.sendNodeCommand(nodeID, "DeleteService", map[string]interface{}{"services": []string{serviceName}}, false, true)
+			return err
+		},
+		tunnelServiceBindRetryDelay,
+	)
+}
+
 func (h *Handler) rollbackTunnelRuntime(chainNodeIDs, serviceNodeIDs []int64, tunnelID int64) {
 	if h == nil || tunnelID <= 0 {
 		return
@@ -3340,6 +3380,14 @@ func (h *Handler) normalizeSpeedLimitReference(speedID *int64) (*int64, error) {
 	return speedID, nil
 }
 
+func sameSpeedLimitSelection(current sql.NullInt64, requested *int64) bool {
+	if requested == nil {
+		return !current.Valid
+	}
+
+	return current.Valid && current.Int64 == *requested
+}
+
 func asAnySlice(v interface{}) []interface{} {
 	if v == nil {
 		return nil

go-backend/internal/store/model/model.go

@@ -573,6 +573,7 @@ type UserTunnelDetail struct {
 	UserID        int64
 	TunnelID      int64
 	TunnelName    string
+	Status        int
 	TunnelFlow    int
 	Flow          int64
 	InFlow        int64

go-backend/internal/store/repo/repository.go

@@ -447,7 +447,7 @@ func (r *Repository) GetUserPackageTunnels(userID int64) ([]model.UserTunnelDeta
 	}
 	var items []model.UserTunnelDetail
 	err := r.db.Model(&model.UserTunnel{}).
-		Select("user_tunnel.id, user_tunnel.user_id, user_tunnel.tunnel_id, tunnel.name AS tunnel_name, tunnel.flow AS tunnel_flow, user_tunnel.flow, user_tunnel.in_flow, user_tunnel.out_flow, user_tunnel.num, user_tunnel.flow_reset_time, user_tunnel.exp_time, user_tunnel.speed_id, speed_limit.name AS speed_limit, speed_limit.speed").
+		Select("user_tunnel.id, user_tunnel.user_id, user_tunnel.tunnel_id, tunnel.name AS tunnel_name, user_tunnel.status, tunnel.flow AS tunnel_flow, user_tunnel.flow, user_tunnel.in_flow, user_tunnel.out_flow, user_tunnel.num, user_tunnel.flow_reset_time, user_tunnel.exp_time, user_tunnel.speed_id, speed_limit.name AS speed_limit, speed_limit.speed").
 		Joins("LEFT JOIN tunnel ON tunnel.id = user_tunnel.tunnel_id").
 		Joins("LEFT JOIN speed_limit ON speed_limit.id = user_tunnel.speed_id").
 		Where("user_tunnel.user_id = ?", userID).
@@ -2612,11 +2612,12 @@ func (r *Repository) GetUserTunnelByID(id int64) (*model.UserTunnel, error) {
 
 // ─── Migration ───────────────────────────────────────────────────────
 
-const currentSchemaVersion = 4
+const currentSchemaVersion = 5
 
 var ensurePostgresIDDefaultsFn = ensurePostgresIDDefaults
 var migrateViteConfigValueColumnTypeFn = migrateViteConfigValueColumnType
 var migrateSpeedLimitTunnelBindingFn = migrateSpeedLimitTunnelBinding
+var migratePostgresTrafficInt64ColumnsFn = migratePostgresTrafficInt64Columns
 
 func getSchemaVersion(db *gorm.DB) int {
 	var v model.SchemaVersion
@@ -2680,6 +2681,12 @@ func migrateSchema(db *gorm.DB) error {
 		}
 	}
 
+	if ver < 5 {
+		if err := migratePostgresTrafficInt64ColumnsFn(db); err != nil {
+			return err
+		}
+	}
+
 	setSchemaVersion(db, currentSchemaVersion)
 	return nil
 }
@@ -2744,6 +2751,87 @@ func migrateSpeedLimitTunnelBinding(db *gorm.DB) error {
 	return nil
 }
 
+func migratePostgresTrafficInt64Columns(db *gorm.DB) error {
+	if db == nil {
+		return errors.New("nil db")
+	}
+
+	if db.Dialector.Name() != "postgres" {
+		return nil
+	}
+
+	type trafficColumn struct {
+		TableName  string
+		ColumnName string
+	}
+
+	columns := []trafficColumn{
+		{TableName: "user", ColumnName: "flow"},
+		{TableName: "user", ColumnName: "in_flow"},
+		{TableName: "user", ColumnName: "out_flow"},
+		{TableName: "forward", ColumnName: "in_flow"},
+		{TableName: "forward", ColumnName: "out_flow"},
+		{TableName: "statistics_flow", ColumnName: "flow"},
+		{TableName: "statistics_flow", ColumnName: "total_flow"},
+		{TableName: "tunnel", ColumnName: "flow"},
+		{TableName: "user_tunnel", ColumnName: "flow"},
+		{TableName: "user_tunnel", ColumnName: "in_flow"},
+		{TableName: "user_tunnel", ColumnName: "out_flow"},
+		{TableName: "peer_share", ColumnName: "max_bandwidth"},
+		{TableName: "peer_share", ColumnName: "current_flow"},
+	}
+
+	for _, column := range columns {
+		if err := alterPostgresColumnToBigIntIfNeeded(db, column.TableName, column.ColumnName); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func alterPostgresColumnToBigIntIfNeeded(db *gorm.DB, tableName, columnName string) error {
+	if db == nil {
+		return errors.New("nil db")
+	}
+
+	if tableName == "" || columnName == "" {
+		return errors.New("empty table or column name")
+	}
+
+	type columnRow struct {
+		DataType string `gorm:"column:data_type"`
+	}
+
+	var row columnRow
+	if err := db.Raw(
+		`SELECT data_type FROM information_schema.columns
+		 WHERE table_schema = current_schema()
+		   AND table_name = ?
+		   AND column_name = ?`,
+		tableName, columnName,
+	).Scan(&row).Error; err != nil {
+		return fmt.Errorf("inspect %s.%s type: %w", tableName, columnName, err)
+	}
+
+	if row.DataType == "" || strings.EqualFold(row.DataType, "bigint") {
+		return nil
+	}
+	if !strings.EqualFold(row.DataType, "integer") {
+		return nil
+	}
+
+	if err := db.Exec(fmt.Sprintf(
+		"ALTER TABLE %s ALTER COLUMN %s TYPE BIGINT",
+		quoteSQLIdentifier(tableName),
+		quoteSQLIdentifier(columnName),
+	)).Error; err != nil {
+		return fmt.Errorf("alter %s.%s to bigint: %w", tableName, columnName, err)
+	}
+
+	return nil
+}
+
 func ensurePostgresIDDefaults(db *gorm.DB) error {
 	if db.Dialector.Name() != "postgres" {
 		return nil

go-backend/internal/store/repo/repository_migrate_test.go

@@ -3,6 +3,7 @@ package repo
 import (
 	"database/sql"
 	"errors"
+	"strings"
 	"testing"
 
 	gsqlite "github.com/glebarez/sqlite"
@@ -250,3 +251,115 @@ func TestMigrateSchemaClearsSpeedLimitTunnelBinding(t *testing.T) {
 		t.Fatalf("expected schema version %d, got %d", currentSchemaVersion, schemaVersion)
 	}
 }
+
+func TestMigrateSchemaRunsTrafficInt64MigrationForLegacySchema(t *testing.T) {
+	db, err := gorm.Open(gsqlite.Open(":memory:"), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() {
+		sqlDB, _ := db.DB()
+		if sqlDB != nil {
+			_ = sqlDB.Close()
+		}
+	})
+
+	if err := db.Exec(`CREATE TABLE schema_version (version INTEGER NOT NULL DEFAULT 0)`).Error; err != nil {
+		t.Fatalf("create schema_version: %v", err)
+	}
+	if err := db.Exec(`INSERT INTO schema_version(version) VALUES(?)`, 4).Error; err != nil {
+		t.Fatalf("seed schema_version: %v", err)
+	}
+
+	originalIDRepair := ensurePostgresIDDefaultsFn
+	ensurePostgresIDDefaultsFn = func(db *gorm.DB) error {
+		return nil
+	}
+	t.Cleanup(func() {
+		ensurePostgresIDDefaultsFn = originalIDRepair
+	})
+
+	called := 0
+	originalMigrate := migratePostgresTrafficInt64ColumnsFn
+	migratePostgresTrafficInt64ColumnsFn = func(db *gorm.DB) error {
+		called++
+		return nil
+	}
+	t.Cleanup(func() {
+		migratePostgresTrafficInt64ColumnsFn = originalMigrate
+	})
+
+	if err := migrateSchema(db); err != nil {
+		t.Fatalf("migrateSchema: %v", err)
+	}
+
+	if called != 1 {
+		t.Fatalf("expected traffic bigint migration to run once, got %d", called)
+	}
+
+	var schemaVersion int
+	if err := db.Raw(`SELECT version FROM schema_version LIMIT 1`).Row().Scan(&schemaVersion); err != nil {
+		t.Fatalf("query schema_version: %v", err)
+	}
+	if schemaVersion != currentSchemaVersion {
+		t.Fatalf("expected schema version %d, got %d", currentSchemaVersion, schemaVersion)
+	}
+}
+
+func TestMigrateSchemaReturnsTrafficInt64MigrationError(t *testing.T) {
+	db, err := gorm.Open(gsqlite.Open(":memory:"), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() {
+		sqlDB, _ := db.DB()
+		if sqlDB != nil {
+			_ = sqlDB.Close()
+		}
+	})
+
+	if err := db.Exec(`CREATE TABLE schema_version (version INTEGER NOT NULL DEFAULT 0)`).Error; err != nil {
+		t.Fatalf("create schema_version: %v", err)
+	}
+	if err := db.Exec(`INSERT INTO schema_version(version) VALUES(?)`, 4).Error; err != nil {
+		t.Fatalf("seed schema_version: %v", err)
+	}
+
+	originalIDRepair := ensurePostgresIDDefaultsFn
+	ensurePostgresIDDefaultsFn = func(db *gorm.DB) error {
+		return nil
+	}
+	t.Cleanup(func() {
+		ensurePostgresIDDefaultsFn = originalIDRepair
+	})
+
+	wantErr := errors.New("traffic bigint migration failed")
+	originalMigrate := migratePostgresTrafficInt64ColumnsFn
+	migratePostgresTrafficInt64ColumnsFn = func(db *gorm.DB) error {
+		return wantErr
+	}
+	t.Cleanup(func() {
+		migratePostgresTrafficInt64ColumnsFn = originalMigrate
+	})
+
+	err = migrateSchema(db)
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("expected error %v, got %v", wantErr, err)
+	}
+}
+
+func TestAlterPostgresColumnToBigIntIfNeededValidatesNames(t *testing.T) {
+	if err := alterPostgresColumnToBigIntIfNeeded(nil, "peer_share", "max_bandwidth"); err == nil || !strings.Contains(err.Error(), "nil db") {
+		t.Fatalf("expected nil db error, got %v", err)
+	}
+	if err := alterPostgresColumnToBigIntIfNeeded(&gorm.DB{}, "", "max_bandwidth"); err == nil || !strings.Contains(err.Error(), "empty table or column name") {
+		t.Fatalf("expected empty name error, got %v", err)
+	}
+	if err := alterPostgresColumnToBigIntIfNeeded(&gorm.DB{}, "peer_share", ""); err == nil || !strings.Contains(err.Error(), "empty table or column name") {
+		t.Fatalf("expected empty name error, got %v", err)
+	}
+}

go-backend/tests/contract/forward_contract_test.go

@@ -7,6 +7,8 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strconv"
+	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -914,6 +916,164 @@ func TestForwardCreateThenPauseResumeContract(t *testing.T) {
 	}
 }
 
+func TestForwardUpdateRecoversFromAddressInUseContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(202, 'forward_bind_retry_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-bind-retry-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "forward-bind-retry-tunnel")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO node(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)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-bind-retry-node", "forward-bind-retry-secret", "10.42.0.1", "10.42.0.1", "", "44000-44010", "", "v1", 1, 1, 1, now, now, 1, "10.42.0.9", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, repo, "forward-bind-retry-node")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 44001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(41, 202, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	createPayload := map[string]interface{}{
+		"name":       "forward-bind-retry-target",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "1.1.1.1:443",
+		"strategy":   "fifo",
+	}
+	createBody, err := json.Marshal(createPayload)
+	if err != nil {
+		t.Fatalf("marshal create payload: %v", err)
+	}
+
+	var mu sync.Mutex
+	counts := map[string]int{}
+	var addServiceAddrs []string
+	triggerConflict := false
+	stopNode := startMockNodeSessionWithCommandRecorder(t, server.URL, "forward-bind-retry-secret", func(cmdType string, data json.RawMessage) (bool, string) {
+		key := strings.ToLower(strings.TrimSpace(cmdType))
+		mu.Lock()
+		counts[key]++
+		attempt := counts[key]
+		if strings.EqualFold(strings.TrimSpace(cmdType), "AddService") || strings.EqualFold(strings.TrimSpace(cmdType), "UpdateService") {
+			var services []map[string]interface{}
+			if err := json.Unmarshal(data, &services); err == nil {
+				for _, svc := range services {
+					if addr, _ := svc["addr"].(string); strings.TrimSpace(addr) != "" {
+						addServiceAddrs = append(addServiceAddrs, addr)
+					}
+				}
+			}
+		}
+		shouldFail := false
+		if triggerConflict {
+			if strings.EqualFold(strings.TrimSpace(cmdType), "UpdateService") && attempt == 1 {
+				shouldFail = true
+			}
+			if strings.EqualFold(strings.TrimSpace(cmdType), "AddService") && attempt == 1 {
+				shouldFail = true
+			}
+		}
+		mu.Unlock()
+		if shouldFail {
+			return true, "create service 57_7_7_tcp failed: listen tcp4 0.0.0.0:46222: bind: address alreadyin use"
+		}
+		return false, ""
+	})
+	defer stopNode()
+	waitNodeStatus(t, repo, nodeID, 1)
+
+	createReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+	createReq.Header.Set("Authorization", adminToken)
+	createReq.Header.Set("Content-Type", "application/json")
+	createRes := httptest.NewRecorder()
+	router.ServeHTTP(createRes, createReq)
+	assertCode(t, createRes, 0)
+	mu.Lock()
+	counts = map[string]int{}
+	addServiceAddrs = nil
+	triggerConflict = true
+	mu.Unlock()
+
+	forwardID := mustLastInsertID(t, repo, "forward-bind-retry-target")
+
+	updatePayload := map[string]interface{}{
+		"id":         forwardID,
+		"name":       "forward-bind-retry-target-updated",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "9.9.9.9:8443",
+		"strategy":   "fifo",
+	}
+	updateBody, err := json.Marshal(updatePayload)
+	if err != nil {
+		t.Fatalf("marshal update payload: %v", err)
+	}
+	updateReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/update", bytes.NewReader(updateBody))
+	updateReq.Header.Set("Authorization", adminToken)
+	updateReq.Header.Set("Content-Type", "application/json")
+	updateRes := httptest.NewRecorder()
+	router.ServeHTTP(updateRes, updateReq)
+	assertCode(t, updateRes, 0)
+
+	mu.Lock()
+	defer mu.Unlock()
+	boundPort := mustQueryInt(t, repo, `SELECT port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
+	if counts["updateservice"] != 1 {
+		t.Fatalf("expected one UpdateService attempt, got %d (%v)", counts["updateservice"], counts)
+	}
+	if counts["deleteservice"] == 0 {
+		t.Fatalf("expected DeleteService cleanup after address-in-use (%v)", counts)
+	}
+	if counts["addservice"] < 2 {
+		t.Fatalf("expected AddService retry path to run at least twice total, got %d (%v)", counts["addservice"], counts)
+	}
+	foundBindAddr := false
+	for _, addr := range addServiceAddrs {
+		if addr == "10.42.0.9:"+strconv.Itoa(boundPort) {
+			foundBindAddr = true
+			break
+		}
+	}
+	if !foundBindAddr {
+		t.Fatalf("expected forward runtime to keep node listen addr 10.42.0.9:%d, got %v", boundPort, addServiceAddrs)
+	}
+
+	storedRemoteAddr := mustQueryString(t, repo, `SELECT remote_addr FROM forward WHERE id = ?`, forwardID)
+	if storedRemoteAddr != "9.9.9.9:8443" {
+		t.Fatalf("expected remote_addr update to persist, got %q", storedRemoteAddr)
+	}
+}
+
 func jsonNumber(v int64) string {
 	return strconv.FormatInt(v, 10)
 }
@@ -1150,6 +1310,30 @@ func TestNonAdminCannotSetSpeedIdOrPort(t *testing.T) {
 		assertCode(t, res, 0)
 	})
 
+	t.Run("non-admin can update when request keeps existing speedId", func(t *testing.T) {
+		if err := repo.DB().Exec(`UPDATE forward SET speed_id = ? WHERE id = ?`, speedID, forwardID).Error; err != nil {
+			t.Fatalf("assign forward speed limit: %v", err)
+		}
+
+		updatePayload := map[string]interface{}{
+			"id":         forwardID,
+			"name":       "perm-forward-keep-speed",
+			"tunnelId":   tunnelID,
+			"remoteAddr": "9.10.11.12:443",
+			"speedId":    speedID,
+		}
+		updateBody, err := json.Marshal(updatePayload)
+		if err != nil {
+			t.Fatalf("marshal update payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/update", bytes.NewReader(updateBody))
+		req.Header.Set("Authorization", userToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	})
+
 	t.Run("non-admin can create with speedId null and inPort 0", func(t *testing.T) {
 		createPayload := map[string]interface{}{
 			"name":       "perm-forward-null-values",

go-backend/tests/contract/limiter_sync_failure_contract_test.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"sort"
 	"strings"
 	"sync"
 	"testing"
@@ -538,6 +539,134 @@ func TestBatchAssignInsertRollbackWhenLimiterDispatchFailsContract(t *testing.T)
 	}
 }
 
+func TestTunnelUpdateRecoversFromAddressInUseContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "tunnel-bind-retry", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "tunnel-bind-retry")
+
+	if err := r.DB().Exec(`
+		INSERT INTO node(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)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "tunnel-bind-entry", "tunnel-bind-entry-secret", "10.41.0.1", "10.41.0.1", "", "43000-43010", "", "v1", 1, 1, 1, now, now, 1, "10.41.0.1", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert entry node: %v", err)
+	}
+	entryNodeID := mustLastInsertID(t, r, "tunnel-bind-entry")
+
+	if err := r.DB().Exec(`
+		INSERT INTO node(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)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "tunnel-bind-exit", "tunnel-bind-exit-secret", "10.41.0.2", "10.41.0.2", "", "43100-43110", "eth0", "v1", 1, 1, 1, now, now, 1, "10.41.0.9", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert exit node: %v", err)
+	}
+	exitNodeID := mustLastInsertID(t, r, "tunnel-bind-exit")
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 43001, 'round', 1, 'tls')
+	`, tunnelID, entryNodeID).Error; err != nil {
+		t.Fatalf("insert entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol, connect_ip)
+		VALUES(?, 3, ?, 43101, 'round', 1, 'tls', ?)
+	`, tunnelID, exitNodeID, "10.41.0.99").Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	var commandMu sync.Mutex
+	commandCounts := map[string]int{}
+	var addServiceAddrs []string
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "tunnel-bind-entry-secret", func(cmdType string, data json.RawMessage) (bool, string) {
+		commandMu.Lock()
+		defer commandMu.Unlock()
+		commandCounts["entry:"+strings.ToLower(strings.TrimSpace(cmdType))]++
+		return false, ""
+	})
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "tunnel-bind-exit-secret", func(cmdType string, data json.RawMessage) (bool, string) {
+		key := "exit:" + strings.ToLower(strings.TrimSpace(cmdType))
+		commandMu.Lock()
+		commandCounts[key]++
+		attempt := commandCounts[key]
+		if strings.EqualFold(strings.TrimSpace(cmdType), "AddService") {
+			var services []map[string]interface{}
+			if err := json.Unmarshal(data, &services); err == nil {
+				for _, svc := range services {
+					if addr, _ := svc["addr"].(string); strings.TrimSpace(addr) != "" {
+						addServiceAddrs = append(addServiceAddrs, addr)
+					}
+				}
+			}
+		}
+		commandMu.Unlock()
+		if strings.EqualFold(strings.TrimSpace(cmdType), "AddService") && attempt == 1 {
+			return true, "listen tcp 10.41.0.99:43101: bind: address already in use"
+		}
+		return false, ""
+	})
+	defer stopExit()
+	waitNodeStatus(t, r, entryNodeID, 1)
+	waitNodeStatus(t, r, exitNodeID, 1)
+
+	payload := map[string]interface{}{
+		"id":           tunnelID,
+		"name":         "tunnel-bind-retry",
+		"type":         2,
+		"flow":         99999,
+		"trafficRatio": 1.0,
+		"status":       1,
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": entryNodeID, "protocol": "tls", "strategy": "round"},
+		},
+		"chainNodes": []interface{}{},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 43101, "connectIp": "10.41.0.99"},
+		},
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+
+	commandMu.Lock()
+	defer commandMu.Unlock()
+	if commandCounts["exit:addservice"] != 2 {
+		t.Fatalf("expected exit AddService twice, got %d (%v)", commandCounts["exit:addservice"], sortedCommandCounts(commandCounts))
+	}
+	if commandCounts["exit:deleteservice"] == 0 {
+		t.Fatalf("expected exit DeleteService retry cleanup to run (%v)", sortedCommandCounts(commandCounts))
+	}
+	if len(addServiceAddrs) < 2 {
+		t.Fatalf("expected recorded AddService addresses, got %v", addServiceAddrs)
+	}
+	for _, addr := range addServiceAddrs {
+		if addr != "10.41.0.99:43101" {
+			t.Fatalf("expected connectIp to stay preferred in AddService addr, got %q", addr)
+		}
+	}
+}
+
 func startMockNodeSessionWithCommandFailures(t *testing.T, baseURL string, nodeSecret string, failCommands map[string]string) func() {
 	t.Helper()
 
@@ -633,3 +762,112 @@ func startMockNodeSessionWithCommandFailures(t *testing.T, baseURL string, nodeS
 		})
 	}
 }
+
+func startMockNodeSessionWithCommandRecorder(t *testing.T, baseURL string, nodeSecret string, onCommand func(cmdType string, data json.RawMessage) (bool, string)) func() {
+	t.Helper()
+
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		t.Fatalf("parse provider url: %v", err)
+	}
+	if strings.EqualFold(u.Scheme, "https") {
+		u.Scheme = "wss"
+	} else {
+		u.Scheme = "ws"
+	}
+	u.Path = "/system-info"
+	q := u.Query()
+	q.Set("type", "1")
+	q.Set("secret", nodeSecret)
+	q.Set("version", "v1")
+	q.Set("http", "1")
+	q.Set("tls", "1")
+	q.Set("socks", "1")
+	u.RawQuery = q.Encode()
+
+	conn, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
+	if err != nil {
+		t.Fatalf("dial mock node websocket: %v", err)
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for {
+			_, raw, readErr := conn.ReadMessage()
+			if readErr != nil {
+				return
+			}
+
+			plain := raw
+			var wrap struct {
+				Encrypted bool   `json:"encrypted"`
+				Data      string `json:"data"`
+			}
+			if err := json.Unmarshal(raw, &wrap); err == nil && wrap.Encrypted && strings.TrimSpace(wrap.Data) != "" {
+				crypto, cryptoErr := security.NewAESCrypto(nodeSecret)
+				if cryptoErr == nil {
+					if dec, decErr := crypto.Decrypt(wrap.Data); decErr == nil {
+						plain = []byte(dec)
+					}
+				}
+			}
+
+			var cmd struct {
+				Type      string          `json:"type"`
+				RequestID string          `json:"requestId"`
+				Data      json.RawMessage `json:"data"`
+			}
+			if err := json.Unmarshal(plain, &cmd); err != nil {
+				continue
+			}
+			if strings.TrimSpace(cmd.RequestID) == "" {
+				continue
+			}
+
+			shouldFail := false
+			failMsg := ""
+			if onCommand != nil {
+				shouldFail, failMsg = onCommand(strings.TrimSpace(cmd.Type), cmd.Data)
+			}
+
+			respType := fmt.Sprintf("%sResponse", cmd.Type)
+			respPayload := map[string]interface{}{
+				"type":      respType,
+				"success":   !shouldFail,
+				"message":   "OK",
+				"requestId": cmd.RequestID,
+			}
+			if shouldFail {
+				if strings.TrimSpace(failMsg) == "" {
+					failMsg = "mock command failed"
+				}
+				respPayload["message"] = failMsg
+			}
+
+			respBytes, err := json.Marshal(respPayload)
+			if err != nil {
+				continue
+			}
+			_ = conn.WriteMessage(websocket.TextMessage, respBytes)
+		}
+	}()
+
+	var stopOnce sync.Once
+	return func() {
+		stopOnce.Do(func() {
+			_ = conn.Close()
+			wg.Wait()
+		})
+	}
+}
+
+func sortedCommandCounts(counts map[string]int) []string {
+	items := make([]string, 0, len(counts))
+	for key, value := range counts {
+		items = append(items, fmt.Sprintf("%s=%d", key, value))
+	}
+	sort.Strings(items)
+	return items
+}

go-backend/tests/contract/user_tunnel_status_contract_test.go

@@ -0,0 +1,105 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+func TestUserTunnelListReturnsStoredStatusContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(201, 'user_tunnel_status_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(301, 'user-tunnel-status-enabled', 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 0)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel enabled: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(302, 'user-tunnel-status-disabled', 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel disabled: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(401, 201, 301, NULL, 10, 500, 0, 0, 1, 2727251700000, 1)
+	`).Error; err != nil {
+		t.Fatalf("insert enabled user_tunnel: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(402, 201, 302, NULL, 10, 500, 0, 0, 1, 2727251700000, 0)
+	`).Error; err != nil {
+		t.Fatalf("insert disabled user_tunnel: %v", err)
+	}
+
+	body := bytes.NewBufferString(`{"userId":201}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/user/list", body)
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 0 {
+		t.Fatalf("expected code 0, got %d (%s)", out.Code, out.Msg)
+	}
+
+	items, ok := out.Data.([]interface{})
+	if !ok {
+		t.Fatalf("expected array data, got %T", out.Data)
+	}
+	if len(items) != 2 {
+		t.Fatalf("expected 2 items, got %d", len(items))
+	}
+
+	statusByTunnelID := make(map[int64]int, len(items))
+	for _, item := range items {
+		obj, ok := item.(map[string]interface{})
+		if !ok {
+			t.Fatalf("expected object item, got %T", item)
+		}
+		tunnelID, ok := obj["tunnelId"].(float64)
+		if !ok {
+			t.Fatalf("expected tunnelId to be float64, got %T", obj["tunnelId"])
+		}
+		status, ok := obj["status"].(float64)
+		if !ok {
+			t.Fatalf("expected status to be float64, got %T", obj["status"])
+		}
+		statusByTunnelID[int64(tunnelID)] = int(status)
+	}
+
+	if statusByTunnelID[301] != 1 {
+		t.Fatalf("expected enabled tunnel status 1, got %d", statusByTunnelID[301])
+	}
+	if statusByTunnelID[302] != 0 {
+		t.Fatalf("expected disabled tunnel status 0, got %d", statusByTunnelID[302])
+	}
+}

plans/016-tunnel-runtime-bind-conflict-retry.md

@@ -0,0 +1,31 @@
+# 016 Tunnel Runtime Bind Conflict Retry
+
+## Checklist
+
+- [x] Confirm tunnel `connectIp` precedence remains `connectIp > node tcp_listen_addr` for runtime service listen address.
+- [x] Add tunnel runtime `address already in use` recovery that deletes the stale service and retries `AddService`.
+- [x] Keep non-bind failures unchanged and avoid altering tunnel chain apply semantics.
+- [x] Add regression tests for tunnel service address precedence and bind-conflict retry behavior.
+- [x] Run focused backend handler tests and record the result.
+- [ ] Add a contract test that simulates node-side `address already in use` during tunnel update and verifies retry success.
+- [ ] Investigate whether forward update `address already in use` reports are only tunnel-redeploy linkage or also an independent forward path.
+- [x] Add a contract test that simulates node-side `address already in use` during tunnel update and verifies retry success.
+- [x] Investigate whether forward update `address already in use` reports are only tunnel-redeploy linkage or also an independent forward path.
+
+## Test Record
+
+- Command: `cd go-backend && go test ./internal/http/handler/...`
+- Result: passed.
+- Command: `cd go-backend && go test ./tests/contract/... -run 'TestTunnelUpdateRecoversFromAddressInUseContract|TestForwardCreateRollbackWhenServiceDispatchReturnsAddressInUseContract|TestForwardUpdateIgnoresDeletedSpeedLimitContract'`
+- Result: passed.
+- Command: `cd go-backend && go test ./tests/contract/... -run 'TestForwardUpdateRecoversFromAddressInUseContract|TestTunnelUpdateRecoversFromAddressInUseContract'`
+- Result: passed.
+- Command: `cd go-backend && go test ./internal/http/handler/... && go test ./tests/contract/... -run 'TestForwardUpdateRecoversFromAddressInUseContract|TestTunnelUpdateRecoversFromAddressInUseContract'`
+- Result: passed.
+
+## Investigation Note
+
+- Forward update still has its own independent `address already in use` recovery path in `syncForwardServicesWithWarnings` / `rebindForwardServiceOnSelfOccupiedPort`; tunnel update linkage is not the only possible source of the symptom.
+- Tunnel update also triggers downstream forward `UpdateService` for bound forwards, so users can still observe the same error around a tunnel edit even when the failing runtime is on the tunnel side.
+- Real node output can collapse spaces into variants like `address alreadyin use` / `cannotassignrequestedaddress`; bind-conflict detection now normalizes whitespace before classifying the error.
+- Forward self-heal cleanup now deletes every candidate runtime name variant instead of stopping after the first successful delete, which avoids leaving sibling `_tcp`/`_udp` services behind to keep the port occupied.

plans/017-pr-284-ui-followup-fixes.md

@@ -0,0 +1,16 @@
+# 017 PR 284 UI Follow-up Fixes
+
+## Checklist
+
+- [x] Review the current frontend route and component state related to PR 284 follow-up fixes.
+- [x] Restore the intended H5 simple-layout route behavior for panel sharing.
+- [x] Improve date text parsing to support separator-free and flexible formats without ambiguous fallbacks.
+- [x] Add config-page back navigation with a safer history fallback and shared icon usage.
+- [x] Run focused frontend verification for the updated files and record the result.
+
+## Test Record
+
+- Command: `cd vite-frontend && npm install`
+- Result: passed.
+- Command: `cd vite-frontend && npm run build`
+- Result: passed.

plans/018-user-tunnel-disable-status-sync.md

@@ -0,0 +1,12 @@
+# 018 User Tunnel Disable Status Sync
+
+## Checklist
+
+- [x] Inspect the user tunnel permission edit flow and identify why disabling an assigned tunnel appears ineffective.
+- [x] Return the real `user_tunnel.status` value from the admin permission list API instead of a hardcoded enabled state.
+- [x] Add contract coverage for the user tunnel permission list status mapping and run focused backend verification.
+
+## Test Record
+
+- Command: `cd go-backend && go test ./tests/contract/...`
+- Result: passed.

plans/019-federation-share-traffic-bigint-migration.md

@@ -0,0 +1,21 @@
+# 019 Federation Share Traffic Bigint Migration
+
+## Checklist
+
+- [x] Inspect federation share creation failure and identify the PostgreSQL `int4` overflow source.
+- [x] Audit other traffic-related legacy PostgreSQL columns that may still be `integer` despite Go models using `int64`.
+- [x] Add a schema migration that widens legacy traffic/quota columns from `integer` to `bigint`.
+- [x] Add migration tests covering the new schema version branch and error propagation.
+- [x] Run focused backend verification for the migration changes.
+
+## Notes
+
+- The reported failing value `536870912000` is 500 GiB in bytes and overflows PostgreSQL `int4`.
+- The fix widens historical PostgreSQL traffic columns in `user`, `forward`, `statistics_flow`, `tunnel`, `user_tunnel`, and `peer_share` to `BIGINT` when needed.
+
+## Test Record
+
+- Command: `cd go-backend && go test ./internal/store/repo/...`
+- Result: passed.
+- Command: `cd go-backend && go test ./tests/contract/...`
+- Result: passed.

vite-frontend/src/App.tsx

@@ -188,7 +188,7 @@ function App() {
       />
       <Route
         element={
-          <ProtectedRoute>
+          <ProtectedRoute useSimpleLayout={true}>
             <PanelSharingPage />
           </ProtectedRoute>
         }

vite-frontend/src/components/icons.tsx

@@ -259,3 +259,29 @@ export const SettingsIcon = ({
     />
   </svg>
 );
+
+export const BackIcon = ({
+  size = 24,
+  width,
+  height,
+  ...props
+}: IconSvgProps) => (
+  <svg
+    aria-hidden="true"
+    focusable="false"
+    height={size || height}
+    role="presentation"
+    viewBox="0 0 24 24"
+    width={size || width}
+    {...props}
+  >
+    <path
+      d="M15 19l-7-7 7-7"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth="2"
+    />
+  </svg>
+);

vite-frontend/src/layouts/h5-simple.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { useNavigate } from "react-router-dom";
 
 import { Button } from "@/shadcn-bridge/heroui/button";
+import { BackIcon } from "@/components/icons";
 import { BrandLogo } from "@/components/brand-logo";
 import { siteConfig } from "@/config/site";
 import { useScrollTopOnPathChange } from "@/hooks/useScrollTopOnPathChange";
@@ -25,13 +26,7 @@ export default function H5SimpleLayout({
       <header className="bg-white dark:bg-black shadow-sm border-b border-gray-200 dark:border-gray-600 h-14 safe-top flex-shrink-0 flex items-center justify-between px-4 relative z-10">
         <div className="flex items-center gap-2">
           <Button isIconOnly size="sm" variant="light" onPress={handleBack}>
-            <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
-              <path
-                clipRule="evenodd"
-                d="M12.707 5.293a1 1 0 010 1.414L9.414 10l3.293 3.293a1 1 0 01-1.414 1.414l-4-4a1 1 0 010-1.414l4-4a1 1 0 011.414 0z"
-                fillRule="evenodd"
-              />
-            </svg>
+            <BackIcon className="w-5 h-5" />
           </Button>
           <BrandLogo size={20} />
           <h1 className="text-sm font-bold text-foreground">

vite-frontend/src/pages/config.tsx

@@ -26,7 +26,7 @@ import {
   updateAnnouncement,
   type AnnouncementData,
 } from "@/api";
-import { SettingsIcon } from "@/components/icons";
+import { BackIcon, SettingsIcon } from "@/components/icons";
 import { isAdmin } from "@/utils/auth";
 import { getCachedConfigs, configCache, updateSiteConfig } from "@/config/site";
 import {
@@ -234,6 +234,21 @@ export default function ConfigPage() {
     Partial<Record<BrandPreviewKey, boolean>>
   >({});
 
+  const canGoBack =
+    typeof window !== "undefined" &&
+    typeof window.history.state?.idx === "number" &&
+    window.history.state.idx > 0;
+
+  const handleBack = () => {
+    if (canGoBack) {
+      navigate(-1);
+
+      return;
+    }
+
+    navigate("/profile", { replace: true });
+  };
+
   // 权限检查
   useEffect(() => {
     if (!isAdmin()) {
@@ -846,6 +861,16 @@ export default function ConfigPage() {
     <div className="p-6 max-w-4xl mx-auto">
       {/* 页面标题 */}
       <div className="flex items-center gap-3 mb-6">
+        <Button
+          isIconOnly
+          aria-label="返回上一页"
+          className="min-w-0 w-9 h-9"
+          size="sm"
+          variant="flat"
+          onPress={handleBack}
+        >
+          <BackIcon className="w-5 h-5" />
+        </Button>
         <SettingsIcon className="w-8 h-8 text-primary" />
         <div>
           <h1 className="text-2xl font-bold">网站配置</h1>

vite-frontend/src/pages/node.tsx

@@ -1563,7 +1563,7 @@ export default function NodePage() {
               />
 
               <Input
-                description="可选：不带协议、不带端口。至少填写一个 IPv4/IPv6/域名"
+                description="可选：不带协议、不带端口。建议在 IPv4 和 IPv6 都未填写时使用。至少填写一个 IPv4/IPv6/域名"
                 errorMessage={errors.serverHost}
                 isInvalid={!!errors.serverHost}
                 label="服务器域名/主机名"

vite-frontend/src/pages/settings.tsx

@@ -9,6 +9,7 @@ import { Select, SelectItem } from "@/shadcn-bridge/heroui/select";
 import { Switch } from "@/shadcn-bridge/heroui/switch";
 import { reinitializeBaseURL } from "@/api/network";
 import { getConfigByName, updateConfig } from "@/api";
+import { BackIcon } from "@/components/icons";
 import {
   type UpdateReleaseChannel,
   getUpdateReleaseChannel,
@@ -168,20 +169,7 @@ export const SettingsPage = () => {
               variant="light"
               onPress={() => navigate(-1)}
             >
-              <svg
-                aria-hidden="true"
-                className="w-5 h-5"
-                fill="none"
-                stroke="currentColor"
-                viewBox="0 0 24 24"
-              >
-                <path
-                  d="M15 19l-7-7 7-7"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={2}
-                />
-              </svg>
+              <BackIcon className="w-5 h-5" />
             </Button>
             <h1 className="text-xl font-semibold text-gray-900 dark:text-white">
               面板设置

vite-frontend/src/pages/tunnel.tsx

@@ -1435,7 +1435,7 @@ export default function TunnelPage() {
                   </div>
 
                   <Textarea
-                    description="支持多个IP，每行一个地址,为空时使用入口节点ip"
+                    description="入口IP由系统自动从入口节点采集，无需手动填写。支持多个IP，每行一个地址，留空则使用入口节点IP"
                     errorMessage={errors.inIp}
                     isInvalid={!!errors.inIp}
                     label="入口IP"

vite-frontend/src/shadcn-bridge/heroui/date-picker.tsx

@@ -38,15 +38,33 @@ function parseDateText(value: string) {
     return null;
   }
 
-  const matched = trimmed.match(/^(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})$/);
+  const digitsOnly = trimmed.replace(/\D/g, "");
 
-  if (!matched) {
+  if (/^\d+$/.test(trimmed)) {
+    if (digitsOnly.length !== 8) {
+      return null;
+    }
+
+    const year = Number(digitsOnly.slice(0, 4));
+    const month = Number(digitsOnly.slice(4, 6));
+    const day = Number(digitsOnly.slice(6, 8));
+
+    if (!isValidCalendarDate(year, month, day)) {
+      return null;
+    }
+
+    return { day, month, year };
+  }
+
+  const numberParts = trimmed.match(/\d+/g);
+
+  if (!numberParts || numberParts.length !== 3 || numberParts[0].length !== 4) {
     return null;
   }
 
-  const year = Number(matched[1]);
-  const month = Number(matched[2]);
-  const day = Number(matched[3]);
+  const year = Number(numberParts[0]);
+  const month = Number(numberParts[1]);
+  const day = Number(numberParts[2]);
 
   if (!isValidCalendarDate(year, month, day)) {
     return null;