feat(agent): 注册失败退避重试不停机,404 时日志提示检查 master_url 基础路径

internal/agent/agent.go

@@ -8,6 +8,7 @@ import (
 	"bytes"
 	"crypto/tls"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -80,6 +81,18 @@ func New(cfg *Config) *Agent {
 	}
 }
 
+// statusError is a non-200 response from the master. It keeps the status
+// code addressable so the registration retry loop can tell a wrong-path
+// 404 (master_url missing the panel base path) apart from other failures.
+type statusError struct {
+	code int
+	body string
+}
+
+func (e *statusError) Error() string {
+	return fmt.Sprintf("register failed with status %d: %s", e.code, e.body)
+}
+
 // Register registers the agent with the master
 func (a *Agent) Register() error {
 	url := fmt.Sprintf("%s/panel/api/agent/register", a.config.MasterURL)
@@ -103,21 +116,83 @@ func (a *Agent) Register() error {
 
 	if resp.StatusCode != http.StatusOK {
 		data, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("register failed with status %d: %s", resp.StatusCode, string(data))
+		return &statusError{code: resp.StatusCode, body: string(data)}
 	}
 
 	logger.Info("Agent registered successfully with master")
 	return nil
 }
 
+// registrationBackoff returns the delay before the next registration
+// attempt: 5s, 15s, 30s, then capped at 60s.
+func registrationBackoff(failures int) time.Duration {
+	switch {
+	case failures <= 1:
+		return 5 * time.Second
+	case failures == 2:
+		return 15 * time.Second
+	case failures == 3:
+		return 30 * time.Second
+	default:
+		return 60 * time.Second
+	}
+}
+
+// registerWait sleeps between registration attempts, returning false when
+// the agent is stopping. A package var so tests can drive the retry loop
+// without real delays.
+var registerWait = func(stopCh chan struct{}, d time.Duration) bool {
+	select {
+	case <-stopCh:
+		return false
+	case <-time.After(d):
+		return true
+	}
+}
+
+// errRegistrationAborted marks a registration loop cut short by Stop.
+var errRegistrationAborted = errors.New("registration aborted: agent stopping")
+
+// registerWithRetry keeps trying to register until the master accepts or
+// the agent is stopped. A one-shot failure used to kill the agent
+// outright — a typo'd master_url (classically: the panel base path
+// missing, so the master answers 404) left the node dead and "unknown"
+// on the panel with nothing retrying. Registration is idempotent on the
+// master, so retrying with backoff is safe.
+func (a *Agent) registerWithRetry() error {
+	failures := 0
+	for {
+		err := a.Register()
+		if err == nil {
+			return nil
+		}
+		failures++
+		var st *statusError
+		if errors.As(err, &st) && st.code == http.StatusNotFound {
+			logger.Warningf("主控返回 404：检查 master_url 是否包含面板基础路径（如 https://host/rogue），当前 master_url=%s", a.config.MasterURL)
+		}
+		delay := registrationBackoff(failures)
+		logger.Warningf("Registration attempt %d failed: %v; retrying in %s", failures, err, delay)
+		if !registerWait(a.stopCh, delay) {
+			return errRegistrationAborted
+		}
+	}
+}
+
 // Run starts the agent main loop
 func (a *Agent) Run() error {
 	logger.Info("Starting 3x-ui agent...")
 	logger.Infof("Master: %s, Node: %s", a.config.MasterURL, a.config.NodeName)
 
-	// Initial registration
-	if err := a.Register(); err != nil {
-		return fmt.Errorf("initial registration failed: %w", err)
+	// Initial registration, retried with backoff: a node that cannot
+	// register yet (master down, URL just fixed, network still coming up)
+	// must not die on the first failure.
+	if err := a.registerWithRetry(); err != nil {
+		if errors.Is(err, errRegistrationAborted) {
+			logger.Info("Agent stopping...")
+			return nil
+		}
+		return err
 	}
 
 	// Start heartbeat ticker