功能: 修复并实现多节点集群部署 (#38)

基础修复：
- 新增节点离线检测：每 15s 扫描，超 45s 未心跳的远程节点自动置离线
- 节点删除前检查关联任务，避免孤立备份任务
- BackupTaskRepository 新增 CountByNodeID/ListByNodeID

Master 端 Agent 协议：
- 新增 AgentCommand 模型与命令队列仓储（pending/dispatched/succeeded/failed/timeout）
- 新增 AgentService：任务下发、命令轮询、结果回收、超时扫描
- 新增专用 Agent HTTP API（X-Agent-Token 认证）：
  /api/agent/heartbeat
  /api/agent/commands/poll
  /api/agent/commands/:id/result
  /api/agent/tasks/:id
  /api/agent/records/:id
- BackupExecutionService 支持 node 路由：task.NodeID 指向远程节点时自动入队派发

Agent CLI（backupx agent 子命令）：
- 配置：YAML 文件 / 环境变量 / CLI 参数，优先级 CLI > 文件 > 环境
- 心跳循环 + 命令轮询循环 + 优雅退出
- 本地复用 BackupRunner 与 storage registry 执行备份并直接上传
- 支持 run_task 和 list_dir 两种命令

远程目录浏览：
- NodeService 支持通过 Agent RPC 列出远程节点目录（15s 超时）

前端：
- NodesPage 添加节点后展示 Agent 启动命令和环境变量配置

文档：
- README 中英文重写"多节点集群"章节，含架构图、步骤、限制、CLI 参考

server/internal/http/agent_handler.go

@@ -0,0 +1,156 @@
+package http
+
+import (
+	stdhttp "net/http"
+	"strconv"
+	"strings"
+
+	"backupx/server/internal/service"
+	"backupx/server/pkg/response"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AgentHandler 实现 Agent 调用 Master 的 HTTP API。
+// 全部端点通过 X-Agent-Token 头做节点认证，不使用 JWT。
+type AgentHandler struct {
+	agentService *service.AgentService
+	nodeService  *service.NodeService
+}
+
+func NewAgentHandler(agentService *service.AgentService, nodeService *service.NodeService) *AgentHandler {
+	return &AgentHandler{agentService: agentService, nodeService: nodeService}
+}
+
+// extractToken 从请求头或 JSON body 中提取 Agent Token。
+func extractToken(c *gin.Context) string {
+	if t := strings.TrimSpace(c.GetHeader("X-Agent-Token")); t != "" {
+		return t
+	}
+	// Authorization: Bearer <token>
+	if auth := c.GetHeader("Authorization"); strings.HasPrefix(auth, "Bearer ") {
+		return strings.TrimSpace(strings.TrimPrefix(auth, "Bearer "))
+	}
+	return ""
+}
+
+// Heartbeat 扩展原有 heartbeat：除上报状态外，返回节点 ID 给 Agent 做后续调用。
+func (h *AgentHandler) Heartbeat(c *gin.Context) {
+	var input struct {
+		Token        string `json:"token"`
+		Hostname     string `json:"hostname"`
+		IPAddress    string `json:"ipAddress"`
+		AgentVersion string `json:"agentVersion"`
+		OS           string `json:"os"`
+		Arch         string `json:"arch"`
+	}
+	_ = c.ShouldBindJSON(&input)
+	// token 优先走 body（向后兼容），否则从 header 读
+	token := input.Token
+	if token == "" {
+		token = extractToken(c)
+	}
+	if token == "" {
+		c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": "missing token"})
+		return
+	}
+	if err := h.nodeService.Heartbeat(c.Request.Context(), token, input.Hostname, input.IPAddress, input.AgentVersion, input.OS, input.Arch); err != nil {
+		response.Error(c, err)
+		return
+	}
+	// 返回节点元信息给 Agent（node_id 用于后续 API 路径）
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), token)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, gin.H{
+		"status": "ok",
+		"nodeId": node.ID,
+		"name":   node.Name,
+	})
+}
+
+// Poll Agent 长轮询获取下一条待执行命令。
+// 无命令时返回 {command: null}。
+func (h *AgentHandler) Poll(c *gin.Context) {
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	cmd, err := h.agentService.PollCommand(c.Request.Context(), node)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, gin.H{"command": cmd})
+}
+
+// SubmitCommandResult Agent 上报命令执行结果。
+func (h *AgentHandler) SubmitCommandResult(c *gin.Context) {
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	var input service.AgentCommandResult
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": err.Error()})
+		return
+	}
+	if err := h.agentService.SubmitCommandResult(c.Request.Context(), node, uint(id), input); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, gin.H{"status": "ok"})
+}
+
+// GetTaskSpec Agent 拉取任务规格（含解密后的存储配置）。
+func (h *AgentHandler) GetTaskSpec(c *gin.Context) {
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	spec, err := h.agentService.GetTaskSpec(c.Request.Context(), node, uint(id))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, spec)
+}
+
+// UpdateRecord Agent 更新备份记录（进度/完成状态/日志）。
+func (h *AgentHandler) UpdateRecord(c *gin.Context) {
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	var input service.AgentRecordUpdate
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": err.Error()})
+		return
+	}
+	if err := h.agentService.UpdateRecord(c.Request.Context(), node, uint(id), input); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, gin.H{"status": "ok"})
+}

server/internal/http/router.go

@@ -28,6 +28,7 @@ type RouterDependencies struct {
 	DashboardService         *service.DashboardService
 	SettingsService          *service.SettingsService
 	NodeService              *service.NodeService
+	AgentService             *service.AgentService
 	DatabaseDiscoveryService *service.DatabaseDiscoveryService
 	AuditService             *service.AuditService
 	JWTManager               *security.JWTManager
@@ -150,8 +151,19 @@ func NewRouter(deps RouterDependencies) *gin.Engine {
 		nodes.DELETE("/:id", nodeHandler.Delete)
 		nodes.GET("/:id/fs/list", nodeHandler.ListDirectory)
 
-		// Agent heartbeat (public, token-authenticated)
-		api.POST("/agent/heartbeat", nodeHandler.Heartbeat)
+		// Agent API（token 认证，无需 JWT）
+		if deps.AgentService != nil {
+			agentHandler := NewAgentHandler(deps.AgentService, deps.NodeService)
+			agent := api.Group("/agent")
+			agent.POST("/heartbeat", agentHandler.Heartbeat)
+			agent.POST("/commands/poll", agentHandler.Poll)
+			agent.POST("/commands/:id/result", agentHandler.SubmitCommandResult)
+			agent.GET("/tasks/:id", agentHandler.GetTaskSpec)
+			agent.POST("/records/:id", agentHandler.UpdateRecord)
+		} else {
+			// 未启用 Agent 服务时，保留原有 heartbeat 端点以兼容
+			api.POST("/agent/heartbeat", nodeHandler.Heartbeat)
+		}
 	}
 
 	engine.NoRoute(func(c *gin.Context) {