refactor: 消除集群执行服务冗余逻辑 + 修复节点状态滞后缺陷 (#74)

抽取备份/恢复/验证/复制四服务的复制粘贴逻辑到 execution_helpers.go（净减约 250 行）；节点状态改为按 LastSeen 实时推导，消除过期 online 误判；Agent systemd 单元补齐 LimitNOFILE 与单机端一致。go build/test 全绿。
2026-09-04 23:16:41 +08:00 · 2026-05-26 14:12:39 +08:00
parent e4c52fd8f4
commit 0f30e7bf52
10 changed files with 317 additions and 323 deletions
@@ -0,0 +1,163 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"backupx/server/internal/apperror"
+	"backupx/server/internal/backup"
+	"backupx/server/internal/model"
+	"backupx/server/internal/repository"
+	"backupx/server/internal/storage"
+	"backupx/server/internal/storage/codec"
+	"backupx/server/pkg/compress"
+	backupcrypto "backupx/server/pkg/crypto"
+)
+
+// 本文件集中放置「备份执行 / 恢复 / 验证 / 复制」四个执行服务共享的执行期辅助逻辑。
+//
+// 历史上这些函数（解密存储配置创建 provider、按后缀解密解压归档、判定远程节点、
+// 跨节点 local_disk 保护、构建任务执行规格）在四个服务里各复制了一份，差异仅在
+// 字段名与少量错误码/日志文案。重复实现既增加维护成本，也容易出现"改了一处忘了
+// 另一处"的不一致缺陷。这里抽取为单一实现，各服务通过薄封装方法委托调用，调用方
+// 无需改动。
+
+// resolveStorageProvider 查询存储目标、解密其配置并创建 provider。
+func resolveStorageProvider(ctx context.Context, targets repository.StorageTargetRepository, registry *storage.Registry, cipher *codec.ConfigCipher, targetID uint) (storage.StorageProvider, error) {
+	target, err := targets.FindByID(ctx, targetID)
+	if err != nil {
+		return nil, apperror.Internal("BACKUP_STORAGE_TARGET_GET_FAILED", "无法获取存储目标详情", err)
+	}
+	if target == nil {
+		return nil, apperror.BadRequest("BACKUP_STORAGE_TARGET_INVALID", "关联的存储目标不存在", nil)
+	}
+	configMap := map[string]any{}
+	if err := cipher.DecryptJSON(target.ConfigCiphertext, &configMap); err != nil {
+		return nil, apperror.Internal("BACKUP_STORAGE_TARGET_DECRYPT_FAILED", "无法解密存储目标配置", err)
+	}
+	return registry.Create(ctx, target.Type, configMap)
+}
+
+// prepareBackupArtifact 按文件后缀依次解密(.enc)与解压(.gz)，返回最终可读路径。
+// logger 可为 nil（此时静默执行）。
+func prepareBackupArtifact(cipher *codec.ConfigCipher, artifactPath string, logger *backup.ExecutionLogger) (string, error) {
+	current := artifactPath
+	if strings.HasSuffix(strings.ToLower(current), ".enc") {
+		if logger != nil {
+			logger.Infof("检测到加密后缀，开始解密")
+		}
+		decrypted, err := backupcrypto.DecryptFile(cipher.Key(), current)
+		if err != nil {
+			return "", err
+		}
+		current = decrypted
+	}
+	if strings.HasSuffix(strings.ToLower(current), ".gz") {
+		if logger != nil {
+			logger.Infof("检测到 gzip 压缩，开始解压")
+		}
+		decompressed, err := compress.GunzipFile(current)
+		if err != nil {
+			return "", err
+		}
+		current = decompressed
+	}
+	return current, nil
+}
+
+// resolveRemoteExecutionNode 返回远程（非本机）节点指针，用于判定任务应下发给
+// Agent 还是在 Master 本地执行。clusterEnabled 通常为「该服务是否注入了 Agent
+// 下发能力」。本机 / 未启用集群 / nodeID=0 / 未找到时返回 nil（走本地执行）。
+func resolveRemoteExecutionNode(ctx context.Context, nodeRepo repository.NodeRepository, clusterEnabled bool, nodeID uint) *model.Node {
+	if nodeRepo == nil || !clusterEnabled || nodeID == 0 {
+		return nil
+	}
+	node, err := nodeRepo.FindByID(ctx, nodeID)
+	if err != nil || node == nil || node.IsLocal {
+		return nil
+	}
+	return node
+}
+
+// validateCrossNodeLocalDisk 跨节点 local_disk 保护：若备份记录归属某远程节点，
+// 且其存储目标是 local_disk（数据位于该节点本地磁盘），Master 无法跨节点访问，
+// 直接返回错误。errCode/opName 由各服务定制，以给出贴合场景的提示文案。
+func validateCrossNodeLocalDisk(ctx context.Context, nodeRepo repository.NodeRepository, targets repository.StorageTargetRepository, record *model.BackupRecord, errCode, opName string) error {
+	if record == nil || record.NodeID == 0 || nodeRepo == nil {
+		return nil
+	}
+	node, err := nodeRepo.FindByID(ctx, record.NodeID)
+	if err != nil || node == nil || node.IsLocal {
+		return nil
+	}
+	target, err := targets.FindByID(ctx, record.StorageTargetID)
+	if err != nil || target == nil {
+		return nil
+	}
+	if strings.EqualFold(target.Type, "local_disk") {
+		return apperror.BadRequest(errCode,
+			fmt.Sprintf("备份位于节点 %s 的本地磁盘（local_disk），Master 无法跨节点%s。", node.Name, opName),
+			nil)
+	}
+	return nil
+}
+
+// buildBackupTaskSpec 由备份任务构建执行规格：解析排除规则/源路径、解密 DB 密码、
+// 套用 ExtraConfig（SAP HANA 等类型特有字段）。被备份执行与恢复服务共享。
+func buildBackupTaskSpec(cipher *codec.ConfigCipher, task *model.BackupTask, startedAt time.Time, tempDir string) (backup.TaskSpec, error) {
+	excludePatterns := []string{}
+	if strings.TrimSpace(task.ExcludePatterns) != "" {
+		if err := json.Unmarshal([]byte(task.ExcludePatterns), &excludePatterns); err != nil {
+			return backup.TaskSpec{}, apperror.Internal("BACKUP_TASK_DECODE_FAILED", "无法解析排除规则", err)
+		}
+	}
+	password := ""
+	if strings.TrimSpace(task.DBPasswordCiphertext) != "" {
+		plain, err := cipher.Decrypt(task.DBPasswordCiphertext)
+		if err != nil {
+			return backup.TaskSpec{}, apperror.Internal("BACKUP_TASK_DECRYPT_FAILED", "无法解密数据库密码", err)
+		}
+		password = string(plain)
+	}
+	sourcePaths := []string{}
+	if strings.TrimSpace(task.SourcePaths) != "" {
+		if err := json.Unmarshal([]byte(task.SourcePaths), &sourcePaths); err != nil {
+			return backup.TaskSpec{}, apperror.Internal("BACKUP_TASK_DECODE_FAILED", "无法解析源路径配置", err)
+		}
+	}
+	dbSpec := backup.DatabaseSpec{
+		Host:     task.DBHost,
+		Port:     task.DBPort,
+		User:     task.DBUser,
+		Password: password,
+		Names:    []string{task.DBName},
+		Path:     task.DBPath,
+	}
+	// 解析 ExtraConfig 填充类型特有字段（目前主要用于 SAP HANA）
+	if strings.TrimSpace(task.ExtraConfig) != "" {
+		extra := map[string]any{}
+		if err := json.Unmarshal([]byte(task.ExtraConfig), &extra); err != nil {
+			return backup.TaskSpec{}, apperror.Internal("BACKUP_TASK_DECODE_FAILED", "无法解析扩展配置", err)
+		}
+		applyHANAExtraConfig(&dbSpec, extra)
+	}
+	return backup.TaskSpec{
+		ID:              task.ID,
+		Name:            task.Name,
+		Type:            task.Type,
+		SourcePath:      task.SourcePath,
+		SourcePaths:     sourcePaths,
+		ExcludePatterns: excludePatterns,
+		StorageTargetID: task.StorageTargetID,
+		Compression:     task.Compression,
+		Encrypt:         task.Encrypt,
+		RetentionDays:   task.RetentionDays,
+		MaxBackups:      task.MaxBackups,
+		StartedAt:       startedAt,
+		TempDir:         tempDir,
+		Database:        dbSpec,
+	}, nil
+}