fix(monitor): unify realtime state and ignore stale requests (#571)

* fix(relay): authenticate endpoints and fail closed on missing routes

* fix(tunnel): retain chains until receiver replacement is acknowledged

* docs: record final relay security review and validation

go-backend/internal/http/client/federation.go

@@ -3,6 +3,7 @@ package client
 import (
 	"encoding/json"
 	"fmt"
+	"go-backend/internal/relaysecurity"
 	"io"
 	"net/http"
 	"strings"
@@ -14,17 +15,18 @@ type FederationClient struct {
 }
 
 type RemoteNodeInfo struct {
-	ShareID        int64  `json:"shareId"`
-	ShareName      string `json:"shareName"`
-	NodeID         int64  `json:"nodeId"`
-	NodeName       string `json:"nodeName"`
-	ServerIP       string `json:"serverIp"`
-	Status         int    `json:"status"`
-	MaxBandwidth   int64  `json:"maxBandwidth"`
-	CurrentFlow    int64  `json:"currentFlow"`
-	ExpiryTime     int64  `json:"expiryTime"`
-	PortRangeStart int    `json:"portRangeStart"`
-	PortRangeEnd   int    `json:"portRangeEnd"`
+	RelayAuthVersion int    `json:"relayAuthVersion"`
+	ShareID          int64  `json:"shareId"`
+	ShareName        string `json:"shareName"`
+	NodeID           int64  `json:"nodeId"`
+	NodeName         string `json:"nodeName"`
+	ServerIP         string `json:"serverIp"`
+	Status           int    `json:"status"`
+	MaxBandwidth     int64  `json:"maxBandwidth"`
+	CurrentFlow      int64  `json:"currentFlow"`
+	ExpiryTime       int64  `json:"expiryTime"`
+	PortRangeStart   int    `json:"portRangeStart"`
+	PortRangeEnd     int    `json:"portRangeEnd"`
 }
 
 type RemoteTunnelResponse struct {
@@ -38,30 +40,34 @@ type RuntimeReservePortRequest struct {
 }
 
 type RuntimeReservePortResponse struct {
-	ReservationID string `json:"reservationId"`
-	BindingID     string `json:"bindingId"`
-	AllocatedPort int    `json:"allocatedPort"`
+	RelayAuthVersion int    `json:"relayAuthVersion"`
+	ReservationID    string `json:"reservationId"`
+	BindingID        string `json:"bindingId"`
+	AllocatedPort    int    `json:"allocatedPort"`
 }
 
 type RuntimeTarget struct {
-	Host     string `json:"host"`
-	Port     int    `json:"port"`
-	Protocol string `json:"protocol"`
+	RelayAuth *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	Host      string                     `json:"host"`
+	Port      int                        `json:"port"`
+	Protocol  string                     `json:"protocol"`
 }
 
 type RuntimeApplyRoleRequest struct {
-	ReservationID string          `json:"reservationId"`
-	ResourceKey   string          `json:"resourceKey"`
-	Role          string          `json:"role"`
-	Protocol      string          `json:"protocol"`
-	Strategy      string          `json:"strategy"`
-	Targets       []RuntimeTarget `json:"targets"`
+	RelayAuth     *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	ReservationID string                     `json:"reservationId"`
+	ResourceKey   string                     `json:"resourceKey"`
+	Role          string                     `json:"role"`
+	Protocol      string                     `json:"protocol"`
+	Strategy      string                     `json:"strategy"`
+	Targets       []RuntimeTarget            `json:"targets"`
 }
 
 type RuntimeApplyRoleResponse struct {
-	BindingID     string `json:"bindingId"`
-	ReservationID string `json:"reservationId"`
-	AllocatedPort int    `json:"allocatedPort"`
+	RelayAuthVersion int    `json:"relayAuthVersion"`
+	BindingID        string `json:"bindingId"`
+	ReservationID    string `json:"reservationId"`
+	AllocatedPort    int    `json:"allocatedPort"`
 }
 
 type RuntimeReleaseRoleRequest struct {
@@ -247,6 +253,9 @@ func (c *FederationClient) ApplyRole(url, token, localDomain string, reqData Run
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
+		if reqData.RelayAuth != nil {
+			return nil, fmt.Errorf("remote authenticated relay apply failed: HTTP %d", resp.StatusCode)
+		}
 		body, _ := io.ReadAll(resp.Body)
 		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
 	}
@@ -260,9 +269,16 @@ func (c *FederationClient) ApplyRole(url, token, localDomain string, reqData Run
 		return nil, err
 	}
 	if res.Code != 0 {
+		if reqData.RelayAuth != nil {
+			return nil, fmt.Errorf("remote authenticated relay apply failed: code %d", res.Code)
+		}
 		return nil, fmt.Errorf("remote api error: %s", res.Msg)
 	}
 
+	if reqData.RelayAuth != nil && res.Data.RelayAuthVersion != relaysecurity.Version {
+		return nil, fmt.Errorf("remote did not acknowledge required relay authentication")
+	}
+
 	return &res.Data, nil
 }
 

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

@@ -534,7 +534,22 @@ func buildForwardServiceDeleteNames(bases []string) []string {
 	return names
 }
 
+type forwardServiceControlOptions struct {
+	tolerateNotFound bool
+	tolerateOffline  bool
+	allowSelfHeal    bool
+	continueOnError  bool
+}
+
 func (h *Handler) controlForwardServices(forward *forwardRecord, commandType string, tolerateNotFound bool) error {
+	return h.controlForwardServicesWithOptions(forward, commandType, forwardServiceControlOptions{
+		tolerateNotFound: tolerateNotFound,
+		tolerateOffline:  true,
+		allowSelfHeal:    true,
+	})
+}
+
+func (h *Handler) controlForwardServicesWithOptions(forward *forwardRecord, commandType string, opts forwardServiceControlOptions) error {
 	if h == nil || forward == nil {
 		return errors.New("invalid forward control context")
 	}
@@ -561,6 +576,7 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 	candidateTunnelIDs = append(candidateTunnelIDs, userTunnelIDs...)
 	candidateTunnelIDs = append(candidateTunnelIDs, allUserTunnelIDs...)
 	bases := buildForwardServiceBaseCandidates(forward.ID, forward.UserID, userTunnelID, candidateTunnelIDs)
+	var nodeErrors []error
 	if strings.EqualFold(strings.TrimSpace(commandType), "DeleteService") {
 		seen := map[int64]struct{}{}
 		for _, fp := range ports {
@@ -569,16 +585,20 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 			}
 			seen[fp.NodeID] = struct{}{}
 			if err := h.deleteForwardServiceBasesOnNode(fp.NodeID, bases); err != nil {
-				if isNodeOfflineOrTimeoutError(err) {
+				if opts.tolerateOffline && isNodeOfflineOrTimeoutError(err) {
 					continue
 				}
-				if tolerateNotFound && isNotFoundError(err) {
+				if opts.tolerateNotFound && isNotFoundError(err) {
+					continue
+				}
+				if opts.continueOnError {
+					nodeErrors = append(nodeErrors, h.nodeCommandError(fp.NodeID, err))
 					continue
 				}
 				return err
 			}
 		}
-		return nil
+		return errors.Join(nodeErrors...)
 	}
 	seen := map[int64]struct{}{}
 	healed := false
@@ -588,37 +608,50 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 		}
 		seen[fp.NodeID] = struct{}{}
 
-		nodeHandled, lastNotFoundErr, err := h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
-		if err != nil {
-			if isNodeOfflineOrTimeoutError(err) {
-				continue
-			}
-			return err
-		}
-
-		if !nodeHandled && lastNotFoundErr != nil && !healed && shouldSelfHealForwardServiceControl(commandType) {
-			if healErr := h.syncForwardServices(forward, "UpdateService", true); healErr != nil {
-				return healErr
-			}
-			healed = true
-			nodeHandled, lastNotFoundErr, err = h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
+		nodeErr := func() error {
+			nodeHandled, lastNotFoundErr, err := h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
 			if err != nil {
+				if opts.tolerateOffline && isNodeOfflineOrTimeoutError(err) {
+					return nil
+				}
 				return err
 			}
-		}
 
-		if nodeHandled {
-			continue
+			if opts.allowSelfHeal && !nodeHandled && lastNotFoundErr != nil && !healed && shouldSelfHealForwardServiceControl(commandType) {
+				if healErr := h.syncForwardServices(forward, "UpdateService", true); healErr != nil {
+					return healErr
+				}
+				healed = true
+				nodeHandled, lastNotFoundErr, err = h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
+				if err != nil {
+					return err
+				}
+			}
+
+			if nodeHandled || opts.tolerateNotFound {
+				return nil
+			}
+			if lastNotFoundErr != nil {
+				return lastNotFoundErr
+			}
+			return errors.New("service control failed")
+		}()
+		if nodeErr != nil {
+			if !opts.continueOnError {
+				return nodeErr
+			}
+			nodeErrors = append(nodeErrors, h.nodeCommandError(fp.NodeID, nodeErr))
 		}
-		if tolerateNotFound {
-			continue
-		}
-		if lastNotFoundErr != nil {
-			return lastNotFoundErr
-		}
-		return errors.New("service control failed")
 	}
-	return nil
+	return errors.Join(nodeErrors...)
+}
+
+func (h *Handler) nodeCommandError(nodeID int64, err error) error {
+	name := strconv.FormatInt(nodeID, 10)
+	if node, lookupErr := h.getNodeRecord(nodeID); lookupErr == nil && node != nil {
+		name = defaultString(strings.TrimSpace(node.Name), name)
+	}
+	return fmt.Errorf("节点 %s (ID %d): %w", name, nodeID, err)
 }
 
 func (h *Handler) controlForwardServicesOnNode(nodeID int64, bases []string, commandType string) (bool, error, error) {
@@ -1939,7 +1972,12 @@ func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel
 			service["listener"].(map[string]interface{})["metadata"] = listenerMetadata
 		}
 		if tunnel != nil && tunnel.Type == 2 {
-			service["handler"].(map[string]interface{})["chain"] = fmt.Sprintf("chains_%d", forward.TunnelID)
+			handlerConfig := service["handler"].(map[string]interface{})
+			handlerConfig["chain"] = fmt.Sprintf("chains_%d", forward.TunnelID)
+			if handlerConfig["metadata"] == nil {
+				handlerConfig["metadata"] = map[string]interface{}{}
+			}
+			handlerConfig["metadata"].(map[string]interface{})["chain.strict"] = true
 		}
 		if tunnel != nil && tunnel.Type == 1 && strings.TrimSpace(node.InterfaceName) != "" {
 			serviceMetadata := ensureServiceMetadata(service)

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

@@ -17,6 +17,7 @@ import (
 
 	"go-backend/internal/http/client"
 	"go-backend/internal/http/response"
+	"go-backend/internal/relaysecurity"
 	"go-backend/internal/store/repo"
 )
 
@@ -68,18 +69,20 @@ type federationRuntimeReservePortRequest struct {
 }
 
 type federationRuntimeTarget struct {
-	Host     string `json:"host"`
-	Port     int    `json:"port"`
-	Protocol string `json:"protocol"`
+	RelayAuth *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	Host      string                     `json:"host"`
+	Port      int                        `json:"port"`
+	Protocol  string                     `json:"protocol"`
 }
 
 type federationRuntimeApplyRoleRequest struct {
-	ReservationID string                    `json:"reservationId"`
-	ResourceKey   string                    `json:"resourceKey"`
-	Role          string                    `json:"role"`
-	Protocol      string                    `json:"protocol"`
-	Strategy      string                    `json:"strategy"`
-	Targets       []federationRuntimeTarget `json:"targets"`
+	RelayAuth     *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	ReservationID string                     `json:"reservationId"`
+	ResourceKey   string                     `json:"resourceKey"`
+	Role          string                     `json:"role"`
+	Protocol      string                     `json:"protocol"`
+	Strategy      string                     `json:"strategy"`
+	Targets       []federationRuntimeTarget  `json:"targets"`
 }
 
 type federationRuntimeReleaseRoleRequest struct {
@@ -115,6 +118,13 @@ func buildFederationMiddleChainConfig(chainName string, runtimeID int64, protoco
 		connector := map[string]interface{}{
 			"type": "relay",
 		}
+		if target.RelayAuth != nil {
+			if err := target.RelayAuth.Validate(); err != nil {
+				return nil, err
+			}
+			connector["auth"] = target.RelayAuth.Config()
+		}
+
 		if isTCPTunnelProtocol(targetProtocol) {
 			connector["metadata"] = map[string]interface{}{
 				"nodelay":               true,
@@ -221,7 +231,7 @@ type remoteUsageNodeItem struct {
 	SyncError        string                   `json:"syncError,omitempty"`
 }
 
-func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName string, targetCount int, interfaceName string) map[string]interface{} {
+func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName string, targetCount int, interfaceName string, credentials *relaysecurity.Credentials) map[string]interface{} {
 	service := map[string]interface{}{
 		"name": serviceName,
 		"addr": addr,
@@ -230,6 +240,10 @@ func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName s
 		},
 		"listener": buildTunnelListenerConfig(protocol),
 	}
+	if credentials != nil {
+		service["handler"].(map[string]interface{})["auth"] = credentials.Config()
+	}
+
 	if isTCPTunnelProtocol(protocol) {
 		service["handler"].(map[string]interface{})["metadata"] = map[string]interface{}{
 			"nodelay":               true,
@@ -243,6 +257,13 @@ func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName s
 		}
 	}
 	if role == "middle" {
+		handler := service["handler"].(map[string]interface{})
+		md, _ := handler["metadata"].(map[string]interface{})
+		if md == nil {
+			md = map[string]interface{}{}
+			handler["metadata"] = md
+		}
+		md["chain.strict"] = true
 		service["handler"].(map[string]interface{})["chain"] = chainName
 		if targetCount > 1 {
 			service["handler"].(map[string]interface{})["retries"] = targetCount - 1
@@ -915,17 +936,18 @@ func (h *Handler) federationConnect(w http.ResponseWriter, r *http.Request) {
 	}
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
-		"shareId":        share.ID,
-		"shareName":      share.Name,
-		"nodeId":         share.NodeID,
-		"nodeName":       nodeInfo.Name,
-		"serverIp":       nodeInfo.ServerIP,
-		"status":         nodeInfo.Status,
-		"maxBandwidth":   share.MaxBandwidth,
-		"currentFlow":    share.CurrentFlow,
-		"expiryTime":     share.ExpiryTime,
-		"portRangeStart": share.PortRangeStart,
-		"portRangeEnd":   share.PortRangeEnd,
+		"shareId":          share.ID,
+		"relayAuthVersion": relaysecurity.Version,
+		"shareName":        share.Name,
+		"nodeId":           share.NodeID,
+		"nodeName":         nodeInfo.Name,
+		"serverIp":         nodeInfo.ServerIP,
+		"status":           nodeInfo.Status,
+		"maxBandwidth":     share.MaxBandwidth,
+		"currentFlow":      share.CurrentFlow,
+		"expiryTime":       share.ExpiryTime,
+		"portRangeStart":   share.PortRangeStart,
+		"portRangeEnd":     share.PortRangeEnd,
 	}))
 }
 
@@ -1079,9 +1101,10 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 	}
 	if existing != nil && existing.Status == 1 {
 		response.WriteJSON(w, response.OK(map[string]interface{}{
-			"reservationId": existing.ReservationID,
-			"allocatedPort": existing.Port,
-			"bindingId":     existing.BindingID,
+			"reservationId":    existing.ReservationID,
+			"allocatedPort":    existing.Port,
+			"relayAuthVersion": relaysecurity.Version,
+			"bindingId":        existing.BindingID,
 		}))
 		return
 	}
@@ -1103,6 +1126,8 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 		existing.ServiceName = ""
 		existing.Strategy = "round"
 		existing.Target = ""
+		existing.RelayAuth = ""
+		existing.RelayAuthVersion = 0
 		existing.Applied = 0
 		existing.Status = 1
 		existing.UpdatedTime = now
@@ -1111,9 +1136,10 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 			return
 		}
 		response.WriteJSON(w, response.OK(map[string]interface{}{
-			"reservationId": existing.ReservationID,
-			"allocatedPort": existing.Port,
-			"bindingId":     existing.BindingID,
+			"reservationId":    existing.ReservationID,
+			"allocatedPort":    existing.Port,
+			"relayAuthVersion": relaysecurity.Version,
+			"bindingId":        existing.BindingID,
 		}))
 		return
 	}
@@ -1142,9 +1168,10 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 	}
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
-		"reservationId": runtime.ReservationID,
-		"allocatedPort": runtime.Port,
-		"bindingId":     runtime.BindingID,
+		"reservationId":    runtime.ReservationID,
+		"allocatedPort":    runtime.Port,
+		"relayAuthVersion": relaysecurity.Version,
+		"bindingId":        runtime.BindingID,
 	}))
 }
 
@@ -1211,6 +1238,20 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 		response.WriteJSON(w, response.ErrDefault("Reserved port is outside share range"))
 		return
 	}
+	if _, err := decodeRuntimeRelayAuth(runtime); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	if err := validateFederationRelayAuth(runtime.RelayAuth, req.RelayAuth, req.Targets); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	if req.RelayAuth != nil {
+		encoded, _ := json.Marshal(req.RelayAuth)
+		runtime.RelayAuth = string(encoded)
+		runtime.RelayAuthVersion = relaysecurity.Version
+	}
+
 	if strings.TrimSpace(runtime.BindingID) == "" {
 		runtime.BindingID = randomToken(24)
 	}
@@ -1230,9 +1271,10 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 	}
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
-		"bindingId":     runtime.BindingID,
-		"reservationId": runtime.ReservationID,
-		"allocatedPort": runtime.Port,
+		"relayAuthVersion": relayAuthVersion(req.RelayAuth),
+		"bindingId":        runtime.BindingID,
+		"reservationId":    runtime.ReservationID,
+		"allocatedPort":    runtime.Port,
 	}))
 }
 

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

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -495,19 +496,22 @@ func TestPeerResourcePendingRetryLeavesAppliedSiblingAlone(t *testing.T) {
 }
 
 func TestPeerResourceLegacyReleaseAcknowledgmentIsAtomic(t *testing.T) {
-	a := newCleanupAgent(t)
+	var failCompletion atomic.Bool
+	a := newCleanupAgent(t, func(r *repo.Repository) {
+		if err := r.DB().Callback().Update().Before("gorm:update").Register("fail-runtime-release", func(tx *gorm.DB) {
+			if failCompletion.Load() && tx.Statement.Table == "peer_share_runtime" {
+				tx.AddError(errors.New("simulated completion failure"))
+			}
+		}); err != nil {
+			t.Fatal(err)
+		}
+	})
 	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
 	share, err := a.h.repo.GetPeerShare(shareID)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if err := a.h.repo.DB().Callback().Update().Before("gorm:update").Register("fail-runtime-release", func(tx *gorm.DB) {
-		if tx.Statement.Table == "peer_share_runtime" {
-			tx.AddError(errors.New("simulated completion failure"))
-		}
-	}); err != nil {
-		t.Fatal(err)
-	}
+	failCompletion.Store(true)
 	got := resourceTestCommand(t, a.h, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp"}})
 	if got.Code == 0 {
 		t.Fatal("completion database failure reported success")
@@ -525,9 +529,7 @@ func TestPeerResourceLegacyReleaseAcknowledgmentIsAtomic(t *testing.T) {
 	if !proof || !pending {
 		t.Fatalf("failure lost ownership or retry marker: %+v", items)
 	}
-	if err := a.h.repo.DB().Callback().Update().Remove("fail-runtime-release"); err != nil {
-		t.Fatal(err)
-	}
+	failCompletion.Store(false)
 	if err := a.h.retryPendingPeerShareResourcesOnNode(1); err != nil {
 		t.Fatal(err)
 	}

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

@@ -228,7 +228,7 @@ func TestPrepareTunnelCreateStateAllowsOfflineRemoteMiddleNode(t *testing.T) {
 }
 
 func TestBuildFederationServiceConfig_MiddleRoleWithMultipleTargets_SetsRetries(t *testing.T) {
-	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 3, "")
+	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 3, "", nil)
 	handler := service["handler"].(map[string]interface{})
 	if handler["chain"] != "chain-next" {
 		t.Fatalf("expected chain 'chain-next', got %v", handler["chain"])
@@ -239,7 +239,7 @@ func TestBuildFederationServiceConfig_MiddleRoleWithMultipleTargets_SetsRetries(
 }
 
 func TestBuildFederationServiceConfig_MiddleRoleWithSingleTarget_NoRetries(t *testing.T) {
-	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 1, "")
+	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 1, "", nil)
 	handler := service["handler"].(map[string]interface{})
 	if handler["chain"] != "chain-next" {
 		t.Fatalf("expected chain 'chain-next', got %v", handler["chain"])
@@ -250,7 +250,7 @@ func TestBuildFederationServiceConfig_MiddleRoleWithSingleTarget_NoRetries(t *te
 }
 
 func TestBuildFederationServiceConfig_ExitRole_NoRetriesRegardlessOfTargets(t *testing.T) {
-	service := buildFederationServiceConfig("svc-exit", ":40000", "tls", "exit", "", 3, "eth0")
+	service := buildFederationServiceConfig("svc-exit", ":40000", "tls", "exit", "", 3, "eth0", nil)
 	handler := service["handler"].(map[string]interface{})
 	if _, hasChain := handler["chain"]; hasChain {
 		t.Fatalf("expected no chain for exit role, got %v", handler["chain"])
@@ -265,7 +265,7 @@ func TestBuildFederationServiceConfig_ExitRole_NoRetriesRegardlessOfTargets(t *t
 }
 
 func TestBuildFederationServiceConfig_TLSTunnelProtocol_SetsNodelay(t *testing.T) {
-	service := buildFederationServiceConfig("svc-tls", ":40000", "tls", "middle", "chain-next", 2, "")
+	service := buildFederationServiceConfig("svc-tls", ":40000", "tls", "middle", "chain-next", 2, "", nil)
 	handler := service["handler"].(map[string]interface{})
 	meta := handler["metadata"].(map[string]interface{})
 	if meta["nodelay"] != true {
@@ -274,10 +274,14 @@ func TestBuildFederationServiceConfig_TLSTunnelProtocol_SetsNodelay(t *testing.T
 }
 
 func TestBuildFederationServiceConfig_NonTLSProtocol_NoNodelay(t *testing.T) {
-	service := buildFederationServiceConfig("svc-tcp", ":40000", "tcp", "middle", "chain-next", 2, "")
+	service := buildFederationServiceConfig("svc-tcp", ":40000", "tcp", "middle", "chain-next", 2, "", nil)
 	handler := service["handler"].(map[string]interface{})
-	if _, hasMeta := handler["metadata"]; hasMeta {
-		t.Fatalf("expected no metadata for non-TLS protocol, got %v", handler["metadata"])
+	metadata, _ := handler["metadata"].(map[string]interface{})
+	if _, hasNodelay := metadata["nodelay"]; hasNodelay {
+		t.Fatal("non-TLS protocol must not set nodelay")
+	}
+	if metadata["chain.strict"] != true {
+		t.Fatal("middle relay must require its configured chain")
 	}
 }
 

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

@@ -305,11 +305,17 @@ func TestFederationRemoteUsageListSyncErrorFallback(t *testing.T) {
 
 	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
+	// Model an unavailable provider entirely on loopback instead of relying on
+	// external DNS or network restrictions to produce the sync error.
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "provider unavailable", http.StatusServiceUnavailable)
+	}))
+	defer provider.Close()
 
 	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, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "sync-error-node", "sync-error-secret", "10.50.60.70", "10.50.60.70", "", "32000-32010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://unreachable.invalid:9999", "bad-token", `{"shareId":42,"maxBandwidth":5368709120,"currentFlow":999999,"portRangeStart":32000,"portRangeEnd":32010}`).Error; err != nil {
+	`, "sync-error-node", "sync-error-secret", "10.50.60.70", "10.50.60.70", "", "32000-32010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, provider.URL, "bad-token", `{"shareId":42,"maxBandwidth":5368709120,"currentFlow":999999,"portRangeStart":32000,"portRangeEnd":32010}`).Error; err != nil {
 		t.Fatalf("insert remote node: %v", err)
 	}
 
@@ -348,7 +354,7 @@ func TestFederationRemoteUsageListSyncErrorFallback(t *testing.T) {
 
 	syncErr, _ := first["syncError"].(string)
 	if syncErr == "" {
-		t.Fatalf("expected non-empty syncError field on unreachable provider")
+		t.Fatalf("expected non-empty syncError field on unavailable provider")
 	}
 }
 
@@ -858,11 +864,15 @@ func TestFederationRemoteUsageList(t *testing.T) {
 
 	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "provider unavailable", http.StatusServiceUnavailable)
+	}))
+	defer provider.Close()
 
 	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, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "remote-consumer-node", "remote-consumer-secret", "10.30.40.50", "10.30.40.50", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://peer.example", "peer-token", `{"shareId":88,"maxBandwidth":2147483648,"currentFlow":1073741824,"portRangeStart":31000,"portRangeEnd":31010}`).Error; err != nil {
+	`, "remote-consumer-node", "remote-consumer-secret", "10.30.40.50", "10.30.40.50", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, provider.URL, "peer-token", `{"shareId":88,"maxBandwidth":2147483648,"currentFlow":1073741824,"portRangeStart":31000,"portRangeEnd":31010}`).Error; err != nil {
 		t.Fatalf("insert remote node: %v", err)
 	}
 	nodeID := mustLastInsertID(t, r, "remote-consumer-node")
@@ -882,8 +892,8 @@ func TestFederationRemoteUsageList(t *testing.T) {
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
 		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 	`,
-		tunnelAID, nodeID, 2, 1, "http://peer.example", "rk-a", "rb-a", 31001, 1, now, now,
-		tunnelBID, nodeID, 3, 0, "http://peer.example", "rk-b", "rb-b", 31002, 1, now, now,
+		tunnelAID, nodeID, 2, 1, provider.URL, "rk-a", "rb-a", 31001, 1, now, now,
+		tunnelBID, nodeID, 3, 0, provider.URL, "rk-b", "rb-b", 31002, 1, now, now,
 	).Error; err != nil {
 		t.Fatalf("insert federation bindings: %v", err)
 	}

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

@@ -37,7 +37,7 @@ type cleanupAgent struct {
 	commands []cleanupAgentCommand
 }
 
-func newCleanupAgent(t *testing.T) *cleanupAgent {
+func newCleanupAgent(t *testing.T, setup ...func(*repo.Repository)) *cleanupAgent {
 	t.Helper()
 	r, err := repo.Open(filepath.Join(t.TempDir(), "cleanup.db"))
 	if err != nil {
@@ -48,6 +48,11 @@ func newCleanupAgent(t *testing.T) *cleanupAgent {
 	if err := r.DB().Create(&model.Node{ID: 1, Name: "relay", Secret: secret, ServerIP: "127.0.0.1", Port: "30000", Status: 1}).Error; err != nil {
 		t.Fatal(err)
 	}
+	// Register test-local database callbacks before WebSocket goroutines can
+	// execute them. Keep registries immutable until the fixture is closed.
+	for _, configure := range setup {
+		configure(r)
+	}
 	server := ws.NewServer(r, "test-jwt-secret")
 	online := make(chan struct{})
 	server.SetNodeOnlineHook(func(int64) { close(online) })

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

@@ -3,6 +3,7 @@ package handler
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"log"
 	"math"
 	"strconv"
@@ -393,6 +394,48 @@ func (h *Handler) getUserTunnelPolicy(userTunnelID int64) (*userTunnelPolicy, er
 	}, nil
 }
 
+// disableUserAccess retains unconfirmed forwards as active so a repeated disable
+// can retry them. Login and tunnel access remain disabled when a node is offline.
+func (h *Handler) disableUserAccess(userID int64, now int64) error {
+	permissionErr := h.repo.DisableUserTunnels(userID)
+	forwards, err := h.listActiveForwardsByUser(userID)
+	if err != nil {
+		return errors.Join(permissionErr, err)
+	}
+	errs := []error{permissionErr}
+	for i := range forwards {
+		forward := &forwards[i]
+		nftMode, entryNodeIDs, pauseErr := h.tunnelUsesNftables(forward.TunnelID)
+		if pauseErr == nil {
+			if nftMode {
+				// Exclude the rule from the desired plan before marking its pause
+				// confirmed. A failed SSH apply must remain eligible for retry.
+				pauseErr = h.syncNftablesNode(entryNodeIDs[0], forward.ID)
+				if pauseErr != nil {
+					pauseErr = h.nodeCommandError(entryNodeIDs[0], pauseErr)
+				}
+			} else {
+				// Missing services are already stopped. Self-healing would recreate
+				// services on every entry and could restart one already paused.
+				pauseErr = h.controlForwardServicesWithOptions(forward, "PauseService", forwardServiceControlOptions{
+					tolerateNotFound: true,
+					tolerateOffline:  false,
+					allowSelfHeal:    false,
+					continueOnError:  true,
+				})
+			}
+		}
+		if pauseErr != nil {
+			errs = append(errs, fmt.Errorf("转发 %d 暂停失败: %w", forward.ID, pauseErr))
+			continue
+		}
+		if err := h.repo.UpdateForwardStatus(forward.ID, 0, now); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
 func (h *Handler) pauseUserForwards(userID int64, now int64) {
 	forwards, err := h.listActiveForwardsByUser(userID)
 	if err != nil {

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

@@ -39,6 +39,9 @@ type Handler struct {
 	healthCheck     *health.Checker
 	nftablesManager nftablesRuntimeManager
 
+	tunnelLifecycleMu    sync.Mutex
+	tunnelLifecycleLocks map[int64]*tunnelLifecycleLock
+
 	peerResourceMu sync.Mutex
 	captchaMu      sync.Mutex
 	captchaTokens  map[string]int64

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

@@ -48,6 +48,9 @@ func (h *Handler) runFederationCleanupRetryLoop(ctx context.Context) {
 		if err := h.retryPendingFederationRuntimeCleanup(); err != nil {
 			log.Printf("federation cleanup remains pending: %v", err)
 		}
+		if err := h.retryPendingTunnelRuntimeCleanup(); err != nil {
+			log.Printf("tunnel runtime cleanup remains pending: %v", err)
+		}
 		h.retryPendingPeerShareOperations()
 		select {
 		case <-ctx.Done():

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

@@ -19,6 +19,7 @@ import (
 
 	"go-backend/internal/http/client"
 	"go-backend/internal/http/response"
+	"go-backend/internal/relaysecurity"
 	"go-backend/internal/security"
 	"go-backend/internal/store/model"
 	"go-backend/internal/store/repo"
@@ -205,6 +206,15 @@ func (h *Handler) userUpdate(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	if status != 1 {
+		// Revoke access before optional quota/group updates can fail or return.
+		if err := h.disableUserAccess(id, now); err != nil {
+			result := response.Err(-2, fmt.Sprintf("账号已禁用，以下权限或节点暂停未确认；其他转发已继续处理，请排查后重试禁用：\n%v", err))
+			result.Data = map[string]interface{}{"userDisabled": true}
+			response.WriteJSON(w, result)
+			return
+		}
+	}
 	h.repo.PropagateUserFlowToTunnels(id, flow, num, expTime, flowResetTime, flowMiB)
 	if hasDailyQuota || hasMonthlyQuota {
 		dailyQuotaGB := asInt64(req["dailyQuotaGB"], 0)
@@ -243,6 +253,13 @@ func (h *Handler) userUpdate(w http.ResponseWriter, r *http.Request) {
 			}
 		}
 	}
+	if status != 1 {
+		// Group changes may have created additional tunnel grants.
+		if err := h.repo.DisableUserTunnels(id); err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
+	}
 	if oldUser.MaxConn != maxConn {
 		warnings, syncErr := h.syncUserMaxConnForwards(id)
 		if syncErr != nil {
@@ -832,10 +849,70 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	var tunnelInIP sql.NullString
+	if trimmed := strings.TrimSpace(inIP); trimmed != "" {
+		tunnelInIP = sql.NullString{String: trimmed, Valid: true}
+	}
+	tunnelProtocol := "tls"
+	if len(runtimeState.InNodes) > 0 && strings.TrimSpace(runtimeState.InNodes[0].Protocol) != "" {
+		tunnelProtocol = strings.TrimSpace(runtimeState.InNodes[0].Protocol)
+	}
+	tunnel := model.Tunnel{
+		RelayAuthMode:   relaysecurity.Legacy,
+		Name:            name,
+		TrafficRatio:    trafficRatio,
+		Type:            typeVal,
+		Protocol:        tunnelProtocol,
+		Flow:            flow,
+		CreatedTime:     now,
+		UpdatedTime:     now,
+		Status:          status,
+		InIP:            tunnelInIP,
+		Inx:             inx,
+		IPPreference:    ipPreference,
+		ProbeTargetHost: probeTargetHost,
+		ProbeTargetPort: probeTargetPort,
+	}
+	if typeVal == 2 {
+		tunnel.RelayAuthMode = relaysecurity.Required
+	}
+	if err := tx.Create(&tunnel).Error; err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	tunnelID := tunnel.ID
+	unlock, locked := h.tryLockNewTunnelLifecycle(tunnelID)
+	if !locked {
+		response.WriteJSON(w, response.ErrDefault("隧道正在变更，请重试"))
+		return
+	}
+	defer unlock()
+	runtimeState.TunnelID = tunnelID
+	runtimeState.RelayAuthMode = tunnel.RelayAuthMode
+	if err := h.resolveTunnelRelayAuth(tx, runtimeState, true); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	if typeVal == 2 {
+		if err := h.persistPreparedTunnelChainsTx(tx, runtimeState); err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
+	}
+	// The lifecycle lock is held before publishing this ID. Network calls below
+	// must not monopolize SQLite's only connection or a database transaction.
+	if err := tx.Commit().Error; err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	failCreate := func(err error, code int) {
+		err = errors.Join(err, h.deleteTunnelByID(tunnelID))
+		response.WriteJSON(w, response.Err(code, err.Error()))
+	}
 	if len(runtimeState.InNodes) > 0 {
 		firstNodeID := runtimeState.InNodes[0].NodeID
-		isRemote, rUrl, rToken, _ := h.repo.GetNodeRemoteFieldsTx(tx, firstNodeID)
-		if isRemote == 1 {
+		entryNode := runtimeState.Nodes[firstNodeID]
+		if entryNode != nil && entryNode.IsRemote == 1 {
 			fc := client.NewFederationClient()
 
 			targetProto := "tcp"
@@ -862,17 +939,12 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 				if targetPort > 0 && targetAddr != "" {
 					inNodeRec := runtimeState.Nodes[firstNodeID]
 					if err := validateRemoteNodePort(inNodeRec, targetPort); err != nil {
-						response.WriteJSON(w, response.ErrDefault(err.Error()))
+						failCreate(err, -1)
 						return
 					}
-					domainCfg, _ := h.repo.GetConfigByName("panel_domain")
-					localDomain := ""
-					if domainCfg != nil {
-						localDomain = domainCfg.Value
-					}
-					_, err := fc.CreateTunnel(rUrl.String, rToken.String, localDomain, targetProto, targetPort, targetAddr)
+					_, err := fc.CreateTunnel(entryNode.RemoteURL, entryNode.RemoteToken, localDomain, targetProto, targetPort, targetAddr)
 					if err != nil {
-						response.WriteJSON(w, response.ErrDefault("Remote tunnel creation failed: "+err.Error()))
+						failCreate(fmt.Errorf("remote tunnel creation failed: %w", err), -1)
 						return
 					}
 				}
@@ -880,66 +952,53 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	var tunnelInIP sql.NullString
-	if trimmed := strings.TrimSpace(inIP); trimmed != "" {
-		tunnelInIP = sql.NullString{String: trimmed, Valid: true}
-	}
-	tunnelProtocol := "tls"
-	if len(runtimeState.InNodes) > 0 && strings.TrimSpace(runtimeState.InNodes[0].Protocol) != "" {
-		tunnelProtocol = strings.TrimSpace(runtimeState.InNodes[0].Protocol)
-	}
-	tunnel := model.Tunnel{
-		Name:            name,
-		TrafficRatio:    trafficRatio,
-		Type:            typeVal,
-		Protocol:        tunnelProtocol,
-		Flow:            flow,
-		CreatedTime:     now,
-		UpdatedTime:     now,
-		Status:          status,
-		InIP:            tunnelInIP,
-		Inx:             inx,
-		IPPreference:    ipPreference,
-		ProbeTargetHost: probeTargetHost,
-		ProbeTargetPort: probeTargetPort,
-	}
-	if err := tx.Create(&tunnel).Error; err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
-		return
-	}
-	tunnelID := tunnel.ID
-	runtimeState.TunnelID = tunnelID
 	var federationBindings []repo.FederationTunnelBinding
 	var federationReleaseRefs []federationRuntimeReleaseRef
 	federationBindings, federationReleaseRefs, err = h.applyFederationRuntime(runtimeState, localDomain)
 	if err != nil {
 		tx.Rollback()
 		err = errors.Join(err, h.releaseFederationRuntimeRefs(federationReleaseRefs))
-		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		failCreate(err, -1)
 		return
 	}
+	tx = h.repo.BeginTx()
+	if tx.Error != nil {
+		failCreate(errors.Join(tx.Error, h.releaseFederationRuntimeRefs(federationReleaseRefs)), -2)
+		return
+	}
+	if typeVal == 2 {
+		if err := h.repo.DeleteChainTunnelsByTunnelTx(tx, tunnelID); err != nil {
+			tx.Rollback()
+			failCreate(errors.Join(err, h.releaseFederationRuntimeRefs(federationReleaseRefs)), -2)
+			return
+		}
+	}
 	applyTunnelPortsToRequest(req, runtimeState)
 	if err := h.replaceTunnelChainsTx(tx, tunnelID, req); err != nil {
 		tx.Rollback()
 		err = errors.Join(err, h.releaseFederationRuntimeRefs(federationReleaseRefs))
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+		failCreate(err, -2)
 		return
 	}
 	if err := h.repo.ReplaceFederationTunnelBindingsTx(tx, tunnelID, federationBindings); err != nil {
 		tx.Rollback()
 		err = errors.Join(err, h.releaseFederationRuntimeRefs(federationReleaseRefs))
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+		failCreate(err, -2)
 		return
 	}
 	if err := tx.Commit().Error; err != nil {
 		tx.Rollback()
 		err = errors.Join(err, h.releaseFederationRuntimeRefs(federationReleaseRefs))
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+		failCreate(err, -2)
 		return
 	}
 	if typeVal == 2 {
 		createdChains, createdServices, applyErr := h.applyTunnelRuntime(runtimeState)
 		if applyErr != nil {
+			if isTunnelRuntimePending(applyErr) {
+				response.WriteJSON(w, tunnelRuntimePendingResponse(tunnelID, applyErr))
+				return
+			}
 			h.rollbackTunnelRuntime(createdChains, createdServices, tunnelID, tunnelProtocol)
 			if cleanupErr := h.cleanupFederationRuntime(tunnelID); cleanupErr != nil {
 				applyErr = errors.Join(applyErr, cleanupErr)
@@ -953,31 +1012,6 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 	response.WriteJSON(w, response.OKEmpty())
 }
 
-func (h *Handler) cleanupTunnelRuntime(tunnelID int64) {
-	tunnel, err := h.getTunnelRecord(tunnelID)
-	if err != nil || tunnel.Type != 2 {
-		return
-	}
-	chainRows, err := h.listChainNodesForTunnel(tunnelID)
-	if err != nil {
-		return
-	}
-
-	chainName := fmt.Sprintf("chains_%d", tunnelID)
-	serviceNames := tunnelRuntimeServiceNames(tunnelID)
-
-	for _, row := range chainRows {
-		if row.ChainType == 1 {
-			_, _ = h.sendNodeCommand(row.NodeID, "DeleteChains", map[string]interface{}{"chain": chainName}, false, true)
-		} else if row.ChainType == 2 {
-			_, _ = h.sendNodeCommand(row.NodeID, "DeleteChains", map[string]interface{}{"chain": chainName}, false, true)
-			_, _ = h.sendNodeCommand(row.NodeID, "DeleteService", map[string]interface{}{"services": serviceNames}, false, true)
-		} else if row.ChainType == 3 {
-			_, _ = h.sendNodeCommand(row.NodeID, "DeleteService", map[string]interface{}{"services": serviceNames}, false, true)
-		}
-	}
-}
-
 func tunnelRuntimeServiceNames(tunnelID int64) []string {
 	return []string{
 		fmt.Sprintf("tunnel_%d", tunnelID),
@@ -1028,20 +1062,6 @@ func removedTunnelRuntimeNodeIDs(oldRows, newRows []chainNodeRecord, needsRuntim
 	return removed
 }
 
-func (h *Handler) cleanupObsoleteTunnelRuntime(tunnelID int64, oldRows, newRows []chainNodeRecord) {
-	if h == nil || tunnelID <= 0 || len(oldRows) == 0 {
-		return
-	}
-	chainName := fmt.Sprintf("chains_%d", tunnelID)
-	for _, nodeID := range removedTunnelRuntimeNodeIDs(oldRows, newRows, tunnelRuntimeNeedsChain) {
-		_, _ = h.sendNodeCommand(nodeID, "DeleteChains", map[string]interface{}{"chain": chainName}, false, true)
-	}
-	serviceNames := tunnelRuntimeServiceNames(tunnelID)
-	for _, nodeID := range removedTunnelRuntimeNodeIDs(oldRows, newRows, tunnelRuntimeNeedsService) {
-		_, _ = h.sendNodeCommand(nodeID, "DeleteService", map[string]interface{}{"services": serviceNames}, false, true)
-	}
-}
-
 func (h *Handler) tunnelGet(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
@@ -1085,6 +1105,8 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("隧道ID不能为空"))
 		return
 	}
+	unlock := h.lockTunnelLifecycle(id)
+	defer unlock()
 	typeVal := asInt(req["type"], 1)
 	ipPreference := asString(req["ipPreference"])
 	_, hasProbeTargetHost := req["probeTargetHost"]
@@ -1140,6 +1162,10 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	runtimeState.TunnelID = id
+	runtimeState.RelayAuthMode = oldTunnel.RelayAuthMode
+	if typeVal == 2 && oldTunnel.Type != 2 {
+		runtimeState.RelayAuthMode = relaysecurity.Required
+	}
 	runtimeState.IPPreference = ipPreference
 	entryNodeIDs := make([]int64, 0, len(runtimeState.InNodes))
 	for _, inNode := range runtimeState.InNodes {
@@ -1183,12 +1209,18 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	if err := h.cleanupFederationRuntime(id); err != nil {
+	if err := h.resolveTunnelRelayAuth(nil, runtimeState, true); err != nil {
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
-	if oldTunnel.Type == 2 && typeVal != 2 {
-		h.cleanupTunnelRuntime(id)
+	if err := h.preflightFederationRelayAuth(runtimeState, localDomain); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+
+	if err := h.cleanupFederationRuntime(id); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
 	}
 
 	var federationBindings []repo.FederationTunnelBinding
@@ -1263,6 +1295,19 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if err := h.repo.SetTunnelRelayAuthModeTx(tx, id, runtimeState.RelayAuthMode); err != nil {
+		tx.Rollback()
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+
+	if oldTunnel.Type == 2 {
+		if err := h.queueObsoleteTunnelRuntimeTx(tx, id, oldChainRows, tunnelStateRuntimeRows(runtimeState)); err != nil {
+			tx.Rollback()
+			response.WriteJSON(w, response.ErrDefault(err.Error()))
+			return
+		}
+	}
 	if err := tx.Commit().Error; err != nil {
 		tx.Rollback()
 		err = errors.Join(err, h.releaseFederationRuntimeRefs(federationReleaseRefs))
@@ -1276,13 +1321,17 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		h.syncTunnelForwardsEntryPorts(id, newEntryNodeIDs)
 	}
 
+	var runtimePending error
 	if typeVal == 2 {
 		applyRuntime := h.applyTunnelRuntime
 		if oldTunnel != nil && oldTunnel.Type == 2 {
 			applyRuntime = h.applyTunnelRuntimeUpsert
 		}
 		createdChains, createdServices, applyErr := applyRuntime(runtimeState)
-		if applyErr != nil {
+		if isTunnelRuntimePending(applyErr) {
+			runtimePending = applyErr
+		}
+		if applyErr != nil && runtimePending == nil {
 			updateProtocol := "tls"
 			if len(runtimeState.InNodes) > 0 && strings.TrimSpace(runtimeState.InNodes[0].Protocol) != "" {
 				updateProtocol = strings.TrimSpace(runtimeState.InNodes[0].Protocol)
@@ -1291,16 +1340,12 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 				h.rollbackTunnelRuntime(createdChains, createdServices, id, updateProtocol)
 			}
 			applyErr = errors.Join(applyErr, h.cleanupFederationRuntime(id))
-			if len(federationReleaseRefs) == 0 && shouldDeferTunnelRuntimeApplyError(applyErr) {
-				response.WriteJSON(w, response.OKEmpty())
-				return
-			}
 			response.WriteJSON(w, response.ErrDefault(applyErr.Error()))
 			return
 		}
-		newChainRows, _ := h.listChainNodesForTunnel(id)
-		h.cleanupObsoleteTunnelRuntime(id, oldChainRows, newChainRows)
+		runtimePending = errors.Join(runtimePending, h.acknowledgeTunnelServiceReplacements(id, createdServices))
 	}
+	runtimePending = errors.Join(runtimePending, h.retryTunnelRuntimeCleanupLocked(id))
 
 	oldType := 0
 	if oldTunnel != nil {
@@ -1309,14 +1354,22 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 	if tunnelForwardRuntimeNeedsSync(oldType, typeVal, oldEntryNodeIDs, newEntryNodeIDs) {
 		forwards, fwdErr := h.listForwardsByTunnel(id)
 		if fwdErr != nil {
-			response.WriteJSON(w, response.OKEmpty())
+			response.WriteJSON(w, tunnelRuntimePendingResponse(id, errors.Join(runtimePending, fwdErr)))
 			return
 		}
+		var forwardErrors []error
 		for i := range forwards {
-			_ = h.syncForwardServices(&forwards[i], "UpdateService", true)
+			if err := h.syncForwardServices(&forwards[i], "UpdateService", true); err != nil {
+				forwardErrors = append(forwardErrors, err)
+			}
 		}
+		runtimePending = errors.Join(runtimePending, errors.Join(forwardErrors...))
 	}
 
+	if runtimePending != nil {
+		response.WriteJSON(w, tunnelRuntimePendingResponse(id, runtimePending))
+		return
+	}
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -1478,6 +1531,15 @@ func (h *Handler) validateForwardPortAvailabilityTx(tx *gorm.DB, node *nodeRecor
 	if h == nil || h.repo == nil || tx == nil || node == nil || port <= 0 {
 		return nil
 	}
+	pendingPorts, err := h.repo.PendingTunnelCleanupPortsTx(tx, node.ID, 0)
+	if err != nil {
+		return err
+	}
+	for _, reserved := range pendingPorts {
+		if reserved == port {
+			return fmt.Errorf("节点 %s 端口 %d 仍在等待旧运行时清理", node.Name, port)
+		}
+	}
 	occupied, err := h.repo.HasOtherForwardOnNodePortTx(tx, node.ID, port, currentForwardID)
 	if err != nil {
 		return err
@@ -1675,11 +1737,12 @@ func (h *Handler) tunnelDelete(w http.ResponseWriter, r *http.Request) {
 	if id <= 0 {
 		return
 	}
+	unlock := h.lockTunnelLifecycle(id)
+	defer unlock()
 	if err := h.cleanupFederationRuntime(id); err != nil {
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
-	h.cleanupTunnelRuntime(id)
 	if err := h.deleteTunnelByID(id); err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
@@ -1740,24 +1803,27 @@ func (h *Handler) tunnelBatchDelete(w http.ResponseWriter, r *http.Request) {
 	fail := 0
 	failures := make([]batchFailureDetail, 0)
 	for _, id := range ids {
-		tunnelName, _ := h.repo.GetTunnelName(id)
-		if _, err := h.getTunnelRecord(id); err != nil {
-			fail++
-			failures = appendBatchFailure(failures, id, tunnelName, err)
-			continue
-		}
-		if err := h.cleanupFederationRuntime(id); err != nil {
-			fail++
-			failures = appendBatchFailure(failures, id, tunnelName, err)
-			continue
-		}
-		h.cleanupTunnelRuntime(id)
-		if err := h.deleteTunnelByID(id); err != nil {
-			fail++
-			failures = appendBatchFailure(failures, id, tunnelName, err)
-		} else {
-			success++
-		}
+		func() {
+			unlock := h.lockTunnelLifecycle(id)
+			defer unlock()
+			tunnelName, _ := h.repo.GetTunnelName(id)
+			if _, err := h.getTunnelRecord(id); err != nil {
+				fail++
+				failures = appendBatchFailure(failures, id, tunnelName, err)
+				return
+			}
+			if err := h.cleanupFederationRuntime(id); err != nil {
+				fail++
+				failures = appendBatchFailure(failures, id, tunnelName, err)
+				return
+			}
+			if err := h.deleteTunnelByID(id); err != nil {
+				fail++
+				failures = appendBatchFailure(failures, id, tunnelName, err)
+			} else {
+				success++
+			}
+		}()
 	}
 	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: success, FailCount: fail, Failures: failures}))
 }
@@ -1776,14 +1842,15 @@ func (h *Handler) reconstructTunnelState(tunnelID int64) (*tunnelCreateState, er
 	ipPreference := h.repo.GetTunnelIPPreference(tunnelID)
 
 	state := &tunnelCreateState{
-		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),
+		RelayAuthMode: tunnel.RelayAuthMode,
+		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)
@@ -1840,10 +1907,23 @@ func (h *Handler) reconstructTunnelState(tunnelID int64) (*tunnelCreateState, er
 		state.Nodes[id] = node
 	}
 
+	if err := h.resolveTunnelRelayAuth(nil, state, false); err != nil {
+		return nil, err
+	}
+
 	return state, nil
 }
 
 func (h *Handler) redeployTunnelAndForwards(tunnelID int64) error {
+	unlock := h.lockTunnelLifecycle(tunnelID)
+	defer unlock()
+	return h.redeployTunnelAndForwardsLocked(tunnelID)
+}
+
+func (h *Handler) redeployTunnelAndForwardsLocked(tunnelID int64) error {
+	if err := h.retryTunnelRuntimeCleanupLocked(tunnelID); err != nil {
+		return err
+	}
 	tunnel, err := h.getTunnelRecord(tunnelID)
 	if err != nil {
 		return err
@@ -1857,28 +1937,44 @@ func (h *Handler) redeployTunnelAndForwards(tunnelID int64) error {
 		if err := validateTunnelRuntimeBeforeApply(state); err != nil {
 			return err
 		}
-		if err := h.cleanupFederationRuntime(tunnelID); err != nil {
+		existingBindings, err := h.repo.ListActiveFederationTunnelBindingsByTunnel(tunnelID)
+		if err != nil {
 			return err
 		}
-		h.cleanupTunnelRuntime(tunnelID)
+		// Reserve/apply use stable resource keys and upsert the peer runtime.
+		// A failed refresh must never release bindings that were already live.
 		federationBindings, federationReleaseRefs, fedErr := h.applyFederationRuntime(state, h.federationLocalDomain())
+		newRefs := make([]federationRuntimeReleaseRef, 0, len(federationReleaseRefs))
+		for _, ref := range federationReleaseRefs {
+			existing := false
+			for _, binding := range existingBindings {
+				if strings.TrimSpace(binding.RemoteURL) == strings.TrimSpace(ref.RemoteURL) && binding.ResourceKey == ref.ResourceKey {
+					existing = true
+					break
+				}
+			}
+			if !existing {
+				newRefs = append(newRefs, ref)
+			}
+		}
 		if fedErr != nil {
-			return errors.Join(fedErr, h.releaseFederationRuntimeRefs(federationReleaseRefs))
+			return errors.Join(fedErr, h.releaseFederationRuntimeRefs(newRefs))
 		}
 		tx := h.repo.BeginTx()
 		if tx.Error != nil {
-			return errors.Join(tx.Error, h.releaseFederationRuntimeRefs(federationReleaseRefs))
+			return errors.Join(tx.Error, h.releaseFederationRuntimeRefs(newRefs))
 		}
 		if replaceErr := h.repo.ReplaceFederationTunnelBindingsTx(tx, tunnelID, federationBindings); replaceErr != nil {
 			tx.Rollback()
-			return errors.Join(replaceErr, h.releaseFederationRuntimeRefs(federationReleaseRefs))
+			return errors.Join(replaceErr, h.releaseFederationRuntimeRefs(newRefs))
 		}
 		if commitErr := tx.Commit().Error; commitErr != nil {
-			return errors.Join(commitErr, h.releaseFederationRuntimeRefs(federationReleaseRefs))
+			return errors.Join(commitErr, h.releaseFederationRuntimeRefs(newRefs))
 		}
-		_, _, applyErr := h.applyTunnelRuntime(state)
+		_, services, applyErr := h.applyTunnelRuntimeUpsert(state)
+		applyErr = errors.Join(applyErr, h.acknowledgeTunnelServiceReplacements(tunnelID, services))
+		applyErr = errors.Join(applyErr, h.retryTunnelRuntimeCleanupLocked(tunnelID))
 		if applyErr != nil {
-			applyErr = errors.Join(applyErr, h.cleanupFederationRuntime(tunnelID))
 			return applyErr
 		}
 	}
@@ -3333,6 +3429,7 @@ func (h *Handler) syncPermissionsByTunnelGroup(tunnelGroupID int64) error {
 }
 
 type tunnelRuntimeNode struct {
+	RelayAuth *relaysecurity.Credentials
 	NodeID    int64
 	Protocol  string
 	Strategy  string
@@ -3343,14 +3440,15 @@ type tunnelRuntimeNode struct {
 }
 
 type tunnelCreateState struct {
-	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
+	RelayAuthMode string
+	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 *gorm.DB, req map[string]interface{}, tunnelType int, excludeTunnelID int64) (*tunnelCreateState, error) {
@@ -3524,6 +3622,21 @@ func (h *Handler) prepareTunnelCreateState(tx *gorm.DB, req map[string]interface
 		}
 	}
 
+	for _, row := range tunnelStateRuntimeRows(state) {
+		if row.Port <= 0 {
+			continue
+		}
+		ports, err := h.repo.PendingTunnelCleanupPortsTx(tx, row.NodeID, excludeTunnelID)
+		if err != nil {
+			return nil, err
+		}
+		for _, port := range ports {
+			if port == row.Port {
+				return nil, errors.New("节点端口仍在等待旧运行时清理")
+			}
+		}
+	}
+
 	return state, nil
 }
 
@@ -3717,6 +3830,10 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState, localDomain s
 	if h == nil || state == nil {
 		return bindings, releaseRefs, nil
 	}
+	if err := h.preflightFederationRelayAuth(state, localDomain); err != nil {
+		return bindings, releaseRefs, err
+	}
+
 	fc := client.NewFederationClient()
 	now := time.Now().UnixMilli()
 
@@ -3752,6 +3869,9 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState, localDomain s
 			ReservationID: reserveRes.ReservationID, ResourceKey: resourceKey,
 		})
 
+		if outNode.RelayAuth != nil && reserveRes.RelayAuthVersion != relaysecurity.Version {
+			return bindings, releaseRefs, errors.New("remote reservation does not support required relay authentication")
+		}
 		state.OutNodes[outIdx].Port = reserveRes.AllocatedPort
 		outNode = state.OutNodes[outIdx]
 
@@ -3759,6 +3879,7 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState, localDomain s
 			ReservationID: reserveRes.ReservationID,
 			ResourceKey:   resourceKey,
 			Role:          "exit",
+			RelayAuth:     outNode.RelayAuth,
 			Protocol:      defaultString(outNode.Protocol, "tls"),
 			Strategy:      defaultString(outNode.Strategy, "round"),
 		}
@@ -3820,6 +3941,9 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState, localDomain s
 				ReservationID: reserveRes.ReservationID, ResourceKey: resourceKey,
 			})
 
+			if chainNode.RelayAuth != nil && reserveRes.RelayAuthVersion != relaysecurity.Version {
+				return bindings, releaseRefs, errors.New("remote reservation does not support required relay authentication")
+			}
 			state.ChainHops[hopIdx][nodeIdx].Port = reserveRes.AllocatedPort
 			chainNode = state.ChainHops[hopIdx][nodeIdx]
 
@@ -3843,9 +3967,10 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState, localDomain s
 					return bindings, releaseRefs, errors.New("节点端口不能为空")
 				}
 				applyTargets = append(applyTargets, client.RuntimeTarget{
-					Host:     host,
-					Port:     target.Port,
-					Protocol: defaultString(target.Protocol, "tls"),
+					Host:      host,
+					RelayAuth: target.RelayAuth,
+					Port:      target.Port,
+					Protocol:  defaultString(target.Protocol, "tls"),
 				})
 			}
 
@@ -3853,6 +3978,7 @@ func (h *Handler) applyFederationRuntime(state *tunnelCreateState, localDomain s
 				ReservationID: reserveRes.ReservationID,
 				ResourceKey:   resourceKey,
 				Role:          "middle",
+				RelayAuth:     chainNode.RelayAuth,
 				Protocol:      defaultString(chainNode.Protocol, "tls"),
 				Strategy:      runtimeStrategyForTargets(chainNode, nextTargets),
 				Targets:       applyTargets,
@@ -4017,6 +4143,7 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 		return createdChains, createdServices, nil
 	}
 
+	var pending []error
 	for _, inNode := range state.InNodes {
 		targets := state.OutNodes
 		if len(state.ChainHops) > 0 {
@@ -4030,6 +4157,7 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 		}
 		if err := h.applyTunnelChainOnNode(inNode.NodeID, chainData, upsert); err != nil {
 			if shouldDeferTunnelRuntimeApplyError(err) {
+				pending = append(pending, err)
 				continue
 			}
 			return createdChains, createdServices, fmt.Errorf("入口节点 %s 下发转发链失败: %w", nodeDisplayName(state.Nodes[inNode.NodeID]), err)
@@ -4046,7 +4174,11 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 				nextTargets = h.orderBestExitTargets(state.TunnelID, chainNode.NodeID, nextTargets)
 			}
 			node := state.Nodes[chainNode.NodeID]
-			if node != nil && (node.IsRemote == 1 || node.Status != 1) {
+			if node != nil && node.IsRemote == 1 {
+				continue
+			}
+			if node != nil && node.Status != 1 {
+				pending = append(pending, fmt.Errorf("节点 %s 不在线", nodeDisplayName(node)))
 				continue
 			}
 			chainData, err := buildTunnelChainConfig(state.TunnelID, chainNode.NodeID, nextTargets, state.Nodes, state.IPPreference)
@@ -4055,6 +4187,7 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 			}
 			if err := h.applyTunnelChainOnNode(chainNode.NodeID, chainData, upsert); err != nil {
 				if shouldDeferTunnelRuntimeApplyError(err) {
+					pending = append(pending, err)
 					continue
 				}
 				return createdChains, createdServices, fmt.Errorf("转发链节点 %s 下发转发链失败: %w", nodeDisplayName(state.Nodes[chainNode.NodeID]), err)
@@ -4064,6 +4197,7 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 			serviceData := buildTunnelChainServiceConfig(state.TunnelID, chainNode, state.Nodes[chainNode.NodeID], len(nextTargets))
 			if err := h.addTunnelServiceOnNodeWithMode(chainNode.NodeID, state.TunnelID, serviceData, upsert); err != nil {
 				if shouldDeferTunnelRuntimeApplyError(err) {
+					pending = append(pending, err)
 					continue
 				}
 				return createdChains, createdServices, fmt.Errorf("转发链节点 %s 下发服务失败: %w", nodeDisplayName(state.Nodes[chainNode.NodeID]), err)
@@ -4074,12 +4208,17 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 
 	for _, outNode := range state.OutNodes {
 		node := state.Nodes[outNode.NodeID]
-		if node != nil && (node.IsRemote == 1 || node.Status != 1) {
+		if node != nil && node.IsRemote == 1 {
+			continue
+		}
+		if node != nil && node.Status != 1 {
+			pending = append(pending, fmt.Errorf("节点 %s 不在线", nodeDisplayName(node)))
 			continue
 		}
 		serviceData := buildTunnelChainServiceConfig(state.TunnelID, outNode, state.Nodes[outNode.NodeID], 1)
 		if err := h.addTunnelServiceOnNodeWithMode(outNode.NodeID, state.TunnelID, serviceData, upsert); err != nil {
 			if shouldDeferTunnelRuntimeApplyError(err) {
+				pending = append(pending, err)
 				continue
 			}
 			return createdChains, createdServices, fmt.Errorf("出口节点 %s 下发服务失败: %w", nodeDisplayName(state.Nodes[outNode.NodeID]), err)
@@ -4087,6 +4226,9 @@ func (h *Handler) applyTunnelRuntimeWithMode(state *tunnelCreateState, upsert bo
 		createdServices = append(createdServices, outNode.NodeID)
 	}
 
+	if len(pending) > 0 {
+		return createdChains, createdServices, &tunnelRuntimePendingError{cause: errors.Join(pending...)}
+	}
 	return createdChains, createdServices, nil
 }
 
@@ -4107,7 +4249,15 @@ func (h *Handler) applyBestExitChainOrder(tunnelID, ownerNodeID int64, outNodes
 		log.Printf("best_exit: invalid chain update input tunnel=%d owner=%d exits=%d", tunnelID, ownerNodeID, len(outNodes))
 		return fmt.Errorf("invalid best exit chain update input tunnel=%d owner=%d exits=%d", tunnelID, ownerNodeID, len(outNodes))
 	}
+	unlock := h.lockTunnelLifecycle(tunnelID)
+	defer unlock()
+	if err := h.validateBestExitSnapshot(tunnelID, ownerNodeID, outNodes, ipPreference); err != nil {
+		return err
+	}
 	targets := chainRecordsToRuntimeTargets(outNodes)
+	if err := h.resolveBestExitRelayAuth(tunnelID, targets); err != nil {
+		return err
+	}
 	orderedIDs := make([]int64, 0, len(scores))
 	for _, score := range scores {
 		if score.ExitNodeID > 0 {
@@ -4188,9 +4338,10 @@ func (h *Handler) applyRemoteBestExitChainOrder(tunnelID, ownerNodeID int64, own
 			return errors.New("节点端口不能为空")
 		}
 		applyTargets = append(applyTargets, client.RuntimeTarget{
-			Host:     host,
-			Port:     target.Port,
-			Protocol: defaultString(target.Protocol, "tls"),
+			Host:      host,
+			RelayAuth: target.RelayAuth,
+			Port:      target.Port,
+			Protocol:  defaultString(target.Protocol, "tls"),
 		})
 	}
 
@@ -4212,8 +4363,30 @@ func (h *Handler) applyRemoteBestExitChainOrder(tunnelID, ownerNodeID int64, own
 		}
 	}
 
+	var credentials *relaysecurity.Credentials
+	tunnel, loadErr := h.repo.GetTunnelRecord(tunnelID)
+	if loadErr != nil {
+		return loadErr
+	}
+	if tunnel == nil {
+		return errors.New("tunnel not found")
+	}
+	if tunnel.RelayAuthMode == relaysecurity.Required {
+		credentials, err = h.repo.RelayEndpointCredentials(nil, tunnelID, ownerNodeID, 2, false)
+		if err != nil {
+			return err
+		}
+		info, e := client.NewFederationClient().Connect(remoteURL, remoteToken, h.federationLocalDomain())
+		if e != nil {
+			return e
+		}
+		if info.RelayAuthVersion != relaysecurity.Version {
+			return errors.New("remote does not support required relay authentication")
+		}
+	}
 	_, err = client.NewFederationClient().ApplyRole(remoteURL, remoteToken, h.federationLocalDomain(), client.RuntimeApplyRoleRequest{
 		ResourceKey: strings.TrimSpace(binding.ResourceKey),
+		RelayAuth:   credentials,
 		Role:        "middle",
 		Protocol:    defaultString(ownerRuntimeNode.Protocol, "tls"),
 		Strategy:    runtimeStrategyForTargets(ownerRuntimeNode, targets),
@@ -4263,19 +4436,20 @@ func (h *Handler) addTunnelServiceOnNodeWithMode(nodeID, tunnelID int64, service
 	if h == nil {
 		return errors.New("invalid tunnel service context")
 	}
+	if upsert {
+		// Update failure must not trigger deletion of an existing listener.
+		_, err := h.sendNodeCommand(nodeID, "UpdateService", serviceData, true, false)
+		return err
+	}
 	serviceName := fmt.Sprintf("%d_tls", tunnelID)
 	if len(serviceData) > 0 {
 		if name, ok := serviceData[0]["name"].(string); ok && strings.TrimSpace(name) != "" {
 			serviceName = strings.TrimSpace(name)
 		}
 	}
-	command := "AddService"
-	if upsert {
-		command = "UpdateService"
-	}
 	return retryTunnelServiceAddWithCleanup(
 		func() error {
-			_, err := h.sendNodeCommand(nodeID, command, serviceData, true, false)
+			_, err := h.sendNodeCommand(nodeID, "AddService", serviceData, true, false)
 			return err
 		},
 		func() error {
@@ -4366,6 +4540,12 @@ func buildTunnelChainConfig(tunnelID int64, fromNodeID int64, targets []tunnelRu
 		connector := map[string]interface{}{
 			"type": "relay",
 		}
+		if target.RelayAuth != nil {
+			if err := target.RelayAuth.Validate(); err != nil {
+				return nil, err
+			}
+			connector["auth"] = target.RelayAuth.Config()
+		}
 		connectorMetadata := map[string]interface{}{}
 		if isTCPTunnelProtocol(protocol) {
 			connectorMetadata["nodelay"] = true
@@ -4438,6 +4618,9 @@ func buildTunnelChainServiceConfig(tunnelID int64, chainNode tunnelRuntimeNode,
 	handlerCfg := map[string]interface{}{
 		"type": "relay",
 	}
+	if chainNode.RelayAuth != nil {
+		handlerCfg["auth"] = chainNode.RelayAuth.Config()
+	}
 	handlerMetadata := map[string]interface{}{}
 	if isTCPTunnelProtocol(protocol) {
 		handlerMetadata["nodelay"] = true
@@ -4466,6 +4649,8 @@ func buildTunnelChainServiceConfig(tunnelID int64, chainNode tunnelRuntimeNode,
 		"listener": buildTunnelListenerConfig(protocol),
 	}
 	if chainNode.ChainType == 2 {
+		handlerMetadata["chain.strict"] = true
+		handlerCfg["metadata"] = handlerMetadata
 		service["handler"].(map[string]interface{})["chain"] = fmt.Sprintf("chains_%d", tunnelID)
 	}
 	if chainNode.ChainType == 3 && strings.TrimSpace(node.InterfaceName) != "" {
@@ -4765,6 +4950,9 @@ func (h *Handler) deleteTunnelByID(id int64) error {
 		return err
 	}
 
+	if err := h.retryTunnelRuntimeCleanupLocked(id); err != nil {
+		return &tunnelDeletionCleanupPendingError{cause: err}
+	}
 	shareID, port, ok := parsePeerShareInfoFromFederationTunnelName(tunnelName)
 	if !ok {
 		return nil
@@ -5456,6 +5644,15 @@ func (h *Handler) validateForwardPortAvailability(node *nodeRecord, port int, cu
 	if h == nil || h.repo == nil || node == nil || port <= 0 {
 		return nil
 	}
+	pendingPorts, err := h.repo.PendingTunnelCleanupPortsTx(nil, node.ID, 0)
+	if err != nil {
+		return err
+	}
+	for _, reserved := range pendingPorts {
+		if reserved == port {
+			return fmt.Errorf("节点 %s 端口 %d 仍在等待旧运行时清理", node.Name, port)
+		}
+	}
 	occupied, err := h.repo.HasOtherForwardOnNodePort(node.ID, port, currentForwardID)
 	if err != nil {
 		return err

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

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"slices"
 	"strings"
 	"time"
 
@@ -150,7 +151,7 @@ func (h *Handler) validateNftablesTunnelStateTx(tx *gorm.DB, entryNodeIDs []int6
 	return nil
 }
 
-func (h *Handler) buildNftablesNodePlan(nodeID int64) (runtimenft.NodePlan, *model.NodeSSHConfig, error) {
+func (h *Handler) buildNftablesNodePlan(nodeID int64, excludedForwardIDs ...int64) (runtimenft.NodePlan, *model.NodeSSHConfig, error) {
 	cfg, err := h.repo.GetNodeSSHConfig(nodeID)
 	if err != nil {
 		return runtimenft.NodePlan{}, nil, err
@@ -162,6 +163,9 @@ func (h *Handler) buildNftablesNodePlan(nodeID int64) (runtimenft.NodePlan, *mod
 	plan := runtimenft.NodePlan{NodeID: nodeID, Rules: make([]runtimenft.Rule, 0, len(forwards))}
 	for i := range forwards {
 		forward := &forwards[i]
+		if slices.Contains(excludedForwardIDs, forward.ID) {
+			continue
+		}
 		tunnel, err := h.getTunnelRecord(forward.TunnelID)
 		if err != nil || tunnel == nil || tunnel.Status != 1 {
 			continue
@@ -201,11 +205,11 @@ func (h *Handler) buildNftablesNodePlan(nodeID int64) (runtimenft.NodePlan, *mod
 	return plan, cfg, nil
 }
 
-func (h *Handler) syncNftablesNode(nodeID int64) error {
+func (h *Handler) syncNftablesNode(nodeID int64, excludedForwardIDs ...int64) error {
 	if h == nil || h.repo == nil {
 		return errors.New("handler not initialized")
 	}
-	plan, cfgModel, err := h.buildNftablesNodePlan(nodeID)
+	plan, cfgModel, err := h.buildNftablesNodePlan(nodeID, excludedForwardIDs...)
 	if err != nil {
 		return err
 	}

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

@@ -29,12 +29,19 @@ func (h *Handler) applyPeerShareRoleRuntime(runtime *repo.PeerShareRuntime) erro
 	if err != nil {
 		return err
 	}
+	credentials, err := decodeRuntimeRelayAuth(runtime)
+	if err != nil {
+		return err
+	}
 	var targets []federationRuntimeTarget
 	if strings.TrimSpace(runtime.Target) != "" {
 		if err := json.Unmarshal([]byte(runtime.Target), &targets); err != nil {
 			return err
 		}
 	}
+	if err := validateFederationRelayAuth(runtime.RelayAuth, credentials, targets); err != nil {
+		return err
+	}
 	var chain map[string]interface{}
 	if runtime.Role == "middle" {
 		chain, err = buildFederationMiddleChainConfig(runtime.ChainName, runtime.ID, runtime.Protocol, runtime.Strategy, targets, node.InterfaceName)
@@ -42,7 +49,7 @@ func (h *Handler) applyPeerShareRoleRuntime(runtime *repo.PeerShareRuntime) erro
 			return err
 		}
 	}
-	service := buildFederationServiceConfig(runtime.ServiceName, fmt.Sprintf("%s:%d", node.TCPListenAddr, runtime.Port), runtime.Protocol, runtime.Role, runtime.ChainName, len(targets), node.InterfaceName)
+	service := buildFederationServiceConfig(runtime.ServiceName, fmt.Sprintf("%s:%d", node.TCPListenAddr, runtime.Port), runtime.Protocol, runtime.Role, runtime.ChainName, len(targets), node.InterfaceName, credentials)
 	runtime.Applied = 0
 	runtime.UpdatedTime = time.Now().UnixMilli()
 	if err := h.repo.UpdatePeerShareRuntime(runtime); err != nil {

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

@@ -145,18 +145,20 @@ func TestPeerShareReleaseOfflineKeepsPortAndReconnectDeletes(t *testing.T) {
 }
 
 func TestPeerShareApplyPersistsBeforeCommand(t *testing.T) {
-	agent := newCleanupAgent(t)
-	runtime := roleRuntimeFixture(t, agent, "exit")
-	callback := "test:fail-role-desired-write"
-	if err := agent.h.repo.DB().Callback().Update().Before("gorm:update").Register(callback, func(tx *gorm.DB) {
-		if tx.Statement.Table == "peer_share_runtime" {
-			tx.AddError(errors.New("desired-state write failed"))
+	var failDesiredWrite atomic.Bool
+	agent := newCleanupAgent(t, func(r *repo.Repository) {
+		if err := r.DB().Callback().Update().Before("gorm:update").Register("test:fail-role-desired-write", func(tx *gorm.DB) {
+			if failDesiredWrite.Load() && tx.Statement.Table == "peer_share_runtime" {
+				tx.AddError(errors.New("desired-state write failed"))
+			}
+		}); err != nil {
+			t.Fatal(err)
 		}
-	}); err != nil {
-		t.Fatal(err)
-	}
-	// This database is test-local; keep the callback registered through the
-	// websocket teardown so callback mutation cannot race node status writes.
+	})
+	runtime := roleRuntimeFixture(t, agent, "exit")
+	failDesiredWrite.Store(true)
+	// Only the atomic flag changes while the WebSocket is running; GORM's
+	// callback registry stays immutable through node-status teardown writes.
 	if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation","role":"exit"}`, false); code == 0 {
 		t.Fatal("failed ownership persistence reported success")
 	}

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

@@ -0,0 +1,125 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/http/client"
+	"go-backend/internal/relaysecurity"
+	"go-backend/internal/store/repo"
+	"gorm.io/gorm"
+)
+
+func (h *Handler) resolveTunnelRelayAuth(tx *gorm.DB, state *tunnelCreateState, create bool) error {
+	if state.Type != 2 || state.RelayAuthMode == relaysecurity.Legacy {
+		return nil
+	}
+	if state.RelayAuthMode != relaysecurity.Required {
+		return fmt.Errorf("unsupported relay authentication mode")
+	}
+	for i := range state.OutNodes {
+		c, err := h.repo.RelayEndpointCredentials(tx, state.TunnelID, state.OutNodes[i].NodeID, 3, create)
+		if err != nil {
+			return err
+		}
+		state.OutNodes[i].RelayAuth = c
+	}
+	for hop := range state.ChainHops {
+		for i := range state.ChainHops[hop] {
+			c, err := h.repo.RelayEndpointCredentials(tx, state.TunnelID, state.ChainHops[hop][i].NodeID, 2, create)
+			if err != nil {
+				return err
+			}
+			state.ChainHops[hop][i].RelayAuth = c
+		}
+	}
+	return nil
+}
+
+func (h *Handler) resolveBestExitRelayAuth(tunnelID int64, targets []tunnelRuntimeNode) error {
+	tunnel, err := h.repo.GetTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+	if tunnel == nil {
+		return fmt.Errorf("tunnel not found")
+	}
+	return h.resolveTunnelRelayAuth(nil, &tunnelCreateState{TunnelID: tunnelID, Type: tunnel.Type, RelayAuthMode: tunnel.RelayAuthMode, OutNodes: targets}, false)
+}
+
+func relayAuthVersion(c *relaysecurity.Credentials) int {
+	if c == nil {
+		return 0
+	}
+	return c.Version
+}
+func decodePersistedRelayAuth(raw string) (*relaysecurity.Credentials, error) {
+	if raw == "" {
+		return nil, nil
+	}
+	var c relaysecurity.Credentials
+	if err := json.Unmarshal([]byte(raw), &c); err != nil {
+		return nil, fmt.Errorf("invalid persisted relay authentication")
+	}
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	return &c, nil
+}
+func validateFederationRelayAuth(persisted string, c *relaysecurity.Credentials, targets []federationRuntimeTarget) error {
+	old, err := decodePersistedRelayAuth(persisted)
+	if err != nil {
+		return err
+	}
+	if old != nil && (c == nil || *old != *c) {
+		return fmt.Errorf("authenticated relay cannot be downgraded or rotated by reapply")
+	}
+	if c != nil {
+		if err := c.Validate(); err != nil {
+			return err
+		}
+		for _, target := range targets {
+			if err := target.RelayAuth.Validate(); err != nil {
+				return err
+			}
+		}
+	} else {
+		for _, target := range targets {
+			if target.RelayAuth != nil {
+				if err := target.RelayAuth.Validate(); err != nil {
+					return err
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func (h *Handler) preflightFederationRelayAuth(state *tunnelCreateState, domain string) error {
+	if state.RelayAuthMode != relaysecurity.Required || state.Type != 2 {
+		return nil
+	}
+	for _, node := range state.Nodes {
+		if node == nil || node.IsRemote != 1 {
+			continue
+		}
+		info, err := client.NewFederationClient().Connect(node.RemoteURL, node.RemoteToken, domain)
+		if err != nil {
+			return fmt.Errorf("relay authentication capability check failed for remote node %d", node.ID)
+		}
+		if info.RelayAuthVersion != relaysecurity.Version {
+			return fmt.Errorf("remote node %d does not support required relay authentication", node.ID)
+		}
+	}
+	return nil
+}
+
+func decodeRuntimeRelayAuth(runtime *repo.PeerShareRuntime) (*relaysecurity.Credentials, error) {
+	c, err := decodePersistedRelayAuth(runtime.RelayAuth)
+	if err != nil {
+		return nil, err
+	}
+	if runtime.RelayAuthVersion != relayAuthVersion(c) {
+		return nil, fmt.Errorf("persisted relay authentication version or credentials unavailable")
+	}
+	return c, nil
+}

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

@@ -371,6 +371,8 @@ func summarizeTunnelDeleteRuleFailures(failures []batchFailureDetail) string {
 }
 
 func (h *Handler) processTunnelDeleteWithForwards(tunnelID int64, action string, targetTunnelID int64) (tunnelDeleteWithForwardsResult, []batchFailureDetail, error) {
+	unlock := h.lockTunnelLifecycle(tunnelID, targetTunnelID)
+	defer unlock()
 	preview, err := h.buildTunnelDeletePreview(tunnelID)
 	if err != nil {
 		return tunnelDeleteWithForwardsResult{}, nil, err
@@ -431,9 +433,14 @@ func (h *Handler) processTunnelDeleteReplaceAction(tunnelID, targetTunnelID int6
 	}
 
 	if err := h.deleteTunnelAndCleanup(tunnelID); err != nil {
-		h.rollbackTunnelForwardMigrationPlans(plans)
-		_ = h.redeployTunnelAndForwards(tunnelID)
-		return tunnelDeleteWithForwardsResult{}, nil, err
+		var pending *tunnelDeletionCleanupPendingError
+		if errors.As(err, &pending) {
+			warnings = append(warnings, err.Error())
+		} else {
+			h.rollbackTunnelForwardMigrationPlans(plans)
+			_ = h.redeployTunnelAndForwardsLocked(tunnelID)
+			return tunnelDeleteWithForwardsResult{}, nil, err
+		}
 	}
 
 	result.MigratedCount = len(plans)
@@ -639,8 +646,9 @@ func (h *Handler) rollbackTunnelForwardMigrationPlans(plans []tunnelForwardMigra
 }
 
 func (h *Handler) deleteTunnelAndCleanup(tunnelID int64) error {
-	h.cleanupTunnelRuntime(tunnelID)
-	h.cleanupFederationRuntime(tunnelID)
+	if err := h.cleanupFederationRuntime(tunnelID); err != nil {
+		return err
+	}
 	if err := h.deleteTunnelByID(tunnelID); err != nil {
 		return err
 	}

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

@@ -0,0 +1,153 @@
+package handler
+
+import (
+	"database/sql"
+	"errors"
+	"go-backend/internal/http/response"
+	"gorm.io/gorm"
+	"slices"
+	"sort"
+	"sync"
+)
+
+type tunnelLifecycleLock struct {
+	mu    sync.Mutex
+	users int
+}
+
+// lockTunnelLifecycle serializes snapshots, persistence and node acknowledgements.
+// Multiple tunnels (forward migration) are locked in ID order to avoid deadlocks.
+// Callers must not acquire these locks recursively or hold a database transaction.
+func (h *Handler) lockTunnelLifecycle(ids ...int64) func() {
+	unique := make(map[int64]bool, len(ids))
+	ordered := make([]int64, 0, len(ids))
+	for _, id := range ids {
+		if id > 0 && !unique[id] {
+			unique[id] = true
+			ordered = append(ordered, id)
+		}
+	}
+	sort.Slice(ordered, func(i, j int) bool { return ordered[i] < ordered[j] })
+	locks := make([]*tunnelLifecycleLock, 0, len(ordered))
+	for _, id := range ordered {
+		h.tunnelLifecycleMu.Lock()
+		if h.tunnelLifecycleLocks == nil {
+			h.tunnelLifecycleLocks = make(map[int64]*tunnelLifecycleLock)
+		}
+		lock := h.tunnelLifecycleLocks[id]
+		if lock == nil {
+			lock = &tunnelLifecycleLock{}
+			h.tunnelLifecycleLocks[id] = lock
+		}
+		lock.users++
+		h.tunnelLifecycleMu.Unlock()
+		lock.mu.Lock()
+		locks = append(locks, lock)
+	}
+	return func() {
+		for i := len(locks) - 1; i >= 0; i-- {
+			h.tunnelLifecycleMu.Lock()
+			locks[i].mu.Unlock()
+			locks[i].users--
+			if locks[i].users == 0 {
+				delete(h.tunnelLifecycleLocks, ordered[i])
+			}
+			h.tunnelLifecycleMu.Unlock()
+		}
+	}
+}
+
+// Probes run without the lifecycle lock. Recheck their topology under the lock
+// so a late result cannot restore a removed middle hop or deleted tunnel.
+func (h *Handler) validateBestExitSnapshot(tunnelID, ownerNodeID int64, exits []chainNodeRecord, ipPreference string) error {
+	tunnel, err := h.getTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+	if tunnel.Type != 2 || h.repo.GetTunnelIPPreference(tunnelID) != ipPreference {
+		return errors.New("best exit topology changed; retry next probe")
+	}
+	rows, err := h.listChainNodesForTunnel(tunnelID)
+	if err != nil {
+		return err
+	}
+	ins, hops, currentExits := splitChainNodeGroups(rows)
+	if !slices.Equal(exits, currentExits) {
+		return errors.New("best exit targets changed; retry next probe")
+	}
+	for _, owner := range bestExitChainOwners(ins, hops) {
+		if owner.NodeID == ownerNodeID {
+			return nil
+		}
+	}
+	return errors.New("best exit owner changed; retry next probe")
+}
+
+// A newly allocated ID is not visible yet. Claim it without waiting while the
+// insert transaction is open: an overlapping request for that ID must not make
+// creation wait on a lifecycle lock whose owner is waiting for this transaction.
+func (h *Handler) tryLockNewTunnelLifecycle(id int64) (func(), bool) {
+	h.tunnelLifecycleMu.Lock()
+	defer h.tunnelLifecycleMu.Unlock()
+	if h.tunnelLifecycleLocks == nil {
+		h.tunnelLifecycleLocks = make(map[int64]*tunnelLifecycleLock)
+	}
+	if h.tunnelLifecycleLocks[id] != nil {
+		return nil, false
+	}
+	lock := &tunnelLifecycleLock{users: 1}
+	lock.mu.Lock()
+	h.tunnelLifecycleLocks[id] = lock
+	return func() {
+		h.tunnelLifecycleMu.Lock()
+		defer h.tunnelLifecycleMu.Unlock()
+		lock.mu.Unlock()
+		lock.users--
+		if lock.users == 0 {
+			delete(h.tunnelLifecycleLocks, id)
+		}
+	}, true
+}
+
+// Pending is not successful application. HTTP create/update retain their
+// accepted-config contract, while redeploy returns this error to its batch result.
+type tunnelRuntimePendingError struct{ cause error }
+
+func (e *tunnelRuntimePendingError) Error() string { return "运行时待同步: " + e.cause.Error() }
+func isTunnelRuntimePending(err error) bool {
+	var pending *tunnelRuntimePendingError
+	return errors.As(err, &pending)
+}
+func tunnelRuntimePendingResponse(tunnelID int64, err error) response.R {
+	message := "配置已保存，部分节点运行时待同步：" + err.Error()
+	out := response.OK(map[string]interface{}{"runtimeStatus": "pending", "tunnelId": tunnelID, "message": message})
+	out.Msg = message
+	return out
+}
+
+// Reserve locally allocated ports with the initial desired state, before any
+// remote acknowledgment. Remote ports remain unallocated until their provider
+// returns; the second transaction replaces these rows with the final bindings.
+func (h *Handler) persistPreparedTunnelChainsTx(tx *gorm.DB, state *tunnelCreateState) error {
+	save := func(node tunnelRuntimeNode, kind string, inx int) error {
+		return h.repo.CreateChainTunnelTx(tx, state.TunnelID, kind, node.NodeID, sql.NullInt64{Int64: int64(node.Port), Valid: node.Port > 0}, defaultString(node.Strategy, "round"), inx, defaultString(node.Protocol, "tls"), node.ConnectIP)
+	}
+	for i, node := range state.InNodes {
+		if err := save(node, "1", i+1); err != nil {
+			return err
+		}
+	}
+	for i, node := range state.OutNodes {
+		if err := save(node, "3", i+1); err != nil {
+			return err
+		}
+	}
+	for i, hop := range state.ChainHops {
+		for _, node := range hop {
+			if err := save(node, "2", i+1); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}

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

@@ -0,0 +1,180 @@
+package handler
+
+import (
+	"errors"
+	"fmt"
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+)
+
+func tunnelStateRuntimeRows(state *tunnelCreateState) []chainNodeRecord {
+	if state.Type != 2 {
+		return nil
+	}
+	var rows []chainNodeRecord
+	for _, n := range state.InNodes {
+		rows = append(rows, chainNodeRecord{NodeID: n.NodeID, ChainType: 1})
+	}
+	for _, hop := range state.ChainHops {
+		for _, n := range hop {
+			rows = append(rows, chainNodeRecord{NodeID: n.NodeID, ChainType: 2, Port: n.Port})
+		}
+	}
+	for _, n := range state.OutNodes {
+		rows = append(rows, chainNodeRecord{NodeID: n.NodeID, ChainType: 3, Port: n.Port})
+	}
+	return rows
+}
+func (h *Handler) queueObsoleteTunnelRuntimeTx(tx *gorm.DB, tunnelID int64, oldRows, newRows []chainNodeRecord) error {
+	var items []model.TunnelRuntimeCleanup
+	for _, nodeID := range removedTunnelRuntimeNodeIDs(oldRows, newRows, tunnelRuntimeNeedsService) {
+		port := 0
+		for _, row := range oldRows {
+			if row.NodeID == nodeID {
+				port = row.Port
+				break
+			}
+		}
+		items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: nodeID, Kind: "service", Port: port})
+	}
+	for _, old := range oldRows {
+		if !tunnelRuntimeNeedsService(old) {
+			continue
+		}
+		for _, current := range newRows {
+			if current.NodeID == old.NodeID && tunnelRuntimeNeedsService(current) && (current.Port != old.Port || current.ChainType != old.ChainType) {
+				items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: old.NodeID, Kind: "service", Port: old.Port})
+			}
+		}
+	}
+	for _, nodeID := range removedTunnelRuntimeNodeIDs(oldRows, newRows, tunnelRuntimeNeedsChain) {
+		items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: nodeID, Kind: "chain"})
+	}
+	return h.repo.QueueTunnelRuntimeCleanupTx(tx, items)
+}
+
+// Caller holds the tunnel lifecycle lock. Recheck current desired roles before
+// every retry so a delayed deletion cannot remove a re-added runtime.
+func (h *Handler) retryTunnelRuntimeCleanupLocked(tunnelID int64) error {
+	items, err := h.repo.ListTunnelRuntimeCleanup(tunnelID)
+	if err != nil {
+		return err
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	tunnel, err := h.repo.GetTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+	var rows []chainNodeRecord
+	if tunnel != nil && tunnel.Type == 2 {
+		rows, err = h.listChainNodesForTunnel(tunnelID)
+		if err != nil {
+			return err
+		}
+	}
+	var failures []error
+	liveServices := map[int64]bool{}
+	for _, item := range items {
+		desired := false
+		for _, row := range rows {
+			if row.NodeID == item.NodeID && ((item.Kind == "service" && tunnelRuntimeNeedsService(row)) || (item.Kind == "chain" && tunnelRuntimeNeedsChain(row))) {
+				desired = true
+				break
+			}
+		}
+		if desired && item.Kind == "service" {
+			// Desired state does not prove that the old receiver was replaced.
+			// Keep this barrier (even at the same port) and protect its old
+			// chain until acknowledgeTunnelServiceReplacements observes ACK.
+			liveServices[item.NodeID] = true
+			continue
+		}
+		if !desired {
+			if item.Kind == "chain" && liveServices[item.NodeID] {
+				continue
+			}
+			var commandErr error
+			if item.Kind == "service" {
+				_, commandErr = h.sendNodeCommand(item.NodeID, "DeleteService", map[string]interface{}{"services": tunnelRuntimeServiceNames(tunnelID)}, false, true)
+			} else {
+				_, commandErr = h.sendNodeCommand(item.NodeID, "DeleteChains", map[string]interface{}{"chain": fmt.Sprintf("chains_%d", tunnelID)}, false, true)
+			}
+			if commandErr != nil {
+				if item.Kind == "service" {
+					liveServices[item.NodeID] = true
+				}
+				failures = append(failures, fmt.Errorf("节点 %d 旧运行时清理失败: %w", item.NodeID, commandErr))
+				continue
+			}
+		}
+		if err := h.repo.DeleteTunnelRuntimeCleanup(item.ID); err != nil {
+			if item.Kind == "service" {
+				liveServices[item.NodeID] = true
+			}
+			failures = append(failures, err)
+		}
+	}
+	return errors.Join(failures...)
+}
+
+func (h *Handler) acknowledgeTunnelServiceReplacements(tunnelID int64, nodeIDs []int64) error {
+	if len(nodeIDs) == 0 {
+		return nil
+	}
+	items, err := h.repo.ListTunnelRuntimeCleanup(tunnelID)
+	if err != nil {
+		return err
+	}
+	for _, item := range items {
+		if item.Kind == "service" {
+			for _, nodeID := range nodeIDs {
+				if item.NodeID == nodeID {
+					if err := h.repo.DeleteTunnelRuntimeCleanup(item.ID); err != nil {
+						return err
+					}
+					break
+				}
+			}
+		}
+	}
+	return nil
+}
+func (h *Handler) retryPendingTunnelRuntimeCleanup() error {
+	return h.retryPendingTunnelRuntimeCleanupOnNode(0)
+}
+
+func (h *Handler) retryPendingTunnelRuntimeCleanupOnNode(nodeID int64) error {
+	items, err := h.repo.ListTunnelRuntimeCleanup(0)
+	if err != nil {
+		return err
+	}
+	seen := map[int64]bool{}
+	var failures []error
+	for _, item := range items {
+		if nodeID > 0 && item.NodeID != nodeID {
+			continue
+		}
+		if seen[item.TunnelID] {
+			continue
+		}
+		seen[item.TunnelID] = true
+		unlock := h.lockTunnelLifecycle(item.TunnelID)
+		err := h.retryTunnelRuntimeCleanupLocked(item.TunnelID)
+		unlock()
+		if err != nil {
+			failures = append(failures, err)
+		}
+	}
+	return errors.Join(failures...)
+}
+
+// The desired tunnel has already been deleted; callers must not roll back a
+// completed forward migration merely because asynchronous cleanup is pending.
+type tunnelDeletionCleanupPendingError struct{ cause error }
+
+func (e *tunnelDeletionCleanupPendingError) Error() string {
+	return "隧道配置已删除，运行时清理待重试: " + e.cause.Error()
+}
+func (e *tunnelDeletionCleanupPendingError) Unwrap() error { return e.cause }

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

@@ -411,6 +411,9 @@ func (h *Handler) onNodeOnline(nodeID int64) {
 
 	// A fresh agent needs a full restore. Shared failures remain persisted and
 	// are retried by maintenance without restarting acknowledged services.
+	if err := h.retryPendingTunnelRuntimeCleanupOnNode(nodeID); err != nil {
+		fmt.Printf("reconnect obsolete tunnel cleanup remains pending: %v\n", err)
+	}
 	h.reconcileSharedNodeRuntime(nodeID)
 	if !h.redeployLocalNodeRuntime(nodeID) {
 		h.scheduleNodeLocalRuntimeRetry(nodeID)
@@ -568,9 +571,10 @@ func (h *Handler) finishNodeOnlineRedeploy(nodeID int64) {
 }
 
 func (h *Handler) redeployNodeRuntimeAfterUpgrade(nodeID int64) bool {
+	cleanupOK := h.retryPendingTunnelRuntimeCleanupOnNode(nodeID) == nil
 	sharedOK := h.reconcileSharedNodeRuntime(nodeID)
 	localOK := h.redeployLocalNodeRuntime(nodeID)
-	return sharedOK && localOK
+	return cleanupOK && sharedOK && localOK
 }
 
 func (h *Handler) reconcileSharedNodeRuntime(nodeID int64) bool {

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

@@ -0,0 +1,527 @@
+package handler
+
+import (
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/model"
+	"go-backend/internal/ws"
+)
+
+func TestUserUpdateDisablesPermissionsAndRunningForwards(t *testing.T) {
+	for _, password := range []string{"", "replacement-password"} {
+		t.Run(fmt.Sprintf("password_changed=%t", password != ""), func(t *testing.T) {
+			a := newCleanupAgent(t)
+			now := time.Now().UnixMilli()
+			for _, userID := range []int64{2, 3} {
+				if err := a.h.repo.DB().Create(&model.User{ID: userID, User: fmt.Sprintf("user%d", userID), Pwd: "pwd", RoleID: 1, Status: 1, ExpTime: now + 86400000, Flow: 100, Num: 10}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			if err := a.h.repo.DB().Create(&model.Tunnel{ID: 1, Name: "test", Type: 1, Protocol: "tls", Status: 1, Flow: 1}).Error; err != nil {
+				t.Fatal(err)
+			}
+			for _, permission := range []model.UserTunnel{
+				{ID: 10, UserID: 2, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+				{ID: 11, UserID: 2, TunnelID: 2, Status: 0, Flow: 100, Num: 10},
+				{ID: 12, UserID: 3, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+			} {
+				if err := a.h.repo.DB().Create(&permission).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			for _, forward := range []model.Forward{
+				{ID: 20, UserID: 2, UserName: "user2", Name: "running", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+				{ID: 21, UserID: 2, UserName: "user2", Name: "paused", TunnelID: 1, RemoteAddr: "127.0.0.1:81", Status: 0},
+				{ID: 22, UserID: 3, UserName: "user3", Name: "other-user", TunnelID: 1, RemoteAddr: "127.0.0.1:82", Status: 1},
+			} {
+				if err := a.h.repo.DB().Create(&forward).Error; err != nil {
+					t.Fatal(err)
+				}
+				if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: forward.ID, NodeID: 1, Port: 31000 + int(forward.ID)}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+
+			update := func(status int) {
+				t.Helper()
+				payload, err := json.Marshal(map[string]interface{}{"id": 2, "user": "user2", "status": status, "pwd": password, "flow": 100, "num": 10, "expTime": now + 86400000})
+				if err != nil {
+					t.Fatal(err)
+				}
+				res := httptest.NewRecorder()
+				a.h.userUpdate(res, httptest.NewRequest(http.MethodPost, "/api/v1/user/update", bytes.NewReader(payload)))
+				var result response.R
+				if err := json.Unmarshal(res.Body.Bytes(), &result); err != nil {
+					t.Fatal(err)
+				}
+				if result.Code != 0 {
+					t.Fatalf("update user: %d %s", result.Code, result.Msg)
+				}
+			}
+
+			update(1)
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 10"); got != 1 {
+				t.Errorf("ordinary account update disabled an enabled permission: %d", got)
+			}
+			if len(a.commandsOfType("PauseService")) != 0 {
+				t.Error("ordinary account update paused services")
+			}
+			update(0)
+			for _, check := range []struct {
+				table string
+				id    int64
+				want  int
+			}{{"user", 2, 0}, {"user_tunnel", 10, 0}, {"user_tunnel", 11, 0}, {"user_tunnel", 12, 1}, {"forward", 20, 0}, {"forward", 21, 0}, {"forward", 22, 1}} {
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM "+check.table+" WHERE id = ?", check.id); got != check.want {
+					t.Errorf("%s %d status = %d, want %d", check.table, check.id, got, check.want)
+				}
+			}
+			commands := a.commandsOfType("PauseService")
+			if len(commands) == 0 {
+				t.Error("running forward never received PauseService")
+			}
+			for _, command := range commands {
+				var data struct {
+					Services []string `json:"services"`
+				}
+				if err := json.Unmarshal(command.Data, &data); err != nil {
+					t.Fatal(err)
+				}
+				for _, name := range data.Services {
+					if !strings.HasPrefix(name, "20_2_") {
+						t.Errorf("paused unrelated service %q", name)
+					}
+				}
+			}
+			update(0)
+			if len(a.commandsOfType("PauseService")) != len(commands) {
+				t.Error("repeated disable replayed pauses for already paused forwards")
+			}
+
+			// Account edits and re-enabling must not grant disabled permissions or
+			// resume forwards that an administrator previously paused.
+			update(1)
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 10"); got != 0 {
+				t.Errorf("account re-enable unexpectedly granted a disabled permission: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 11"); got != 0 {
+				t.Errorf("re-enabled independently disabled permission: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 21"); got != 0 {
+				t.Errorf("resumed previously paused forward: %d", got)
+			}
+			if len(a.commandsOfType("ResumeService")) != 0 {
+				t.Error("account re-enable unexpectedly resumed services")
+			}
+		})
+	}
+}
+
+func TestUserDisableMultiEntryNeverRecreatesMissingServices(t *testing.T) {
+	for _, secondNodeState := range []string{"missing", "offline", "timeout"} {
+		t.Run(secondNodeState, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			var remoteMu sync.Mutex
+			remoteServices := make(map[string]bool)
+			var remoteCommands []string
+			remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				var command struct {
+					Type string          `json:"commandType"`
+					Data json.RawMessage `json:"data"`
+				}
+				if err := json.NewDecoder(r.Body).Decode(&command); err != nil {
+					t.Error(err)
+					return
+				}
+				remoteMu.Lock()
+				defer remoteMu.Unlock()
+				remoteCommands = append(remoteCommands, command.Type)
+				switch command.Type {
+				case "UpdateService", "AddService":
+					var services []struct {
+						Name string `json:"name"`
+					}
+					if err := json.Unmarshal(command.Data, &services); err != nil {
+						t.Error(err)
+						return
+					}
+					for _, service := range services {
+						remoteServices[service.Name] = true
+					}
+				case "PauseService":
+					if secondNodeState != "missing" {
+						message := "节点不在线"
+						if secondNodeState == "timeout" {
+							message = "等待节点响应超时"
+						}
+						response.WriteJSON(w, response.ErrDefault(message))
+						return
+					}
+					var data struct {
+						Services []string `json:"services"`
+					}
+					if err := json.Unmarshal(command.Data, &data); err != nil {
+						t.Error(err)
+						return
+					}
+					for _, name := range data.Services {
+						if _, exists := remoteServices[name]; !exists {
+							response.WriteJSON(w, response.OK(map[string]interface{}{"success": false, "message": "service not found"}))
+							return
+						}
+						remoteServices[name] = false
+					}
+				}
+				response.WriteJSON(w, response.OK(map[string]interface{}{"success": true, "type": command.Type}))
+			}))
+			defer remote.Close()
+			now := time.Now().UnixMilli()
+			userID, err := a.h.repo.CreateUser("multi-entry-disable", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, value := range []interface{}{
+				&model.Node{ID: 2, Name: "second-entry", Secret: "test", ServerIP: "127.0.0.1", Status: 1, IsRemote: 1, RemoteURL: sql.NullString{String: remote.URL, Valid: true}, RemoteToken: sql.NullString{String: "test-token", Valid: true}},
+				&model.Tunnel{ID: 1, Name: "multi-entry", Type: 1, Status: 1, Protocol: "tls", Flow: 1},
+				&model.ChainTunnel{TunnelID: 1, NodeID: 1, ChainType: "1"},
+				&model.ChainTunnel{TunnelID: 1, NodeID: 2, ChainType: "1"},
+				&model.UserTunnel{ID: 10, UserID: userID, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+				&model.Forward{ID: 20, UserID: userID, UserName: "multi-entry-disable", Name: "running", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+				&model.ForwardPort{ForwardID: 20, NodeID: 1, Port: 31020},
+				&model.ForwardPort{ForwardID: 20, NodeID: 2, Port: 31020},
+			} {
+				if err := a.h.repo.DB().Create(value).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			res := postJSONToHandler(t, a.h.userUpdate, map[string]interface{}{"id": userID, "user": "multi-entry-disable", "status": 0})
+			var out response.R
+			if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			wantStatus := 1
+			if secondNodeState == "missing" {
+				wantStatus = 0
+				if out.Code != 0 {
+					t.Errorf("missing service should count as stopped: %s", out.Msg)
+				}
+			} else if out.Code == 0 {
+				t.Error("unconfirmed second entry pause returned success")
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != wantStatus {
+				t.Errorf("forward status = %d, want %d", got, wantStatus)
+			}
+			a.mu.Lock()
+			commands := append([]cleanupAgentCommand(nil), a.commands...)
+			a.mu.Unlock()
+			firstEntryRunning := true
+			for _, command := range commands {
+				switch command.Type {
+				case "PauseService":
+					firstEntryRunning = false
+				case "UpdateService", "AddService", "ResumeService":
+					firstEntryRunning = true
+					t.Errorf("disable sent %s to already paused entry A", command.Type)
+				}
+			}
+			if firstEntryRunning {
+				t.Error("entry A is running after disable")
+			}
+			remoteMu.Lock()
+			defer remoteMu.Unlock()
+			if len(remoteCommands) == 0 {
+				t.Error("entry B was never checked")
+			}
+			for _, command := range remoteCommands {
+				if command != "PauseService" {
+					t.Errorf("disable sent %s to entry B", command)
+				}
+			}
+			for name, running := range remoteServices {
+				if running {
+					t.Errorf("entry B service %s is still running", name)
+				}
+			}
+		})
+	}
+}
+
+func TestUserDisableContinuesAcrossNodesAndForwards(t *testing.T) {
+	for _, failure := range []string{"节点不在线", "等待节点响应超时", "pause rejected"} {
+		for _, failedNodeFirst := range []bool{false, true} {
+			t.Run(fmt.Sprintf("%s/failed_node_first=%t", failure, failedNodeFirst), func(t *testing.T) {
+				a := newCleanupAgent(t)
+				var mu sync.Mutex
+				recovered := false
+				attempts := make(map[string]int)
+				remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					var command struct {
+						Type string `json:"commandType"`
+					}
+					if err := json.NewDecoder(r.Body).Decode(&command); err != nil {
+						t.Error(err)
+						return
+					}
+					if command.Type != "PauseService" {
+						t.Errorf("disable sent %s", command.Type)
+					}
+					mu.Lock()
+					attempts[r.Header.Get("Authorization")]++
+					isRecovered := recovered
+					mu.Unlock()
+					if !isRecovered {
+						response.WriteJSON(w, response.ErrDefault(failure))
+						return
+					}
+					response.WriteJSON(w, response.OK(map[string]interface{}{"success": true, "type": command.Type}))
+				}))
+				defer remote.Close()
+				now := time.Now().UnixMilli()
+				userID, err := a.h.repo.CreateUser("continue-disable", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+				if err != nil {
+					t.Fatal(err)
+				}
+				for _, value := range []interface{}{
+					&model.Tunnel{ID: 1, Name: "multi-entry", Type: 2, Status: 1, Flow: 1},
+					&model.Node{ID: 4, Name: "offline-middle", Secret: "test", ServerIP: "127.0.0.1", Status: 0},
+					&model.ChainTunnel{TunnelID: 1, NodeID: 4, ChainType: "2"},
+					&model.UserTunnel{ID: 10, UserID: userID, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+					&model.Forward{ID: 20, UserID: userID, UserName: "continue-disable", Name: "mixed-nodes", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+					&model.Forward{ID: 21, UserID: userID, UserName: "continue-disable", Name: "healthy-forward", TunnelID: 1, RemoteAddr: "127.0.0.1:81", Status: 1},
+				} {
+					if err := a.h.repo.DB().Create(value).Error; err != nil {
+						t.Fatal(err)
+					}
+				}
+				for _, nodeID := range []int64{2, 3} {
+					node := model.Node{ID: nodeID, Name: fmt.Sprintf("failed-node-%d", nodeID), Secret: "test", ServerIP: "127.0.0.1", Status: 1, IsRemote: 1, RemoteURL: sql.NullString{String: remote.URL, Valid: true}, RemoteToken: sql.NullString{String: fmt.Sprintf("test-node-%d", nodeID), Valid: true}}
+					if err := a.h.repo.DB().Create(&node).Error; err != nil {
+						t.Fatal(err)
+					}
+				}
+				nodeOrder := []int64{1, 2, 3}
+				if failedNodeFirst {
+					nodeOrder = []int64{2, 1, 3}
+				}
+				for _, nodeID := range nodeOrder {
+					if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: 20, NodeID: nodeID, Port: 31020}).Error; err != nil {
+						t.Fatal(err)
+					}
+					if err := a.h.repo.DB().Create(&model.ChainTunnel{TunnelID: 1, NodeID: nodeID, ChainType: "1"}).Error; err != nil {
+						t.Fatal(err)
+					}
+				}
+				if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: 21, NodeID: 1, Port: 31021}).Error; err != nil {
+					t.Fatal(err)
+				}
+				update := func() response.R {
+					t.Helper()
+					res := postJSONToHandler(t, a.h.userUpdate, map[string]interface{}{"id": userID, "user": "continue-disable", "status": 0})
+					var out response.R
+					if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+						t.Fatal(err)
+					}
+					return out
+				}
+				out := update()
+				if out.Code == 0 {
+					t.Error("partial node failure reported complete success")
+				}
+				state, ok := out.Data.(map[string]interface{})
+				if !ok || state["userDisabled"] != true {
+					t.Errorf("partial response did not tell the UI the account is disabled: %#v", out.Data)
+				}
+				for _, nodeID := range []int64{2, 3} {
+					if !strings.Contains(out.Msg, fmt.Sprintf("failed-node-%d", nodeID)) || !strings.Contains(out.Msg, fmt.Sprintf("ID %d", nodeID)) {
+						t.Errorf("failure response did not identify node %d: %s", nodeID, out.Msg)
+					}
+					mu.Lock()
+					count := attempts[fmt.Sprintf("Bearer test-node-%d", nodeID)]
+					mu.Unlock()
+					if count == 0 {
+						t.Errorf("failure on another node prevented node %d from being attempted", nodeID)
+					}
+				}
+				paused := make(map[string]bool)
+				for _, command := range a.commandsOfType("PauseService") {
+					var data struct {
+						Services []string `json:"services"`
+					}
+					if err := json.Unmarshal(command.Data, &data); err != nil {
+						t.Fatal(err)
+					}
+					for _, name := range data.Services {
+						paused[strings.Split(name, "_")[0]] = true
+					}
+				}
+				for _, id := range []string{"20", "21"} {
+					if !paused[id] {
+						t.Errorf("healthy node never paused forward %s", id)
+					}
+				}
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 1 {
+					t.Errorf("unconfirmed forward status = %d", got)
+				}
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 21"); got != 0 {
+					t.Errorf("healthy later forward was not paused: %d", got)
+				}
+				mu.Lock()
+				recovered = true
+				mu.Unlock()
+				if retry := update(); retry.Code != 0 {
+					t.Errorf("retry after recovery failed: %s", retry.Msg)
+				}
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 0 {
+					t.Errorf("retry did not confirm all nodes: %d", got)
+				}
+				for _, kind := range []string{"UpdateService", "AddService", "ResumeService"} {
+					if len(a.commandsOfType(kind)) != 0 {
+						t.Errorf("disable sent %s", kind)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestUserDisableRemovesNftablesRuleOnlyAfterConfirmedApply(t *testing.T) {
+	fixture := setupNftablesHandler(t)
+	h := fixture.handler
+	t.Cleanup(func() { _ = h.repo.Close() })
+	seedNftablesSSHConfig(t, h, fixture.nodeID)
+	tunnelID := seedTunnelForNftables(t, h, "disable-nft", fixture.nodeID)
+	forward := seedForwardForNftables(t, h, tunnelID, fixture.nodeID, "203.0.113.9:8080")
+	now := time.Now().UnixMilli()
+	userID, err := h.repo.CreateUser("disable-nft", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := h.repo.DB().Model(&model.Forward{}).Where("id = ?", forward.ID).Update("user_id", userID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := h.repo.DB().Create(&model.UserTunnel{UserID: userID, TunnelID: tunnelID, Status: 1, Flow: 100, Num: 10}).Error; err != nil {
+		t.Fatal(err)
+	}
+	otherForwardID := forward.ID + 100
+	for _, value := range []interface{}{
+		&model.Forward{ID: otherForwardID, UserID: 1, UserName: "admin", Name: "other-user", TunnelID: tunnelID, RemoteAddr: "203.0.113.9:8081", Status: 1},
+		&model.ForwardPort{ForwardID: otherForwardID, NodeID: fixture.nodeID, Port: 20001},
+	} {
+		if err := h.repo.DB().Create(value).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	manager := &fakeNftablesManager{reconcileErr: errors.New("ssh unavailable")}
+	h.nftablesManager = manager
+	update := func() response.R {
+		t.Helper()
+		res := postJSONToHandler(t, h.userUpdate, map[string]interface{}{"id": userID, "user": "disable-nft", "status": 0})
+		var out response.R
+		if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+			t.Fatal(err)
+		}
+		return out
+	}
+	if out := update(); out.Code == 0 {
+		t.Error("failed SSH apply returned success")
+	}
+	if got := mustQueryInt(t, h.repo, "SELECT status FROM forward WHERE id = ?", forward.ID); got != 1 {
+		t.Errorf("unconfirmed nftables pause marked completed: %d", got)
+	}
+	if manager.reconcileCount() != 1 || len(manager.lastPlan.Rules) != 1 || manager.lastPlan.Rules[0].ForwardID != otherForwardID {
+		t.Fatalf("did not attempt to remove disabled user's nftables rule: %+v", manager.lastPlan)
+	}
+	manager.reconcileErr = nil
+	if out := update(); out.Code != 0 {
+		t.Fatalf("retry nftables disable: %s", out.Msg)
+	}
+	if got := mustQueryInt(t, h.repo, "SELECT status FROM forward WHERE id = ?", forward.ID); got != 0 {
+		t.Errorf("confirmed nftables pause was not stored: %d", got)
+	}
+	if manager.reconcileCount() != 2 || len(manager.lastPlan.Rules) != 1 || manager.lastPlan.Rules[0].ForwardID != otherForwardID {
+		t.Errorf("retry did not apply a plan without disabled forward: %+v", manager.lastPlan)
+	}
+	if got := mustQueryInt(t, h.repo, "SELECT status FROM forward WHERE id = ?", otherForwardID); got != 1 {
+		t.Errorf("disabled another user's nftables forward: %d", got)
+	}
+}
+
+func TestUserDisableReportsPauseFailureAndCanRetry(t *testing.T) {
+	for _, offline := range []bool{false, true} {
+		t.Run(fmt.Sprintf("offline=%t", offline), func(t *testing.T) {
+			a := newCleanupAgent(t)
+			now := time.Now().UnixMilli()
+			userID, err := a.h.repo.CreateUser("disable-retry", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, value := range []interface{}{
+				&model.Tunnel{ID: 1, Name: "test", Type: 1, Status: 1, Flow: 1},
+				&model.UserTunnel{ID: 10, UserID: userID, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+				&model.Forward{ID: 20, UserID: userID, UserName: "disable-retry", Name: "running", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+				&model.ForwardPort{ForwardID: 20, NodeID: 1, Port: 31020},
+			} {
+				if err := a.h.repo.DB().Create(value).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			onlineServer := a.h.wsServer
+			if offline {
+				a.h.wsServer = ws.NewServer(a.h.repo, "test-jwt-secret")
+			} else {
+				ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					response.WriteJSON(w, response.ErrDefault("pause rejected"))
+				}))
+				defer ts.Close()
+				if err := a.h.repo.DB().Model(&model.Node{}).Where("id = 1").Updates(map[string]interface{}{"is_remote": 1, "remote_url": ts.URL, "remote_token": "test-token"}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			update := func() response.R {
+				t.Helper()
+				res := postJSONToHandler(t, a.h.userUpdate, map[string]interface{}{"id": userID, "user": "disable-retry", "status": 0})
+				var out response.R
+				if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+					t.Fatal(err)
+				}
+				return out
+			}
+			if out := update(); out.Code == 0 {
+				t.Error("pause failure returned success")
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user WHERE id = ?", userID); got != 0 {
+				t.Errorf("failed pause restored account access: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 10"); got != 0 {
+				t.Errorf("failed pause restored tunnel access: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 1 {
+				t.Errorf("unconfirmed pause marked completed, status = %d", got)
+			}
+			a.h.wsServer = onlineServer
+			if err := a.h.repo.DB().Model(&model.Node{}).Where("id = 1").Update("is_remote", 0).Error; err != nil {
+				t.Fatal(err)
+			}
+			if out := update(); out.Code != 0 {
+				t.Fatalf("retry failed: %s", out.Msg)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 0 {
+				t.Errorf("retry did not pause forward: %d", got)
+			}
+			if len(a.commandsOfType("PauseService")) == 0 {
+				t.Error("retry never sent PauseService")
+			}
+		})
+	}
+}

go-backend/internal/relaysecurity/auth.go

@@ -0,0 +1,41 @@
+// Package relaysecurity defines the versioned, endpoint-scoped relay contract.
+// It authenticates relay clients, not the confidentiality of their transport.
+package relaysecurity
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"strings"
+)
+
+const Version = 1
+const Required = "required"
+const Legacy = "legacy"
+
+type Credentials struct {
+	Version  int    `json:"version"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+func New() (*Credentials, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return nil, errors.New("relay credential randomness unavailable")
+	}
+	u := make([]byte, 12)
+	if _, err := rand.Read(u); err != nil {
+		return nil, errors.New("relay credential randomness unavailable")
+	}
+	return &Credentials{Version: Version, Username: "relay-" + hex.EncodeToString(u), Password: hex.EncodeToString(b)}, nil
+}
+func (c *Credentials) Validate() error {
+	if c == nil || c.Version != Version || strings.TrimSpace(c.Username) == "" || len(c.Username) > 255 || len(c.Password) < 32 || len(c.Password) > 255 {
+		return errors.New("invalid required relay authentication")
+	}
+	return nil
+}
+func (c *Credentials) Config() map[string]interface{} {
+	return map[string]interface{}{"username": c.Username, "password": c.Password}
+}

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

@@ -175,6 +175,7 @@ type StatisticsFlow struct {
 func (StatisticsFlow) TableName() string { return "statistics_flow" }
 
 type Tunnel struct {
+	RelayAuthMode   string         `gorm:"column:relay_auth_mode;type:varchar(20);not null;default:legacy"`
 	ID              int64          `gorm:"primaryKey;autoIncrement"`
 	Name            string         `gorm:"type:varchar(100);not null"`
 	TrafficRatio    float64        `gorm:"column:traffic_ratio;not null;default:1.0"`
@@ -354,24 +355,26 @@ type PeerShare struct {
 func (PeerShare) TableName() string { return "peer_share" }
 
 type PeerShareRuntime struct {
-	ID             int64  `gorm:"primaryKey;autoIncrement"`
-	ShareID        int64  `gorm:"column:share_id;not null;index:idx_peer_share_runtime_share_node_status"`
-	NodeID         int64  `gorm:"column:node_id;not null;index:idx_peer_share_runtime_share_node_status"`
-	ReservationID  string `gorm:"column:reservation_id;type:text;not null;uniqueIndex"`
-	ResourceKey    string `gorm:"column:resource_key;type:text;not null;uniqueIndex"`
-	BindingID      string `gorm:"column:binding_id;type:text;not null;default:'';index:idx_peer_share_runtime_binding_id"`
-	Role           string `gorm:"type:text;not null;default:''"`
-	ChainName      string `gorm:"column:chain_name;type:text;not null;default:''"`
-	ServiceName    string `gorm:"column:service_name;type:text;not null;default:''"`
-	Protocol       string `gorm:"type:text;not null;default:'tls'"`
-	Strategy       string `gorm:"type:text;not null;default:'round'"`
-	Port           int    `gorm:"not null;default:0"`
-	Target         string `gorm:"type:text;not null;default:''"`
-	Applied        int    `gorm:"not null;default:0"`
-	ReleasePending int    `gorm:"column:release_pending;not null;default:0"`
-	Status         int    `gorm:"not null;default:1;index:idx_peer_share_runtime_share_node_status"`
-	CreatedTime    int64  `gorm:"column:created_time;not null"`
-	UpdatedTime    int64  `gorm:"column:updated_time;not null"`
+	RelayAuthVersion int    `gorm:"column:relay_auth_version;not null;default:0" json:"-"`
+	RelayAuth        string `gorm:"column:relay_auth;type:text;not null;default:''" json:"-"`
+	ID               int64  `gorm:"primaryKey;autoIncrement"`
+	ShareID          int64  `gorm:"column:share_id;not null;index:idx_peer_share_runtime_share_node_status"`
+	NodeID           int64  `gorm:"column:node_id;not null;index:idx_peer_share_runtime_share_node_status"`
+	ReservationID    string `gorm:"column:reservation_id;type:text;not null;uniqueIndex"`
+	ResourceKey      string `gorm:"column:resource_key;type:text;not null;uniqueIndex"`
+	BindingID        string `gorm:"column:binding_id;type:text;not null;default:'';index:idx_peer_share_runtime_binding_id"`
+	Role             string `gorm:"type:text;not null;default:''"`
+	ChainName        string `gorm:"column:chain_name;type:text;not null;default:''"`
+	ServiceName      string `gorm:"column:service_name;type:text;not null;default:''"`
+	Protocol         string `gorm:"type:text;not null;default:'tls'"`
+	Strategy         string `gorm:"type:text;not null;default:'round'"`
+	Port             int    `gorm:"not null;default:0"`
+	Target           string `gorm:"type:text;not null;default:''" json:"-"`
+	Applied          int    `gorm:"not null;default:0"`
+	ReleasePending   int    `gorm:"column:release_pending;not null;default:0"`
+	Status           int    `gorm:"not null;default:1;index:idx_peer_share_runtime_share_node_status"`
+	CreatedTime      int64  `gorm:"column:created_time;not null"`
+	UpdatedTime      int64  `gorm:"column:updated_time;not null"`
 }
 
 func (PeerShareRuntime) TableName() string { return "peer_share_runtime" }
@@ -464,6 +467,7 @@ type NodeBackup struct {
 }
 
 type TunnelBackup struct {
+	RelayAuthMode   string              `json:"relayAuthMode,omitempty"`
 	ID              int64               `json:"id"`
 	Name            string              `json:"name"`
 	TrafficRatio    float64             `json:"trafficRatio"`
@@ -621,6 +625,7 @@ type ForwardRecord struct {
 
 // TunnelRecord is a minimal tunnel view used by control plane.
 type TunnelRecord struct {
+	RelayAuthMode   string
 	ID              int64
 	Type            int
 	Status          int

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

@@ -0,0 +1,15 @@
+package model
+
+// RelayEndpointAuth is private desired state, never an API or backup DTO.
+// Retained endpoint identities keep their credentials across topology edits.
+type RelayEndpointAuth struct {
+	ID        int64  `gorm:"primaryKey;autoIncrement" json:"-"`
+	TunnelID  int64  `gorm:"not null;uniqueIndex:idx_relay_endpoint" json:"-"`
+	NodeID    int64  `gorm:"not null;uniqueIndex:idx_relay_endpoint" json:"-"`
+	ChainType int    `gorm:"not null;uniqueIndex:idx_relay_endpoint" json:"-"`
+	Version   int    `gorm:"not null" json:"-"`
+	Username  string `gorm:"type:text;not null" json:"-"`
+	Password  string `gorm:"type:text;not null" json:"-"`
+}
+
+func (RelayEndpointAuth) TableName() string { return "relay_endpoint_auth" }

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

@@ -0,0 +1,13 @@
+package model
+
+// TunnelRuntimeCleanup retains ownership until an obsolete local runtime is
+// acknowledged removed. It intentionally survives deletion of its tunnel.
+type TunnelRuntimeCleanup struct {
+	ID       int64  `gorm:"primaryKey;autoIncrement"`
+	TunnelID int64  `gorm:"not null;uniqueIndex:idx_tunnel_cleanup"`
+	NodeID   int64  `gorm:"not null;uniqueIndex:idx_tunnel_cleanup"`
+	Kind     string `gorm:"type:varchar(16);not null;uniqueIndex:idx_tunnel_cleanup"`
+	Port     int    `gorm:"not null;default:0;uniqueIndex:idx_tunnel_cleanup"`
+}
+
+func (TunnelRuntimeCleanup) TableName() string { return "tunnel_runtime_cleanup" }

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

@@ -299,6 +299,8 @@ func autoMigrateAll(db *gorm.DB) error {
 		&model.SpeedLimit{},
 		&model.StatisticsFlow{},
 		&model.Tunnel{},
+		&model.RelayEndpointAuth{},
+		&model.TunnelRuntimeCleanup{},
 		&model.ChainTunnel{},
 		&model.UserTunnel{},
 		&model.TunnelGroup{},
@@ -1252,7 +1254,8 @@ func (r *Repository) ListTunnels() ([]map[string]interface{}, error) {
 		tunnelMap[t.ID] = map[string]interface{}{
 			"id": t.ID, "inx": t.Inx, "name": t.Name,
 			"type": t.Type, "flow": t.Flow, "trafficRatio": t.TrafficRatio,
-			"status": t.Status, "createdTime": t.CreatedTime,
+			"relayAuthMode": t.RelayAuthMode,
+			"status":        t.Status, "createdTime": t.CreatedTime,
 			"inIp":            nullableString(t.InIP),
 			"ipPreference":    t.IPPreference,
 			"probeTargetHost": t.ProbeTargetHost,
@@ -1616,8 +1619,10 @@ func (r *Repository) UpdatePeerShareRuntime(item *model.PeerShareRuntime) error
 		return errors.New("runtime item is nil")
 	}
 	return r.db.Model(&model.PeerShareRuntime{}).Where("id = ?", item.ID).Updates(map[string]interface{}{
-		"reservation_id": item.ReservationID,
-		"binding_id":     item.BindingID, "role": item.Role,
+		"reservation_id":     item.ReservationID,
+		"relay_auth":         item.RelayAuth,
+		"relay_auth_version": item.RelayAuthVersion,
+		"binding_id":         item.BindingID, "role": item.Role,
 		"chain_name": item.ChainName, "service_name": item.ServiceName,
 		"protocol": item.Protocol, "strategy": item.Strategy,
 		"port": item.Port, "target": item.Target,
@@ -2161,7 +2166,8 @@ func (r *Repository) exportTunnels() ([]model.TunnelBackup, error) {
 	out := make([]model.TunnelBackup, 0, len(tunnels))
 	for _, t := range tunnels {
 		b := model.TunnelBackup{
-			ID: t.ID, Name: t.Name, TrafficRatio: t.TrafficRatio,
+			RelayAuthMode: t.RelayAuthMode,
+			ID:            t.ID, Name: t.Name, TrafficRatio: t.TrafficRatio,
 			Type: t.Type, Protocol: t.Protocol, Flow: t.Flow,
 			CreatedTime: t.CreatedTime, UpdatedTime: t.UpdatedTime,
 			Status: t.Status, Inx: t.Inx, IPPreference: t.IPPreference,
@@ -2595,6 +2601,18 @@ func importNodes(tx *gorm.DB, nodes []model.NodeBackup, now int64) (int, error)
 func importTunnels(tx *gorm.DB, tunnels []model.TunnelBackup, now int64) (int, error) {
 	count := 0
 	for _, t := range tunnels {
+		if t.RelayAuthMode != "" && t.RelayAuthMode != "legacy" {
+			return count, errors.New("authenticated relay tunnels require a full database restore; configuration backup has no private relay credentials")
+		}
+		var existing model.Tunnel
+		lookupErr := tx.First(&existing, t.ID).Error
+		if lookupErr != nil && !errors.Is(lookupErr, gorm.ErrRecordNotFound) {
+			return count, lookupErr
+		}
+		if lookupErr == nil && existing.RelayAuthMode == "required" {
+			return count, errors.New("configuration import cannot replace an authenticated relay tunnel")
+		}
+
 		item := model.Tunnel{
 			ID:              t.ID,
 			Name:            t.Name,

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

@@ -202,6 +202,13 @@ func (r *Repository) ListUsedPortsOnNode(nodeID int64) ([]int, error) {
 		}
 	}
 
+	pendingPorts, err := r.PendingTunnelCleanupPortsTx(nil, nodeID, 0)
+	if err != nil {
+		return nil, err
+	}
+	for _, port := range pendingPorts {
+		used[port] = struct{}{}
+	}
 	result := make([]int, 0, len(used))
 	for p := range used {
 		result = append(result, p)

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

@@ -272,6 +272,7 @@ func (r *Repository) GetTunnelRecord(tunnelID int64) (*model.TunnelRecord, error
 		return nil, err
 	}
 	tr := model.TunnelRecord{
+		RelayAuthMode:   t.RelayAuthMode,
 		ID:              t.ID,
 		Type:            t.Type,
 		Status:          t.Status,

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

@@ -151,6 +151,13 @@ func (r *Repository) PropagateUserFlowToTunnels(userID int64, flow int64, num in
 		}).Error
 }
 
+func (r *Repository) DisableUserTunnels(userID int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	return r.db.Model(&model.UserTunnel{}).Where("user_id = ?", userID).Update("status", 0).Error
+}
+
 func (r *Repository) DeleteUserCascade(userID int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
@@ -577,6 +584,13 @@ func (r *Repository) pickNodePortTx(tx *gorm.DB, nodeID int64, allocated map[int
 		}
 	}
 
+	pendingPorts, err := r.PendingTunnelCleanupPortsTx(tx, nodeID, excludeTunnelID)
+	if err != nil {
+		return 0, err
+	}
+	for _, port := range pendingPorts {
+		used[port] = struct{}{}
+	}
 	var available []int
 	for _, candidate := range candidates {
 		if candidate <= 0 {
@@ -622,6 +636,9 @@ func (r *Repository) DeleteTunnelCascade(tunnelID int64) error {
 		return errors.New("repository not initialized")
 	}
 	return r.db.Transaction(func(tx *gorm.DB) error {
+		if err := r.queueDeletedTunnelRuntimeTx(tx, tunnelID); err != nil {
+			return err
+		}
 		forwardIDs := tx.Model(&model.Forward{}).Select("id").Where("tunnel_id = ?", tunnelID)
 		if err := tx.Where("forward_id IN (?)", forwardIDs).Delete(&model.ForwardPort{}).Error; err != nil {
 			return err
@@ -638,6 +655,9 @@ func (r *Repository) DeleteTunnelCascade(tunnelID int64) error {
 		if err := tx.Where("tunnel_id = ?", tunnelID).Delete(&model.FederationTunnelBinding{}).Error; err != nil {
 			return err
 		}
+		if err := tx.Where("tunnel_id = ?", tunnelID).Delete(&model.RelayEndpointAuth{}).Error; err != nil {
+			return err
+		}
 		return tx.Where("id = ?", tunnelID).Delete(&model.Tunnel{}).Error
 	})
 }
@@ -897,6 +917,13 @@ func (r *Repository) GetUsedPortsOnNodeAsMap(nodeID int64) (map[int]bool, error)
 	for _, p := range chainPorts {
 		used[p] = true
 	}
+	pendingPorts, err := r.PendingTunnelCleanupPortsTx(nil, nodeID, 0)
+	if err != nil {
+		return nil, err
+	}
+	for _, port := range pendingPorts {
+		used[port] = true
+	}
 	return used, nil
 }
 

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

@@ -0,0 +1,64 @@
+package repo
+
+import (
+	"errors"
+	"go-backend/internal/relaysecurity"
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// RelayEndpointCredentials loads existing state, creating only when explicitly
+// requested by a new endpoint operation. Reconnects must never recreate a secret.
+func (r *Repository) RelayEndpointCredentials(tx *gorm.DB, tunnelID, nodeID int64, role int, create bool) (*relaysecurity.Credentials, error) {
+	db := tx
+	if db == nil {
+		db = r.db
+	}
+	var row model.RelayEndpointAuth
+	find := func() error {
+		return db.Where("tunnel_id = ? AND node_id = ? AND chain_type = ?", tunnelID, nodeID, role).First(&row).Error
+	}
+	err := find()
+	if errors.Is(err, gorm.ErrRecordNotFound) && create {
+		var existing int64
+		if e := db.Model(&model.ChainTunnel{}).Where("tunnel_id = ? AND node_id = ? AND chain_type = ?", tunnelID, nodeID, role).Count(&existing).Error; e != nil {
+			return nil, e
+		}
+		if existing > 0 {
+			var tunnel model.Tunnel
+			if e := db.First(&tunnel, tunnelID).Error; e != nil {
+				return nil, e
+			}
+			if tunnel.Type == 2 || tunnel.RelayAuthMode == relaysecurity.Required {
+				return nil, errors.New("required relay endpoint credentials unavailable; refusing regeneration")
+			}
+		}
+
+		c, e := relaysecurity.New()
+		if e != nil {
+			return nil, e
+		}
+		row = model.RelayEndpointAuth{TunnelID: tunnelID, NodeID: nodeID, ChainType: role, Version: c.Version, Username: c.Username, Password: c.Password}
+		if e = db.Clauses(clause.OnConflict{DoNothing: true}).Create(&row).Error; e != nil {
+			return nil, e
+		}
+		row = model.RelayEndpointAuth{}
+		err = find()
+	}
+	if err != nil {
+		return nil, errors.New("required relay endpoint credentials unavailable")
+	}
+	c := &relaysecurity.Credentials{Version: row.Version, Username: row.Username, Password: row.Password}
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	return c, nil
+}
+
+func (r *Repository) SetTunnelRelayAuthModeTx(tx *gorm.DB, tunnelID int64, mode string) error {
+	if mode != relaysecurity.Required && mode != relaysecurity.Legacy {
+		return errors.New("invalid relay authentication mode")
+	}
+	return tx.Model(&model.Tunnel{}).Where("id = ?", tunnelID).Update("relay_auth_mode", mode).Error
+}

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

@@ -0,0 +1,71 @@
+package repo
+
+import (
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func (r *Repository) QueueTunnelRuntimeCleanupTx(tx *gorm.DB, items []model.TunnelRuntimeCleanup) error {
+	for _, item := range items {
+		var node model.Node
+		if err := tx.Select("id", "is_remote").Where("id = ?", item.NodeID).First(&node).Error; err != nil {
+			return err
+		}
+		if node.IsRemote == 1 {
+			continue
+		}
+		if err := tx.Clauses(clause.OnConflict{Columns: []clause.Column{{Name: "tunnel_id"}, {Name: "node_id"}, {Name: "kind"}, {Name: "port"}}, DoNothing: true}).Create(&item).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+func (r *Repository) ListTunnelRuntimeCleanup(tunnelID int64) ([]model.TunnelRuntimeCleanup, error) {
+	var items []model.TunnelRuntimeCleanup
+	q := r.db.Model(&model.TunnelRuntimeCleanup{})
+	if tunnelID > 0 {
+		q = q.Where("tunnel_id = ?", tunnelID)
+	}
+	err := q.Order("tunnel_id, node_id, kind DESC").Find(&items).Error
+	return items, err
+}
+func (r *Repository) DeleteTunnelRuntimeCleanup(id int64) error {
+	return r.db.Where("id = ?", id).Delete(&model.TunnelRuntimeCleanup{}).Error
+}
+func (r *Repository) PendingTunnelCleanupPortsTx(tx *gorm.DB, nodeID, excludeTunnelID int64) ([]int, error) {
+	if tx == nil {
+		tx = r.db
+	}
+	q := tx.Model(&model.TunnelRuntimeCleanup{}).Where("node_id = ? AND kind = ? AND port > 0", nodeID, "service")
+	if excludeTunnelID > 0 {
+		q = q.Where("tunnel_id != ?", excludeTunnelID)
+	}
+	var ports []int
+	err := q.Pluck("port", &ports).Error
+	return ports, err
+}
+
+func (r *Repository) queueDeletedTunnelRuntimeTx(tx *gorm.DB, tunnelID int64) error {
+	var tunnels []model.Tunnel
+	if err := tx.Where("id = ? AND type = ?", tunnelID, 2).Find(&tunnels).Error; err != nil {
+		return err
+	}
+	if len(tunnels) == 0 {
+		return nil
+	}
+	var rows []model.ChainTunnel
+	if err := tx.Where("tunnel_id = ?", tunnelID).Find(&rows).Error; err != nil {
+		return err
+	}
+	var items []model.TunnelRuntimeCleanup
+	for _, row := range rows {
+		if row.ChainType == "2" || row.ChainType == "3" {
+			items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: row.NodeID, Kind: "service", Port: int(row.Port.Int64)})
+		}
+		if row.ChainType == "1" || row.ChainType == "2" {
+			items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: row.NodeID, Kind: "chain"})
+		}
+	}
+	return r.QueueTunnelRuntimeCleanupTx(tx, items)
+}

go-backend/tests/contract/forward_required_chain_contract_test.go

@@ -0,0 +1,131 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+)
+
+func TestForwardEntryRequiresTunnelChainContract(t *testing.T) {
+	for _, tunnelType := range []int{1, 2} {
+		t.Run(fmt.Sprintf("type-%d", tunnelType), func(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, tunnelType, "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 tunnelType == 2 {
+				if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 44002, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+					t.Fatalf("insert exit chain: %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
+			var emitted []map[string]interface{}
+			stop := startMockNodeSessionWithCommandRecorder(t, server.URL, "forward-bind-retry-secret", func(kind string, data json.RawMessage) (bool, string) {
+				if kind == "AddService" || kind == "UpdateService" {
+					var services []map[string]interface{}
+					if json.Unmarshal(data, &services) == nil {
+						mu.Lock()
+						emitted = append(emitted, services...)
+						mu.Unlock()
+					}
+				}
+				return false, ""
+			})
+			defer stop()
+			waitNodeStatus(t, repo, nodeID, 1)
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+			req.Header.Set("Authorization", adminToken)
+			req.Header.Set("Content-Type", "application/json")
+			res := httptest.NewRecorder()
+			router.ServeHTTP(res, req)
+			assertCode(t, res, 0)
+			mu.Lock()
+			defer mu.Unlock()
+			found := 0
+			for _, svc := range emitted {
+				h, ok := svc["handler"].(map[string]interface{})
+				if !ok || (h["type"] != "tcp" && h["type"] != "udp") {
+					continue
+				}
+				found++
+				md, _ := h["metadata"].(map[string]interface{})
+				if tunnelType == 2 {
+					if h["chain"] != fmt.Sprintf("chains_%d", tunnelID) || md["chain.strict"] != true {
+						t.Fatalf("tunnel forward must require chain, got %v", h)
+					}
+				} else if md["chain.strict"] == true {
+					t.Fatal("direct forward cannot require a tunnel chain")
+				}
+			}
+			if found < 2 {
+				t.Fatalf("expected TCP and UDP forwarding commands, got %d", found)
+			}
+		})
+	}
+}

go-backend/tests/contract/relay_auth_contract_test.go

@@ -0,0 +1,637 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/store/repo"
+)
+
+func TestNewRelayTunnelEmitsMatchingPrivateEndpointAuthentication(t *testing.T) {
+	router, r := setupContractRouter(t, "relay-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "relay-auth-contract")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "auth-entry", "192.0.2.10", "41000-41010", "entry-management-secret", 1)
+	exit := insertContractNode(t, r, "auth-exit", "192.0.2.11", "42000-42010", "exit-management-secret", 1)
+	var mu sync.Mutex
+	var connector, receiver map[string]interface{}
+	reconnectEvents := make(chan string, 8)
+	watchReconnect := false
+	record := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "AddChains" || kind == "UpdateChains" {
+			var c map[string]interface{}
+			_ = json.Unmarshal(data, &c)
+			if nested, ok := c["data"].(map[string]interface{}); ok {
+				c = nested
+			}
+			hops, _ := c["hops"].([]interface{})
+			if len(hops) > 0 {
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				connector, _ = nodes[0].(map[string]interface{})["connector"].(map[string]interface{})["auth"].(map[string]interface{})
+			}
+		}
+		if kind == "AddService" || kind == "UpdateService" {
+			var services []map[string]interface{}
+			_ = json.Unmarshal(data, &services)
+			if len(services) > 0 {
+				receiver, _ = services[0]["handler"].(map[string]interface{})["auth"].(map[string]interface{})
+				if watchReconnect {
+					p, _ := receiver["password"].(string)
+					select {
+					case reconnectEvents <- p:
+					default:
+					}
+				}
+			}
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "entry-management-secret", record)
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "exit-management-secret", record)
+	defer stopExit()
+	payload := map[string]interface{}{"name": "authenticated-new-tunnel", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	body, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+	mu.Lock()
+	if connector == nil || receiver == nil {
+		t.Fatal("new relay tunnel emitted no endpoint authentication")
+	}
+	if connector["username"] == "" || connector["password"] == "" || connector["username"] != receiver["username"] || connector["password"] != receiver["password"] {
+		t.Fatal("relay endpoint credentials missing or mismatched")
+	}
+	if receiver["password"] == "entry-management-secret" || receiver["password"] == "exit-management-secret" {
+		t.Fatal("management secret reused for relay")
+	}
+	listReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", bytes.NewBufferString(`{}`))
+	listReq.Header.Set("Authorization", token)
+	listRes := httptest.NewRecorder()
+	router.ServeHTTP(listRes, listReq)
+	if !bytes.Contains(listRes.Body.Bytes(), []byte(`"relayAuthMode":"required"`)) {
+		t.Fatalf("tunnel list does not expose required authentication state: %s", listRes.Body.String())
+	}
+	password, _ := receiver["password"].(string)
+	if bytes.Contains(listRes.Body.Bytes(), []byte(password)) {
+		t.Fatal("tunnel list disclosed relay credential")
+	}
+	exportReq := httptest.NewRequest(http.MethodPost, "/api/v1/backup/export", bytes.NewBufferString(`{"types":["tunnels"]}`))
+	exportReq.Header.Set("Authorization", token)
+	exportRes := httptest.NewRecorder()
+	router.ServeHTTP(exportRes, exportReq)
+	if !bytes.Contains(exportRes.Body.Bytes(), []byte(`"relayAuthMode":"required"`)) {
+		t.Fatal("configuration export lost required authentication policy")
+	}
+	if bytes.Contains(exportRes.Body.Bytes(), []byte(password)) {
+		t.Fatal("configuration export disclosed private relay password")
+	}
+	originalPassword := password
+	mu.Unlock()
+	var listed struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listRes.Body.Bytes(), &listed); err != nil || len(listed.Data) != 1 {
+		t.Fatal("missing created tunnel in list")
+	}
+	payload["id"] = listed.Data[0].ID
+	body, _ = json.Marshal(payload)
+	updateReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	updateReq.Header.Set("Authorization", token)
+	updateRes := httptest.NewRecorder()
+	router.ServeHTTP(updateRes, updateReq)
+
+	assertCode(t, updateRes, 0)
+	mu.Lock()
+	if connector == nil || receiver == nil || connector["password"] != originalPassword || receiver["password"] != originalPassword {
+		t.Fatal("topology reapply lost or changed persisted endpoint authentication")
+	}
+
+	watchReconnect = true
+	mu.Unlock()
+	stopExit()
+	stopReconnected := startMockNodeSessionWithCommandRecorder(t, server.URL, "exit-management-secret", record)
+	defer stopReconnected()
+	// Request reconciliation explicitly rather than waiting for the production
+	// reconnect debounce (30 seconds). This crosses the same HTTP/command seam.
+	redeployBody, _ := json.Marshal(map[string]interface{}{"ids": []int64{listed.Data[0].ID}})
+	redeployReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(redeployBody))
+	redeployReq.Header.Set("Authorization", token)
+	redeployRes := httptest.NewRecorder()
+	router.ServeHTTP(redeployRes, redeployReq)
+	assertCode(t, redeployRes, 0)
+
+	select {
+	case password := <-reconnectEvents:
+		if password != originalPassword {
+			t.Fatal("node reconnect lost persisted authentication")
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("node reconnect did not reconcile relay service")
+	}
+	// Corrupt private desired state as a fault fixture. Reapply must stop rather
+	// than regenerating a password or emitting an anonymous listener.
+	if err := r.DB().Exec("DELETE FROM relay_endpoint_auth WHERE tunnel_id = ?", listed.Data[0].ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	missingReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	missingReq.Header.Set("Authorization", token)
+	missingRes := httptest.NewRecorder()
+	router.ServeHTTP(missingRes, missingReq)
+	var missing struct {
+		Code int `json:"code"`
+	}
+	_ = json.Unmarshal(missingRes.Body.Bytes(), &missing)
+	if missing.Code == 0 {
+		t.Fatal("missing required credentials silently regenerated or downgraded")
+	}
+}
+
+func TestFederatedRelayRequiresVersionedAuthAndRejectsDowngrade(t *testing.T) {
+	router, r := setupContractRouter(t, "provider-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	node := insertContractNode(t, r, "provider-auth", "192.0.2.30", "45000-45010", "provider-management", 1)
+	insertPeerShare(t, r, &repo.PeerShare{Name: "auth-share", NodeID: node, Token: "auth-share-token", PortRangeStart: 45000, PortRangeEnd: 45010, IsActive: 1})
+	var mu sync.Mutex
+	var received map[string]interface{}
+	stop := startMockNodeSessionWithCommandRecorder(t, server.URL, "provider-management", func(kind string, data json.RawMessage) (bool, string) {
+		if kind == "UpdateService" {
+			var services []map[string]interface{}
+			_ = json.Unmarshal(data, &services)
+			if len(services) > 0 {
+				mu.Lock()
+				received, _ = services[0]["handler"].(map[string]interface{})["auth"].(map[string]interface{})
+				mu.Unlock()
+			}
+		}
+		return false, ""
+	})
+	defer stop()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		b, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(b))
+		req.Header.Set("Authorization", "Bearer auth-share-token")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	reserve := post("/api/v1/federation/runtime/reserve-port", map[string]interface{}{"resourceKey": "auth-contract-endpoint", "protocol": "tls"})
+	var reservation struct {
+		Code int `json:"code"`
+		Data struct {
+			ReservationID    string `json:"reservationId"`
+			RelayAuthVersion int    `json:"relayAuthVersion"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(reserve.Body.Bytes(), &reservation); err != nil || reservation.Code != 0 {
+		t.Fatal("reserve failed")
+	}
+	if reservation.Data.RelayAuthVersion != 1 {
+		t.Fatal("provider did not advertise relay authentication capability")
+	}
+	creds := map[string]interface{}{"version": 1, "username": "test-relay-user", "password": "test-only-relay-password-32-bytes-long"}
+	request := map[string]interface{}{"reservationId": reservation.Data.ReservationID, "resourceKey": "auth-contract-endpoint", "role": "exit", "protocol": "tls", "relayAuth": creds}
+	applied := post("/api/v1/federation/runtime/apply-role", request)
+	if !bytes.Contains(applied.Body.Bytes(), []byte(`"relayAuthVersion":1`)) {
+		t.Fatal("provider did not acknowledge authenticated runtime")
+	}
+	assertCode(t, applied, 0)
+	mu.Lock()
+	actual := received
+	mu.Unlock()
+	if actual == nil || actual["username"] != creds["username"] || actual["password"] != creds["password"] {
+		t.Fatal("provider omitted requested relay authentication")
+	}
+	delete(request, "relayAuth")
+	rejected := post("/api/v1/federation/runtime/apply-role", request)
+	var result struct {
+		Code int `json:"code"`
+	}
+	_ = json.Unmarshal(rejected.Body.Bytes(), &result)
+	if result.Code == 0 {
+		t.Fatal("provider silently downgraded authenticated runtime")
+	}
+
+	// Loss of private persisted state must not be mistaken for legacy mode.
+	if err := r.DB().Exec("UPDATE peer_share_runtime SET relay_auth = '' WHERE resource_key = ?", "auth-contract-endpoint").Error; err != nil {
+		t.Fatal(err)
+	}
+	request["relayAuth"] = creds
+	missing := post("/api/v1/federation/runtime/apply-role", request)
+	_ = json.Unmarshal(missing.Body.Bytes(), &result)
+	if result.Code == 0 {
+		t.Fatal("provider recreated missing protected state instead of failing closed")
+	}
+}
+
+func TestNewFederatedTunnelAuthenticatesEveryRelayHop(t *testing.T) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	providerServer := httptest.NewServer(providerRouter)
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry", "198.51.100.11", "43000-43010", "provider-entry-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle", "198.51.100.12", "44000-44010", "provider-middle-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit", "198.51.100.13", "45000-45010", "provider-exit-secret", 1)
+
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-token",
+		PortRangeStart: 43000,
+		PortRangeEnd:   43010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-token",
+		PortRangeStart: 44000,
+		PortRangeEnd:   44010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-token",
+		PortRangeStart: 45000,
+		PortRangeEnd:   45010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-token")
+
+	var mu sync.Mutex
+	services := map[string]string{}
+	strictMiddle, strictExit := false, false
+	connectors := map[string]string{}
+	record := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "UpdateService" || kind == "AddService" {
+			var items []map[string]interface{}
+			_ = json.Unmarshal(data, &items)
+			for _, item := range items {
+				handler, _ := item["handler"].(map[string]interface{})
+				if handler["type"] == "relay" {
+					md, _ := handler["metadata"].(map[string]interface{})
+					if handler["chain"] != nil {
+						strictMiddle, _ = md["chain.strict"].(bool)
+					} else {
+						strictExit, _ = md["chain.strict"].(bool)
+					}
+					a, _ := handler["auth"].(map[string]interface{})
+					if a != nil {
+						user, _ := a["username"].(string)
+						pass, _ := a["password"].(string)
+						services[user] = pass
+					}
+				}
+			}
+		}
+		if kind == "UpdateChains" || kind == "AddChains" {
+			var c map[string]interface{}
+			_ = json.Unmarshal(data, &c)
+			if d, ok := c["data"].(map[string]interface{}); ok {
+				c = d
+			}
+			hops, _ := c["hops"].([]interface{})
+			for _, hop := range hops {
+				nodes, _ := hop.(map[string]interface{})["nodes"].([]interface{})
+				for _, node := range nodes {
+					a, _ := node.(map[string]interface{})["connector"].(map[string]interface{})["auth"].(map[string]interface{})
+					if a != nil {
+						user, _ := a["username"].(string)
+						pass, _ := a["password"].(string)
+						connectors[user] = pass
+					}
+				}
+			}
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-entry-secret", record)
+	defer stopEntry()
+	stopMiddle := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-middle-secret", record)
+	defer stopMiddle()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-exit-secret", record)
+	defer stopExit()
+
+	createTunnel := func(name string) int64 {
+		payload := map[string]interface{}{
+			"name":   name,
+			"type":   2,
+			"flow":   99999,
+			"status": 1,
+			"inNodeId": []map[string]interface{}{
+				{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+			"chainNodes": [][]map[string]interface{}{
+				{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+			},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal create payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", consumerAdminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		consumerRouter.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+
+		tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name)
+		if tunnelID <= 0 {
+			t.Fatalf("invalid tunnel id for %s", name)
+		}
+		return tunnelID
+	}
+
+	_ = createTunnel("dual-panel-middle-exit-1")
+
+	mu.Lock()
+	defer mu.Unlock()
+	if !strictMiddle || strictExit {
+		t.Fatal("middle must require its chain and exit must permit direct dialing")
+	}
+	if len(services) != 2 || len(connectors) != 2 {
+		t.Fatalf("expected two authenticated receivers and matching connectors, got %d and %d", len(services), len(connectors))
+	}
+	for user, pass := range services {
+		if pass == "" || connectors[user] != pass {
+			t.Fatal("federation relay credentials do not match")
+		}
+	}
+}
+
+func TestRelayAuthenticationSurvivesInsertingBeforeExistingMiddle(t *testing.T) {
+	router, r := setupContractRouter(t, "insert-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, _ := auth.GenerateToken(1, "admin", 0, "insert-auth-contract")
+	ids := []int64{}
+	var mu sync.Mutex
+	received := map[string]string{}
+	for i, name := range []string{"entry-a", "middle-b", "middle-c", "exit-d"} {
+		id := insertContractNode(t, r, name, fmt.Sprintf("192.0.2.%d", 40+i), fmt.Sprintf("%d-%d", 46000+i*100, 46010+i*100), name+"-secret", 1)
+		ids = append(ids, id)
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, name+"-secret", func(kind string, data json.RawMessage) (bool, string) {
+			if kind == "AddService" || kind == "UpdateService" {
+				var items []map[string]interface{}
+				_ = json.Unmarshal(data, &items)
+				for _, item := range items {
+					handler, _ := item["handler"].(map[string]interface{})
+					if a, ok := handler["auth"].(map[string]interface{}); ok {
+						mu.Lock()
+						received[name], _ = a["password"].(string)
+						mu.Unlock()
+					}
+				}
+			}
+			return false, ""
+		})
+		defer stop()
+	}
+	node := func(id int64) map[string]interface{} { return map[string]interface{}{"nodeId": id, "protocol": "tls"} }
+	payload := map[string]interface{}{"name": "insert-auth", "type": 2, "inNodeId": []map[string]interface{}{node(ids[0])}, "chainNodes": [][]map[string]interface{}{{node(ids[1])}}, "outNodeId": []map[string]interface{}{node(ids[3])}}
+	post := func(path string) *httptest.ResponseRecorder {
+		b, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(b))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	assertCode(t, post("/api/v1/tunnel/create"), 0)
+	mu.Lock()
+	original := received["middle-b"]
+	mu.Unlock()
+	if original == "" {
+		t.Fatal("original middle missing auth")
+	}
+	payload["id"] = mustQueryInt64(t, r, "SELECT id FROM tunnel WHERE name = ?", "insert-auth")
+	payload["chainNodes"] = [][]map[string]interface{}{{node(ids[2])}, {node(ids[1])}}
+	assertCode(t, post("/api/v1/tunnel/update"), 0)
+	mu.Lock()
+	defer mu.Unlock()
+	if received["middle-b"] != original || received["middle-c"] == "" || received["middle-c"] == original {
+		t.Fatal("hop insertion changed existing receiver identity or reused another credential")
+	}
+}
+
+func TestConvertingDirectTunnelRequiresRelayAuthentication(t *testing.T) {
+	router, r := setupContractRouter(t, "relay-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "relay-auth-contract")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "auth-entry", "192.0.2.10", "41000-41010", "entry-management-secret", 1)
+	exit := insertContractNode(t, r, "auth-exit", "192.0.2.11", "42000-42010", "exit-management-secret", 1)
+	var mu sync.Mutex
+	var connector, receiver map[string]interface{}
+	record := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "AddChains" || kind == "UpdateChains" {
+			var c map[string]interface{}
+			_ = json.Unmarshal(data, &c)
+			if nested, ok := c["data"].(map[string]interface{}); ok {
+				c = nested
+			}
+			hops, _ := c["hops"].([]interface{})
+			if len(hops) > 0 {
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				connector, _ = nodes[0].(map[string]interface{})["connector"].(map[string]interface{})["auth"].(map[string]interface{})
+			}
+		}
+		if kind == "AddService" || kind == "UpdateService" {
+			var services []map[string]interface{}
+			_ = json.Unmarshal(data, &services)
+			if len(services) > 0 {
+				receiver, _ = services[0]["handler"].(map[string]interface{})["auth"].(map[string]interface{})
+			}
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "entry-management-secret", record)
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "exit-management-secret", record)
+	defer stopExit()
+	payload := map[string]interface{}{"name": "authenticated-new-tunnel", "type": 1, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	body, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+	payload["type"] = 2
+	payload["id"] = mustQueryInt64(t, r, "SELECT id FROM tunnel WHERE name = ?", "authenticated-new-tunnel")
+	conversionBody, _ := json.Marshal(payload)
+	conversionReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(conversionBody))
+	conversionReq.Header.Set("Authorization", token)
+	conversionRes := httptest.NewRecorder()
+	router.ServeHTTP(conversionRes, conversionReq)
+	assertCode(t, conversionRes, 0)
+
+	mu.Lock()
+	if connector == nil || receiver == nil {
+		t.Fatal("new relay tunnel emitted no endpoint authentication")
+	}
+	if connector["username"] == "" || connector["password"] == "" || connector["username"] != receiver["username"] || connector["password"] != receiver["password"] {
+		t.Fatal("relay endpoint credentials missing or mismatched")
+	}
+	if receiver["password"] == "entry-management-secret" || receiver["password"] == "exit-management-secret" {
+		t.Fatal("management secret reused for relay")
+	}
+	listReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", bytes.NewBufferString(`{}`))
+	listReq.Header.Set("Authorization", token)
+	listRes := httptest.NewRecorder()
+	router.ServeHTTP(listRes, listReq)
+	if !bytes.Contains(listRes.Body.Bytes(), []byte(`"relayAuthMode":"required"`)) {
+		t.Fatalf("tunnel list does not expose required authentication state: %s", listRes.Body.String())
+	}
+	password, _ := receiver["password"].(string)
+	if bytes.Contains(listRes.Body.Bytes(), []byte(password)) {
+		t.Fatal("tunnel list disclosed relay credential")
+	}
+	originalPassword := password
+	mu.Unlock()
+	var listed struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listRes.Body.Bytes(), &listed); err != nil || len(listed.Data) != 1 {
+		t.Fatal("missing created tunnel in list")
+	}
+	payload["id"] = listed.Data[0].ID
+	body, _ = json.Marshal(payload)
+	updateReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	updateReq.Header.Set("Authorization", token)
+	updateRes := httptest.NewRecorder()
+	router.ServeHTTP(updateRes, updateReq)
+
+	assertCode(t, updateRes, 0)
+	mu.Lock()
+	defer mu.Unlock()
+	if connector == nil || receiver == nil || connector["password"] != originalPassword || receiver["password"] != originalPassword {
+		t.Fatal("topology reapply lost or changed persisted endpoint authentication")
+	}
+}
+
+func TestBackupImportCannotSilentlyDowngradeRequiredRelay(t *testing.T) {
+	router, _ := setupContractRouter(t, "backup-relay-auth")
+	token, _ := auth.GenerateToken(1, "admin", 0, "backup-relay-auth")
+	request := httptest.NewRequest(http.MethodPost, "/api/v1/backup/import", bytes.NewBufferString(`{"version":"1","types":["tunnels"],"tunnels":[{"id":92,"name":"protected-backup","type":2,"protocol":"tls","flow":1,"trafficRatio":1,"createdTime":1000,"status":1,"relayAuthMode":"required"}]}`))
+	request.Header.Set("Authorization", token)
+	result := httptest.NewRecorder()
+	router.ServeHTTP(result, request)
+	var out struct {
+		Code int `json:"code"`
+	}
+	if err := json.Unmarshal(result.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	if out.Code == 0 {
+		t.Fatal("configuration backup restored required relay without its private credentials")
+	}
+}
+
+func TestNewRelayTunnelRefusesLegacyFederationBeforeReservation(t *testing.T) {
+	var mu sync.Mutex
+	mutations := 0
+	oldPeer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		if req.URL.Path != "/api/v1/federation/connect" {
+			mu.Lock()
+			mutations++
+			mu.Unlock()
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"code":0,"data":{"shareId":1,"shareName":"legacy","nodeId":1,"nodeName":"legacy-exit","serverIp":"192.0.2.80","status":1,"portRangeStart":49000,"portRangeEnd":49010}}`))
+	}))
+	defer oldPeer.Close()
+	router, r := setupContractRouter(t, "legacy-peer-contract")
+	token, _ := auth.GenerateToken(1, "admin", 0, "legacy-peer-contract")
+	entry := insertContractNode(t, r, "legacy-test-entry", "192.0.2.79", "48000-48010", "legacy-test-entry-secret", 1)
+	importRemoteNodeForContract(t, router, token, oldPeer.URL, "legacy-share-token")
+	exit := queryRemoteNodeIDByToken(t, r, "legacy-share-token")
+	payload := map[string]interface{}{"name": "must-not-downgrade", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	b, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(b))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	var out struct {
+		Code int `json:"code"`
+	}
+	_ = json.Unmarshal(res.Body.Bytes(), &out)
+	if out.Code == 0 {
+		t.Fatal("new tunnel silently accepted legacy federation")
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if mutations != 0 {
+		t.Fatal("legacy peer was mutated before capability refusal")
+	}
+}
+
+func TestLegacyRelayStateRemainsExplicitInList(t *testing.T) {
+	router, r := setupContractRouter(t, "legacy-mode-contract")
+	token, _ := auth.GenerateToken(1, "admin", 0, "legacy-mode-contract")
+	if err := r.DB().Exec(`INSERT INTO tunnel(name,traffic_ratio,type,protocol,flow,created_time,updated_time,status,inx) VALUES('legacy-existing',1,2,'tls',1,1000,1000,1,0)`).Error; err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", nil)
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	if !bytes.Contains(res.Body.Bytes(), []byte(`"relayAuthMode":"legacy"`)) {
+		t.Fatal("legacy relay exposure is hidden from API clients")
+	}
+}

go-backend/tests/contract/tunnel_create_lifecycle_test.go

@@ -0,0 +1,311 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestTunnelDeleteWaitsForCreateRuntime(t *testing.T) {
+	router, r := setupContractRouter(t, "create-lifecycle")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "create-lifecycle")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "create-entry", "192.0.2.10", "41000-41010", "create-entry-secret", 1)
+	exit := insertContractNode(t, r, "create-exit", "192.0.2.11", "42000-42010", "create-exit-secret", 1)
+	entered, release := make(chan struct{}), make(chan struct{})
+	var once, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	deleted := make(chan struct{}, 1)
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "create-entry-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "DeleteChains" {
+			select {
+			case deleted <- struct{}{}:
+			default:
+			}
+		}
+		return false, ""
+	})
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "create-exit-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "AddService" {
+			once.Do(func() { close(entered); <-release })
+		}
+		return false, ""
+	})
+	defer stopExit()
+	defer unblock()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	created := make(chan *httptest.ResponseRecorder, 1)
+	go func() {
+		created <- post("/api/v1/tunnel/create", map[string]interface{}{"name": "create-race", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}})
+	}()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("create did not reach runtime gate")
+	}
+	listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+	var list struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+		t.Fatal("committed create not listed")
+	}
+	deleteDone := make(chan *httptest.ResponseRecorder, 1)
+	go func() { deleteDone <- post("/api/v1/tunnel/delete", map[string]interface{}{"id": list.Data[0].ID}) }()
+	select {
+	case <-deleted:
+		t.Error("delete removed runtime while create was still applying")
+	case <-time.After(150 * time.Millisecond):
+	}
+	unblock()
+	for _, done := range []chan *httptest.ResponseRecorder{created, deleteDone} {
+		select {
+		case res := <-done:
+			assertCode(t, res, 0)
+		case <-time.After(5 * time.Second):
+			t.Fatal("lifecycle operation stuck")
+		}
+	}
+	listed = post("/api/v1/tunnel/list", map[string]interface{}{})
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 0 {
+		t.Fatal("deleted tunnel remains listed")
+	}
+}
+
+func TestOfflineTunnelCreateReportsPendingRuntime(t *testing.T) {
+	router, r := setupContractRouter(t, "pending-lifecycle")
+	token, err := auth.GenerateToken(1, "admin", 0, "pending-lifecycle")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "pending-entry", "192.0.2.10", "41000-41010", "pending-entry-secret", 1)
+	exit := insertContractNode(t, r, "pending-exit", "192.0.2.11", "42000-42010", "pending-exit-secret", 1)
+	payload := map[string]interface{}{"name": "pending-tunnel", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	raw, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(raw))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	var out struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+		Data struct {
+			RuntimeStatus string `json:"runtimeStatus"`
+			TunnelID      int64  `json:"tunnelId"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code != 0 || out.Data.RuntimeStatus != "pending" || out.Data.TunnelID <= 0 || out.Msg == "操作成功" {
+		t.Fatalf("offline create must preserve config but explicitly report pending: %s", res.Body.String())
+	}
+
+	payload["id"] = out.Data.TunnelID
+	raw, _ = json.Marshal(payload)
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+	req.Header.Set("Authorization", token)
+	res = httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	out.Data.RuntimeStatus = ""
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code != 0 || out.Data.RuntimeStatus != "pending" {
+		t.Fatalf("offline update must report pending: %s", res.Body.String())
+	}
+	raw, _ = json.Marshal(map[string]interface{}{"ids": []int64{out.Data.TunnelID}})
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+	req.Header.Set("Authorization", token)
+	res = httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	var batch struct {
+		Data struct {
+			SuccessCount int `json:"successCount"`
+			FailCount    int `json:"failCount"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &batch); err != nil {
+		t.Fatal(err)
+	}
+	if batch.Data.SuccessCount != 0 || batch.Data.FailCount != 1 {
+		t.Fatalf("pending redeploy must not count as success: %s", res.Body.String())
+	}
+}
+
+func TestPendingTunnelUpdateStillRemovesObsoleteRelay(t *testing.T) {
+	testPendingTunnelRemoval(t, false, false)
+}
+func TestFailedObsoleteRelayRemovalPreservesItsChain(t *testing.T) {
+	testPendingTunnelRemoval(t, true, false)
+}
+func TestRedesiredRelayKeepsOldPortReservedUntilReplacementAcknowledged(t *testing.T) {
+	testPendingTunnelRemoval(t, true, true)
+}
+
+func testPendingTunnelRemoval(t *testing.T, failCleanup, readd bool) {
+	router, r := setupContractRouter(t, "pending-removal")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "pending-removal")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "removal-entry", "192.0.2.10", "41000-41010", "removal-entry-secret", 1)
+	middle := insertContractNode(t, r, "removal-middle", "192.0.2.20", "42000-42010", "removal-middle-secret", 1)
+	exit := insertContractNode(t, r, "removal-exit", "192.0.2.30", "43000-43010", "removal-exit-secret", 1)
+	var entryTimeout atomic.Bool
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "removal-entry-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if entryTimeout.Load() && (kind == "AddChains" || kind == "UpdateChains") {
+			return true, "等待节点响应超时"
+		}
+		return false, ""
+	})
+	defer stopEntry()
+	var mu sync.Mutex
+	deleted := map[string]bool{}
+	var timeoutReplacement bool
+	stopMiddle := startMockNodeSessionWithCommandRecorder(t, server.URL, "removal-middle-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "DeleteService" || kind == "DeleteChains" {
+			deleted[kind] = true
+		}
+		if timeoutReplacement && kind == "UpdateService" {
+			return true, "等待节点响应超时"
+		}
+		if failCleanup && kind == "DeleteService" {
+			return true, "cleanup rejected"
+		}
+		return false, ""
+	})
+	defer stopMiddle()
+	stopExit := startMockNodeSession(t, server.URL, "removal-exit-secret")
+	defer stopExit()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	payload := map[string]interface{}{"name": "pending-removal", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42000}}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+	listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+	var list struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+		t.Fatal("missing tunnel")
+	}
+	if readd {
+		entryTimeout.Store(true)
+	} else {
+		stopEntry()
+		waitNodeStatus(t, r, entry, 0)
+	}
+	payload["id"] = list.Data[0].ID
+	payload["chainNodes"] = [][]map[string]interface{}{}
+	res := post("/api/v1/tunnel/update", payload)
+	var out struct {
+		Msg  string `json:"msg"`
+		Code int    `json:"code"`
+		Data struct {
+			RuntimeStatus string `json:"runtimeStatus"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code != 0 || out.Data.RuntimeStatus != "pending" {
+		t.Fatalf("expected pending update: %s", res.Body.String())
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if failCleanup {
+		if !deleted["DeleteService"] || deleted["DeleteChains"] {
+			t.Fatalf("failed listener deletion must preserve its required chain: %v", deleted)
+		}
+		if !strings.Contains(out.Msg, "cleanup rejected") {
+			t.Fatalf("cleanup failure hidden: %s", out.Msg)
+		}
+		if readd {
+			deleted = map[string]bool{}
+			timeoutReplacement = true
+			mu.Unlock()
+			payload["chainNodes"] = [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42001}}}
+			changed := post("/api/v1/tunnel/update", payload)
+			if err := json.Unmarshal(changed.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code != 0 || out.Data.RuntimeStatus != "pending" {
+				t.Fatalf("expected pending replacement: %s", changed.Body.String())
+			}
+			contender := map[string]interface{}{"name": "old-port-contender", "type": 2, "inNodeId": payload["inNodeId"], "outNodeId": payload["outNodeId"], "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42000}}}}
+			blocked := post("/api/v1/tunnel/create", contender)
+			if err := json.Unmarshal(blocked.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code == 0 || !strings.Contains(out.Msg, "旧运行时清理") {
+				t.Fatalf("unacknowledged old port was not reserved: %s", blocked.Body.String())
+			}
+			mu.Lock()
+			timeoutReplacement = false
+			mu.Unlock()
+			post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{list.Data[0].ID}})
+			accepted := post("/api/v1/tunnel/create", contender)
+			if err := json.Unmarshal(accepted.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code != 0 {
+				t.Fatalf("acknowledged replacement did not release old port: %s", accepted.Body.String())
+			}
+			mu.Lock()
+			if len(deleted) != 0 {
+				t.Fatalf("delayed cleanup deleted re-desired relay: %v", deleted)
+			}
+			return
+		}
+		failCleanup = false
+		deleted = map[string]bool{}
+		mu.Unlock()
+		post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{list.Data[0].ID}})
+		mu.Lock()
+		if !deleted["DeleteService"] || !deleted["DeleteChains"] {
+			t.Fatalf("redeploy lost obsolete cleanup ownership after failure: %v", deleted)
+		}
+		deleted = map[string]bool{}
+		mu.Unlock()
+		post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{list.Data[0].ID}})
+		mu.Lock()
+		if len(deleted) != 0 {
+			t.Fatalf("acknowledged cleanup repeated: %v", deleted)
+		}
+	} else if !deleted["DeleteService"] || !deleted["DeleteChains"] {
+		t.Fatalf("pending update left removed relay live: %v", deleted)
+	}
+}

go-backend/tests/contract/tunnel_create_port_reservation_test.go

@@ -0,0 +1,92 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	"go-backend/internal/store/repo"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestConcurrentCreatesReserveLocalPortsBeforeFederationAcknowledgment(t *testing.T) {
+	provider, pr := setupContractRouter(t, "port-provider")
+	entered, release := make(chan struct{}), make(chan struct{})
+	var gateOnce, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	ps := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/api/v1/federation/runtime/apply-role" {
+			gateOnce.Do(func() { close(entered); <-release })
+		}
+		provider.ServeHTTP(w, r)
+	}))
+	defer ps.Close()
+	exit := insertContractNode(t, pr, "provider-port-exit", "192.0.2.30", "43000-43010", "provider-port-exit-secret", 1)
+	now := time.Now().UnixMilli()
+	insertPeerShare(t, pr, &repo.PeerShare{Name: "port-share", NodeID: exit, Token: "port-share-token", PortRangeStart: 43000, PortRangeEnd: 43010, IsActive: 1, CreatedTime: now, UpdatedTime: now})
+	stop := startMockNodeSession(t, ps.URL, "provider-port-exit-secret")
+	defer stop()
+	defer unblock()
+	consumer, cr := setupContractRouter(t, "port-consumer")
+	token, err := auth.GenerateToken(1, "admin", 0, "port-consumer")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, cr, "local-port-entry", "192.0.2.10", "41000-41010", "local-port-entry-secret", 1)
+	middle := insertContractNode(t, cr, "local-port-middle", "192.0.2.20", "42000", "local-port-middle-secret", 1)
+	importRemoteNodeForContract(t, consumer, token, ps.URL, "port-share-token")
+	remoteExit := queryRemoteNodeIDByToken(t, cr, "port-share-token")
+	create := func(name string) *httptest.ResponseRecorder {
+		payload := map[string]interface{}{"name": name, "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls"}}}, "outNodeId": []map[string]interface{}{{"nodeId": remoteExit, "protocol": "tls"}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		consumer.ServeHTTP(res, req)
+		return res
+	}
+	first := make(chan *httptest.ResponseRecorder, 1)
+	go func() { first <- create("port-owner") }()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("first create did not reach provider gate")
+	}
+	second := make(chan *httptest.ResponseRecorder, 1)
+	go func() { second <- create("port-contender") }()
+	secondCompleted := false
+	select {
+	case res := <-second:
+		secondCompleted = true
+		var out struct {
+			Code int `json:"code"`
+		}
+		if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+			t.Fatal(err)
+		}
+		if out.Code == 0 {
+			t.Errorf("second create reused the only reserved local port: %s", res.Body.String())
+		}
+	case <-time.After(300 * time.Millisecond):
+		t.Error("second create did not reject the reserved local port before provider acknowledgment")
+	}
+	unblock()
+	select {
+	case res := <-first:
+		assertCode(t, res, 0)
+	case <-time.After(5 * time.Second):
+		t.Fatal("first create stuck")
+	}
+	// If the regression let the second request reach the gated provider, drain it
+	// before closing test servers; its success still cannot erase the failure above.
+	if !secondCompleted {
+		select {
+		case <-second:
+		case <-time.After(5 * time.Second):
+			t.Fatal("second create stuck after gate release")
+		}
+	}
+}

go-backend/tests/contract/tunnel_deleted_cleanup_test.go

@@ -0,0 +1,110 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	httpserver "go-backend/internal/http"
+	"go-backend/internal/http/handler"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+func TestDeletedTunnelCleanupSurvivesHandlerReplacement(t *testing.T) {
+	const secret = "deleted-cleanup"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "deleted-entry", "192.0.2.10", "41000-41010", "deleted-entry-secret", 1)
+	exit := insertContractNode(t, r, "deleted-exit", "192.0.2.20", "42000", "deleted-exit-secret", 1)
+	stopEntry := startMockNodeSession(t, server.URL, "deleted-entry-secret")
+	defer stopEntry()
+	var rejectDelete atomic.Bool
+	rejectDelete.Store(true)
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "deleted-exit-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "DeleteService" && rejectDelete.Load() {
+			return true, "cleanup rejected"
+		}
+		return false, ""
+	})
+	defer stopExit()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	payload := map[string]interface{}{"name": "deleted-owner", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls", "port": 42000}}}
+	assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+	listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+	var list struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+		t.Fatal("missing tunnel")
+	}
+	id := list.Data[0].ID
+	res := post("/api/v1/tunnel/delete", map[string]interface{}{"id": id})
+	var out struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code == 0 || !strings.Contains(out.Msg, "待重试") {
+		t.Fatalf("failed post-delete cleanup not reported: %s", res.Body.String())
+	}
+	listed = post("/api/v1/tunnel/list", map[string]interface{}{})
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 0 {
+		t.Fatal("desired tunnel not deleted")
+	}
+	payload["name"] = "deleted-port-contender"
+	res = post("/api/v1/tunnel/create", payload)
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code == 0 || !strings.Contains(out.Msg, "旧运行时清理") {
+		t.Fatalf("deleted tunnel lost port ownership: %s", res.Body.String())
+	}
+	stopEntry()
+	stopExit()
+	waitNodeStatus(t, r, entry, 0)
+	waitNodeStatus(t, r, exit, 0)
+	// A fresh handler has no old in-memory topology, locks, or cleanup state.
+	router = httpserver.NewRouter(handler.New(r, secret), secret)
+	recoveredServer := httptest.NewServer(router)
+	defer recoveredServer.Close()
+	newEntry := startMockNodeSession(t, recoveredServer.URL, "deleted-entry-secret")
+	defer newEntry()
+	var deleted atomic.Int32
+	newExit := startMockNodeSessionWithCommandRecorder(t, recoveredServer.URL, "deleted-exit-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "DeleteService" {
+			deleted.Add(1)
+		}
+		return false, ""
+	})
+	defer newExit()
+	waitNodeStatus(t, r, entry, 1)
+	waitNodeStatus(t, r, exit, 1)
+	assertCode(t, post("/api/v1/tunnel/delete", map[string]interface{}{"id": id}), 0)
+	if deleted.Load() != 1 {
+		t.Fatalf("fresh handler did not recover obsolete listener ownership: %d", deleted.Load())
+	}
+	assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+	post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{id}})
+	if deleted.Load() != 1 {
+		t.Fatal("acknowledged cleanup replayed against replacement tunnel")
+	}
+}

go-backend/tests/contract/tunnel_federation_lifecycle_regression_test.go

@@ -0,0 +1,214 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	"go-backend/internal/store/repo"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestFederationRedeployPreservesExistingBindings(t *testing.T) {
+	testFederationRedeploy(t, false, false)
+}
+func TestFederationFailedRedeployPreservesExistingBindings(t *testing.T) {
+	testFederationRedeploy(t, true, false)
+}
+func TestFederationCreateDoesNotHoldDatabaseDuringAcknowledgment(t *testing.T) {
+	testFederationRedeploy(t, false, true)
+}
+
+func testFederationRedeploy(t *testing.T, failRedeploy, gateCreate bool) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	entered, release := make(chan struct{}), make(chan struct{})
+	var gateOnce, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	providerServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if gateCreate && r.URL.Path == "/api/v1/federation/runtime/apply-role" {
+			gateOnce.Do(func() { close(entered); <-release })
+		}
+		providerRouter.ServeHTTP(w, r)
+	}))
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry", "198.51.100.11", "43000-43010", "provider-entry-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle", "198.51.100.12", "44000-44010", "provider-middle-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit", "198.51.100.13", "45000-45010", "provider-exit-secret", 1)
+
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-token",
+		PortRangeStart: 43000,
+		PortRangeEnd:   43010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-token",
+		PortRangeStart: 44000,
+		PortRangeEnd:   44010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-token",
+		PortRangeStart: 45000,
+		PortRangeEnd:   45010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-token")
+
+	var mu sync.Mutex
+	var destructive []string
+	var armed bool
+	recorder := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "DeleteService" || kind == "DeleteChains" {
+			destructive = append(destructive, kind)
+		}
+		if armed && failRedeploy && kind == "UpdateService" {
+			return true, "simulated node update failure"
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-entry-secret", recorder)
+	defer stopEntry()
+	stopMiddle := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-middle-secret", recorder)
+	defer stopMiddle()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-exit-secret", recorder)
+	defer stopExit()
+
+	createTunnel := func(name string) int64 {
+		payload := map[string]interface{}{
+			"name":   name,
+			"type":   2,
+			"flow":   99999,
+			"status": 1,
+			"inNodeId": []map[string]interface{}{
+				{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+			"chainNodes": [][]map[string]interface{}{
+				{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+			},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal create payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", consumerAdminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		consumerRouter.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+
+		tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name)
+		if tunnelID <= 0 {
+			t.Fatalf("invalid tunnel id for %s", name)
+		}
+		return tunnelID
+	}
+
+	defer unblock()
+	var firstTunnelID int64
+	if gateCreate {
+		created := make(chan int64, 1)
+		go func() { created <- createTunnel("dual-panel-middle-exit-1") }()
+		select {
+		case <-entered:
+		case <-time.After(5 * time.Second):
+			t.Fatal("create did not reach federation gate")
+		}
+		listed := make(chan struct{})
+		go func() {
+			defer close(listed)
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", bytes.NewBufferString("{}"))
+			req.Header.Set("Authorization", consumerAdminToken)
+			consumerRouter.ServeHTTP(httptest.NewRecorder(), req)
+		}()
+		select {
+		case <-listed:
+		case <-time.After(300 * time.Millisecond):
+			t.Error("federation create held database while waiting for acknowledgment")
+		}
+		unblock()
+		select {
+		case firstTunnelID = <-created:
+		case <-time.After(5 * time.Second):
+			t.Fatal("create stuck after release")
+		}
+		select {
+		case <-listed:
+		case <-time.After(5 * time.Second):
+			t.Fatal("list stuck after release")
+		}
+		return
+	}
+	firstTunnelID = createTunnel("dual-panel-middle-exit-1")
+
+	mu.Lock()
+	destructive = nil
+	armed = true
+	mu.Unlock()
+	body, _ := json.Marshal(map[string]interface{}{"ids": []int64{firstTunnelID}})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(body))
+	req.Header.Set("Authorization", consumerAdminToken)
+	res := httptest.NewRecorder()
+	consumerRouter.ServeHTTP(res, req)
+	var out struct {
+		Code int `json:"code"`
+		Data struct {
+			SuccessCount int `json:"successCount"`
+			FailCount    int `json:"failCount"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	expectedSuccess, expectedFailure := 1, 0
+	if failRedeploy {
+		expectedSuccess, expectedFailure = 0, 1
+	}
+	if out.Code != 0 || out.Data.SuccessCount != expectedSuccess || out.Data.FailCount != expectedFailure {
+		t.Fatalf("redeploy failed: %s", res.Body.String())
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(destructive) > 0 {
+		t.Fatalf("redeploy destroyed existing federation runtime: %v", destructive)
+	}
+}

go-backend/tests/contract/tunnel_insert_middle_hop_investigation_test.go

@@ -0,0 +1,510 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestTunnelInsertMiddleHopRecordedRuntimeContract(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 user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.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(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			defer mu.Unlock()
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round"}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		lastChains := map[string]int{}
+		lastServices := map[string]int{}
+		for i, c := range commands {
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				lastChains[c.node] = i
+			}
+			if c.kind == "UpdateService" || c.kind == "AddService" {
+				lastServices[c.node] = i
+			}
+		}
+		for i, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				if lastChains[c.node] != i {
+					continue
+				}
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ? LIMIT 1`, tunnelID, target)
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				if lastServices[c.node] != i {
+					continue
+				}
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+	update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}})
+	check(map[string]int64{"A": entryB, "B": entryC, "C": exitNodeID})
+	// A remains the entry and the user's forward remains bound there.
+	after, _ := mustQueryInt64Int(t, r, `SELECT node_id,port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
+	if after != entryA {
+		t.Fatalf("forward entry changed: %d", after)
+	}
+}
+
+func TestTunnelRedeployEditMissingChainWindowInvestigation(t *testing.T) {
+	t.Skip("Pre-repair characterization; preserved in plans/evidence/070-tunnel-insert-middle-hop-investigation.go.txt. Replaced by TestTunnelRedeployPreservesLiveRoutes and TestTunnelEditWaitsForRedeploy.")
+	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 user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.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(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	armed := false
+	chainPresent, servicePresent := map[string]bool{}, map[string]bool{}
+	atDeleteService, releaseDeleteService, editReachedA := make(chan struct{}), make(chan struct{}), make(chan struct{}, 1)
+	var gateOnce, releaseOnce sync.Once
+	release := func() { releaseOnce.Do(func() { close(releaseDeleteService) }) }
+	defer release()
+
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			active := armed
+			shouldGate := active && name == "B" && kind == "DeleteService"
+			if active && name == "A" && kind == "UpdateChains" {
+				select {
+				case editReachedA <- struct{}{}:
+				default:
+				}
+			}
+			mu.Unlock()
+			if shouldGate {
+				gateOnce.Do(func() { close(atDeleteService); <-releaseDeleteService })
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			if kind == "DeleteChains" {
+				chainPresent[name] = false
+			}
+			if kind == "AddChains" || kind == "UpdateChains" {
+				chainPresent[name] = true
+			}
+			if kind == "DeleteService" {
+				servicePresent[name] = false
+			}
+			if kind == "AddService" || kind == "UpdateService" {
+				servicePresent[name] = true
+			}
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round"}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		lastChains := map[string]int{}
+		lastServices := map[string]int{}
+		for i, c := range commands {
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				lastChains[c.node] = i
+			}
+			if c.kind == "UpdateService" || c.kind == "AddService" {
+				lastServices[c.node] = i
+			}
+		}
+		for i, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				if lastChains[c.node] != i {
+					continue
+				}
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ? LIMIT 1`, tunnelID, target)
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				if lastServices[c.node] != i {
+					continue
+				}
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+
+	mu.Lock()
+	armed = true
+	mu.Unlock()
+	redeployDone := make(chan struct{})
+	go func() {
+		defer close(redeployDone)
+		raw, _ := json.Marshal(map[string]interface{}{"ids": []int64{tunnelID}})
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		t.Logf("redeploy response: %s", res.Body.String())
+	}()
+	await := func(ch <-chan struct{}, label string) {
+		t.Helper()
+		select {
+		case <-ch:
+		case <-time.After(10 * time.Second):
+			release()
+			t.Fatalf("timeout waiting for %s", label)
+		}
+	}
+	await(atDeleteService, "B DeleteService gate")
+	editDone := make(chan struct{})
+	go func() { defer close(editDone); update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}}) }()
+	await(editReachedA, "edit UpdateChains on A")
+	mu.Lock()
+	missing, live := !chainPresent["B"], servicePresent["B"]
+	mu.Unlock()
+	if !missing || !live {
+		release()
+		t.Fatalf("expected B live service with missing chain during overlap, missing=%v live=%v", missing, live)
+	}
+	t.Log("Deterministic overlap confirmed: edit reached A while redeploy had deleted B chain but had not deleted B relay service")
+	release()
+	await(editDone, "edit completion")
+	await(redeployDone, "redeploy completion")
+	mu.Lock()
+	defer mu.Unlock()
+	t.Logf("final mock runtime chain presence: A=%v B=%v C=%v; services B=%v C=%v D=%v", chainPresent["A"], chainPresent["B"], chainPresent["C"], servicePresent["B"], servicePresent["C"], servicePresent["D"])
+}

go-backend/tests/contract/tunnel_lifecycle_regression_test.go

@@ -0,0 +1,363 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestTunnelRedeployPreservesLiveRoutes(t *testing.T) {
+	testTunnelLifecycle(t, false, false, false)
+}
+
+func TestTunnelEditWaitsForRedeploy(t *testing.T) {
+	testTunnelLifecycle(t, true, false, false)
+}
+
+func TestTunnelFailedRedeployPreservesLiveRoutes(t *testing.T) {
+	testTunnelLifecycle(t, false, true, false)
+}
+
+func TestTunnelDeleteWaitsForRedeploy(t *testing.T) { testTunnelLifecycle(t, true, false, true) }
+
+func testTunnelLifecycle(t *testing.T, concurrentEdit, failRedeploy, concurrentDelete bool) {
+	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 user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.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(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	var armed, gateClaimed bool
+	entered := make(chan struct{})
+	release := make(chan struct{})
+	var gateOnce, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	defer unblock()
+	editApplied := make(chan struct{}, 1)
+
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			gate := armed && !gateClaimed && name == "D" && kind == "UpdateService"
+			if gate {
+				gateClaimed = true
+			}
+			if armed && ((name == "C" && (kind == "UpdateChains" || kind == "AddChains")) || (concurrentDelete && kind == "DeleteChains")) {
+				select {
+				case editApplied <- struct{}{}:
+				default:
+				}
+			}
+			mu.Unlock()
+			if gate {
+				gateOnce.Do(func() { close(entered); <-release })
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			if armed && failRedeploy && name == "B" && kind == "UpdateService" {
+				return true, "bind: address already in use"
+			}
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round", "port": 54002}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		lastChains := map[string]int{}
+		lastServices := map[string]int{}
+		for i, c := range commands {
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				lastChains[c.node] = i
+			}
+			if c.kind == "UpdateService" || c.kind == "AddService" {
+				lastServices[c.node] = i
+			}
+		}
+		for i, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				if lastChains[c.node] != i {
+					continue
+				}
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := 54002
+				if target == exitNodeID {
+					port = 57001
+				}
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				if lastServices[c.node] != i {
+					continue
+				}
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+	mu.Lock()
+	commands = nil
+	mu.Unlock()
+	raw, _ := json.Marshal(map[string]interface{}{"ids": []int64{tunnelID}})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+	req.Header.Set("Authorization", adminToken)
+	res := httptest.NewRecorder()
+	if !concurrentEdit {
+		mu.Lock()
+		armed = failRedeploy
+		mu.Unlock()
+		router.ServeHTTP(res, req)
+		if failRedeploy {
+			var out struct {
+				Data struct {
+					FailCount    int `json:"failCount"`
+					SuccessCount int `json:"successCount"`
+				} `json:"data"`
+			}
+			if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Data.FailCount != 1 || out.Data.SuccessCount != 0 {
+				t.Fatalf("expected redeploy failure: %s", res.Body.String())
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			for _, c := range commands {
+				if c.kind == "DeleteService" || c.kind == "DeleteChains" {
+					t.Errorf("failed redeploy removed existing runtime: %s on %s", c.kind, c.node)
+				}
+			}
+		} else {
+			assertCode(t, res, 0)
+			check(map[string]int64{"A": entryB, "B": exitNodeID})
+		}
+		return
+	}
+	mu.Lock()
+	armed = true
+	mu.Unlock()
+	redeployDone := make(chan struct{})
+	go func() { defer close(redeployDone); router.ServeHTTP(res, req) }()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("redeploy did not reach command gate")
+	}
+	editDone := make(chan struct{})
+	go func() {
+		defer close(editDone)
+		if concurrentDelete {
+			body, _ := json.Marshal(map[string]interface{}{"id": tunnelID})
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/delete", bytes.NewReader(body))
+			req.Header.Set("Authorization", adminToken)
+			res := httptest.NewRecorder()
+			router.ServeHTTP(res, req)
+			assertCode(t, res, 0)
+		} else {
+			update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}})
+		}
+	}()
+	select {
+	case <-editApplied:
+		t.Error("concurrent mutation changed runtime before redeploy finished")
+	case <-time.After(150 * time.Millisecond):
+	}
+	unblock()
+	for _, done := range []chan struct{}{redeployDone, editDone} {
+		select {
+		case <-done:
+		case <-time.After(5 * time.Second):
+			t.Fatal("lifecycle operation did not complete")
+		}
+	}
+	assertCode(t, res, 0)
+	if !concurrentDelete {
+		mu.Lock()
+		defer mu.Unlock()
+		latest := map[string]string{}
+		for _, c := range commands {
+			if c.kind != "UpdateChains" && c.kind != "AddChains" {
+				continue
+			}
+			var raw map[string]interface{}
+			if err := json.Unmarshal(c.data, &raw); err != nil {
+				t.Fatal(err)
+			}
+			if nested, ok := raw["data"].(map[string]interface{}); ok {
+				raw = nested
+			}
+			hops := raw["hops"].([]interface{})
+			nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+			latest[c.node] = nodes[0].(map[string]interface{})["addr"].(string)
+		}
+		if latest["B"] != "10.52.0.3:54002" {
+			t.Fatalf("stale redeploy overwrote edit: B targets %s", latest["B"])
+		}
+	}
+}

go-backend/tests/contract/tunnel_role_transition_test.go

@@ -0,0 +1,117 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+)
+
+func TestMiddleToExitKeepsChainUntilReceiverReplacementAcknowledged(t *testing.T) {
+	for _, port := range []int{42000, 42001} {
+		for _, failure := range []string{"等待节点响应超时", "replacement rejected"} {
+			t.Run(fmt.Sprintf("port=%d/failure=%s", port, failure), func(t *testing.T) {
+				router, r := setupContractRouter(t, "role-transition")
+				server := httptest.NewServer(router)
+				defer server.Close()
+				token, err := auth.GenerateToken(1, "admin", 0, "role-transition")
+				if err != nil {
+					t.Fatal(err)
+				}
+				entry := insertContractNode(t, r, "role-entry", "192.0.2.10", "41000-41010", "role-entry-secret", 1)
+				middle := insertContractNode(t, r, "role-middle", "192.0.2.20", "42000-42010", "role-middle-secret", 1)
+				exit := insertContractNode(t, r, "role-exit", "192.0.2.30", "43000-43010", "role-exit-secret", 1)
+				stopEntry := startMockNodeSession(t, server.URL, "role-entry-secret")
+				defer stopEntry()
+				var mu sync.Mutex
+				failReplacement := false
+				replacementAccepted := false
+				unsafeDeletion := false
+				chainDeletes := 0
+				stopMiddle := startMockNodeSessionWithCommandRecorder(t, server.URL, "role-middle-secret", func(kind string, data json.RawMessage) (bool, string) {
+					mu.Lock()
+					defer mu.Unlock()
+					if kind == "UpdateService" {
+						if failReplacement {
+							return true, failure
+						}
+						var services []struct {
+							Handler struct {
+								Chain string `json:"chain"`
+							} `json:"handler"`
+						}
+						if err := json.Unmarshal(data, &services); err == nil && len(services) > 0 && services[0].Handler.Chain == "" {
+							replacementAccepted = true
+						}
+					}
+					if kind == "DeleteChains" {
+						chainDeletes++
+						if !replacementAccepted {
+							unsafeDeletion = true
+						}
+					}
+					return false, ""
+				})
+				defer stopMiddle()
+				stopExit := startMockNodeSession(t, server.URL, "role-exit-secret")
+				defer stopExit()
+				post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+					raw, _ := json.Marshal(payload)
+					req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+					req.Header.Set("Authorization", token)
+					res := httptest.NewRecorder()
+					router.ServeHTTP(res, req)
+					return res
+				}
+				payload := map[string]interface{}{"name": "role-transition", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42000}}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls", "port": 43000}}}
+				assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+				listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+				var list struct {
+					Data []struct {
+						ID int64 `json:"id"`
+					} `json:"data"`
+				}
+				if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+					t.Fatal("missing tunnel")
+				}
+				id := list.Data[0].ID
+				mu.Lock()
+				failReplacement = true
+				mu.Unlock()
+				payload["id"] = id
+				payload["chainNodes"] = [][]map[string]interface{}{}
+				payload["outNodeId"] = []map[string]interface{}{{"nodeId": middle, "protocol": "tls", "port": port}}
+				post("/api/v1/tunnel/update", payload)
+				post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{id}})
+				mu.Lock()
+				if chainDeletes != 0 || unsafeDeletion {
+					t.Errorf("old middle chain removed before receiver replacement ACK: deletes=%d unsafe=%v", chainDeletes, unsafeDeletion)
+				}
+				failReplacement = false
+				mu.Unlock()
+				recovered := post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{id}})
+				var result struct {
+					Data struct {
+						SuccessCount int `json:"successCount"`
+						FailCount    int `json:"failCount"`
+					} `json:"data"`
+				}
+				if err := json.Unmarshal(recovered.Body.Bytes(), &result); err != nil {
+					t.Fatal(err)
+				}
+				if result.Data.SuccessCount != 1 || result.Data.FailCount != 0 {
+					t.Fatalf("replacement retry failed: %s", recovered.Body.String())
+				}
+				mu.Lock()
+				defer mu.Unlock()
+				if !replacementAccepted || chainDeletes != 1 || unsafeDeletion {
+					t.Fatalf("obsolete chain must be removed exactly after successful exit replacement: accepted=%v deletes=%d unsafe=%v", replacementAccepted, chainDeletes, unsafeDeletion)
+				}
+			})
+		}
+	}
+}

go-backend/tests/contract/user_disable_contract_test.go

@@ -0,0 +1,87 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/model"
+)
+
+func TestManualUserDisableRevokesLoginTokenAndForwardAccess(t *testing.T) {
+	const secret = "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	seedContractUser(t, r, 2, "disable-contract", 1, 1)
+	for _, value := range []interface{}{
+		&model.Tunnel{ID: 1, Name: "disable-contract", Type: 1, Status: 1, Flow: 1},
+		&model.UserTunnel{ID: 10, UserID: 2, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+		&model.Forward{ID: 20, UserID: 2, UserName: "disable-contract", Name: "paused", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 0},
+	} {
+		if err := r.DB().Create(value).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	userToken, err := auth.GenerateToken(2, "disable-contract", 1, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	request := func(path, token, body string) response.R {
+		t.Helper()
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewBufferString(body))
+		req.Header.Set("Authorization", token)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		var out response.R
+		if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+			t.Fatal(err)
+		}
+		return out
+	}
+	if out := request("/api/v1/forward/list", userToken, `{}`); out.Code != 0 {
+		t.Fatalf("token invalid before disable: %s", out.Msg)
+	}
+	if out := request("/api/v1/user/update", adminToken, `{"id":2,"user":"disable-contract","status":0}`); out.Code != 0 {
+		t.Fatalf("disable user: %s", out.Msg)
+	}
+	for _, check := range []struct{ path, body string }{
+		{"/api/v1/forward/list", `{}`},
+		{"/api/v1/forward/create", `{"tunnelId":1,"name":"bypass","remoteAddr":"127.0.0.1:80"}`},
+		{"/api/v1/forward/resume", `{"id":20}`},
+		{"/api/v1/forward/batch-resume", `{"ids":[20]}`},
+	} {
+		if out := request(check.path, userToken, check.body); out.Code != 401 {
+			t.Errorf("disabled user's old token accepted at %s: %+v", check.path, out)
+		}
+	}
+	if out := request("/api/v1/user/login", "", `{"username":"disable-contract","password":"contract-pass","captchaId":""}`); out.Code == 0 || !strings.Contains(out.Msg, "停用") {
+		t.Errorf("disabled account login: %+v", out)
+	}
+	if out := request("/api/v1/forward/resume", adminToken, `{"id":20}`); out.Code == 0 || !strings.Contains(out.Msg, "禁用") {
+		t.Errorf("admin bypassed disabled owner's policy: %+v", out)
+	}
+	out := request("/api/v1/tunnel/user/list", adminToken, `{"userId":2}`)
+	if out.Code != 0 {
+		t.Fatalf("list permissions: %s", out.Msg)
+	}
+	items, ok := out.Data.([]interface{})
+	if !ok || len(items) != 1 {
+		t.Fatalf("permission list: %#v", out.Data)
+	}
+	permission, ok := items[0].(map[string]interface{})
+	if !ok || permission["status"] != float64(0) {
+		t.Errorf("permission still displayed as enabled: %#v", items[0])
+	}
+	if got := mustQueryInt(t, r, "SELECT status FROM forward WHERE id = 20"); got != 0 {
+		t.Errorf("disabled forward resumed: %d", got)
+	}
+}

go-gost/x/chain/relay_auth_matrix_investigation_test.go

@@ -0,0 +1,197 @@
+package chain_test
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	corechain "github.com/go-gost/core/chain"
+	"github.com/go-gost/core/connector"
+	"github.com/go-gost/core/dialer"
+	"github.com/go-gost/core/handler"
+	"github.com/go-gost/core/listener"
+	corelogger "github.com/go-gost/core/logger"
+	xauth "github.com/go-gost/x/auth"
+	xchain "github.com/go-gost/x/chain"
+	relayconnector "github.com/go-gost/x/connector/relay"
+	kcpdialer "github.com/go-gost/x/dialer/kcp"
+	relayhandler "github.com/go-gost/x/handler/relay"
+	netdialer "github.com/go-gost/x/internal/net/dialer"
+	kcplistener "github.com/go-gost/x/listener/kcp"
+	tcplistener "github.com/go-gost/x/listener/tcp"
+	tlslistener "github.com/go-gost/x/listener/tls"
+	xlogger "github.com/go-gost/x/logger"
+	"github.com/go-gost/x/metadata"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Local-only matrix: native GOST listeners, relay handler and connectors. The
+// credential below is synthetic test data, never used outside loopback sockets.
+func TestRelayAuthTransportMatrixInvestigation(t *testing.T) {
+	log := xlogger.Nop()
+	corelogger.SetDefault(log)
+	certServer := httptest.NewTLSServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	cert := certServer.TLS.Certificates[0]
+	leaf := certServer.Certificate()
+	certServer.Close()
+	roots := x509.NewCertPool()
+	roots.AddCert(leaf)
+	tcpTarget, e := net.Listen("tcp", "127.0.0.1:0")
+	if e != nil {
+		t.Fatal(e)
+	}
+	defer tcpTarget.Close()
+	go func() {
+		for {
+			c, e := tcpTarget.Accept()
+			if e != nil {
+				return
+			}
+			go func() { defer c.Close(); io.Copy(c, c) }()
+		}
+	}()
+	udpTarget, e := net.ListenPacket("udp", "127.0.0.1:0")
+	if e != nil {
+		t.Fatal(e)
+	}
+	defer udpTarget.Close()
+	go func() {
+		buf := make([]byte, 1024)
+		for {
+			n, a, e := udpTarget.ReadFrom(buf)
+			if e != nil {
+				return
+			}
+			udpTarget.WriteTo(buf[:n], a)
+		}
+	}()
+	for _, transport := range []string{"tcp", "tls", "kcp"} {
+		for _, network := range []string{"tcp", "udp"} {
+			for _, test := range []struct {
+				name        string
+				auth        bool
+				credentials *url.Userinfo
+				success     bool
+			}{
+				{"legacy-no-credentials", false, nil, true},
+				{"legacy-valid-credentials", false, url.UserPassword("test-peer", "synthetic-test-secret"), true},
+				{"secured-no-credentials", true, nil, false},
+				{"secured-wrong-credentials", true, url.UserPassword("test-peer", "incorrect"), false},
+				{"secured-valid-credentials", true, url.UserPassword("test-peer", "synthetic-test-secret"), true},
+			} {
+				t.Run(transport+"/"+network+"/"+test.name, func(t *testing.T) {
+					opts := []listener.Option{listener.AddrOption("127.0.0.1:0"), listener.LoggerOption(log), listener.TLSConfigOption(&tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS12})}
+					var ln listener.Listener
+					switch transport {
+					case "tls":
+						ln = tlslistener.NewListener(opts...)
+					case "kcp":
+						ln = kcplistener.NewListener(opts...)
+					default:
+						ln = tcplistener.NewListener(opts...)
+					}
+					md := metadata.NewMetadata(map[string]any{"kcp.tcp": false, "kcp.nocomp": true})
+					if e := ln.Init(md); e != nil {
+						t.Fatal(e)
+					}
+					defer ln.Close()
+					hopts := []handler.Option{handler.RouterOption(xchain.NewRouter(corechain.LoggerRouterOption(log))), handler.LoggerOption(log), handler.ServiceOption("auth-investigation")}
+					if test.auth {
+						au := xauth.NewAuthenticator(xauth.AuthsOption(map[string]string{"test-peer": "synthetic-test-secret"}))
+						if closer, ok := au.(io.Closer); ok {
+							defer closer.Close()
+						}
+						hopts = append(hopts, handler.AutherOption(au))
+					}
+					h := relayhandler.NewHandler(hopts...)
+					if e := h.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+						t.Fatal(e)
+					}
+					if closer, ok := h.(io.Closer); ok {
+						defer closer.Close()
+					}
+					handled := make(chan struct{})
+					go func() {
+						defer close(handled)
+						c, e := ln.Accept()
+						if e == nil {
+							h.Handle(context.Background(), c)
+						}
+					}()
+					var raw net.Conn
+					var err error
+					switch transport {
+					case "tls":
+						raw, err = tls.DialWithDialer(&net.Dialer{Timeout: time.Second}, "tcp", ln.Addr().String(), &tls.Config{RootCAs: roots, MinVersion: tls.VersionTLS12})
+					case "kcp":
+						d := kcpdialer.NewDialer(dialer.LoggerOption(log))
+						if e := d.Init(md); e != nil {
+							t.Fatal(e)
+						}
+						if closer, ok := d.(io.Closer); ok {
+							defer closer.Close()
+						}
+						raw, err = d.Dial(context.Background(), ln.Addr().String(), dialer.NetDialerDialOption(&netdialer.Dialer{Logger: log}))
+					default:
+						raw, err = net.DialTimeout("tcp", ln.Addr().String(), time.Second)
+					}
+					if err != nil {
+						t.Fatal(err)
+					}
+					defer raw.Close()
+					raw.SetDeadline(time.Now().Add(5 * time.Second))
+					copts := []connector.Option{connector.LoggerOption(log)}
+					if test.credentials != nil {
+						copts = append(copts, connector.AuthOption(test.credentials))
+					}
+					client := relayconnector.NewConnector(copts...)
+					if e := client.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+						t.Fatal(e)
+					}
+					target := tcpTarget.Addr().String()
+					if network == "udp" {
+						target = udpTarget.LocalAddr().String()
+					}
+					conn, err := client.Connect(context.Background(), raw, network, target)
+					if !test.success {
+						if err == nil {
+							t.Fatal("unauthorized client was accepted")
+						}
+						if !strings.Contains(strings.ToLower(err.Error()), "unauthorized") {
+							t.Fatalf("expected authentication refusal, got %v", err)
+						}
+						raw.Close()
+						<-handled
+						return
+					}
+					if err != nil {
+						t.Fatal(err)
+					}
+					if _, err = conn.Write([]byte("probe")); err != nil {
+						t.Fatal(err)
+					}
+					b := make([]byte, 64)
+					n, err := conn.Read(b)
+					if err != nil {
+						t.Fatal(err)
+					}
+					if string(b[:n]) != "probe" {
+						t.Fatalf("unexpected response %q", b[:n])
+					}
+					raw.Close()
+					select {
+					case <-handled:
+					case <-time.After(5 * time.Second):
+						t.Fatal("handler did not close")
+					}
+				})
+			}
+		}
+	}
+}

go-gost/x/chain/relay_missing_chain_investigation_test.go

@@ -0,0 +1,151 @@
+package chain_test
+
+import (
+	"context"
+	corechain "github.com/go-gost/core/chain"
+	"github.com/go-gost/core/connector"
+	"github.com/go-gost/core/handler"
+	corelogger "github.com/go-gost/core/logger"
+	xchain "github.com/go-gost/x/chain"
+	"github.com/go-gost/x/config"
+	parser "github.com/go-gost/x/config/parsing/chain"
+	relayconnector "github.com/go-gost/x/connector/relay"
+	_ "github.com/go-gost/x/dialer/tcp"
+	relayhandler "github.com/go-gost/x/handler/relay"
+	xlogger "github.com/go-gost/x/logger"
+	"github.com/go-gost/x/metadata"
+	"github.com/go-gost/x/registry"
+	"io"
+	"net"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// This test documents existing fail-open behavior, not desired secure behavior.
+// Every socket is bound to 127.0.0.1, no production config or external target.
+func TestRelayMissingChainDataPathInvestigation(t *testing.T) {
+	log := xlogger.Nop()
+	originalLogger := corelogger.Default()
+	corelogger.SetDefault(log)
+	if originalLogger != nil {
+		defer corelogger.SetDefault(originalLogger)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	target, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer target.Close()
+	go func() {
+		for {
+			c, e := target.Accept()
+			if e != nil {
+				return
+			}
+			go func() { defer c.Close(); io.Copy(c, c) }()
+		}
+	}()
+	type relay struct {
+		addr  string
+		count *atomic.Int32
+	}
+	start := func(name, chainName string) relay {
+		ln, e := net.Listen("tcp", "127.0.0.1:0")
+		if e != nil {
+			t.Fatal(e)
+		}
+		t.Cleanup(func() { ln.Close() })
+		router := xchain.NewRouter(corechain.ChainRouterOption(registry.ChainRegistry().Get(chainName)), corechain.LoggerRouterOption(log))
+		h := relayhandler.NewHandler(handler.RouterOption(router), handler.LoggerOption(log), handler.ServiceOption(name))
+		if e := h.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+			t.Fatal(e)
+		}
+		t.Cleanup(func() {
+			if closer, ok := h.(io.Closer); ok {
+				closer.Close()
+			}
+		})
+		count := &atomic.Int32{}
+		go func() {
+			for {
+				c, e := ln.Accept()
+				if e != nil {
+					return
+				}
+				count.Add(1)
+				go h.Handle(ctx, c)
+			}
+		}()
+		return relay{ln.Addr().String(), count}
+	}
+	replace := func(name, addr string) {
+		c, e := parser.ParseChain(&config.ChainConfig{Name: name, Hops: []*config.HopConfig{{Name: name + "-hop", Nodes: []*config.NodeConfig{{Name: name + "-next", Addr: addr, Connector: &config.ConnectorConfig{Type: "relay", Metadata: map[string]any{"nodelay": true}}, Dialer: &config.DialerConfig{Type: "tcp"}}}}}}, log)
+		if e != nil {
+			t.Fatal(e)
+		}
+		if e = registry.ReplaceChain(name, c); e != nil {
+			t.Fatal(e)
+		}
+	}
+	for _, name := range []string{"investigation-A", "investigation-B", "investigation-C"} {
+		name := name
+		t.Cleanup(func() { registry.ChainRegistry().Unregister(name) })
+	}
+	d := start("D", "")
+	c := start("C", "investigation-C")
+	replace("investigation-C", d.addr)
+	b := start("B", "investigation-B")
+	replace("investigation-B", d.addr)
+	a := start("A", "investigation-A")
+	replace("investigation-A", b.addr)
+	request := func() {
+		raw, e := net.DialTimeout("tcp", a.addr, time.Second)
+		if e != nil {
+			t.Fatal(e)
+		}
+		defer raw.Close()
+		raw.SetDeadline(time.Now().Add(3 * time.Second))
+		client := relayconnector.NewConnector(connector.LoggerOption(log))
+		if e := client.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+			t.Fatal(e)
+		}
+		conn, e := client.Connect(ctx, raw, "tcp", target.Addr().String())
+		if e != nil {
+			t.Fatal(e)
+		}
+		if _, e = conn.Write([]byte("probe")); e != nil {
+			t.Fatal(e)
+		}
+		buf := make([]byte, 5)
+		if _, e = io.ReadFull(conn, buf); e != nil {
+			t.Fatal(e)
+		}
+		if string(buf) != "probe" {
+			t.Fatalf("bad response %q", buf)
+		}
+	}
+	request()
+	if b.count.Load() != 1 || c.count.Load() != 0 || d.count.Load() != 1 {
+		t.Fatalf("initial B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+	replace("investigation-B", c.addr)
+	request()
+	if b.count.Load() != 2 || c.count.Load() != 1 || d.count.Load() != 2 {
+		t.Fatalf("insert C B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+	// Deterministic cleanup boundary: DeleteChains has completed, while the B
+	// relay service is still alive (before a subsequent DeleteService command).
+	registry.ChainRegistry().Unregister("investigation-B")
+	request()
+	if b.count.Load() != 3 || c.count.Load() != 1 || d.count.Load() != 2 {
+		t.Fatalf("missing chain B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+	t.Log("Confirmed real relay data flow: A-B-D, then A-B-C-D, then A-B-target with B chain missing; no credentials supplied")
+	replace("investigation-B", c.addr)
+	request()
+	if b.count.Load() != 4 || c.count.Load() != 2 || d.count.Load() != 3 {
+		t.Fatalf("restored B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+}

go-gost/x/chain/required_relay_recovery_test.go

@@ -0,0 +1,190 @@
+package chain_test
+
+import (
+	"context"
+	"io"
+	"net"
+	"net/url"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	corechain "github.com/go-gost/core/chain"
+	"github.com/go-gost/core/connector"
+	"github.com/go-gost/core/handler"
+	corelogger "github.com/go-gost/core/logger"
+	xauth "github.com/go-gost/x/auth"
+	xchain "github.com/go-gost/x/chain"
+	"github.com/go-gost/x/config"
+	parser "github.com/go-gost/x/config/parsing/chain"
+	relayconnector "github.com/go-gost/x/connector/relay"
+	_ "github.com/go-gost/x/dialer/tcp"
+	relayhandler "github.com/go-gost/x/handler/relay"
+	xlogger "github.com/go-gost/x/logger"
+	"github.com/go-gost/x/metadata"
+	"github.com/go-gost/x/registry"
+)
+
+// This regression uses real loopback GOST relay endpoints and verifies the required-route policy.
+// Every socket is bound to 127.0.0.1, no production config or external target.
+func TestRequiredRelayRouteRejectsMissingHopAndRecovers(t *testing.T) {
+	testRequiredRelayRecovery(t, false)
+}
+
+func TestRequiredAuthenticatedRelayRouteRejectsMissingHopAndRecovers(t *testing.T) {
+	testRequiredRelayRecovery(t, true)
+}
+
+func testRequiredRelayRecovery(t *testing.T, authenticated bool) {
+	t.Helper()
+	log := xlogger.Nop()
+	originalLogger := corelogger.Default()
+	corelogger.SetDefault(log)
+	if originalLogger != nil {
+		defer corelogger.SetDefault(originalLogger)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	target, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer target.Close()
+	go func() {
+		for {
+			c, e := target.Accept()
+			if e != nil {
+				return
+			}
+			go func() { defer c.Close(); io.Copy(c, c) }()
+		}
+	}()
+	type relay struct {
+		name  string
+		addr  string
+		count *atomic.Int32
+	}
+	start := func(name, chainName string) relay {
+		ln, e := net.Listen("tcp", "127.0.0.1:0")
+		if e != nil {
+			t.Fatal(e)
+		}
+		t.Cleanup(func() { ln.Close() })
+		router := xchain.NewRouter(corechain.ChainRouterOption(registry.ChainRegistry().Get(chainName)), corechain.LoggerRouterOption(log))
+		if chainName != "" {
+			router.WithRequiredChain()
+		}
+		opts := []handler.Option{handler.RouterOption(router), handler.LoggerOption(log), handler.ServiceOption(name)}
+		if authenticated {
+			au := xauth.NewAuthenticator(xauth.AuthsOption(map[string]string{name: "synthetic-local-password-for-" + name}))
+			if closer, ok := au.(io.Closer); ok {
+				t.Cleanup(func() { closer.Close() })
+			}
+			opts = append(opts, handler.AutherOption(au))
+		}
+		h := relayhandler.NewHandler(opts...)
+		if e := h.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+			t.Fatal(e)
+		}
+		t.Cleanup(func() {
+			if closer, ok := h.(io.Closer); ok {
+				closer.Close()
+			}
+		})
+		count := &atomic.Int32{}
+		go func() {
+			for {
+				c, e := ln.Accept()
+				if e != nil {
+					return
+				}
+				count.Add(1)
+				go h.Handle(ctx, c)
+			}
+		}()
+		return relay{name, ln.Addr().String(), count}
+	}
+	replace := func(name string, next relay) {
+		connectorConfig := &config.ConnectorConfig{Type: "relay", Metadata: map[string]any{"nodelay": true}}
+		if authenticated {
+			connectorConfig.Auth = &config.AuthConfig{Username: next.name, Password: "synthetic-local-password-for-" + next.name}
+		}
+		c, e := parser.ParseChain(&config.ChainConfig{Name: name, Hops: []*config.HopConfig{{Name: name + "-hop", Nodes: []*config.NodeConfig{{Name: name + "-next", Addr: next.addr, Connector: connectorConfig, Dialer: &config.DialerConfig{Type: "tcp"}}}}}}, log)
+		if e != nil {
+			t.Fatal(e)
+		}
+		if e = registry.ReplaceChain(name, c); e != nil {
+			t.Fatal(e)
+		}
+	}
+	for _, name := range []string{"strict-regression-A", "strict-regression-B", "strict-regression-C"} {
+		name := name
+		t.Cleanup(func() { registry.ChainRegistry().Unregister(name) })
+	}
+	d := start("D", "")
+	c := start("C", "strict-regression-C")
+	replace("strict-regression-C", d)
+	b := start("B", "strict-regression-B")
+	replace("strict-regression-B", d)
+	a := start("A", "strict-regression-A")
+	replace("strict-regression-A", b)
+	request := func(wantSuccess bool) {
+		raw, e := net.DialTimeout("tcp", a.addr, time.Second)
+		if e != nil {
+			t.Fatal(e)
+		}
+		defer raw.Close()
+		raw.SetDeadline(time.Now().Add(3 * time.Second))
+		opts := []connector.Option{connector.LoggerOption(log)}
+		if authenticated {
+			opts = append(opts, connector.AuthOption(url.UserPassword("A", "synthetic-local-password-for-A")))
+		}
+		client := relayconnector.NewConnector(opts...)
+		if e := client.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+			t.Fatal(e)
+		}
+		conn, e := client.Connect(ctx, raw, "tcp", target.Addr().String())
+		if !wantSuccess {
+			if e == nil {
+				conn.Close()
+				t.Fatal("relay connected through a missing required hop")
+			}
+			return
+		}
+		if e != nil {
+			t.Fatal(e)
+		}
+		if _, e = conn.Write([]byte("probe")); e != nil {
+			t.Fatal(e)
+		}
+		buf := make([]byte, 5)
+		if _, e = io.ReadFull(conn, buf); e != nil {
+			t.Fatal(e)
+		}
+		if string(buf) != "probe" {
+			t.Fatalf("bad response %q", buf)
+		}
+	}
+	request(true)
+	if b.count.Load() != 1 || c.count.Load() != 0 || d.count.Load() != 1 {
+		t.Fatalf("initial B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+	replace("strict-regression-B", c)
+	request(true)
+	if b.count.Load() != 2 || c.count.Load() != 1 || d.count.Load() != 2 {
+		t.Fatalf("insert C B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+	// Deterministic cleanup boundary: DeleteChains has completed, while the B
+	// relay service is still alive (before a subsequent DeleteService command).
+	registry.ChainRegistry().Unregister("strict-regression-B")
+	request(false)
+	if b.count.Load() != 3 || c.count.Load() != 1 || d.count.Load() != 2 {
+		t.Fatalf("missing chain B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+	t.Log("Required route refuses the missing B chain and recovers after replacement")
+	replace("strict-regression-B", c)
+	request(true)
+	if b.count.Load() != 4 || c.count.Load() != 2 || d.count.Load() != 3 {
+		t.Fatalf("restored B/C/D: %d/%d/%d", b.count.Load(), c.count.Load(), d.count.Load())
+	}
+}

go-gost/x/chain/required_relay_route_test.go

@@ -0,0 +1,100 @@
+package chain_test
+
+import (
+	"context"
+	"crypto/tls"
+	"io"
+	"net"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/go-gost/core/connector"
+	corelogger "github.com/go-gost/core/logger"
+	"github.com/go-gost/x/config"
+	"github.com/go-gost/x/config/parsing"
+	chainparser "github.com/go-gost/x/config/parsing/chain"
+	serviceparser "github.com/go-gost/x/config/parsing/service"
+	relayconnector "github.com/go-gost/x/connector/relay"
+	_ "github.com/go-gost/x/handler/relay"
+	_ "github.com/go-gost/x/listener/tcp"
+	xlogger "github.com/go-gost/x/logger"
+	"github.com/go-gost/x/metadata"
+	"github.com/go-gost/x/registry"
+)
+
+func TestRequiredRelayChainCannotDialTargetWhenMissing(t *testing.T) {
+	assertRequiredRelayCannotDial(t, "missing-required-chain", "tcp")
+}
+
+func TestRequiredRelayChainRejectsEmptySelectionAndAbsentConfiguration(t *testing.T) {
+	corelogger.SetDefault(xlogger.Nop())
+	const name = "empty-required-chain"
+	c, err := chainparser.ParseChain(&config.ChainConfig{Name: name, Hops: []*config.HopConfig{{Name: "empty-hop", Nodes: []*config.NodeConfig{}}}}, xlogger.Nop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := registry.ReplaceChain(name, c); err != nil {
+		t.Fatal(err)
+	}
+	defer registry.ChainRegistry().Unregister(name)
+	for _, network := range []string{"tcp", "udp"} {
+		for _, chainName := range []string{name, ""} {
+			t.Run(network+"/"+chainName, func(t *testing.T) { assertRequiredRelayCannotDial(t, chainName, network) })
+		}
+	}
+}
+
+func assertRequiredRelayCannotDial(t *testing.T, chainName, network string) {
+	t.Helper()
+	corelogger.SetDefault(xlogger.Nop())
+	previousTLS := parsing.DefaultTLSConfig()
+	parsing.SetDefaultTLSConfig(&tls.Config{})
+	defer parsing.SetDefaultTLSConfig(previousTLS)
+	target, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer target.Close()
+	var accepted atomic.Int32
+	go func() {
+		for {
+			c, e := target.Accept()
+			if e != nil {
+				return
+			}
+			accepted.Add(1)
+			c.Close()
+		}
+	}()
+	svc, err := serviceparser.ParseService(&config.ServiceConfig{Name: "required-route-regression", Addr: "127.0.0.1:0", Listener: &config.ListenerConfig{Type: "tcp"}, Handler: &config.HandlerConfig{Type: "relay", Chain: chainName, Metadata: map[string]any{"chain.strict": true, "nodelay": true}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan struct{})
+	go func() { defer close(done); svc.Serve() }()
+	defer func() { svc.Close(); <-done }()
+	raw, err := net.DialTimeout("tcp", svc.Addr().String(), time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer raw.Close()
+	raw.SetDeadline(time.Now().Add(3 * time.Second))
+	client := relayconnector.NewConnector(connector.LoggerOption(xlogger.Nop()))
+	if err := client.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); err != nil {
+		t.Fatal(err)
+	}
+	conn, err := client.Connect(context.Background(), raw, network, target.Addr().String())
+	if err == nil {
+		if conn != nil {
+			conn.Close()
+		}
+		t.Fatal("required chain is missing, but relay accepted a direct connection")
+	}
+	if accepted.Load() != 0 {
+		t.Fatalf("ultimate target received %d connections without the required chain", accepted.Load())
+	}
+	if closer, ok := client.(io.Closer); ok {
+		closer.Close()
+	}
+}

go-gost/x/chain/required_relay_transport_test.go

@@ -0,0 +1,196 @@
+package chain_test
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+
+	corechain "github.com/go-gost/core/chain"
+	"github.com/go-gost/core/connector"
+	"github.com/go-gost/core/dialer"
+	"github.com/go-gost/core/handler"
+	"github.com/go-gost/core/listener"
+	corelogger "github.com/go-gost/core/logger"
+	xauth "github.com/go-gost/x/auth"
+	xchain "github.com/go-gost/x/chain"
+	relayconnector "github.com/go-gost/x/connector/relay"
+	kcpdialer "github.com/go-gost/x/dialer/kcp"
+	relayhandler "github.com/go-gost/x/handler/relay"
+	netdialer "github.com/go-gost/x/internal/net/dialer"
+	kcplistener "github.com/go-gost/x/listener/kcp"
+	tcplistener "github.com/go-gost/x/listener/tcp"
+	tlslistener "github.com/go-gost/x/listener/tls"
+	xlogger "github.com/go-gost/x/logger"
+	"github.com/go-gost/x/metadata"
+)
+
+// Required intermediates reject missing chains on every supported transport.
+// Legitimate authenticated exits remain direct. All credentials and endpoints are local test data.
+func TestRequiredRelayRouteTransportMatrix(t *testing.T) {
+	log := xlogger.Nop()
+	corelogger.SetDefault(log)
+	certServer := httptest.NewTLSServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	cert := certServer.TLS.Certificates[0]
+	leaf := certServer.Certificate()
+	certServer.Close()
+	roots := x509.NewCertPool()
+	roots.AddCert(leaf)
+	tcpTarget, e := net.Listen("tcp", "127.0.0.1:0")
+	if e != nil {
+		t.Fatal(e)
+	}
+	defer tcpTarget.Close()
+	go func() {
+		for {
+			c, e := tcpTarget.Accept()
+			if e != nil {
+				return
+			}
+			go func() { defer c.Close(); io.Copy(c, c) }()
+		}
+	}()
+	udpTarget, e := net.ListenPacket("udp", "127.0.0.1:0")
+	if e != nil {
+		t.Fatal(e)
+	}
+	defer udpTarget.Close()
+	go func() {
+		buf := make([]byte, 1024)
+		for {
+			n, a, e := udpTarget.ReadFrom(buf)
+			if e != nil {
+				return
+			}
+			udpTarget.WriteTo(buf[:n], a)
+		}
+	}()
+	for _, transport := range []string{"tcp", "tls", "kcp"} {
+		for _, network := range []string{"tcp", "udp"} {
+			for _, test := range []struct {
+				name        string
+				required    bool
+				credentials *url.Userinfo
+				success     bool
+			}{
+				{"authenticated-exit", false, url.UserPassword("test-peer", "synthetic-test-secret"), true},
+				{"required-missing-chain", true, url.UserPassword("test-peer", "synthetic-test-secret"), false},
+			} {
+				t.Run(transport+"/"+network+"/"+test.name, func(t *testing.T) {
+					opts := []listener.Option{listener.AddrOption("127.0.0.1:0"), listener.LoggerOption(log), listener.TLSConfigOption(&tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS12})}
+					var ln listener.Listener
+					switch transport {
+					case "tls":
+						ln = tlslistener.NewListener(opts...)
+					case "kcp":
+						ln = kcplistener.NewListener(opts...)
+					default:
+						ln = tcplistener.NewListener(opts...)
+					}
+					md := metadata.NewMetadata(map[string]any{"kcp.tcp": false, "kcp.nocomp": true})
+					if e := ln.Init(md); e != nil {
+						t.Fatal(e)
+					}
+					defer ln.Close()
+					router := xchain.NewRouter(corechain.LoggerRouterOption(log))
+					if test.required {
+						router.WithRequiredChain()
+					}
+					hopts := []handler.Option{handler.RouterOption(router), handler.LoggerOption(log), handler.ServiceOption("strict-transport-regression")}
+					{
+						au := xauth.NewAuthenticator(xauth.AuthsOption(map[string]string{"test-peer": "synthetic-test-secret"}))
+						if closer, ok := au.(io.Closer); ok {
+							defer closer.Close()
+						}
+						hopts = append(hopts, handler.AutherOption(au))
+					}
+					h := relayhandler.NewHandler(hopts...)
+					if e := h.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+						t.Fatal(e)
+					}
+					if closer, ok := h.(io.Closer); ok {
+						defer closer.Close()
+					}
+					handled := make(chan struct{})
+					go func() {
+						defer close(handled)
+						c, e := ln.Accept()
+						if e == nil {
+							h.Handle(context.Background(), c)
+						}
+					}()
+					var raw net.Conn
+					var err error
+					switch transport {
+					case "tls":
+						raw, err = tls.DialWithDialer(&net.Dialer{Timeout: time.Second}, "tcp", ln.Addr().String(), &tls.Config{RootCAs: roots, MinVersion: tls.VersionTLS12})
+					case "kcp":
+						d := kcpdialer.NewDialer(dialer.LoggerOption(log))
+						if e := d.Init(md); e != nil {
+							t.Fatal(e)
+						}
+						if closer, ok := d.(io.Closer); ok {
+							defer closer.Close()
+						}
+						raw, err = d.Dial(context.Background(), ln.Addr().String(), dialer.NetDialerDialOption(&netdialer.Dialer{Logger: log}))
+					default:
+						raw, err = net.DialTimeout("tcp", ln.Addr().String(), time.Second)
+					}
+					if err != nil {
+						t.Fatal(err)
+					}
+					defer raw.Close()
+					raw.SetDeadline(time.Now().Add(5 * time.Second))
+					copts := []connector.Option{connector.LoggerOption(log)}
+					if test.credentials != nil {
+						copts = append(copts, connector.AuthOption(test.credentials))
+					}
+					client := relayconnector.NewConnector(copts...)
+					if e := client.Init(metadata.NewMetadata(map[string]any{"nodelay": true})); e != nil {
+						t.Fatal(e)
+					}
+					target := tcpTarget.Addr().String()
+					if network == "udp" {
+						target = udpTarget.LocalAddr().String()
+					}
+					conn, err := client.Connect(context.Background(), raw, network, target)
+					if !test.success {
+						if err == nil {
+							t.Fatal("required route missing but direct connection accepted")
+						}
+
+						raw.Close()
+						<-handled
+						return
+					}
+					if err != nil {
+						t.Fatal(err)
+					}
+					if _, err = conn.Write([]byte("probe")); err != nil {
+						t.Fatal(err)
+					}
+					b := make([]byte, 64)
+					n, err := conn.Read(b)
+					if err != nil {
+						t.Fatal(err)
+					}
+					if string(b[:n]) != "probe" {
+						t.Fatalf("unexpected response %q", b[:n])
+					}
+					raw.Close()
+					select {
+					case <-handled:
+					case <-time.After(5 * time.Second):
+						t.Fatal("handler did not close")
+					}
+				})
+			}
+		}
+	}
+}

go-gost/x/chain/router.go

@@ -15,7 +15,8 @@ import (
 )
 
 type Router struct {
-	options chain.RouterOptions
+	options      chain.RouterOptions
+	requireChain bool
 }
 
 func NewRouter(opts ...chain.RouterOption) *Router {
@@ -35,6 +36,13 @@ func NewRouter(opts ...chain.RouterOption) *Router {
 	return r
 }
 
+// WithRequiredChain disables direct fallback when an explicitly required chain
+// is absent or selects no route. Configure it before serving requests.
+func (r *Router) WithRequiredChain() *Router {
+	r.requireChain = true
+	return r
+}
+
 func (r *Router) Options() *chain.RouterOptions {
 	if r == nil {
 		return nil
@@ -117,6 +125,10 @@ func (r *Router) dial(ctx context.Context, network, address string, log logger.L
 			route = r.options.Chain.Route(ctx, network, ipAddr, chain.WithHostRouteOption(address))
 		}
 
+		if r.requireChain && (route == nil || len(route.Nodes()) == 0) {
+			return nil, ErrEmptyRoute
+		}
+
 		if buf == nil {
 			buf = &bytes.Buffer{}
 		}
@@ -164,6 +176,9 @@ func (r *Router) Bind(ctx context.Context, network, address string, opts ...chai
 			defer cancel()
 		}
 
+		if r.requireChain && r.options.Chain == nil {
+			return nil, ErrEmptyRoute
+		}
 		var route chain.Route
 		if r.options.Chain != nil {
 			route = r.options.Chain.Route(ctx, network, address)

go-gost/x/config/parsing/service/parse.go

@@ -327,10 +327,15 @@ func ParseService(cfg *config.ServiceConfig) (service.Service, error) {
 		)
 	}
 
+	handlerRouter := xchain.NewRouter(routerOpts...)
+	if mdutil.GetBool(metadata.NewMetadata(cfg.Handler.Metadata), "chain.strict") {
+		handlerRouter.WithRequiredChain()
+	}
+
 	var h handler.Handler
 	if rf := registry.HandlerRegistry().Get(cfg.Handler.Type); rf != nil {
 		h = rf(
-			handler.RouterOption(xchain.NewRouter(routerOpts...)),
+			handler.RouterOption(handlerRouter),
 			handler.AutherOption(auther),
 			handler.AuthOption(auth_parser.Info(cfg.Handler.Auth)),
 			handler.BypassOption(xbypass.BypassGroup(bypass_parser.List(cfg.Bypass, cfg.Bypasses...)...)),

go-gost/x/socket/agent_restart.go

@@ -0,0 +1,139 @@
+package socket
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+type agentServiceManager struct{ kind, control, runner string }
+
+// Alpine must never select a systemctl compatibility shim. Elsewhere prefer
+// an active systemd instance, matching the installer, then OpenRC.
+func detectAgentServiceManager(alpine, systemd bool, lookup func(string) (string, error)) (agentServiceManager, error) {
+	if !alpine && systemd {
+		control, err := lookup("systemctl")
+		if err != nil {
+			return agentServiceManager{}, fmt.Errorf("systemctl 不可用: %w", err)
+		}
+		runner, err := lookup("systemd-run")
+		if err != nil {
+			return agentServiceManager{}, fmt.Errorf("systemd-run 不可用: %w", err)
+		}
+		return agentServiceManager{kind: "systemd", control: control, runner: runner}, nil
+	}
+	control, err := lookup("rc-service")
+	if err != nil {
+		return agentServiceManager{}, fmt.Errorf("未检测到受支持的服务管理器 (systemd/OpenRC): %w", err)
+	}
+	return agentServiceManager{kind: "openrc", control: control}, nil
+}
+
+func (w *WebSocketReporter) agentRestartLauncher(cleanLegacy bool) (func(string, string) error, error) {
+	// Existing per-reporter seam is also used by checksum-only tests.
+	if w.startUpgradeRestart != nil {
+		return w.startUpgradeRestart, nil
+	}
+	detect := w.detectAgentManager
+	if detect == nil {
+		detect = func() (agentServiceManager, error) {
+			_, alpineErr := os.Stat("/etc/alpine-release")
+			_, systemdErr := os.Stat("/run/systemd/system")
+			return detectAgentServiceManager(alpineErr == nil, systemdErr == nil, exec.LookPath)
+		}
+	}
+	manager, err := detect()
+	if err != nil {
+		return nil, err
+	}
+	if manager.kind == "openrc" {
+		if err := checkAgentDetach(); err != nil {
+			return nil, err
+		}
+	}
+	return func(staged, binary string) error {
+		script := buildManagedAgentRestartScript(manager, staged, binary, cleanLegacy)
+		if manager.kind == "systemd" {
+			// Wait only for submission, never for helper completion. A separate unit is
+			// essential: systemctl stop kills every process in the agent's cgroup.
+			ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+			defer cancel()
+			out, err := exec.CommandContext(ctx, manager.runner, "--quiet", "/bin/sh", "-c", script).CombinedOutput()
+			if err != nil {
+				return fmt.Errorf("提交重启任务失败: %w: %s", err, strings.TrimSpace(string(out)))
+			}
+			return nil
+		}
+		return startDetachedAgentHelper(script)
+	}, nil
+}
+
+func shellQuote(value string) string { return "'" + strings.ReplaceAll(value, "'", "'\"'\"'") + "'" }
+
+func buildManagedAgentRestartScript(manager agentServiceManager, staged, binary string, cleanLegacy bool) string {
+	control := shellQuote(manager.control)
+	stop, start := control+" stop flux_agent", control+" start flux_agent"
+	if manager.kind == "openrc" {
+		stop, start = control+" flux_agent stop", control+" flux_agent start"
+	}
+	legacy := ""
+	if manager.kind == "systemd" && cleanLegacy {
+		legacy = `legacy_service=''; for service_file in /etc/systemd/system/gost.service /lib/systemd/system/gost.service /usr/lib/systemd/system/gost.service; do if [ -f "$service_file" ] && grep -Fq "WorkingDirectory=/etc/gost" "$service_file" && (grep -Fq "ExecStart=/etc/gost/gost" "$service_file" || (grep -Fq "ExecStart=/usr/local/bin/gost" "$service_file" && [ -f /etc/gost/config.json ] && [ -f /etc/gost/gost.json ])); then legacy_service="$service_file"; break; fi; done; if [ -n "$legacy_service" ]; then (` + control + ` stop gost 2>/dev/null || true); (` + control + ` disable gost 2>/dev/null || true); rm -f /usr/local/bin/gost /etc/gost/gost "$legacy_service"; (` + control + ` daemon-reload 2>/dev/null || true); fi; `
+	}
+	// The caller owns staging until launch. Afterwards the helper always removes
+	// it, including stop/replace failures. Never truncate the running executable.
+	return "trap " + shellQuote("rm -f -- "+shellQuote(staged)) + " EXIT; sleep 1; " + stop + " || exit $?; " + legacy +
+		"if [ ! -d " + shellQuote(binary) + " ] && mv -f -- " + shellQuote(staged) + " " + shellQuote(binary) + "; then " + start + "; else status=$?; " + start + "; exit \"$status\"; fi"
+}
+
+// Copy to a unique file on the destination filesystem, then let the caller
+// atomically rename. Failure never truncates a previous usable backup.
+func stageAgentCopy(source, destination string) (path string, err error) {
+	in, err := os.Open(source)
+	if err != nil {
+		return "", err
+	}
+	defer in.Close()
+	info, err := in.Stat()
+	if err != nil {
+		return "", err
+	}
+	if !info.Mode().IsRegular() {
+		return "", fmt.Errorf("不是普通文件: %s", source)
+	}
+	out, err := os.CreateTemp(filepath.Dir(destination), ".flux-agent-*")
+	if err != nil {
+		return "", err
+	}
+	path = out.Name()
+	defer func() {
+		out.Close()
+		if err != nil {
+			os.Remove(path)
+		}
+	}()
+	if _, err = io.Copy(out, in); err != nil {
+		return path, err
+	}
+	if err = out.Chmod(0755); err != nil {
+		return path, err
+	}
+	if err = out.Close(); err != nil {
+		return path, err
+	}
+	return path, nil
+}
+
+func backupAgentBinary(binary string) error {
+	staged, err := stageAgentCopy(binary, binary+".old")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(staged)
+	return os.Rename(staged, binary+".old")
+}

go-gost/x/socket/agent_restart_linux.go

@@ -0,0 +1,20 @@
+package socket
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+func checkAgentDetach() error { return nil }
+
+func startDetachedAgentHelper(script string) error {
+	cmd := exec.Command("/bin/sh", "-c", script)
+	// The installed OpenRC service stops the agent PID. A separate session also
+	// survives a process-group stop. No inherited stdio or parent-death signal.
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	go func() { _ = cmd.Wait() }()
+	return nil
+}

go-gost/x/socket/agent_restart_linux_test.go

@@ -0,0 +1,132 @@
+package socket
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// This subprocess stands in for the running agent. The rc-service double kills
+// its entire process group, not merely a fake PID, while the real helper runs.
+func TestAgentDetachedParent(t *testing.T) {
+	dir := os.Getenv("FLVX_TEST_DETACH_ROOT")
+	if dir == "" {
+		t.Skip("subprocess helper")
+	}
+	binary := filepath.Join(dir, "agent")
+	control := filepath.Join(dir, "rc-service")
+	writeAgentFixture(t, control, "#!/bin/sh\nif [ \"$2\" = stop ]; then kill -TERM -"+strconv.Itoa(os.Getpid())+"; else echo started > "+shellQuote(filepath.Join(dir, "started"))+"; fi\n")
+	reporter := &WebSocketReporter{upgradeBinaryPath: binary, detectAgentManager: func() (agentServiceManager, error) { return agentServiceManager{kind: "openrc", control: control}, nil }}
+	response := routeAgentOperation(t, reporter, "RollbackAgent", nil)
+	if !response.Success {
+		t.Fatal(response.Message)
+	}
+	time.Sleep(15 * time.Second)
+	t.Fatal("original agent was not stopped")
+}
+
+func TestOpenRCHelperSurvivesAgentProcessGroupStop(t *testing.T) {
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "agent")
+	writeAgentFixture(t, binary, "current")
+	writeAgentFixture(t, binary+".old", "backup")
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestAgentDetachedParent$", "-test.v")
+	cmd.Env = append(os.Environ(), "FLVX_TEST_DETACH_ROOT="+dir)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	output, err := cmd.CombinedOutput()
+	if err == nil || ctx.Err() != nil {
+		t.Fatalf("parent termination = %v, timeout=%v, %s", err, ctx.Err(), output)
+	}
+	exit, ok := err.(*exec.ExitError)
+	if !ok || exit.Sys().(syscall.WaitStatus).Signal() != syscall.SIGTERM {
+		t.Fatalf("parent did not receive SIGTERM: %v %s", err, output)
+	}
+	waitAgentFixture(t, filepath.Join(dir, "started"), "started\n")
+	if readAgentFixture(t, binary) != "backup" || readAgentFixture(t, binary+".old") != "backup" {
+		t.Fatal("rollback failed after parent termination")
+	}
+	fmt.Println("detached OpenRC helper survived original agent process-group SIGTERM")
+}
+
+// Run only in an explicitly opted-in disposable Alpine container. The docker
+// invocation mounts only the test binary, never a host /bin directory. Removing
+// the container's /bin/sh symlink forces the real detached cmd.Start to fail.
+func TestOpenRCCommandsCleanStageOnHelperExecFailure(t *testing.T) {
+	if os.Getenv("FLVX_TEST_DISPOSABLE_ALPINE_SHELL_FAILURE") != "1" {
+		t.Skip("requires explicit disposable Alpine container opt-in")
+	}
+	for _, path := range []string{"/etc/alpine-release", "/.dockerenv"} {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("refusing shell mutation outside disposable Alpine: %s: %v", path, err)
+		}
+	}
+	info, err := os.Lstat("/bin/sh")
+	if err != nil || info.Mode()&os.ModeSymlink == 0 {
+		t.Fatalf("refusing to rename a non-symlink /bin/sh: %v", err)
+	}
+	saved := "/bin/.flvx-test-sh-" + strconv.Itoa(os.Getpid())
+	if _, err := os.Lstat(saved); !os.IsNotExist(err) {
+		t.Fatalf("refusing to overwrite shell backup: %v", err)
+	}
+	if err := os.Rename("/bin/sh", saved); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		if err := os.Rename(saved, "/bin/sh"); err != nil {
+			t.Errorf("restore container shell: %v", err)
+		}
+	}()
+	for _, operation := range []string{"UpgradeAgent", "RollbackAgent"} {
+		t.Run(operation, func(t *testing.T) {
+			dir := t.TempDir()
+			binary := filepath.Join(dir, "agent")
+			writeAgentFixture(t, binary, "current")
+			writeAgentFixture(t, binary+".old", "prior backup")
+			writeAgentFixture(t, filepath.Join(dir, "rc-service"), "#!/bin/sh\nexit 0\n")
+			t.Setenv("PATH", dir)
+			// No manager or launcher injection: Alpine detection and exec.LookPath are
+			// production code too. Only the installation path points to an isolated dir.
+			reporter := &WebSocketReporter{upgradeBinaryPath: binary}
+			fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.URL.Path == "/checksum" {
+					fmt.Fprint(w, abcSHA256)
+				} else {
+					fmt.Fprint(w, "abc")
+				}
+			}))
+			defer fixture.Close()
+			response := routeAgentOperation(t, reporter, operation, map[string]string{"downloadUrl": fixture.URL + "/binary", "checksumUrl": fixture.URL + "/checksum"})
+			if response.Success || !strings.Contains(response.Message, "/bin/sh") || !strings.Contains(response.Message, "no such file") {
+				t.Fatalf("expected real helper exec failure, got %+v", response)
+			}
+			if readAgentFixture(t, binary) != "current" {
+				t.Fatal("live binary changed")
+			}
+			backup := "prior backup"
+			if operation == "UpgradeAgent" {
+				backup = "current"
+			}
+			if readAgentFixture(t, binary+".old") != backup {
+				t.Fatal("unexpected backup contents")
+			}
+			matches, err := filepath.Glob(filepath.Join(dir, ".flux-agent-*"))
+			if err != nil || len(matches) != 0 {
+				t.Fatalf("rollback staging residue: %v %v", matches, err)
+			}
+			if _, err := os.Stat(binary + ".new"); !os.IsNotExist(err) {
+				t.Fatalf("upgrade staging residue: %v", err)
+			}
+		})
+	}
+}

go-gost/x/socket/agent_restart_other.go

@@ -0,0 +1,8 @@
+//go:build !linux
+
+package socket
+
+import "fmt"
+
+func checkAgentDetach() error               { return fmt.Errorf("OpenRC Agent 重启仅支持 Linux") }
+func startDetachedAgentHelper(string) error { return checkAgentDetach() }

go-gost/x/socket/agent_restart_test.go

@@ -0,0 +1,329 @@
+package socket
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+func routeAgentOperation(t *testing.T, reporter *WebSocketReporter, operation string, data interface{}) CommandResponse {
+	t.Helper()
+	peer := make(chan *websocket.Conn, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		c, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err == nil {
+			peer <- c
+		}
+	}))
+	defer server.Close()
+	c, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http"), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close()
+	reader := <-peer
+	defer reader.Close()
+	reporter.ctx = context.Background()
+	reporter.conn = c
+	reporter.connected = true
+	reporter.routeCommand(CommandMessage{Type: operation, RequestId: "restart-request", Data: data})
+	reader.SetReadDeadline(time.Now().Add(3 * time.Second))
+	for {
+		var response CommandResponse
+		if err := reader.ReadJSON(&response); err != nil {
+			t.Fatal(err)
+		}
+		if response.Type == operation+"Response" {
+			if response.RequestId != "restart-request" {
+				t.Fatalf("request id lost: %s", response.RequestId)
+			}
+			return response
+		}
+	}
+}
+
+func TestRollbackAgentStagesBackupBeforeRestart(t *testing.T) {
+	binary := filepath.Join(t.TempDir(), "flux_agent")
+	for path, body := range map[string]string{binary: "current", binary + ".old": "backup"} {
+		if err := os.WriteFile(path, []byte(body), 0755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	called := false
+	reporter := &WebSocketReporter{upgradeBinaryPath: binary, startUpgradeRestart: func(staged, dest string) error {
+		called = true
+		body, err := os.ReadFile(staged)
+		if err != nil || string(body) != "backup" || staged == binary+".old" || dest != binary {
+			t.Fatalf("bad rollback staging: %s %s %q %v", staged, dest, body, err)
+		}
+		return os.Rename(staged, dest)
+	}}
+	response := routeAgentOperation(t, reporter, "RollbackAgent", nil)
+	if !response.Success || !called {
+		t.Fatalf("rollback failed: called=%v %s", called, response.Message)
+	}
+	body, err := os.ReadFile(binary + ".old")
+	if err != nil || string(body) != "backup" {
+		t.Fatalf("backup consumed: %q %v", body, err)
+	}
+}
+
+func TestAgentServiceManagerDetection(t *testing.T) {
+	for _, tc := range []struct {
+		name            string
+		alpine, systemd bool
+		tools           string
+		want            string
+	}{
+		{"alpine shim", true, true, "rc-service systemctl systemd-run", "openrc"},
+		{"alpine missing openrc", true, true, "systemctl systemd-run", ""},
+		{"systemd", false, true, "rc-service systemctl systemd-run", "systemd"},
+		{"missing runner", false, true, "systemctl", ""},
+		{"openrc fallback", false, false, "rc-service", "openrc"},
+		{"unmanaged", false, false, "systemctl systemd-run", ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			manager, err := detectAgentServiceManager(tc.alpine, tc.systemd, func(name string) (string, error) {
+				if strings.Contains(" "+tc.tools+" ", " "+name+" ") {
+					return name, nil
+				}
+				return "", os.ErrNotExist
+			})
+			if manager.kind != tc.want || (err != nil) != (tc.want == "") {
+				t.Fatalf("manager=%+v err=%v", manager, err)
+			}
+		})
+	}
+}
+
+func writeAgentFixture(t *testing.T, path, body string) {
+	t.Helper()
+	if err := os.WriteFile(path, []byte(body), 0755); err != nil {
+		t.Fatal(err)
+	}
+}
+func readAgentFixture(t *testing.T, path string) string {
+	t.Helper()
+	body, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(body)
+}
+func waitAgentFixture(t *testing.T, path, want string) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		body, _ := os.ReadFile(path)
+		if string(body) == want {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	body, _ := os.ReadFile(path)
+	t.Fatalf("%s = %q, want %q", path, body, want)
+}
+
+func TestAgentCommandsManagerLaunch(t *testing.T) {
+	for _, operation := range []string{"UpgradeAgent", "RollbackAgent"} {
+		for _, mode := range []string{"systemd", "openrc", "missing", "rejected"} {
+			t.Run(operation+"/"+mode, func(t *testing.T) {
+				if mode == "openrc" && runtime.GOOS != "linux" {
+					t.Skip("detached launcher is Linux-only")
+				}
+				dir := t.TempDir()
+				binary := filepath.Join(dir, "flux 'agent")
+				log := filepath.Join(dir, "events")
+				writeAgentFixture(t, binary, "current")
+				writeAgentFixture(t, binary+".old", "backup")
+				control := filepath.Join(dir, "manager")
+				writeAgentFixture(t, control, "#!/bin/sh\nprintf '%s\\n' \"$*\" >> "+shellQuote(log)+"\n")
+				runner := filepath.Join(dir, "runner")
+				writeAgentFixture(t, runner, "#!/bin/sh\nshift\n\"$@\" >/dev/null 2>&1 &\n")
+				if mode == "rejected" {
+					writeAgentFixture(t, runner, "#!/bin/sh\necho rejected >&2\nexit 9\n")
+				}
+				reporter := &WebSocketReporter{upgradeBinaryPath: binary, detectAgentManager: func() (agentServiceManager, error) {
+					return detectAgentServiceManager(mode == "openrc", mode != "missing", func(name string) (string, error) {
+						if mode == "missing" {
+							return "", os.ErrNotExist
+						}
+						if name == "systemd-run" {
+							return runner, nil
+						}
+						return control, nil
+					})
+				}}
+				fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					if r.URL.Path == "/checksum" {
+						fmt.Fprint(w, abcSHA256)
+					} else {
+						fmt.Fprint(w, "abc")
+					}
+				}))
+				defer fixture.Close()
+				response := routeAgentOperation(t, reporter, operation, map[string]string{"downloadUrl": fixture.URL + "/binary", "checksumUrl": fixture.URL + "/checksum"})
+				if mode == "missing" || mode == "rejected" {
+					if response.Success {
+						t.Fatal("accepted failed manager launch")
+					}
+					if readAgentFixture(t, binary) != "current" {
+						t.Fatal("live binary mutated")
+					}
+					if mode == "missing" && readAgentFixture(t, binary+".old") != "backup" {
+						t.Fatal("backup mutated before manager validation")
+					}
+					matches, _ := filepath.Glob(filepath.Join(dir, ".flux-agent-*"))
+					if len(matches) != 0 {
+						t.Fatalf("staging residue %v", matches)
+					}
+					if _, err := os.Stat(binary + ".new"); !os.IsNotExist(err) {
+						t.Fatal("upgrade residue")
+					}
+					return
+				}
+				if !response.Success {
+					t.Fatal(response.Message)
+				}
+				want, backup := "abc", "current"
+				if operation == "RollbackAgent" {
+					want, backup = "backup", "backup"
+				}
+				waitAgentFixture(t, binary, want)
+				events := "stop flux_agent\nstart flux_agent\n"
+				if mode == "openrc" {
+					events = "flux_agent stop\nflux_agent start\n"
+				}
+				waitAgentFixture(t, log, events)
+				if readAgentFixture(t, binary+".old") != backup {
+					t.Fatal("wrong backup")
+				}
+			})
+		}
+	}
+}
+
+func TestAgentRestartScriptFailureOrdering(t *testing.T) {
+	for _, mode := range []string{"stop", "replace"} {
+		t.Run(mode, func(t *testing.T) {
+			dir := t.TempDir()
+			binary := filepath.Join(dir, "agent")
+			staged := filepath.Join(dir, "staged")
+			log := filepath.Join(dir, "events")
+			writeAgentFixture(t, binary, "current")
+			writeAgentFixture(t, staged, "replacement")
+			control := filepath.Join(dir, "rc-service")
+			script := "#!/bin/sh\necho \"$*\" >> " + shellQuote(log) + "\n"
+			if mode == "stop" {
+				script += "[ \"$2\" != stop ]\n"
+			}
+			writeAgentFixture(t, control, script)
+			if mode == "replace" {
+				writeAgentFixture(t, filepath.Join(dir, "mv"), "#!/bin/sh\nexit 23\n")
+				t.Setenv("PATH", dir+":"+os.Getenv("PATH"))
+			}
+			cmd := exec.Command("/bin/sh", "-c", buildManagedAgentRestartScript(agentServiceManager{kind: "openrc", control: control}, staged, binary, true))
+			if err := cmd.Run(); err == nil {
+				t.Fatal("expected failed stop/replacement")
+			}
+			if readAgentFixture(t, binary) != "current" {
+				t.Fatal("changed binary after failure")
+			}
+			want := "flux_agent stop\n"
+			if mode == "replace" {
+				want += "flux_agent start\n"
+			}
+			if readAgentFixture(t, log) != want {
+				t.Fatalf("wrong sequence %q", readAgentFixture(t, log))
+			}
+			if _, err := os.Stat(staged); !os.IsNotExist(err) {
+				t.Fatal("staging residue")
+			}
+		})
+	}
+}
+
+func TestUpgradeAgentBackupFailurePreservesExistingBackup(t *testing.T) {
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "agent")
+	writeAgentFixture(t, binary+".old", "prior")
+	called := false
+	reporter := &WebSocketReporter{upgradeBinaryPath: binary, startUpgradeRestart: func(string, string) error { called = true; return nil }}
+	fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/checksum" {
+			fmt.Fprint(w, abcSHA256)
+		} else {
+			fmt.Fprint(w, "abc")
+		}
+	}))
+	defer fixture.Close()
+	response := routeAgentOperation(t, reporter, "UpgradeAgent", map[string]string{"downloadUrl": fixture.URL + "/binary", "checksumUrl": fixture.URL + "/checksum"})
+	if response.Success || called {
+		t.Fatal("upgrade accepted without backup")
+	}
+	if readAgentFixture(t, binary+".old") != "prior" {
+		t.Fatal("backup lost")
+	}
+	if _, err := os.Stat(binary + ".new"); !os.IsNotExist(err) {
+		t.Fatal("staging residue")
+	}
+}
+
+func TestRollbackAgentRejectsDirectoryDestination(t *testing.T) {
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "agent")
+	if err := os.Mkdir(binary, 0755); err != nil {
+		t.Fatal(err)
+	}
+	writeAgentFixture(t, binary+".old", "backup")
+	called := false
+	reporter := &WebSocketReporter{upgradeBinaryPath: binary, startUpgradeRestart: func(string, string) error { called = true; return nil }}
+	response := routeAgentOperation(t, reporter, "RollbackAgent", nil)
+	if response.Success || called {
+		t.Fatal("accepted directory destination")
+	}
+	if readAgentFixture(t, binary+".old") != "backup" {
+		t.Fatal("changed backup")
+	}
+	entries, err := os.ReadDir(binary)
+	if err != nil || len(entries) != 0 {
+		t.Fatalf("destination changed: %v %v", entries, err)
+	}
+}
+
+func TestAgentRestartScriptRejectsDirectoryDestination(t *testing.T) {
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "agent")
+	staged := filepath.Join(dir, "stage")
+	if err := os.Mkdir(binary, 0755); err != nil {
+		t.Fatal(err)
+	}
+	writeAgentFixture(t, staged, "replacement")
+	script := buildManagedAgentRestartScript(agentServiceManager{kind: "openrc", control: "/usr/bin/true"}, staged, binary, false)
+	if err := exec.Command("/bin/sh", "-c", script).Run(); err == nil {
+		t.Fatal("accepted directory destination")
+	}
+	entries, err := os.ReadDir(binary)
+	if err != nil || len(entries) != 0 {
+		t.Fatalf("binary moved inside directory: %v %v", entries, err)
+	}
+}
+
+func TestOpenRCRestartNeverCleansSystemdLegacyService(t *testing.T) {
+	script := buildManagedAgentRestartScript(agentServiceManager{kind: "openrc", control: "rc-service"}, "staged", "binary", true)
+	for _, forbidden := range []string{"systemctl", "gost", "daemon-reload", "/etc/systemd"} {
+		if strings.Contains(script, forbidden) {
+			t.Fatalf("OpenRC helper contains %s: %s", forbidden, script)
+		}
+	}
+}

go-gost/x/socket/upgrade_test.go

@@ -0,0 +1,198 @@
+package socket
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+// All writes are confined to TempDir; the restart callback never starts a process.
+func exerciseUpgrade(t *testing.T, checksum string, serveChecksum http.HandlerFunc, valid bool) {
+	t.Helper()
+	dir := t.TempDir()
+	binary := filepath.Join(dir, "flux_agent")
+	for path, body := range map[string]string{binary: "old binary", binary + ".old": "prior backup"} {
+		if err := os.WriteFile(path, []byte(body), 0700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	downloads := 0
+	fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/binary-"+runtime.GOARCH {
+			downloads++
+			fmt.Fprint(w, "abc")
+			return
+		}
+		if r.URL.Path != "/checksum-"+runtime.GOARCH {
+			t.Errorf("unexpected checksum path: %s", r.URL.Path)
+			http.NotFound(w, r)
+			return
+		}
+		serveChecksum(w, r)
+	}))
+	defer fixture.Close()
+	if checksum == "fixture" {
+		checksum = fixture.URL + "/checksum-{ARCH}"
+	}
+	peer := make(chan *websocket.Conn, 1)
+	ws := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		c, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err != nil {
+			return
+		}
+		peer <- c
+	}))
+	defer ws.Close()
+	conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(ws.URL, "http"), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	reader := <-peer
+	defer reader.Close()
+	restarted := false
+	reporter := &WebSocketReporter{ctx: context.Background(), conn: conn, connected: true, upgradeBinaryPath: binary,
+		startUpgradeRestart: func(staged, destination string) error {
+			restarted = true
+			if destination != binary {
+				t.Errorf("wrong restart destination: %s", destination)
+			}
+			b, e := os.ReadFile(staged)
+			if e != nil || string(b) != "abc" {
+				t.Errorf("staged binary = %q, %v", b, e)
+			}
+			return nil
+		},
+	}
+	reporter.routeCommand(CommandMessage{Type: "UpgradeAgent", RequestId: "upgrade-test-request", Data: map[string]any{"downloadUrl": fixture.URL + "/binary-{ARCH}", "checksumUrl": checksum}})
+	reader.SetReadDeadline(time.Now().Add(2 * time.Second))
+	verified, installing := false, false
+	for {
+		var response CommandResponse
+		if err := reader.ReadJSON(&response); err != nil {
+			t.Fatal(err)
+		}
+		if response.Type == "UpgradeAgentResponse" {
+			if response.RequestId != "upgrade-test-request" {
+				t.Errorf("response request ID = %q", response.RequestId)
+			}
+			if response.Success != valid {
+				t.Errorf("success = %v, want %v: %s", response.Success, valid, response.Message)
+			}
+			break
+		}
+		if response.Type == "UpgradeProgress" {
+			data := response.Data.(map[string]interface{})
+			if data["stage"] == "verifying" && data["percent"] == float64(100) {
+				verified = true
+			}
+			if data["stage"] == "installing" {
+				installing = true
+			}
+		}
+	}
+	if restarted != valid || verified != valid || installing != valid {
+		t.Errorf("restart=%v verified=%v installing=%v, want %v", restarted, verified, installing, valid)
+	}
+	b, e := os.ReadFile(binary)
+	if e != nil || string(b) != "old binary" {
+		t.Errorf("old binary changed: %q %v", b, e)
+	}
+	if !valid {
+		b, e = os.ReadFile(binary + ".old")
+		if e != nil || string(b) != "prior backup" {
+			t.Errorf("backup changed: %q %v", b, e)
+		}
+		if _, err := os.Stat(binary + ".new"); !os.IsNotExist(err) {
+			t.Errorf("staged binary remains: %v", err)
+		}
+	}
+	if strings.TrimSpace(checksum) == "" && downloads != 0 {
+		t.Errorf("downloaded without checksum URL")
+	}
+}
+
+func TestUpgradeAgentRequiresChecksumURL(t *testing.T) {
+	exerciseUpgrade(t, "", func(w http.ResponseWriter, r *http.Request) { t.Error("unexpected checksum request") }, false)
+}
+
+func TestUpgradeAgentRejectsChecksumHTTPFailure(t *testing.T) {
+	exerciseUpgrade(t, "fixture", func(w http.ResponseWriter, r *http.Request) { http.Error(w, "unavailable", http.StatusNotFound) }, false)
+}
+
+const abcSHA256 = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+
+func TestUpgradeAgentRejectsAmbiguousChecksum(t *testing.T) {
+	exerciseUpgrade(t, "fixture", func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, abcSHA256+"  gost-amd64\n"+abcSHA256+"  gost-arm64\n")
+	}, false)
+}
+
+func TestUpgradeAgentRejectsOversizedChecksum(t *testing.T) {
+	exerciseUpgrade(t, "fixture", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, abcSHA256+"  "+strings.Repeat("a", 4096)) }, false)
+}
+
+func TestUpgradeAgentChecksumRecords(t *testing.T) {
+	for _, tc := range []struct {
+		name, body string
+		valid      bool
+	}{
+		{"bare", abcSHA256, true},
+		{"GNU text", abcSHA256 + "  gost-arm64\n", true},
+		{"GNU binary", abcSHA256 + " *gost-arm64\n", true},
+		{"uppercase CRLF surrounding whitespace", " \t" + strings.ToUpper(abcSHA256) + "  gost-arm64\r\n", true},
+		{"bare surrounding whitespace", "\r\n\t" + abcSHA256 + " \r\n", true},
+		{"empty", "", false},
+		{"whitespace", " \r\n\t", false},
+		{"truncated", abcSHA256[:63], false},
+		{"nonhex", "z" + abcSHA256[1:], false},
+		{"mismatch", strings.Repeat("0", 64), false},
+		{"missing GNU marker", abcSHA256 + " gost-arm64", false},
+		{"invalid GNU marker", abcSHA256 + " ?gost-arm64", false},
+		{"missing filename", abcSHA256 + " *", false},
+		{"appended garbage", abcSHA256 + "garbage", false},
+		{"embedded CR", abcSHA256 + "  gost\rarm64", false},
+		{"NUL", abcSHA256 + "  gost\x00arm64", false},
+		{"two bare digests", abcSHA256 + "\n" + abcSHA256, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			exerciseUpgrade(t, "fixture", func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, tc.body) }, tc.valid)
+		})
+	}
+}
+
+func TestUpgradeAgentRejectsChecksumTransportFailure(t *testing.T) {
+	exerciseUpgrade(t, "://invalid", nil, false)
+}
+
+func TestUpgradeAgentRejectsChecksumReadFailure(t *testing.T) {
+	exerciseUpgrade(t, "fixture", func(w http.ResponseWriter, r *http.Request) {
+		// A valid-looking record is incomplete relative to the declared body length.
+		w.Header().Set("Content-Length", "999")
+		fmt.Fprint(w, abcSHA256)
+	}, false)
+}
+
+func TestUpgradeAgentRejectsBlankChecksumURL(t *testing.T) {
+	exerciseUpgrade(t, " \t\r\n", nil, false)
+}
+
+func TestUpgradeAgentRejectsChecksumConnectionFailure(t *testing.T) {
+	exerciseUpgrade(t, "fixture", func(w http.ResponseWriter, r *http.Request) {
+		conn, _, err := w.(http.Hijacker).Hijack()
+		if err != nil {
+			t.Error(err)
+			return
+		}
+		conn.Close()
+	}, false)
+}

go-gost/x/socket/websocket_reporter.go

@@ -14,7 +14,6 @@ import (
 	"net/http"
 	"net/url"
 	"os"
-	"os/exec"
 	"runtime"
 	"runtime/debug"
 	"strconv"
@@ -158,6 +157,11 @@ const (
 )
 
 type WebSocketReporter struct {
+	// Per-reporter upgrade dependencies keep staging and process launch isolated.
+	upgradeBinaryPath   string
+	startUpgradeRestart func(string, string) error
+	detectAgentManager  func() (agentServiceManager, error)
+
 	url               string
 	addr              string // 保存服务器地址
 	secret            string // 保存密钥
@@ -1377,6 +1381,23 @@ func (w *WebSocketReporter) sendUpgradeProgress(stage string, percent int, messa
 	w.sendResponse(response)
 }
 
+// parseUpgradeChecksum accepts one bare SHA256 or one GNU sha256sum record.
+// A manifest cannot safely identify the requested binary by its first record.
+func parseUpgradeChecksum(body []byte) (string, error) {
+	record := strings.TrimSpace(string(body))
+	if len(record) < 64 || strings.ContainsAny(record, "\r\n\x00") {
+		return "", fmt.Errorf("校验文件格式无效: 需要单条 SHA256 记录")
+	}
+	digest := record[:64]
+	if _, err := hex.DecodeString(digest); err != nil {
+		return "", fmt.Errorf("校验文件格式无效: SHA256 必须为 64 位十六进制")
+	}
+	if len(record) != 64 && (len(record) < 67 || record[64] != ' ' || (record[65] != ' ' && record[65] != '*') || strings.TrimSpace(record[66:]) == "") {
+		return "", fmt.Errorf("校验文件格式无效: 需要单条 GNU SHA256 记录")
+	}
+	return digest, nil
+}
+
 func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
 	jsonData, err := json.Marshal(data)
 	if err != nil {
@@ -1394,6 +1415,10 @@ func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
 		return fmt.Errorf("下载地址不能为空")
 	}
 
+	if strings.TrimSpace(req.ChecksumURL) == "" {
+		return fmt.Errorf("校验文件地址不能为空")
+	}
+
 	// 替换架构占位符
 	downloadURL := strings.ReplaceAll(req.DownloadURL, "{ARCH}", runtime.GOARCH)
 	checksumURL := strings.ReplaceAll(req.ChecksumURL, "{ARCH}", runtime.GOARCH)
@@ -1402,9 +1427,11 @@ func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
 	fmt.Printf("📦 开始下载升级包: %s\n", downloadURL)
 
 	// 下载新版本二进制
-	const binaryPath = "/etc/flux_agent/flux_agent"
+	binaryPath := w.upgradeBinaryPath
+	if binaryPath == "" {
+		binaryPath = "/etc/flux_agent/flux_agent"
+	}
 	tmpPath := binaryPath + ".new"
-	backupPath := binaryPath + ".old"
 
 	resp, err := http.Get(downloadURL)
 	if err != nil {
@@ -1421,6 +1448,14 @@ func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
 		return fmt.Errorf("创建临时文件失败: %v", err)
 	}
 
+	// The restart process owns the staged file only after launch succeeds.
+	restartStarted := false
+	defer func() {
+		if !restartStarted {
+			_ = os.Remove(tmpPath)
+		}
+	}()
+
 	// 带进度的下载
 	totalSize := resp.ContentLength
 	var downloaded int64
@@ -1433,7 +1468,6 @@ func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
 		if n > 0 {
 			if _, wErr := outFile.Write(buf[:n]); wErr != nil {
 				outFile.Close()
-				os.Remove(tmpPath)
 				return fmt.Errorf("写入升级包失败: %v", wErr)
 			}
 			hasher.Write(buf[:n])
@@ -1451,104 +1485,97 @@ func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
 				break
 			}
 			outFile.Close()
-			os.Remove(tmpPath)
 			return fmt.Errorf("读取升级包失败: %v", readErr)
 		}
 	}
-	outFile.Close()
+	if err := outFile.Close(); err != nil {
+		return fmt.Errorf("关闭升级包失败: %w", err)
+	}
 
 	if downloaded == 0 {
-		os.Remove(tmpPath)
 		return fmt.Errorf("下载的升级包为空")
 	}
 
 	w.sendUpgradeProgress("downloading", 100, fmt.Sprintf("下载完成 (%d bytes)", downloaded))
 
-	// Checksum 校验
-	if checksumURL != "" {
-		w.sendUpgradeProgress("verifying", 0, "校验文件完整性...")
-		checksumResp, err := http.Get(checksumURL)
-		if err == nil {
-			defer checksumResp.Body.Close()
-			if checksumResp.StatusCode == http.StatusOK {
-				checksumBody, err := io.ReadAll(checksumResp.Body)
-				if err == nil {
-					// 格式: "<hash>  <filename>" 或 "<hash>"
-					expectedHash := strings.TrimSpace(strings.Split(string(checksumBody), " ")[0])
-					actualHash := hex.EncodeToString(hasher.Sum(nil))
-					if !strings.EqualFold(expectedHash, actualHash) {
-						os.Remove(tmpPath)
-						return fmt.Errorf("校验失败: 期望 %s, 实际 %s", expectedHash, actualHash)
-					}
-					fmt.Printf("✅ Checksum 校验通过: %s\n", actualHash)
-				}
-			}
-		}
-		w.sendUpgradeProgress("verifying", 100, "校验通过")
+	// Every checksum failure must abort before installation.
+	w.sendUpgradeProgress("verifying", 0, "校验文件完整性...")
+	checksumResp, err := http.Get(checksumURL)
+	if err != nil {
+		return fmt.Errorf("下载校验文件失败: %w", err)
 	}
+	defer checksumResp.Body.Close()
+	if checksumResp.StatusCode != http.StatusOK {
+		return fmt.Errorf("下载校验文件失败, HTTP状态码: %d", checksumResp.StatusCode)
+	}
+	const maxChecksumBytes = 4096
+	checksumBody, err := io.ReadAll(io.LimitReader(checksumResp.Body, maxChecksumBytes+1))
+	if err != nil {
+		return fmt.Errorf("读取校验文件失败: %w", err)
+	}
+	if len(checksumBody) > maxChecksumBytes {
+		return fmt.Errorf("校验文件过大: 最大 %d bytes", maxChecksumBytes)
+	}
+	expectedHash, err := parseUpgradeChecksum(checksumBody)
+	if err != nil {
+		return err
+	}
+	actualHash := hex.EncodeToString(hasher.Sum(nil))
+	if !strings.EqualFold(expectedHash, actualHash) {
+		return fmt.Errorf("校验失败: 期望 %s, 实际 %s", expectedHash, actualHash)
+	}
+	w.sendUpgradeProgress("verifying", 100, "校验通过")
 
 	if err := os.Chmod(tmpPath, 0755); err != nil {
-		os.Remove(tmpPath)
 		return fmt.Errorf("设置执行权限失败: %v", err)
 	}
 
-	// 备份旧版本
-	w.sendUpgradeProgress("installing", 50, "备份旧版本...")
-	if _, err := os.Stat(binaryPath); err == nil {
-		// 复制旧文件作为备份（不用 rename，因为可能正在运行）
-		oldData, err := os.ReadFile(binaryPath)
-		if err == nil {
-			_ = os.WriteFile(backupPath, oldData, 0755)
-			fmt.Println("📦 旧版本已备份到", backupPath)
-		}
+	// Resolve the manager before mutating an existing rollback backup.
+	startRestart, err := w.agentRestartLauncher(true)
+	if err != nil {
+		return err
+	}
+	w.sendUpgradeProgress("installing", 50, "备份旧版本...")
+	if err := backupAgentBinary(binaryPath); err != nil {
+		return fmt.Errorf("备份旧版本失败: %w", err)
 	}
-
 	w.sendUpgradeProgress("installing", 80, "准备重启...")
-	fmt.Printf("✅ 升级包下载完成 (%d bytes), 准备重启...\n", downloaded)
-
-	// 执行重启脚本
-	// 使用 systemd-run 在独立的 transient unit 中运行重启脚本，
-	// 避免 systemctl stop 杀死 flux_agent cgroup 内所有进程（包括此脚本自身）导致 mv 未执行。
-	script := buildAgentRestartScript(tmpPath, binaryPath)
-	cmd := exec.Command("systemd-run", "--quiet", "/bin/sh", "-c", script)
-	if err := cmd.Start(); err != nil {
-		os.Remove(tmpPath)
+	if err := startRestart(tmpPath, binaryPath); err != nil {
 		return fmt.Errorf("启动重启脚本失败: %v", err)
 	}
 
+	restartStarted = true
 	w.sendUpgradeProgress("installing", 100, "重启中...")
 	fmt.Println("🔄 重启脚本已启动, Agent 将在 1 秒后重启...")
 	return nil
 }
 
 func (w *WebSocketReporter) handleRollbackAgent(data interface{}) error {
-	const binaryPath = "/etc/flux_agent/flux_agent"
-	backupPath := binaryPath + ".old"
-
-	// 检查备份文件是否存在
-	if _, err := os.Stat(backupPath); os.IsNotExist(err) {
-		return fmt.Errorf("没有可用的备份文件，无法回退")
+	binaryPath := w.upgradeBinaryPath
+	if binaryPath == "" {
+		binaryPath = "/etc/flux_agent/flux_agent"
 	}
-
-	fmt.Println("🔄 开始回退到旧版本...")
-
-	// 执行回退脚本（同升级逻辑，使用 systemd-run 避免 cgroup 问题）
-	script := fmt.Sprintf("sleep 1 && systemctl stop flux_agent && cp %s %s && systemctl start flux_agent", backupPath, binaryPath)
-	cmd := exec.Command("systemd-run", "--quiet", "/bin/sh", "-c", script)
-	if err := cmd.Start(); err != nil {
-		return fmt.Errorf("启动回退脚本失败: %v", err)
+	startRestart, err := w.agentRestartLauncher(false)
+	if err != nil {
+		return err
+	}
+	if info, err := os.Stat(binaryPath); err != nil || !info.Mode().IsRegular() {
+		return fmt.Errorf("回退目标不是可用的普通文件: %s", binaryPath)
+	}
+	staged, err := stageAgentCopy(binaryPath+".old", binaryPath)
+	if err != nil {
+		return fmt.Errorf("准备回退备份失败: %w", err)
+	}
+	if err := startRestart(staged, binaryPath); err != nil {
+		_ = os.Remove(staged)
+		return fmt.Errorf("启动回退脚本失败: %w", err)
 	}
-
 	fmt.Println("🔄 回退脚本已启动, Agent 将在 1 秒后重启...")
 	return nil
 }
 
 func buildAgentRestartScript(tmpPath, binaryPath string) string {
-	return fmt.Sprintf(
-		"sleep 1 && systemctl stop flux_agent && legacy_service='' && for service_file in /etc/systemd/system/gost.service /lib/systemd/system/gost.service /usr/lib/systemd/system/gost.service; do if [ -f \"$service_file\" ] && grep -Fq \"WorkingDirectory=/etc/gost\" \"$service_file\" && (grep -Fq \"ExecStart=/etc/gost/gost\" \"$service_file\" || (grep -Fq \"ExecStart=/usr/local/bin/gost\" \"$service_file\" && [ -f /etc/gost/config.json ] && [ -f /etc/gost/gost.json ])); then legacy_service=\"$service_file\"; break; fi; done && if [ -n \"$legacy_service\" ]; then (systemctl stop gost 2>/dev/null || true) && (systemctl disable gost 2>/dev/null || true) && rm -f /usr/local/bin/gost /etc/gost/gost \"$legacy_service\" && (systemctl daemon-reload 2>/dev/null || true); fi && mv %s %s && systemctl start flux_agent",
-		tmpPath,
-		binaryPath,
-	)
+	return buildManagedAgentRestartScript(agentServiceManager{kind: "systemd", control: "systemctl"}, tmpPath, binaryPath, true)
 }
 
 // updateLocalConfigJSON 将 http/tls/socks 写入工作目录下的 config.json

go-gost/x/socket/websocket_reporter_test.go

@@ -186,16 +186,16 @@ func TestFormatWebSocketDialErrorIncludesHTTPStatus(t *testing.T) {
 func TestAgentUpgradeRestartScriptStopsLegacyGostService(t *testing.T) {
 	script := buildAgentRestartScript("/tmp/flux_agent.new", "/etc/flux_agent/flux_agent")
 
-	if !strings.Contains(script, "systemctl stop flux_agent") {
+	if !strings.Contains(script, "'systemctl' stop flux_agent") {
 		t.Fatalf("expected script to stop flux_agent, got %s", script)
 	}
-	if !strings.Contains(script, "mv /tmp/flux_agent.new /etc/flux_agent/flux_agent") {
+	if !strings.Contains(script, "mv -f -- '/tmp/flux_agent.new' '/etc/flux_agent/flux_agent'") {
 		t.Fatalf("expected script to replace the flux_agent binary, got %s", script)
 	}
-	if !strings.Contains(script, "systemctl stop gost") {
+	if !strings.Contains(script, "'systemctl' stop gost") {
 		t.Fatalf("expected script to stop the legacy gost service, got %s", script)
 	}
-	if !strings.Contains(script, "systemctl disable gost") {
+	if !strings.Contains(script, "'systemctl' disable gost") {
 		t.Fatalf("expected script to disable the legacy gost service, got %s", script)
 	}
 	if !strings.Contains(script, "rm -f /usr/local/bin/gost") {
@@ -204,7 +204,7 @@ func TestAgentUpgradeRestartScriptStopsLegacyGostService(t *testing.T) {
 	if !strings.Contains(script, "WorkingDirectory=/etc/gost") {
 		t.Fatalf("expected script to scope cleanup to the legacy FLVX gost service definition, got %s", script)
 	}
-	if !strings.Contains(script, "systemctl start flux_agent") {
+	if !strings.Contains(script, "'systemctl' start flux_agent") {
 		t.Fatalf("expected script to restart flux_agent, got %s", script)
 	}
 	if strings.Contains(script, "systemctl stop flux_agent && systemctl stop gost 2>/dev/null || true") {

plans/070-relay-auth-and-required-route-security.md

@@ -0,0 +1,159 @@
+# Relay authentication and required-route security repair
+
+Status: implementation, two-axis review and local integrated validation complete. Remote CI must pass before the authorized merge and release. Approved initial review base: 3549fe5; upstream rc7 is preserved.
+Base inspected: 3549fe5 (existing checkout); existing investigation tests are preserved.
+Workflow: installed Matt Pocock skills 1.3.2, diagnosing-bugs → TDD → code-review. The owner subsequently authorized PR submission, merge and the next release tag after review.
+
+## Problems and evidence
+
+1. Local and federated relay services and connectors are emitted without authentication. Native TCP, TLS, and KCP listener tests with both TCP and UDP destinations confirm unauthenticated forwarding. Existing authenticator support rejects absent/wrong credentials and permits correct credentials. TLS encryption alone does not authenticate clients.
+2. A named chain missing at runtime produces a nil route, and an empty selected route also falls back to direct dialing. The loopback A–B–D → A–B–C–D test confirms that removing only B's chain permits A–B–target. A gated backend test confirms the live-service/missing-chain interval during redeployment overlaps topology editing. This is a demonstrated trigger, not proof of the reported production incident.
+3. TLS client generation defaults to unverified server identity. KCP defaults are public, not unique deployment credentials. Authentication must not be advertised as protected against credential interception without addressing transport trust.
+
+## Scope and safety
+
+- Keep work in the existing checkout, preserve all local changes, and add no dependencies or infrastructure without asking.
+- Do not mutate live production configuration or create production credentials. The owner subsequently authorized committing, pushing a PR, merging after checks, and publishing the next release tag through the existing workflow.
+- Existing production topology and agent versions are unknown. All tests use temporary databases and loopback endpoints.
+- Investigations characterize insecure behavior; permanent regression tests must assert desired secure behavior without deleting the historical evidence.
+
+## Confirmed test seams
+
+1. Panel HTTP and agent/federation command interfaces: generated authentication and strict-route policy, persistence, migration/reconnect, and serialized topology transitions. Use temporary repository storage and mock external node connections; do not test private helper implementation shapes.
+2. Native GOST service/config and relay data interfaces: TCP/TLS/KCP carrying TCP/UDP, absent/wrong/correct credentials, required-route disappearance/empty selection, recovery, and legitimate exit direct dialing. Use local real sockets and public parsing/registry interfaces.
+
+## Vertical implementation slices
+
+1. Required-route invariant: explicit FLVX intermediate-route policy fails closed for missing or empty routes; ordinary direct exits remain valid. Do not globally redefine every GOST bypass/empty-route behavior. First write a failing behavioral test, make the minimal change, then verify recovery and transport variants.
+2. Runtime lifecycle: serialize operations for the same tunnel; replace chains without delete/recreate gaps when possible. Avoid stale redeploy snapshots overwriting newer edits. Check create/update/redeploy/delete and failover owner paths. Do not hold a database transaction while awaiting node acknowledgements.
+3. Authentication model and persistence: define a single runtime-auth contract usable by local and federation generation. Credentials must be purpose-separated from node management secrets, nonempty, stable across normal resync, absent from public list responses/logs, and fail safely on malformed or unavailable state.
+4. Compatibility/migration: verify the exact old/new capability contract. Where staged migration is needed, teach all authorized upstream connectors before enforcing receiver auth, and expose incomplete migration rather than silently claim protection. Do not silently fall back to anonymous mode on an error. Validate restart, reconnect, edits, sharing and rollback.
+5. Transport trust: use verified encryption for reusable credentials; evaluate how existing raw TCP/KCP configurations can migrate without pretending public defaults are authentication. Any unresolvable product decision or component addition must be raised before implementation.
+6. Final validation and two-axis review: focused red/green evidence, race tests, relevant full module suites/build/vet, standards review and spec coverage review. Document blocked PostgreSQL/production checks separately.
+
+## Candidate decisions requiring research
+
+- Best credential storage granularity: tunnel listener/binding vs per-node identity; federation must carry the correct receiving identity without exposing management keys.
+- Existing schema/API compatibility and capability reporting; no assumption that old agent/remote panel versions accept new required fields.
+- Opt-in strict-route metadata protects FLVX-specific invariants while preserving generic GOST use; missing policy support on old agents must be visible.
+- Safest no-new-component authenticated transport plan and handling of legacy unencrypted TCP.
+
+## Completion conditions
+
+- An unauthenticated relay client cannot use newly secured local/federated endpoints; wrong credentials are rejected and authorized forwarding works.
+- Missing a required chain cannot connect directly to the ultimate target; restored chains resume the intended path.
+- Editing and redeploying the same tunnel cannot leave a stale or partially rebuilt runtime presented as successful.
+- No production-side actions or new external dependencies are introduced. Limitations and remaining migration steps are explicit.
+
+## Authentication implementation decision (confirmed test seams)
+
+The owner confirmed both seams. New relay tunnels require endpoint-scoped relay
+credentials; existing rows remain explicitly `legacy` in the tunnel list API.
+No reconnect automatically migrates an existing tunnel. This is an auth-only
+repair against anonymous relay abuse, not protection against interception: TCP,
+unverified relay TLS, public-default KCP and HTTP/WS control-plane paths retain
+transport confidentiality limitations. We do not silently change those protocols.
+
+Persist independent credentials per tunnel/receiving node/role, never reuse
+management/share tokens, and fail on RNG failure. Credentials survive reconnect,
+best-exit ordering and edits. Missing required credentials fail closed. New
+federation provisioning requires an explicit auth-version capability and apply
+acknowledgment; authenticated runtimes reject legacy reapply. Credentials are
+excluded from ordinary public DTOs. Backups without the security state must not
+be represented as protected after restoration; migration/credential backup and
+rotation require a later explicit maintenance workflow.
+
+Legacy live migration is not automatic in this patch. A future explicit migration
+must coordinate all upstreams and receivers in a maintenance cutover, persist
+progress, and never report protection before all acknowledgments. Existing legacy
+tunnels remain unprotected until that work is completed. No production credentials
+or configuration are generated by this local development task.
+
+## Validation and release boundaries
+
+Implemented required-route behavior is opt-in handler metadata `chain.strict`.
+The panel emits it for tunnel entry forwards and relay intermediates; direct
+exits do not set it. A new agent build is required: existing binaries can ignore
+unknown metadata. A panel command acknowledgment alone is not proof that an
+unknown older binary enforces this policy.
+
+The runtime lock serializes operations within one panel process; it is not a
+distributed transaction or a cross-panel lock. Updating desired topology and
+applying it to multiple nodes still permits partial failure. Errors must remain
+visible, and a later explicit resync may be needed. No claim is made that old
+connections switch route atomically during an edit.
+
+Before a production rollout, back up the database, deploy matching agent builds,
+test a small explicitly selected tunnel, then deploy the panel using a planned
+maintenance window. The local implementation task does not perform these steps.
+Existing legacy tunnels require a separately designed, explicitly initiated
+credential migration. Required auth is a policy, not proof of every live
+receiver's current enforcement.
+
+Validation completed so far:
+- Public parsed-service missing/empty/no-chain rejection and restored A–B–C–D
+  forwarding: race repeated passes.
+- Native TCP/TLS/KCP carrying TCP/UDP: required missing route rejects and
+  authenticated direct exit works; race repeated three times.
+- Panel forward-create commands emit strict policy only for type-2 tunnel
+  forwards, preserving ordinary direct forwards; race repeated three times.
+- go-gost/x: complete `go test ./...` and `go vet ./...` passed.
+- go-gost: complete `go test ./...` passed, including agent lifecycle tests.
+
+PostgreSQL behavior and deployment compatibility need separate verification;
+no production endpoint was used. The test TLS certificate is verified but is
+not evidence that generated production TLS configurations validate peers.
+
+### Final identity and recovery details
+
+The stable credential key is tunnel + receiving node + role, NOT hop index:
+inserting a hop ahead of an existing receiver must preserve its password. A
+direct tunnel converted to a relay tunnel is a new protected relay deployment;
+converting back does not erase required mode or credentials. Existing relay
+legacy rows are unchanged and listed as `relayAuthMode: legacy`. Required means
+configuration policy, not proof of deployment or old-agent capability.
+
+Both consumer policy and provider authentication version are persisted separately
+from private credentials. Missing credentials fail closed on update/reconnect;
+ordinary reapply cannot rotate or remove established authentication. Config
+exports retain the required policy but omit credentials. Config imports of
+protected tunnels (or over existing protected rows) are explicitly rejected with
+an explanation to use full-database recovery. Secure configuration-only credential
+export/import and rotation are not implemented. Full database backups contain
+private credentials and must be protected as secrets.
+
+The federation provider advertises auth version 1 on connect/reserve and
+acknowledges it on apply. Consumers preflight before reservation and before
+tearing down update resources. This is panel capability negotiation; unknown
+old local agents are not remotely attested by this patch. The new strict-route
+metadata requires the patched agent, and an old agent can ignore it. Deployment
+must upgrade the participating agents before claiming the required-route fix.
+
+Log audit: normal agent service/node parsing logs metadata and relay usernames,
+not the `auth` password fields. The backend's GORM logger is Silent. Authenticated
+federation apply errors suppress peer-supplied response text to avoid reflected
+credential disclosure. Private provider incoming credentials and downstream
+Target JSON are excluded from whole-model JSON serialization. Authentication
+still resides in desired-state database/agent configuration; this is not an
+at-rest encryption feature.
+
+Downgrading the panel to an older build is not a safe rollback for protected
+tunnels: older generation code can omit authentication and overwrite receiver
+configuration. Preserve the full security-aware database and deploy compatible
+panel/agent versions together. Any rollback or old-tunnel migration needs an
+explicit maintenance plan and validation of the live receiver, not only API
+policy fields.
+
+## Final lifecycle guarantees and limits
+
+Creation reserves prepared topology and local ports before waiting for remote
+acknowledgments. Create/update report saved-but-pending outcomes explicitly,
+including a frontend warning. Obsolete runtime ownership persists until cleanup
+is acknowledged, even after desired topology or tunnel deletion. Unconfirmed
+receiver ports remain reserved. Re-added resources and middle-to-exit role
+changes cannot lose a required chain before receiver replacement acknowledgment.
+
+This still does not provide distributed atomic topology cutover. During pending
+application, old paths or established connections can remain. Upgrade agents,
+resynchronize their configurations, and verify required-route policy is active
+before claiming the deployed protection.

plans/071-agent-upgrade-checksum-fail-closed.md

@@ -0,0 +1,27 @@
+# Agent upgrade checksum fail-closed
+
+## Scope
+
+Fix the panel-issued UpgradeAgent flow only. Do not change Alpine support, installer scripts, release artifacts, production state, or publish changes.
+
+## Observed defect
+
+`handleUpgradeAgent` treats checksum fetch errors, non-200 responses and body read errors as success and emits `校验通过`. An absent checksum URL bypasses verification entirely. The panel already supplies a checksum URL for individual and batch upgrades, and the release workflow generates GNU sha256sum files.
+
+## Intended behavior
+
+- Require a nonblank checksum URL before downloading an upgrade.
+- Abort before chmod, backup, or restart on fetch/status/read/format/hash failure; remove the staged binary.
+- Only emit verification success after a complete, valid SHA256 record matches the downloaded bytes.
+- Accept one bare 64-hex SHA256 or a single GNU sha256sum record (text or binary marker), case-insensitive hex and surrounding whitespace/CRLF. Reject empty, truncated, nonhex, multiline and oversized payloads. Do not treat an ambiguous multi-file manifest as a checksum.
+- Preserve architecture substitution and current installation flow. This is integrity checking, not a signature or an independent guarantee against a compromised download source.
+
+## Verification plan
+
+User-confirmed seam: actual UpgradeAgent command handling, loopback HTTP fixtures, isolated binary paths and an intercepted restart action. Assert error/response and progress, untouched old executable/backup, absence of staged bytes and no restart on every invalid checksum condition. Valid records should reach the intercepted restart with exact downloaded bytes.
+
+Use red-green slices, then race tests, module checks, build and independent scope review. No push, PR, merge, tag or deployment is authorized for this task.
+
+## Review scope
+
+User confirmed review against rc8 commit `fadc2b6c122df99140e0c9cbd481a1214d17d175`, covering all changes for this task and this plan. Run independent Standards and Spec reviews after the implementation is ready.

plans/072-agent-openrc-upgrade-rollback.md

@@ -0,0 +1,29 @@
+# Agent panel upgrade and rollback on OpenRC
+
+## Scope
+
+Repair the agent UpgradeAgent/RollbackAgent paths on Alpine/OpenRC without regressing systemd. Preserve the pending checksum fail-closed repair. Do not change live nodes, install components, publish or deploy.
+
+## Evidence
+
+In a disposable cached Alpine 3.22.5 linux/amd64 container, the actual handlers fail launching `systemd-run` after successful download and verification, and also when rolling back an existing backup. Installer scripts already support OpenRC, but their CI does not exercise these command handlers.
+
+## Safety requirements
+
+- Prefer OpenRC on Alpine, including when a systemctl shim exists; refuse missing required manager tools.
+- Keep systemd's independent transient unit behavior to survive stopping the agent cgroup.
+- Launch an independent OpenRC restart helper that survives termination of the original agent, without installing extra utilities.
+- Use the selected manager for stop/start; do not run systemd legacy-service cleanup on OpenRC.
+- Retain validated upgrade staging and backup behavior, and do not consume the rollback backup.
+- Reject setup/launch errors before claiming restart was launched. Report asynchronous-completion limits honestly.
+- Preserve existing command response, request ID and progress contracts.
+
+## Proposed tests and review
+
+User-confirmed boundaries: real UpgradeAgent/RollbackAgent command routing, isolated files, systemd/OpenRC tools as test doubles, no-manager rejection and launch/stop/replacement failures. Use cached Alpine to execute the helper with rc-service doubles, not a real OpenRC installation. Explicitly distinguish this from service-manager integration testing.
+
+User-confirmed review baseline is fadc2b6, covering both pending fixes and plans. No commits, push, PR, merge, release or deployment.
+
+## Publication authorization
+
+After the local implementation, verification and independent reviews were complete, the user authorized submitting a PR, merging if checks pass, and publishing the next tag. Earlier no-publication limits above describe the implementation phase. Deployment to live nodes remains outside scope.

plans/evidence/070-code-review.md

@@ -0,0 +1,73 @@
+# Two-axis review
+
+Fixed base: 3549fe5ad8a6e9b863b3e4f7b9bf738facff87ee plus all task working-tree
+changes, including new files. The owner approved this scope and subsequently
+authorized PR submission, merge and the next release tag. Initial review was
+performed as independent Standards and Spec passes.
+
+## Standards
+
+No new hard violations found against applicable AGENTS.md rules. Repository
+access, explicit table names, migrations, response envelopes and agent extension
+boundaries comply.
+
+Two non-blocking judgement calls:
+1. Possible duplicated code: required_relay_transport_test.go repeats the native
+   TCP/TLS/KCP fixture in relay_auth_matrix_investigation_test.go. The historical
+   investigation fixture is deliberately retained separately in this patch, to
+   preserve the original evidence; helper extraction is deferred.
+2. Possible speculative generality: buildFederationServiceConfig accepted a
+   variadic credential argument but only used its first item. Fixed by accepting
+   one nullable credential pointer, updating legacy callers explicitly. Focused
+   generator and federation authentication tests pass.
+
+Summary: zero hard violations; two low-priority smells, one corrected and one
+explicitly deferred.
+
+## Spec
+
+Three partial requirements found:
+1. Create did not take the lifecycle lock, committing a visible tunnel before
+   runtime application. Concurrent delete/edit/reconnect could interleave with
+   stale creation. This violated the create/update/redeploy/delete scope.
+2. Federated create held an open database transaction across provider/node
+   acknowledgments, contrary to the no-network-wait-in-transaction requirement.
+3. Offline/timeouts and forward synchronization failures could be swallowed as
+   success, contrary to the requirement to expose partial application.
+
+These were inherited behaviors within the explicitly promised repair scope,
+not regressions introduced by the patch. No additional confirmed auth or
+strict-route defect, and no unjustified scope creep found. Explicit legacy,
+transport, old-agent and distributed-rollback limits remain documented.
+
+Summary: three lifecycle completion gaps, all assigned for correction before
+publication. Follow-up verification will be appended after the fixes.
+
+## Review-driven recovery additions
+
+Follow-up inspection found two additional lifecycle issues during the transaction
+and pending-state changes: local port reservations must be published before the
+remote acknowledgment wait, and pending updates must still clean obsolete
+runtime and reconcile forwards. Both have focused regressions.
+
+A cleanup failure must not discard the removed runtime's ownership. Persistent
+cleanup records are being added in the existing database so retries can identify
+old endpoints even after desired topology changes. Records are removed only after
+acknowledgment and are canceled if current desired topology needs the resource
+again. This is targeted cleanup recovery, not distributed transaction rollback.
+
+## Final follow-up
+
+Final code commit: 89a1a7b, integrated on rc7 (46bfb86).
+All reported correctness/completion gaps were corrected. Durable cleanup keeps
+port reservations, survives topology/tunnel deletion, and is retried through
+existing maintenance and reconnect paths. Re-adding a receiver cannot cause a
+delayed deletion, and changing its port does not free the old port before ACK.
+The additional middle-to-exit role transition preserves the old chain until
+receiver replacement is acknowledged, for both same and changed ports.
+
+Standards: no hard violations remain; one fixture-duplication smell is deferred.
+Spec: no remaining release blocker found in the reviewed scope.
+The final full backend race run passed (excluding the documented external
+Cloudflare test). Frontend build/typecheck, GOST x race/vet, agent tests/build/vet
+and backend build/vet passed. Publication remains conditional on remote CI.

plans/evidence/070-final-validation.md

@@ -0,0 +1,53 @@
+# Final local validation
+
+Local darwin/arm64 checkout, initial baseline 3549fe5; final integration includes upstream rc7 (46bfb86); 2026-11-08.
+Go toolchain inside all modules: 1.26.10. No dependencies installed.
+No production configuration was changed. Publication is authorized after review and CI.
+
+## Final commands
+- go-backend: go test -race ./... -skip '^TestCaptchaVerifyLoginContract$'
+  PASS on the final code at 89a1a7b. Handler 140.273s; contract 110.907s. This includes upstream user-disable regressions.
+- go-backend: go vet ./... and go build ./cmd/paneld
+  PASS; executable output was directed to /tmp, not the repository.
+- go-gost/x: go test -race ./... and go vet ./...
+  PASS, including authenticated A–B–C–D transition/rejection/recovery.
+- go-gost: go test ./..., go vet ./..., go build .
+  PASS; executable output was directed to /tmp.
+- git diff --check: PASS.
+
+## Test-environment adjustments
+Two pre-existing federation cache-fallback tests formerly relied on external
+unreachable.invalid and peer.example requests failing. They now use loopback
+httptest providers returning HTTP 503, preserving the fallback assertions.
+The existing TestCaptchaVerifyLoginContract makes a real Cloudflare verification
+request; it was excluded, not reported as passing. No external access restriction
+was bypassed.
+
+The broad race run exposed a pre-existing test-fixture GORM Update callback
+registration racing WebSocket teardown's node-status update. Test setup now
+registers those callbacks before WebSocket startup, with atomic flags for failure
+injection. Two matching fixture tests passed with race detection repeated three
+times, followed by the passing full backend race run above. Production behavior
+was not changed for this fixture repair.
+
+FLVX_POSTGRES_TEST_DSN is absent; PostgreSQL execution was not verified.
+Three original investigation test files remain. The old bug-expecting gated test
+is skipped and its complete original source preserved in the evidence directory.
+
+## Review status and operational limits
+The approved two-axis review is complete. Standards found no hard violations;
+one fixture-duplication judgement call remains explicitly deferred. Spec
+follow-up at 89a1a7b found no remaining blocker in the reviewed scope after the
+create, pending, reservation, durable-cleanup and role-transition fixes.
+Review details are in 070-code-review.md.
+
+This local patch does not secure existing production listeners by itself.
+Existing legacy tunnels remain unauthenticated until a separately initiated
+migration is implemented and performed. Required is a policy, not runtime
+attestation. Agents must support chain.strict, protected tunnels require full
+database recovery rather than credential-free configuration restore, and older
+panel rollback can reintroduce anonymous receivers. The patch does not provide
+cross-node transactional rollback or fix transport confidentiality.
+
+Frontend TypeScript and production/PWA build passed after rc7 integration using
+the existing Node 24.22.1 runtime. No dependency install or engine bypass.

plans/evidence/070-relay-auth-validation.md

@@ -0,0 +1,58 @@
+# Relay authentication validation
+
+Local darwin/arm64 checkout, base 3549fe5. No deploy/push/release or production
+credentials. Three pre-existing investigation tests were preserved.
+
+## Confirmed seam
+
+Panel HTTP plus node/federation commands, using temporary SQLite repositories,
+loopback HTTP/WebSocket peers, and captured command data. Native data-plane auth
+matrix is recorded separately in the required-route validation evidence.
+
+## Vertical regression evidence
+
+- New local tunnel: observed failure because generated relay connector/receiver
+  authentication was absent; implemented purpose-separated endpoint credentials.
+- Required tunnel configuration export: observed missing authentication-policy
+  marker; exported marker added, credentials remain excluded. Configuration
+  restore of protected tunnels explicitly rejects missing private state.
+- Federation reserve/apply: observed missing capability advertisement; added
+  versioned contract, receiver authentication, persistent state, and no-downgrade.
+- Full dual-panel middle/exit tunnel: observed zero authenticated receivers;
+  threaded receiving and next-target credentials through consumer requests.
+- Federation strict middle policy: observed absent chain.strict; local and
+  federation middle generators now set it while exits retain direct dialing.
+- Insert a new middle before an existing middle: observed rejected update with
+  hop-index credentials; receiver identity changed to tunnel/node/role, preserving
+  the existing credential and assigning the new receiver a distinct credential.
+- Direct-to-relay conversion: observed absent relay authentication; conversion now
+  requires credentials while existing legacy relay tunnels remain explicit.
+- Provider private JSON loss: observed successful reapply recreating protected
+  state; separately persisted auth version now rejects missing private material.
+
+Additional command-seam checks cover local update stability, reconnect followed
+by explicit public batch-redeploy (avoids the 30-second production debounce),
+missing consumer private state rejection, old peer refusal before reservation,
+legacy list visibility, matched per-hop credentials and secret-free list/export.
+
+## Results
+
+Eight authentication contract tests with race detection, repeated three times:
+`go test -race ./tests/contract -run '^(TestNewRelayTunnelEmitsMatchingPrivateEndpointAuthentication|TestFederatedRelayRequiresVersionedAuthAndRejectsDowngrade|TestNewFederatedTunnelAuthenticatesEveryRelayHop|TestRelayAuthenticationSurvivesInsertingBeforeExistingMiddle|TestConvertingDirectTunnelRequiresRelayAuthentication|TestBackupImportCannotSilentlyDowngradeRequiredRelay|TestNewRelayTunnelRefusesLegacyFederationBeforeReservation|TestLegacyRelayStateRemainsExplicitInList)$' -count=3`
+
+Earlier pass: 17.878 seconds. Final run after provider version guard and log
+redaction: PASS, 19.584 seconds. Focused non-TLS generation
+regression passes after narrowing its old overbroad no-metadata assertion.
+`git diff --check` passes.
+
+## Explicit limitations
+
+- Authentication-only protection against anonymous relay clients, not credential
+  confidentiality over raw TCP/unverified TLS/public-default KCP or insecure
+  control-plane paths.
+- Required mode is desired policy, not attestation of every participating agent.
+  Old agent strict-route support requires upgrading the agent.
+- Existing legacy relay tunnels remain unprotected. No automatic migration,
+  credential rotation, or configuration-only credential recovery is implemented.
+- SQLite/loopback verification only in this task; production topology, live
+  upgrades, and PostgreSQL runtime checks are not exercised here.

plans/evidence/070-required-route-validation.md

@@ -0,0 +1,41 @@
+# Required-route repair validation
+
+Local darwin/arm64 checkout, baseline 3549fe5; 2026-11-08 UTC.
+
+## Red / green
+- New parsed-service regression failed before implementation with:
+  "required chain is missing, but relay accepted a direct connection".
+- Added opt-in handler metadata chain.strict and a router required-chain guard.
+  The same test passed with race detection repeated three times.
+- New panel command contract failed before generation change:
+  "tunnel forward must require chain, got map[chain:chains_1 type:tcp]".
+- Emitting strict metadata for type-2 forwards fixed it; type-1 direct forwards
+  remain unrestricted. Race detection repeated three times passed.
+
+## Native data evidence
+- Real loopback A–B–D, then A–B–C–D, refuses traffic while B's chain is missing;
+  C/D counters remain unchanged on the rejected request; restoring B's chain
+  restores the complete path.
+- Parsed services reject missing chain names, empty candidate selection and an
+  absent chain configuration with strict policy; TCP and UDP requests covered.
+- Authenticated native TCP/TLS/KCP relay transports carrying TCP/UDP targets
+  reject a required missing route and continue to support legitimate direct exit
+  services. TLS certificates are verified in the fixture.
+- All TestRequiredRelay tests: race detection, count=3 passed, 1.836s.
+- All go-gost/x tests: ordinary and race passed; go vet passed.
+- Agent module tests (including lifecycle), build and go vet passed.
+
+## Limits
+The guard prevents direct destination dialing when the required selected route
+is nil or empty. It does not promise zero DNS activity before rejection, nor
+change generic GOST behavior without the strict option. FLVX's per-node chain
+has one next-hop selection; arbitrary partially populated multi-hop GOST routes
+are not claimed to be validated by this change. Existing established connections
+are not rerouted by an edit. Older agents must be upgraded to enforce the new
+metadata; ordinary command acknowledgment cannot prove unknown-binary support.
+
+Additional composed regression: each A/B/C/D receiver has independent synthetic
+credentials, and every upstream connector uses the next receiver's credential.
+The authenticated A–B–D → A–B–C–D transition, missing-B-chain rejection and
+recovery all pass on real TCP loopback sockets. All required-route regressions,
+including this composition: race repeated three times, PASS, 1.912s.

plans/evidence/070-tunnel-insert-middle-hop-investigation.go.txt

@@ -0,0 +1,477 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestTunnelInsertMiddleHopRecordedRuntimeContract(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 user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.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(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			defer mu.Unlock()
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round"}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		for _, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ? LIMIT 1`, tunnelID, target)
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+	update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}})
+	check(map[string]int64{"A": entryB, "B": entryC, "C": exitNodeID})
+	// A remains the entry and the user's forward remains bound there.
+	after, _ := mustQueryInt64Int(t, r, `SELECT node_id,port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
+	if after != entryA {
+		t.Fatalf("forward entry changed: %d", after)
+	}
+}
+
+func TestTunnelRedeployEditMissingChainWindowInvestigation(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 user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.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(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	armed := false
+	chainPresent, servicePresent := map[string]bool{}, map[string]bool{}
+	atDeleteService, releaseDeleteService, editReachedA := make(chan struct{}), make(chan struct{}), make(chan struct{}, 1)
+	var gateOnce, releaseOnce sync.Once
+	release := func() { releaseOnce.Do(func() { close(releaseDeleteService) }) }
+	defer release()
+
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			active := armed
+			shouldGate := active && name == "B" && kind == "DeleteService"
+			if active && name == "A" && kind == "UpdateChains" {
+				select {
+				case editReachedA <- struct{}{}:
+				default:
+				}
+			}
+			mu.Unlock()
+			if shouldGate {
+				gateOnce.Do(func() { close(atDeleteService); <-releaseDeleteService })
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			if kind == "DeleteChains" {
+				chainPresent[name] = false
+			}
+			if kind == "AddChains" || kind == "UpdateChains" {
+				chainPresent[name] = true
+			}
+			if kind == "DeleteService" {
+				servicePresent[name] = false
+			}
+			if kind == "AddService" || kind == "UpdateService" {
+				servicePresent[name] = true
+			}
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round"}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		for _, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ? LIMIT 1`, tunnelID, target)
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+
+	mu.Lock()
+	armed = true
+	mu.Unlock()
+	redeployDone := make(chan struct{})
+	go func() {
+		defer close(redeployDone)
+		raw, _ := json.Marshal(map[string]interface{}{"ids": []int64{tunnelID}})
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		t.Logf("redeploy response: %s", res.Body.String())
+	}()
+	await := func(ch <-chan struct{}, label string) {
+		t.Helper()
+		select {
+		case <-ch:
+		case <-time.After(10 * time.Second):
+			release()
+			t.Fatalf("timeout waiting for %s", label)
+		}
+	}
+	await(atDeleteService, "B DeleteService gate")
+	editDone := make(chan struct{})
+	go func() { defer close(editDone); update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}}) }()
+	await(editReachedA, "edit UpdateChains on A")
+	mu.Lock()
+	missing, live := !chainPresent["B"], servicePresent["B"]
+	mu.Unlock()
+	if !missing || !live {
+		release()
+		t.Fatalf("expected B live service with missing chain during overlap, missing=%v live=%v", missing, live)
+	}
+	t.Log("Deterministic overlap confirmed: edit reached A while redeploy had deleted B chain but had not deleted B relay service")
+	release()
+	await(editDone, "edit completion")
+	await(redeployDone, "redeploy completion")
+	mu.Lock()
+	defer mu.Unlock()
+	t.Logf("final mock runtime chain presence: A=%v B=%v C=%v; services B=%v C=%v D=%v", chainPresent["A"], chainPresent["B"], chainPresent["C"], servicePresent["B"], servicePresent["C"], servicePresent["D"])
+}

plans/evidence/070-tunnel-lifecycle-validation.md

@@ -0,0 +1,68 @@
+# Tunnel lifecycle repair validation
+
+Local darwin/arm64 checkout, baseline 3549fe5; 2026-11-08 UTC. No deployment, push, commit, dependency, or real node used.
+
+## Agreed seams
+
+Panel HTTP requests, temporary repository storage, and mock external agent/federation command interfaces. Tests observe runtime command payloads and API results. No private lifecycle helper tests.
+
+## Red → green evidence
+
+1. `go test ./tests/contract -run '^TestTunnelRedeployPreservesLiveRoutes$' -count=1`
+   - Red: `unexpected chain deletion on A: {"chain":"chains_1"}`.
+   - Green after replacing cleanup + create with existing chain/service upsert: 1.620s.
+2. `go test ./tests/contract -run '^TestTunnelEditWaitsForRedeploy$' -count=1`
+   - Red: `edit changed runtime before redeploy finished` while the redeploy's exit service command was gated.
+   - Green after per-tunnel locking over snapshot, persistence and runtime application. Combined first two tests: 2.879s.
+3. `go test ./tests/contract -run '^TestTunnelFailedRedeployPreservesLiveRoutes$' -count=1`
+   - Red: `failed redeploy removed existing runtime: DeleteService on B` on an injected bind failure.
+   - Green after removing destructive cleanup retry for upsert. Existing add/create retry behavior remains unchanged. Combined local tests: 3.922s.
+4. `go test ./tests/contract -run '^TestFederationRedeployPreservesExistingBindings$' -count=1`
+   - Red: `redeploy destroyed existing federation runtime: [DeleteService DeleteService DeleteChains]`.
+   - Green: 0.653s after reusing stable resource keys and excluding existing bindings from failure cleanup.
+
+Additional verification covers failed federation apply, concurrent delete waiting for redeploy, and final middle-hop target after concurrent edit. Full six-regression race invocation:
+
+`go test -race ./tests/contract -run 'Test(Tunnel(RedeployPreservesLiveRoutes|FailedRedeployPreservesLiveRoutes|EditWaitsForRedeploy|DeleteWaitsForRedeploy)|Federation(Failed)?RedeployPreservesExistingBindings)' -count=3`
+
+Result: PASS, 32.626s. The gated concurrency observation lasts 150ms; successful completion and the final B→C target are also asserted.
+
+## Scope and limitations
+
+- One process's Handler owns the locks. Different tunnels remain independent; migration locks source and target in sorted order. Update, redeploy/reconnect (through the shared redeploy path), ordinary/batch delete, and delete-with-forward migration participate. Best-exit probes remain unlocked while measuring, then revalidate owner/exit topology under the lifecycle lock before applying.
+- Existing PR #550 agent mutation queue and service rollback were not modified. Panel upserts defer failure rollback to the agent rather than deleting a preserved listener.
+- This is not a distributed multi-node transaction. Existing tunnel edits still commit desired state before node application; partial apply can leave some nodes ahead of others, and full atomic rollback was not introduced. Offline/deferred application behavior is inherited and is not proof of complete deployment.
+- Forward CRUD and provider-side federation ownership are not newly serialized by this per-consumer-tunnel lock.
+- Original bug-characterization source is preserved verbatim at `070-tunnel-insert-middle-hop-investigation.go.txt`; only its old-bug gated test is skipped in the active test file because waiting for the removed insecure event is no longer a passing regression.
+
+## Release review follow-up (2026-11-08 UTC)
+
+Review findings were repaired before publication:
+
+- `TestTunnelDeleteWaitsForCreateRuntime`: red `delete removed runtime while create was still applying`; green after claiming the new ID's lifecycle lock before its first commit. Claim is nonblocking so it never waits for a lifecycle owner while holding a database transaction.
+- `TestFederationCreateDoesNotHoldDatabaseDuringAcknowledgment`: red `federation create held database while waiting for acknowledgment`; green after splitting local desired-state persistence and final provider-binding persistence into short transactions around network work. Initial topology and allocated local ports are persisted with credentials before waiting for the provider; unallocated remote ports are NULL.
+- `TestConcurrentCreatesReserveLocalPortsBeforeFederationAcknowledgment`: mixed local/remote topology with one available local receiver port. The second tunnel is rejected while the first awaits provider acknowledgment. Mutation proof disabling only initial prepared-chain persistence produced red `second create did not reject the reserved local port before provider acknowledgment`; restoring persistence produced green.
+- `TestOfflineTunnelCreateReportsPendingRuntime`: red response was only `code:0,msg:操作成功`. Create/update now retain code-0 accepted-configuration compatibility but include explicit pending message and `runtimeStatus:pending`; batch redeploy reports pending in its failure count. Desired configuration/authentication and previously applied runtime are retained.
+- `TestPendingTunnelUpdateStillRemovesObsoleteRelay`: red `pending update left removed relay live: map[]`; pending results now continue obsolete cleanup and required forward reconciliation before responding.
+- `TestFailedObsoleteRelayRemovalPreservesItsChain`: red deleted both listener and chain despite rejected listener deletion. Cleanup now removes service before chain, preserves the chain on unacknowledged listener deletion, and reports cleanup errors in the pending outcome.
+
+The original statement that offline application is silently inherited no longer applies to create/update/redeploy outcomes. This remains an asynchronous, multi-node workflow rather than a distributed transaction. Failed obsolete cleanup is reported; full durable cross-node rollback was not introduced.
+
+After these changes, handler and contract suites passed in 11.951s and 16.189s respectively (prior to the final isolated cleanup-error regression/hardening, which also passed focused validation).
+
+### Durable obsolete-runtime cleanup
+
+A later review identified that a pending message alone loses obsolete endpoint ownership once topology rows are replaced. The repair adds `tunnel_runtime_cleanup` in the existing database (no external component). Each row contains tunnel ID, node ID, runtime kind and old receiver port. Topology updates queue ownership in the same transaction that replaces topology; tunnel deletion queues current runtime before deleting its desired rows. Cleanup records are not cascaded with the tunnel or authentication rows.
+
+Reconciliation uses existing maintenance, reconnect, and redeploy paths under the tunnel lifecycle lock. Service deletion must be acknowledged before its chain is removed. Successful removal clears only acknowledged records. Re-desired roles cancel obsolete deletion safely; changed receiver ports remain reserved until an acknowledged service replacement. Multiple unresolved ports can coexist for the same named receiver. Automatic allocation, explicit relay/forward port validation, and federation port discovery include these reservations.
+
+Public-seam regressions:
+- Extended failed-cleanup test first failed `redeploy lost obsolete cleanup ownership after failure: map[]`; now a subsequent successful redeploy removes both obsolete resources and a third pass sends no repeated deletion.
+- `TestRedesiredRelayKeepsOldPortReservedUntilReplacementAcknowledged` re-adds a removed node on a different receiver port with a simulated timeout, rejects another tunnel claiming the unresolved old port, then permits that port only after a successful replacement ACK. No delayed deletion reaches the re-desired listener.
+- `TestDeletedTunnelCleanupSurvivesHandlerReplacement` deletes desired state despite a rejected listener deletion, verifies old-port reservation, then replaces the Handler and reconnects node sessions. Persisted ownership permits cleanup/retry and releases the port only after ACK. Subsequent retry does not remove the replacement tunnel.
+
+The full repository, handler and contract suites passed (2.965s, 12.463s, 16.974s) before the final reconnect-specific test and forward-port reservation check. Focused race validation results are reported with the integration checkpoint.
+
+### Receiver role-transition acknowledgment barrier
+
+Final review on rebased baseline `7f01774` found that middle→exit on the same node could remove the old chain after a rejected/timed-out receiver replacement. `TestMiddleToExitKeepsChainUntilReceiverReplacementAcknowledged` reproduced this in all four combinations of same/changed receiver port and timeout/hard rejection (`deletes=1 unsafe=true`). The fix queues a service-replacement barrier on receiver role changes, including same-port changes. A still-desired service record is retained and protects chain cleanup until successful service upsert acknowledgment; redeploy drains obsolete chains after that acknowledgment. Focused green result: PASS, 0.764s. Red evidence: `/tmp/flvx-role-transition-red.log`; race validation is reported in the final integration checkpoint.

plans/evidence/071-agent-upgrade-checksum-validation.md

@@ -0,0 +1,32 @@
+# Agent checksum upgrade validation
+
+## Scope and baseline
+
+Reviewed local changes against `fadc2b6c122df99140e0c9cbd481a1214d17d175` (rc8), as confirmed by the user. Tests use the actual UpgradeAgent command router and WebSocket response path, loopback HTTP, temporary executable/backup paths, and an intercepted restart action. No real installer or service process is launched.
+
+## Reproduction and fix
+
+Four red-to-green slices reproduced missing URL, checksum HTTP 404, ambiguous multiple records, and oversized checksum acceptance. Initially the command returned success, emitted verification/install progress, and reached the restart substitute. The corrected flow returns an unsuccessful UpgradeAgentResponse before installation and removes staged bytes.
+
+Additional cases cover blank URL, invalid request URL, connection interruption, truncated HTTP body despite a valid-looking hash, empty/whitespace checksum, short/nonhex/mismatched hash, invalid GNU marker, absent filename, garbage, NUL and embedded newline. Valid fixtures cover bare digest, GNU text and binary records, uppercase hex, CRLF and surrounding whitespace. Both URL architecture placeholders and response request IDs are checked. Failed cases preserve old executable and backup; valid cases reach the intercepted restart with exact `abc` bytes and the independent known SHA256 fixture.
+
+## Checks
+
+- Initial socket baseline: passed.
+- UpgradeAgent targeted tests and race tests: passed.
+- Socket package race tests, three runs: passed (2.009s after cleanup).
+- go-gost/x: `go test ./...` and `go vet ./...`: passed.
+- go-gost: `go test ./...`, `go vet ./...`, and build to a temporary output: passed.
+- `git diff --check`: passed.
+- All listed module checks and the build were rerun after cleanup and passed.
+- Go toolchain: 1.26.10 darwin/arm64.
+
+## Independent review
+
+Standards: no hard violations or blockers. One optional duplicate cleanup observation was addressed by consolidating staging removal in the defer.
+
+Spec: no actionable deviations found. Missing checksum, fetch/status/read/format/hash errors stop before success and installation; supported SHA256 formats and architecture substitution are retained. No unrelated installer, Alpine, release or deployment changes.
+
+## Limits
+
+This verifies the agent command and integrity gate, not actual systemd installation or live-node deployment. The fix must be installed on an agent before that agent gains the new behavior; updating the panel alone cannot retrofit old agents. Hash comparison is not a signature and does not protect against a compromised source supplying both artifact and matching checksum. No push, PR, merge, tag or deployment was performed. HTTP request timeout and installer/platform redesign remain outside this repair.

plans/evidence/072-agent-openrc-upgrade-validation.md

@@ -0,0 +1,43 @@
+# OpenRC agent upgrade and rollback validation
+
+## Baseline and scope
+
+User-approved review baseline: fadc2b6c122df99140e0c9cbd481a1214d17d175. Includes the pending checksum fail-closed repair (071) and manager-aware upgrade/rollback (072). No publication, deployment, or new software installation.
+
+## Reproduction
+
+A disposable existing Alpine 3.22.5 linux/amd64 image on Mac mini Docker reproduced both failures: actual upgrade and rollback handlers could not find systemd-run. The upgrade used a valid checksum. Source inspection confirmed install.sh supports OpenRC but the two agent handlers did not. Existing installer CI did not test those command handlers.
+
+## Regression coverage
+
+Actual UpgradeAgent/RollbackAgent routing and WebSocket responses cover manager selection, Alpine preference over systemctl shims, missing manager, rejected submission, backup preservation, atomic rollback staging, request IDs and all checksum cases from 071. Script execution checks stop/replace/start order, stop failure, replacement failure recovery, directory targets and no systemd legacy cleanup on OpenRC.
+
+Linux-only integration executes the real detached helper. An rc-service double sends SIGTERM to the original test-agent's entire process group. The test verifies that the original process receives SIGTERM while the helper survives, replaces the binary with the rollback copy, preserves the backup and invokes the start command.
+
+## Environment and checks
+
+- Mac mini: Go 1.26.10 darwin/arm64.
+- Cached Alpine 3.22.5 linux/amd64 under Docker emulation; no package installation. Tests use loopback HTTP and service-command doubles, with no host service mounts.
+- Full socket tests and focused race tests: passed.
+- Alpine manager/upgrade/rollback/checksum/helper-survival suite: passed.
+- go-gost/x full `go test ./...`, `go vet ./...`: passed.
+- go-gost `go test ./...`, `go vet ./...`, build to temporary output: passed.
+- `git diff --check`: passed.
+
+## Limitations
+
+Real OpenRC/systemd service integration was not run. The detached process test models the installed OpenRC PID/process-group stopping behavior, not custom cgroup policies. Successful command response acknowledges helper launch or systemd submission, not completed asynchronous service restart. No automatic downgrade is attempted if starting the replaced executable fails. Live nodes were not changed. HTTP request timeouts, release/deployment, and retrofitting already installed agents are outside this local repair.
+
+## Independent review
+
+Standards: no documented violations or blockers. Optional one-line legacy restart-script wrapper cleanup was deferred to preserve the existing focused legacy-service regression interface.
+
+Spec: no blocking implementation deviation. Reviewer requested explicit OpenRC process-launch-failure coverage; follow-up validation is tracked below.
+
+Follow-up: explicit OpenRC exec-failure coverage passed for both routed commands. A Linux-only, explicitly opted-in disposable Alpine test temporarily hides only the container's /bin/sh symlink and restores it afterward. It uses production Alpine detection, executable lookup and cmd.Start; both commands reject ENOENT, preserve the live executable and expected backup, and remove staging. No runtime test abstraction was added. The test requires Alpine and Docker markers and is skipped by default.
+
+Reproduction of the opt-in case (only a disposable container; never mount host /bin): build the socket test binary with `CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go test -c -o /tmp/flvx-072-socket.test ./socket` from go-gost/x, then run `docker run --rm --pull=never --platform linux/amd64 --network none -e FLVX_TEST_DISPOSABLE_ALPINE_SHELL_FAILURE=1 -v /tmp/flvx-072-socket.test:/probe/socket.test:ro alpine:3.22 /probe/socket.test -test.run '^TestOpenRCCommandsCleanStageOnHelperExecFailure$' -test.v`.
+
+Final host full socket race suite passed in 8.844s. Final follow-up changed only Linux test coverage; Mac socket/vet and diff checks passed again.
+
+Independent Spec re-review confirmed the launch-failure gap is closed, with no remaining actionable spec gaps.

vite-frontend/src/pages/monitor.tsx

@@ -1,6 +1,7 @@
 import type { MonitorNodeApiItem } from "@/api/types";
+import type { RealtimeNodeMetric } from "@/pages/node/monitor-view";
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import toast from "react-hot-toast";
 import {
   RefreshCw,
@@ -44,73 +45,117 @@ export default function MonitorPage() {
   const [viewMode, setViewMode] = useState<"list" | "grid">("list");
   const [activeTab, setActiveTab] = useState<MonitorTab>("nodes");
 
-  const [realtimeNodeStatus, setRealtimeNodeStatus] = useState<
-    Record<number, "online" | "offline">
-  >({});
+  const realtimeNodeStatusRef = useRef(new Map<number, { status: number }>());
+  const nodesRequestIdRef = useRef(0);
   const [realtimeNodeMetrics, setRealtimeNodeMetrics] = useState<
-    Record<number, any>
+    Record<number, RealtimeNodeMetric>
   >({});
 
-  const handleRealtimeMessage = useCallback((message: any) => {
-    const nodeId = Number(message?.id ?? 0);
-
-    if (!nodeId || Number.isNaN(nodeId)) return;
-
-    const type = String(message?.type ?? "");
-    const payload = message?.data;
-
-    if (type === "status") {
-      const status = Number(payload);
-
-      setRealtimeNodeStatus((prev) => ({
-        ...prev,
-        [nodeId]: status === 1 ? "online" : "offline",
-      }));
-
-      return;
-    }
-
-    if (type === "metric") {
-      let raw = payload;
-
-      if (typeof raw === "string") {
-        try {
-          raw = JSON.parse(raw);
-        } catch {
-          return;
-        }
-      }
-      if (!raw || typeof raw !== "object") return;
-      const metric = raw as any;
-
-      setRealtimeNodeMetrics((prev) => ({
-        ...prev,
-        [nodeId]: {
-          cpuUsage: Number(metric.cpuUsage ?? metric.cpu_usage ?? 0),
-          netInSpeed: Number(metric.netInSpeed ?? metric.net_in_speed ?? 0),
-          netOutSpeed: Number(metric.netOutSpeed ?? metric.net_out_speed ?? 0),
-          tcpConns: Number(metric.tcpConns ?? metric.tcp_conns ?? 0),
-          udpConns: Number(metric.udpConns ?? metric.udp_conns ?? 0),
-        },
-      }));
-    }
+  const updateNodeStatus = useCallback((nodeId: number, status: number) => {
+    realtimeNodeStatusRef.current.set(nodeId, { status });
+    setNodes((prev) =>
+      prev.map((node) =>
+        Number(node.id) === nodeId ? { ...node, status } : node,
+      ),
+    );
   }, []);
 
-  useNodeRealtime({
+  const handleRealtimeMessage = useCallback(
+    (message: any) => {
+      const nodeId = Number(message?.id ?? 0);
+
+      if (!nodeId || Number.isNaN(nodeId)) return;
+
+      const type = String(message?.type ?? "");
+      const payload = message?.data;
+
+      if (type === "status") {
+        updateNodeStatus(nodeId, Number(payload) === 1 ? 1 : 0);
+
+        return;
+      }
+
+      if (type === "info") {
+        updateNodeStatus(nodeId, 1);
+
+        return;
+      }
+
+      if (type === "metric") {
+        let raw = payload;
+
+        if (typeof raw === "string") {
+          try {
+            raw = JSON.parse(raw);
+          } catch {
+            return;
+          }
+        }
+        if (!raw || typeof raw !== "object") return;
+        const metric = raw as Record<string, unknown>;
+        const receivedAt = Date.now();
+        const incomingUptime = Number(metric.uptime ?? 0);
+
+        setRealtimeNodeMetrics((prev) => ({
+          ...prev,
+          [nodeId]: {
+            receivedAt,
+            cpuUsage: Number(metric.cpuUsage ?? metric.cpu_usage ?? 0),
+            memoryUsage: Number(metric.memoryUsage ?? metric.memory_usage ?? 0),
+            diskUsage: Number(metric.diskUsage ?? metric.disk_usage ?? 0),
+            netInBytes: Number(metric.netInBytes ?? metric.bytes_received ?? 0),
+            netOutBytes: Number(
+              metric.netOutBytes ?? metric.bytes_transmitted ?? 0,
+            ),
+            netInSpeed: Number(metric.netInSpeed ?? metric.net_in_speed ?? 0),
+            netOutSpeed: Number(
+              metric.netOutSpeed ?? metric.net_out_speed ?? 0,
+            ),
+            load1: Number(metric.load1 ?? 0),
+            load5: Number(metric.load5 ?? 0),
+            load15: Number(metric.load15 ?? 0),
+            tcpConns: Number(metric.tcpConns ?? metric.tcp_conns ?? 0),
+            udpConns: Number(metric.udpConns ?? metric.udp_conns ?? 0),
+            uptime: incomingUptime || prev[nodeId]?.uptime || 0,
+          },
+        }));
+        updateNodeStatus(nodeId, 1);
+      }
+    },
+    [updateNodeStatus],
+  );
+
+  const { wsConnected, wsConnecting } = useNodeRealtime({
     onMessage: handleRealtimeMessage,
     enabled: true,
   });
 
   const loadNodes = useCallback(async (options?: { silent?: boolean }) => {
     const silent = options?.silent ?? false;
+    const requestId = ++nodesRequestIdRef.current;
+    const statusAtRequest = new Map(realtimeNodeStatusRef.current);
 
     if (!silent) setNodesLoading(true);
     try {
       const response = await getMonitorNodes();
 
+      // A newer refresh or poll owns the page state, even if it finishes first.
+      if (requestId !== nodesRequestIdRef.current) return;
+
       if (response.code === 0 && Array.isArray(response.data)) {
         setNodesError(null);
-        setNodes(response.data);
+        // A fresh snapshot repairs missed WS events. Events received while the
+        // request was in flight are newer than that snapshot and must win.
+        setNodes(
+          response.data.map((node) => {
+            const nodeId = Number(node.id);
+            const latest = realtimeNodeStatusRef.current.get(nodeId);
+
+            return latest && latest !== statusAtRequest.get(nodeId)
+              ? { ...node, status: latest.status }
+              : node;
+          }),
+        );
 
         return;
       }
@@ -124,14 +169,21 @@ export default function MonitorPage() {
 
       if (!silent) toast.error(response.msg || "加载节点失败");
     } catch {
-      if (!silent) toast.error("加载节点失败");
+      if (requestId === nodesRequestIdRef.current && !silent) {
+        toast.error("加载节点失败");
+      }
     } finally {
-      if (!silent) setNodesLoading(false);
+      // A silent poll may supersede a foreground refresh that showed loading.
+      if (requestId === nodesRequestIdRef.current) setNodesLoading(false);
     }
   }, []);
 
   useEffect(() => {
     void loadNodes();
+
+    return () => {
+      nodesRequestIdRef.current += 1;
+    };
   }, [loadNodes]);
 
   useEffect(() => {
@@ -148,14 +200,12 @@ export default function MonitorPage() {
       .map((n) => ({
         id: Number(n.id),
         name: String(n.name ?? ""),
-        connectionStatus:
-          realtimeNodeStatus[Number(n.id)] ||
-          (n.status === 1 ? "online" : "offline"),
+        connectionStatus: n.status === 1 ? "online" : "offline",
         version: n.version,
       }));
 
     return new Map<number, MonitorNode>(list.map((n) => [n.id, n]));
-  }, [nodes, realtimeNodeStatus]);
+  }, [nodes]);
 
   const aggregateMetrics = useMemo(() => {
     let totalCpu = 0;
@@ -326,7 +376,13 @@ export default function MonitorPage() {
       </div>
 
       {activeTab === "nodes" ? (
-        <MonitorView nodeMap={nodeMap} viewMode={viewMode} />
+        <MonitorView
+          nodeMap={nodeMap}
+          realtimeNodeMetrics={realtimeNodeMetrics}
+          viewMode={viewMode}
+          wsConnected={wsConnected}
+          wsConnecting={wsConnecting}
+        />
       ) : (
         <TunnelMonitorView viewMode={viewMode} />
       )}

vite-frontend/src/pages/node/monitor-view.tsx

@@ -78,17 +78,19 @@ import {
 } from "@/shadcn-bridge/heroui/dropdown";
 import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
 import { Progress } from "@/shadcn-bridge/heroui/progress";
-import { useNodeRealtime } from "@/pages/node/use-node-realtime";
 
 interface MonitorViewProps {
   nodeMap: Map<
     number,
     { id: number; name: string; connectionStatus: string; version?: string }
   >;
+  realtimeNodeMetrics: Record<number, RealtimeNodeMetric>;
+  wsConnected: boolean;
+  wsConnecting: boolean;
   viewMode?: "list" | "grid";
 }
 
-type RealtimeNodeMetric = {
+export type RealtimeNodeMetric = {
   receivedAt: number;
   cpuUsage: number;
   memoryUsage: number;
@@ -532,7 +534,13 @@ const DEFAULT_SERVICE_MONITOR_LIMITS: ServiceMonitorLimitsApiData = {
   maxTimeoutSec: 60,
 };
 
-export function MonitorView({ nodeMap, viewMode = "grid" }: MonitorViewProps) {
+export function MonitorView({
+  nodeMap,
+  realtimeNodeMetrics,
+  wsConnected,
+  wsConnecting,
+  viewMode = "grid",
+}: MonitorViewProps) {
   const [detailNodeId, setDetailNodeId] = useState<number | null>(null);
   const [selectedNodeId, setSelectedNodeId] = useState<number | null>(null);
   const [metrics, setMetrics] = useState<NodeMetricApiItem[]>([]);
@@ -582,27 +590,7 @@ export function MonitorView({ nodeMap, viewMode = "grid" }: MonitorViewProps) {
   const [resultsLimit, setResultsLimit] = useState(50);
   const [resultsLoading, setResultsLoading] = useState(false);
 
-  const [realtimeNodeStatus, setRealtimeNodeStatus] = useState<
-    Record<number, "online" | "offline">
-  >({});
-  const [realtimeNodeMetrics, setRealtimeNodeMetrics] = useState<
-    Record<number, RealtimeNodeMetric>
-  >({});
-
-  const nodes = useMemo(() => {
-    return Array.from(nodeMap.values()).map((n) => {
-      const status = realtimeNodeStatus[n.id];
-
-      if (!status) {
-        return n;
-      }
-
-      return {
-        ...n,
-        connectionStatus: status,
-      };
-    });
-  }, [nodeMap, realtimeNodeStatus]);
+  const nodes = useMemo(() => Array.from(nodeMap.values()), [nodeMap]);
 
   const onlineNodes = nodes.filter((n) => n.connectionStatus === "online");
   const preferredNodeId = onlineNodes[0]?.id ?? nodes[0]?.id ?? 0;
@@ -610,91 +598,6 @@ export function MonitorView({ nodeMap, viewMode = "grid" }: MonitorViewProps) {
   const resolvedServiceMonitorLimits =
     serviceMonitorLimits ?? DEFAULT_SERVICE_MONITOR_LIMITS;
 
-  const handleRealtimeMessage = useCallback((message: any) => {
-    const nodeId = Number(message?.id ?? 0);
-
-    if (!nodeId || Number.isNaN(nodeId)) {
-      return;
-    }
-
-    const type = String(message?.type ?? "");
-    const payload = message?.data;
-
-    if (type === "status") {
-      const status = Number(payload);
-
-      setRealtimeNodeStatus((prev) => ({
-        ...prev,
-        [nodeId]: status === 1 ? "online" : "offline",
-      }));
-
-      return;
-    }
-
-    if (type === "metric") {
-      let raw = payload;
-
-      if (typeof raw === "string") {
-        try {
-          raw = JSON.parse(raw);
-        } catch {
-          return;
-        }
-      }
-      if (!raw || typeof raw !== "object") {
-        return;
-      }
-
-      const metric = raw as Record<string, unknown>;
-      const receivedAt = Date.now();
-      const incomingUptime = Number(metric.uptime ?? 0);
-
-      setRealtimeNodeMetrics((prev) => {
-        const normalized: RealtimeNodeMetric = {
-          receivedAt,
-          cpuUsage: Number(metric.cpuUsage ?? metric.cpu_usage ?? 0),
-          memoryUsage: Number(metric.memoryUsage ?? metric.memory_usage ?? 0),
-          diskUsage: Number(metric.diskUsage ?? metric.disk_usage ?? 0),
-          netInBytes: Number(metric.netInBytes ?? metric.bytes_received ?? 0),
-          netOutBytes: Number(
-            metric.netOutBytes ?? metric.bytes_transmitted ?? 0,
-          ),
-          netInSpeed: Number(metric.netInSpeed ?? metric.net_in_speed ?? 0),
-          netOutSpeed: Number(metric.netOutSpeed ?? metric.net_out_speed ?? 0),
-          load1: Number(metric.load1 ?? 0),
-          load5: Number(metric.load5 ?? 0),
-          load15: Number(metric.load15 ?? 0),
-          tcpConns: Number(metric.tcpConns ?? metric.tcp_conns ?? 0),
-          udpConns: Number(metric.udpConns ?? metric.udp_conns ?? 0),
-          uptime: incomingUptime || prev[nodeId]?.uptime || 0,
-        };
-
-        return {
-          ...prev,
-          [nodeId]: normalized,
-        };
-      });
-      setRealtimeNodeStatus((prev) => ({
-        ...prev,
-        [nodeId]: "online",
-      }));
-
-      return;
-    }
-
-    if (type === "info") {
-      setRealtimeNodeStatus((prev) => ({
-        ...prev,
-        [nodeId]: "online",
-      }));
-    }
-  }, []);
-
-  const { wsConnected, wsConnecting } = useNodeRealtime({
-    onMessage: handleRealtimeMessage,
-    enabled: !accessDenied,
-  });
-
   useEffect(() => {
     if (!selectedNodeId && preferredNodeId > 0) {
       setSelectedNodeId(preferredNodeId);

vite-frontend/src/pages/tunnel.tsx

@@ -926,7 +926,19 @@ export default function TunnelPage() {
         : await createTunnel(data);
 
       if (response.code === 0) {
-        toast.success(isEdit ? "更新成功" : "创建成功");
+        if (
+          response.data &&
+          typeof response.data === "object" &&
+          "runtimeStatus" in response.data &&
+          response.data.runtimeStatus === "pending"
+        ) {
+          toast(response.msg || "配置已保存，部分节点运行时待同步", {
+            icon: "⚠️",
+            duration: 6000,
+          });
+        } else {
+          toast.success(isEdit ? "更新成功" : "创建成功");
+        }
         setModalOpen(false);
         await refreshTunnelList(false);
       } else {

vite-frontend/src/pages/user.tsx

@@ -231,6 +231,9 @@ export default function UserPage() {
     maxConn: 0,
   });
   const [userFormLoading, setUserFormLoading] = useState(false);
+  const [userSubmitWarning, setUserSubmitWarning] = useState<string | null>(
+    null,
+  );
   const [userFlowInput, setUserFlowInput] = useState("1000");
   const [userFlowUnit, setUserFlowUnit] = useState<TrafficUnit>("GB");
   const [quotaResetLoading, setQuotaResetLoading] = useState(false);
@@ -517,6 +520,7 @@ export default function UserPage() {
   };
 
   const handleAdd = () => {
+    setUserSubmitWarning(null);
     setIsEdit(false);
     setUserFlowInput("1000");
     setUserFlowUnit("GB");
@@ -537,6 +541,7 @@ export default function UserPage() {
   };
 
   const handleEdit = async (user: User) => {
+    setUserSubmitWarning(null);
     setIsEdit(true);
     const trafficInput = trafficInputFor(user.flow, user.flowMiB);
 
@@ -618,6 +623,7 @@ export default function UserPage() {
     }
 
     setUserFormLoading(true);
+    setUserSubmitWarning(null);
     try {
       const submitData: any = {
         ...userForm,
@@ -660,7 +666,19 @@ export default function UserPage() {
           await loadUsers();
         }
       } else {
-        toast.error(response.msg || (isEdit ? "更新失败" : "创建失败"));
+        const userDisabled =
+          isEdit &&
+          response.data !== null &&
+          typeof response.data === "object" &&
+          "userDisabled" in response.data &&
+          response.data.userDisabled === true;
+
+        if (userDisabled) {
+          setUserSubmitWarning(response.msg);
+          await loadUsers();
+        } else {
+          toast.error(response.msg || (isEdit ? "更新失败" : "创建失败"));
+        }
       }
     } catch {
       toast.error(isEdit ? "更新失败" : "创建失败");
@@ -1532,6 +1550,14 @@ export default function UserPage() {
         <ModalContent>
           <ModalHeader>{isEdit ? "编辑用户" : "新增用户"}</ModalHeader>
           <ModalBody>
+            {userSubmitWarning ? (
+              <div
+                className="whitespace-pre-wrap break-words rounded-lg border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900 dark:border-amber-700 dark:bg-amber-950/50 dark:text-amber-100"
+                role="alert"
+              >
+                {userSubmitWarning}
+              </div>
+            ) : null}
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               <Input
                 isRequired