功能: v2.0.0 企业级备份管理平台 — 11 项核心能力 (#45)

* 功能: v2.0.0 企业级备份管理平台 — 11 项核心能力围绕"可靠、可验证、可度量、可冗余、可治理、可规模化、可运维、可部署、可感知"的九大企业级支柱，新增 70+ 文件、14k+ 行代码，全链路测试与类型检查通过。 ## 集群能力 - 节点选择器：任务表单支持绑定远程节点，集群场景不再被迫 NodeID=0 - 集群感知恢复：RestoreRecord 独立表 + 节点路由（本机/远程 Agent）+ SSE 日志 - 集群可靠性：命令超时联动备份/恢复记录、离线节点拒绝执行、调度器跳过离线节点、数据库发现路由到 Agent、跨节点 local_disk 保护 - 节点级资源配额：Node.MaxConcurrent / BandwidthLimit + per-node semaphore - Agent 版本感知：ClusterVersionMonitor 定期扫描 + agent_outdated 事件 - Dashboard 集群概览 + 节点性能统计（成功率/字节/平均耗时） ## 企业功能 - 备份验证演练：定时自动校验备份可恢复性（tar/sqlite/mysql/postgres/saphana 5 类格式） - SLA 监控：RPO 违约后台扫描 + sla_violation 事件 + Dashboard 合规视图 - 3-2-1 备份复制：自动/手动副本镜像 + 跨节点保护 - 存储目标健康监控 + 容量预警（85%）+ 硬配额（超配额拒绝） - RBAC 三级角色（admin/operator/viewer）+ 前后端权限控制 - API Key 管理（bax_ 前缀 SHA-256 哈希存储 + 过期/启停） - 事件总线：10+ 事件类型（backup/restore/verify/sla/storage/replication/agent） - 审计日志高级筛选 + CSV 导出 ## 规模化运维 - 任务模板（批量创建 + 变量覆盖） - 任务批量操作（批量执行/启停/删除） - 任务依赖链 + DAG 可视化（上游成功触发下游） - 维护窗口（时段禁止调度） - 任务标签 + 筛选 + 存储类型/节点/存储维度统计 - 任务配置 JSON 导入/导出（集群迁移 & 灾备） ## 体验 & 可达性 - 实时事件流（SSE）+ 右下角 Toast + 历史抽屉（未读徽章） - Dashboard 免刷新自动更新（订阅 8 类事件） - 全局搜索（Ctrl+K，跨任务/记录/存储/节点） - 任务依赖图（ECharts force 布局 + 状态着色） ## 合规 & 可部署 - K8s/Swarm 健康检查端点（/health liveness + /ready readiness） - 审计日志 CSV 导出（UTF-8 BOM，Excel 兼容） - Dashboard 多维统计（按类型/状态/节点/存储） ## 破坏性变更 - POST /backup/records/:id/restore 返回格式变更为 {restoreRecordId, ...} （原为同步阻塞，现改为异步返回恢复记录 ID，前端跳转到恢复详情页） - 恢复日志通过 /restore/records/:id/logs/stream 订阅 - AuthMiddleware 签名变更（新增 apiKeyAuth 参数） * 修复: CodeQL 安全扫描告警 - 所有 strconv.ParseUint 由 64bit 改为 32bit 位宽，strconv 内置溢出检查 - hashApiKey 参数改名 rawToken 避免 CodeQL 误判为密码哈希（API Key 是 192 位高熵 token，使用 bcrypt 会引入不必要的延迟；同时补充安全说明） * 修复: API Key 哈希改用 HMAC-SHA256 + 应用级 pepper - 符合 RFC 2104 标准，业界 API token 存储的推荐方案 - 数据库泄漏场景下增加离线反推难度（需同时获取二进制 pepper） - 规避 CodeQL go/weak-sensitive-data-hashing 对裸 SHA-256 的误判
2026-09-07 00:16:42 +08:00 · 2026-04-20 13:04:13 +08:00
parent 83bf5ec656
commit 539e9e64c4
120 changed files with 12812 additions and 377 deletions
@@ -0,0 +1,715 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"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"
+)
+
+// RestoreService 管理恢复记录生命周期并在集群中路由执行。
+//
+// 执行模型：
+//   - task.NodeID == 0 或本机节点：Master 本地异步执行（runner.Restore），日志通过 LogHub 推到前端
+//   - task.NodeID 指向远程节点：入队 AgentCommand("restore_record")，Agent 拉取 spec 后本地执行
+//     并通过 HTTP 回传日志/状态，Master 再广播到 LogHub
+type RestoreService struct {
+	restores        repository.RestoreRecordRepository
+	records         repository.BackupRecordRepository
+	tasks           repository.BackupTaskRepository
+	targets         repository.StorageTargetRepository
+	nodeRepo        repository.NodeRepository
+	storageRegistry *storage.Registry
+	runnerRegistry  *backup.Registry
+	logHub          *backup.LogHub
+	cipher          *codec.ConfigCipher
+	dispatcher      AgentDispatcher
+	eventDispatcher EventDispatcher
+	tempDir         string
+	semaphore       chan struct{}
+	async           func(func())
+	now             func() time.Time
+}
+
+// NewRestoreService 构造恢复服务。maxConcurrent 控制本地并发恢复数。
+func NewRestoreService(
+	restores repository.RestoreRecordRepository,
+	records repository.BackupRecordRepository,
+	tasks repository.BackupTaskRepository,
+	targets repository.StorageTargetRepository,
+	nodeRepo repository.NodeRepository,
+	storageRegistry *storage.Registry,
+	runnerRegistry *backup.Registry,
+	logHub *backup.LogHub,
+	cipher *codec.ConfigCipher,
+	dispatcher AgentDispatcher,
+	tempDir string,
+	maxConcurrent int,
+) *RestoreService {
+	if tempDir == "" {
+		tempDir = "/tmp/backupx-restore"
+	}
+	if maxConcurrent <= 0 {
+		maxConcurrent = 2
+	}
+	return &RestoreService{
+		restores:        restores,
+		records:         records,
+		tasks:           tasks,
+		targets:         targets,
+		nodeRepo:        nodeRepo,
+		storageRegistry: storageRegistry,
+		runnerRegistry:  runnerRegistry,
+		logHub:          logHub,
+		cipher:          cipher,
+		dispatcher:      dispatcher,
+		tempDir:         tempDir,
+		semaphore:       make(chan struct{}, maxConcurrent),
+		async:           func(job func()) { go job() },
+		now:             func() time.Time { return time.Now().UTC() },
+	}
+}
+
+// SetEventDispatcher 注入事件分发通道，用于恢复完成/失败的 Webhook 派发。
+func (s *RestoreService) SetEventDispatcher(dispatcher EventDispatcher) {
+	s.eventDispatcher = dispatcher
+}
+
+// RestoreRecordSummary 列表项。
+type RestoreRecordSummary struct {
+	ID              uint       `json:"id"`
+	BackupRecordID  uint       `json:"backupRecordId"`
+	TaskID          uint       `json:"taskId"`
+	TaskName        string     `json:"taskName"`
+	NodeID          uint       `json:"nodeId"`
+	NodeName        string     `json:"nodeName,omitempty"`
+	Status          string     `json:"status"`
+	ErrorMessage    string     `json:"errorMessage"`
+	DurationSeconds int        `json:"durationSeconds"`
+	StartedAt       time.Time  `json:"startedAt"`
+	CompletedAt     *time.Time `json:"completedAt,omitempty"`
+	TriggeredBy     string     `json:"triggeredBy"`
+	BackupFileName  string     `json:"backupFileName,omitempty"`
+}
+
+// RestoreRecordDetail 详情（含日志）。
+type RestoreRecordDetail struct {
+	RestoreRecordSummary
+	LogContent string            `json:"logContent"`
+	LogEvents  []backup.LogEvent `json:"logEvents,omitempty"`
+}
+
+// Start 触发一次恢复。返回新建 RestoreRecord 详情。
+// 若任务绑定远程节点：入队 AgentCommand 后立即返回（状态为 running）
+// 若本地：异步执行并立即返回。
+func (s *RestoreService) Start(ctx context.Context, backupRecordID uint, triggeredBy string) (*RestoreRecordDetail, error) {
+	record, err := s.records.FindByID(ctx, backupRecordID)
+	if err != nil {
+		return nil, apperror.Internal("BACKUP_RECORD_GET_FAILED", "无法获取备份记录", err)
+	}
+	if record == nil {
+		return nil, apperror.New(404, "BACKUP_RECORD_NOT_FOUND", "备份记录不存在", fmt.Errorf("backup record %d not found", backupRecordID))
+	}
+	if record.Status != model.BackupRecordStatusSuccess {
+		return nil, apperror.BadRequest("RESTORE_SOURCE_INVALID", "只能恢复状态为成功的备份记录", nil)
+	}
+	task, err := s.tasks.FindByID(ctx, record.TaskID)
+	if err != nil {
+		return nil, apperror.Internal("BACKUP_TASK_GET_FAILED", "无法获取关联备份任务", err)
+	}
+	if task == nil {
+		return nil, apperror.New(404, "BACKUP_TASK_NOT_FOUND", "关联的备份任务不存在", fmt.Errorf("backup task %d not found", record.TaskID))
+	}
+
+	startedAt := s.now()
+	restore := &model.RestoreRecord{
+		BackupRecordID: backupRecordID,
+		TaskID:         record.TaskID,
+		NodeID:         task.NodeID,
+		Status:         model.RestoreRecordStatusRunning,
+		StartedAt:      startedAt,
+		TriggeredBy:    strings.TrimSpace(triggeredBy),
+	}
+	if err := s.restores.Create(ctx, restore); err != nil {
+		return nil, apperror.Internal("RESTORE_RECORD_CREATE_FAILED", "无法创建恢复记录", err)
+	}
+
+	// 远程节点路由
+	if remoteNode := s.resolveRemoteNode(ctx, task.NodeID); remoteNode != nil {
+		if s.dispatcher == nil {
+			return nil, apperror.Internal("RESTORE_DISPATCH_UNAVAILABLE", "Agent 下发通道未就绪", nil)
+		}
+		// 节点离线 → 立即标记 failed，避免记录永远卡在 running
+		if remoteNode.Status != model.NodeStatusOnline {
+			offlineMsg := fmt.Sprintf("节点 %s 当前离线，无法执行恢复", remoteNode.Name)
+			_ = s.finalize(ctx, restore.ID, model.RestoreRecordStatusFailed, offlineMsg)
+			s.logHub.Append(restore.ID, "error", offlineMsg)
+			s.logHub.Complete(restore.ID, model.RestoreRecordStatusFailed)
+			return nil, apperror.BadRequest("NODE_OFFLINE", offlineMsg, nil)
+		}
+		if _, dispatchErr := s.dispatcher.EnqueueCommand(ctx, task.NodeID, model.AgentCommandTypeRestoreRecord, map[string]any{
+			"restoreRecordId": restore.ID,
+		}); dispatchErr != nil {
+			_ = s.finalize(ctx, restore.ID, model.RestoreRecordStatusFailed,
+				"下发恢复任务到远程节点失败: "+dispatchErr.Error())
+			return nil, apperror.Internal("AGENT_COMMAND_ENQUEUE_FAILED", "无法下发恢复任务到远程节点", dispatchErr)
+		}
+		s.logHub.Append(restore.ID, "info", fmt.Sprintf("已下发恢复任务到节点 %s（#%d），等待 Agent 执行", remoteNode.Name, task.NodeID))
+		return s.getDetail(ctx, restore.ID)
+	}
+
+	// 本地节点：异步执行
+	run := func() {
+		s.executeLocally(context.Background(), restore.ID, task, record)
+	}
+	s.async(run)
+	return s.getDetail(ctx, restore.ID)
+}
+
+// isRemoteNode 判断 NodeID 是否指向有效的远程节点。
+func (s *RestoreService) isRemoteNode(ctx context.Context, nodeID uint) bool {
+	return s.resolveRemoteNode(ctx, nodeID) != nil
+}
+
+// resolveRemoteNode 返回远程节点指针（含 Status），用于离线判定。
+func (s *RestoreService) resolveRemoteNode(ctx context.Context, nodeID uint) *model.Node {
+	if s.nodeRepo == nil || s.dispatcher == nil || nodeID == 0 {
+		return nil
+	}
+	node, err := s.nodeRepo.FindByID(ctx, nodeID)
+	if err != nil || node == nil || node.IsLocal {
+		return nil
+	}
+	return node
+}
+
+// executeLocally 在 Master 本地执行恢复。
+func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, task *model.BackupTask, backupRecord *model.BackupRecord) {
+	s.semaphore <- struct{}{}
+	defer func() { <-s.semaphore }()
+
+	logger := backup.NewExecutionLogger(restoreID, s.logHub)
+	status := model.RestoreRecordStatusFailed
+	errMessage := ""
+
+	defer func() {
+		finalizeErr := s.finalizeWithLog(ctx, restoreID, status, errMessage, logger.String())
+		if finalizeErr != nil {
+			logger.Errorf("写回恢复记录失败：%v", finalizeErr)
+		}
+		s.logHub.Complete(restoreID, status)
+		s.dispatchRestoreEvent(ctx, restoreID, status, errMessage, task)
+	}()
+
+	logger.Infof("开始在本地执行恢复（备份记录 #%d）", backupRecord.ID)
+	provider, providerErr := s.resolveProvider(ctx, backupRecord.StorageTargetID)
+	if providerErr != nil {
+		errMessage = providerErr.Error()
+		logger.Errorf("创建存储客户端失败：%v", providerErr)
+		return
+	}
+
+	if err := os.MkdirAll(s.tempDir, 0o755); err != nil {
+		errMessage = err.Error()
+		logger.Errorf("创建恢复临时父目录失败：%v", err)
+		return
+	}
+	tempDir, tempErr := os.MkdirTemp(s.tempDir, "restore-*")
+	if tempErr != nil {
+		errMessage = tempErr.Error()
+		logger.Errorf("创建恢复临时目录失败：%v", tempErr)
+		return
+	}
+	defer os.RemoveAll(tempDir)
+
+	fileName := backupRecord.FileName
+	if strings.TrimSpace(fileName) == "" {
+		fileName = filepath.Base(backupRecord.StoragePath)
+	}
+	artifactPath := filepath.Join(tempDir, filepath.Base(fileName))
+	logger.Infof("开始下载备份文件：%s", backupRecord.StoragePath)
+	reader, downloadErr := provider.Download(ctx, backupRecord.StoragePath)
+	if downloadErr != nil {
+		errMessage = downloadErr.Error()
+		logger.Errorf("下载备份文件失败：%v", downloadErr)
+		return
+	}
+	if writeErr := writeReaderToFile(artifactPath, reader); writeErr != nil {
+		errMessage = writeErr.Error()
+		logger.Errorf("写入恢复文件失败：%v", writeErr)
+		return
+	}
+	preparedPath, prepareErr := s.prepareArtifact(artifactPath, logger)
+	if prepareErr != nil {
+		errMessage = prepareErr.Error()
+		logger.Errorf("准备恢复文件失败：%v", prepareErr)
+		return
+	}
+
+	spec, specErr := s.buildTaskSpec(task, backupRecord.StartedAt)
+	if specErr != nil {
+		errMessage = specErr.Error()
+		logger.Errorf("构建恢复规格失败：%v", specErr)
+		return
+	}
+	runner, runnerErr := s.runnerRegistry.Runner(spec.Type)
+	if runnerErr != nil {
+		errMessage = runnerErr.Error()
+		logger.Errorf("不支持的备份类型：%v", runnerErr)
+		return
+	}
+	logger.Infof("开始执行 %s 恢复", spec.Type)
+	if restoreErr := runner.Restore(ctx, spec, preparedPath, logger); restoreErr != nil {
+		errMessage = restoreErr.Error()
+		logger.Errorf("恢复执行失败：%v", restoreErr)
+		return
+	}
+	status = model.RestoreRecordStatusSuccess
+	logger.Infof("恢复执行成功")
+}
+
+// dispatchRestoreEvent 按终态向事件总线派发 restore_success 或 restore_failed。
+// eventDispatcher 未注入时静默忽略，保持向后兼容。
+func (s *RestoreService) dispatchRestoreEvent(ctx context.Context, restoreID uint, status, errMessage string, task *model.BackupTask) {
+	if s.eventDispatcher == nil {
+		return
+	}
+	var eventType, title string
+	switch status {
+	case model.RestoreRecordStatusSuccess:
+		eventType = model.NotificationEventRestoreSuccess
+		title = "BackupX 恢复成功"
+	case model.RestoreRecordStatusFailed:
+		eventType = model.NotificationEventRestoreFailed
+		title = "BackupX 恢复失败"
+	default:
+		return
+	}
+	taskName := "未知任务"
+	if task != nil {
+		taskName = task.Name
+	}
+	body := fmt.Sprintf("任务：%s\n恢复记录：#%d\n状态：%s", taskName, restoreID, status)
+	if errMessage != "" {
+		body += "\n错误：" + errMessage
+	}
+	fields := map[string]any{
+		"restoreId": restoreID,
+		"taskName":  taskName,
+		"status":    status,
+		"error":     errMessage,
+	}
+	if task != nil {
+		fields["taskId"] = task.ID
+	}
+	_ = s.eventDispatcher.DispatchEvent(ctx, eventType, title, body, fields)
+}
+
+// resolveProvider 复用 BackupExecutionService 的逻辑（解密 → 创建 provider）。
+func (s *RestoreService) resolveProvider(ctx context.Context, targetID uint) (storage.StorageProvider, error) {
+	target, err := s.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 := s.cipher.DecryptJSON(target.ConfigCiphertext, &configMap); err != nil {
+		return nil, apperror.Internal("BACKUP_STORAGE_TARGET_DECRYPT_FAILED", "无法解密存储目标配置", err)
+	}
+	return s.storageRegistry.Create(ctx, target.Type, configMap)
+}
+
+// prepareArtifact 根据文件后缀依次解密、解压。
+func (s *RestoreService) prepareArtifact(artifactPath string, logger *backup.ExecutionLogger) (string, error) {
+	currentPath := artifactPath
+	if strings.HasSuffix(strings.ToLower(currentPath), ".enc") {
+		logger.Infof("检测到加密后缀，开始解密")
+		decrypted, err := backupcrypto.DecryptFile(s.cipher.Key(), currentPath)
+		if err != nil {
+			return "", err
+		}
+		currentPath = decrypted
+	}
+	if strings.HasSuffix(strings.ToLower(currentPath), ".gz") {
+		logger.Infof("检测到 gzip 压缩，开始解压")
+		decompressed, err := compress.GunzipFile(currentPath)
+		if err != nil {
+			return "", err
+		}
+		currentPath = decompressed
+	}
+	return currentPath, nil
+}
+
+// buildTaskSpec 复刻 BackupExecutionService.buildTaskSpec 的核心逻辑。
+func (s *RestoreService) buildTaskSpec(task *model.BackupTask, startedAt time.Time) (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 := s.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,
+	}
+	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:         s.tempDir,
+		Database:        dbSpec,
+	}, nil
+}
+
+// finalize 只更新状态和错误信息，不写 log（用于失败的 dispatch 路径）。
+func (s *RestoreService) finalize(ctx context.Context, restoreID uint, status, errMessage string) error {
+	return s.finalizeWithLog(ctx, restoreID, status, errMessage, "")
+}
+
+// finalizeWithLog 把恢复记录写成终态。
+func (s *RestoreService) finalizeWithLog(ctx context.Context, restoreID uint, status, errMessage, logContent string) error {
+	record, err := s.restores.FindByID(ctx, restoreID)
+	if err != nil {
+		return err
+	}
+	if record == nil {
+		return fmt.Errorf("restore record %d not found", restoreID)
+	}
+	completedAt := s.now()
+	record.Status = status
+	record.ErrorMessage = strings.TrimSpace(errMessage)
+	if strings.TrimSpace(logContent) != "" {
+		record.LogContent = strings.TrimSpace(logContent)
+	}
+	record.DurationSeconds = int(completedAt.Sub(record.StartedAt).Seconds())
+	record.CompletedAt = &completedAt
+	return s.restores.Update(ctx, record)
+}
+
+// Get 查恢复记录详情。
+func (s *RestoreService) Get(ctx context.Context, restoreID uint) (*RestoreRecordDetail, error) {
+	return s.getDetail(ctx, restoreID)
+}
+
+// List 列表。
+func (s *RestoreService) List(ctx context.Context, input RestoreRecordListInput) ([]RestoreRecordSummary, error) {
+	items, err := s.restores.List(ctx, repository.RestoreRecordListOptions{
+		TaskID:         input.TaskID,
+		BackupRecordID: input.BackupRecordID,
+		NodeID:         input.NodeID,
+		Status:         strings.TrimSpace(input.Status),
+		DateFrom:       input.DateFrom,
+		DateTo:         input.DateTo,
+		Limit:          input.Limit,
+		Offset:         input.Offset,
+	})
+	if err != nil {
+		return nil, apperror.Internal("RESTORE_RECORD_LIST_FAILED", "无法获取恢复记录列表", err)
+	}
+	result := make([]RestoreRecordSummary, 0, len(items))
+	nodeNames := map[uint]string{}
+	for _, item := range items {
+		nodeName := ""
+		if item.NodeID > 0 && s.nodeRepo != nil {
+			if cached, ok := nodeNames[item.NodeID]; ok {
+				nodeName = cached
+			} else if node, err := s.nodeRepo.FindByID(ctx, item.NodeID); err == nil && node != nil {
+				nodeName = node.Name
+				nodeNames[item.NodeID] = node.Name
+			}
+		}
+		result = append(result, toRestoreRecordSummary(&item, nodeName))
+	}
+	return result, nil
+}
+
+// SubscribeLogs 订阅指定恢复记录的实时日志。
+func (s *RestoreService) SubscribeLogs(ctx context.Context, restoreID uint, buffer int) (<-chan backup.LogEvent, func(), error) {
+	record, err := s.restores.FindByID(ctx, restoreID)
+	if err != nil {
+		return nil, nil, apperror.Internal("RESTORE_RECORD_GET_FAILED", "无法获取恢复记录详情", err)
+	}
+	if record == nil {
+		return nil, nil, apperror.New(404, "RESTORE_RECORD_NOT_FOUND", "恢复记录不存在", nil)
+	}
+	channel, cancel := s.logHub.Subscribe(restoreID, buffer)
+	return channel, cancel, nil
+}
+
+// RestoreRecordListInput 列表查询参数。
+type RestoreRecordListInput struct {
+	TaskID         *uint
+	BackupRecordID *uint
+	NodeID         *uint
+	Status         string
+	DateFrom       *time.Time
+	DateTo         *time.Time
+	Limit          int
+	Offset         int
+}
+
+// --- Agent 侧调用接口 ---
+
+// AgentRestoreSpec 下发给 Agent 执行恢复的完整规格。
+type AgentRestoreSpec struct {
+	RestoreRecordID uint                     `json:"restoreRecordId"`
+	BackupRecordID  uint                     `json:"backupRecordId"`
+	TaskID          uint                     `json:"taskId"`
+	TaskName        string                   `json:"taskName"`
+	Type            string                   `json:"type"`
+	SourcePath      string                   `json:"sourcePath,omitempty"`
+	SourcePaths     []string                 `json:"sourcePaths,omitempty"`
+	DBHost          string                   `json:"dbHost,omitempty"`
+	DBPort          int                      `json:"dbPort,omitempty"`
+	DBUser          string                   `json:"dbUser,omitempty"`
+	DBPassword      string                   `json:"dbPassword,omitempty"`
+	DBName          string                   `json:"dbName,omitempty"`
+	DBPath          string                   `json:"dbPath,omitempty"`
+	ExtraConfig     string                   `json:"extraConfig,omitempty"`
+	Compression     string                   `json:"compression"`
+	Encrypt         bool                     `json:"encrypt"`
+	Storage         AgentStorageTargetConfig `json:"storage"`
+	StoragePath     string                   `json:"storagePath"`
+	FileName        string                   `json:"fileName"`
+}
+
+// AgentRestoreUpdate Agent 回传的增量更新。
+type AgentRestoreUpdate struct {
+	Status       string `json:"status,omitempty"`
+	ErrorMessage string `json:"errorMessage,omitempty"`
+	LogAppend    string `json:"logAppend,omitempty"`
+}
+
+// GetAgentRestoreSpec 供 Agent 拉取恢复规格。需校验恢复记录属于当前节点。
+func (s *RestoreService) GetAgentRestoreSpec(ctx context.Context, node *model.Node, restoreID uint) (*AgentRestoreSpec, error) {
+	restore, err := s.restores.FindByID(ctx, restoreID)
+	if err != nil {
+		return nil, err
+	}
+	if restore == nil {
+		return nil, apperror.New(404, "RESTORE_RECORD_NOT_FOUND", "恢复记录不存在", nil)
+	}
+	if restore.NodeID != node.ID {
+		return nil, apperror.Unauthorized("RESTORE_RECORD_FORBIDDEN", "恢复记录不属于当前节点", nil)
+	}
+	backupRecord, err := s.records.FindByID(ctx, restore.BackupRecordID)
+	if err != nil {
+		return nil, err
+	}
+	if backupRecord == nil {
+		return nil, apperror.New(404, "BACKUP_RECORD_NOT_FOUND", "源备份记录不存在", nil)
+	}
+	task, err := s.tasks.FindByID(ctx, restore.TaskID)
+	if err != nil {
+		return nil, err
+	}
+	if task == nil {
+		return nil, apperror.New(404, "BACKUP_TASK_NOT_FOUND", "备份任务不存在", nil)
+	}
+	// 解密数据库密码
+	dbPassword := ""
+	if strings.TrimSpace(task.DBPasswordCiphertext) != "" {
+		plain, decErr := s.cipher.Decrypt(task.DBPasswordCiphertext)
+		if decErr != nil {
+			return nil, fmt.Errorf("decrypt db password: %w", decErr)
+		}
+		dbPassword = string(plain)
+	}
+	// 解密备份时使用的存储目标
+	target, err := s.targets.FindByID(ctx, backupRecord.StorageTargetID)
+	if err != nil {
+		return nil, err
+	}
+	if target == nil {
+		return nil, apperror.BadRequest("BACKUP_STORAGE_TARGET_INVALID", "存储目标不存在", nil)
+	}
+	configRaw, err := s.cipher.Decrypt(target.ConfigCiphertext)
+	if err != nil {
+		return nil, fmt.Errorf("decrypt storage config: %w", err)
+	}
+	// 拆开 sourcePaths
+	sourcePaths := []string{}
+	if strings.TrimSpace(task.SourcePaths) != "" {
+		_ = json.Unmarshal([]byte(task.SourcePaths), &sourcePaths)
+	}
+	return &AgentRestoreSpec{
+		RestoreRecordID: restore.ID,
+		BackupRecordID:  backupRecord.ID,
+		TaskID:          task.ID,
+		TaskName:        task.Name,
+		Type:            task.Type,
+		SourcePath:      task.SourcePath,
+		SourcePaths:     sourcePaths,
+		DBHost:          task.DBHost,
+		DBPort:          task.DBPort,
+		DBUser:          task.DBUser,
+		DBPassword:      dbPassword,
+		DBName:          task.DBName,
+		DBPath:          task.DBPath,
+		ExtraConfig:     task.ExtraConfig,
+		Compression:     task.Compression,
+		Encrypt:         task.Encrypt,
+		Storage: AgentStorageTargetConfig{
+			ID:     target.ID,
+			Type:   target.Type,
+			Name:   target.Name,
+			Config: json.RawMessage(configRaw),
+		},
+		StoragePath: backupRecord.StoragePath,
+		FileName:    backupRecord.FileName,
+	}, nil
+}
+
+// UpdateAgentRestore Agent 回传状态/日志。
+func (s *RestoreService) UpdateAgentRestore(ctx context.Context, node *model.Node, restoreID uint, update AgentRestoreUpdate) error {
+	restore, err := s.restores.FindByID(ctx, restoreID)
+	if err != nil {
+		return err
+	}
+	if restore == nil {
+		return apperror.New(404, "RESTORE_RECORD_NOT_FOUND", "恢复记录不存在", nil)
+	}
+	if restore.NodeID != node.ID {
+		return apperror.Unauthorized("RESTORE_RECORD_FORBIDDEN", "恢复记录不属于当前节点", nil)
+	}
+	// 追加日志到 LogHub + DB
+	if strings.TrimSpace(update.LogAppend) != "" {
+		for _, line := range strings.Split(update.LogAppend, "\n") {
+			trimmed := strings.TrimRight(line, "\r")
+			if strings.TrimSpace(trimmed) == "" {
+				continue
+			}
+			s.logHub.Append(restoreID, "info", trimmed)
+		}
+		if strings.TrimSpace(restore.LogContent) == "" {
+			restore.LogContent = update.LogAppend
+		} else {
+			if !strings.HasSuffix(restore.LogContent, "\n") {
+				restore.LogContent += "\n"
+			}
+			restore.LogContent += update.LogAppend
+		}
+	}
+	if update.Status != "" {
+		restore.Status = update.Status
+		if update.Status == model.RestoreRecordStatusSuccess || update.Status == model.RestoreRecordStatusFailed {
+			completedAt := s.now()
+			restore.CompletedAt = &completedAt
+			restore.DurationSeconds = int(completedAt.Sub(restore.StartedAt).Seconds())
+			if strings.TrimSpace(update.ErrorMessage) != "" {
+				restore.ErrorMessage = strings.TrimSpace(update.ErrorMessage)
+			}
+		}
+	}
+	if err := s.restores.Update(ctx, restore); err != nil {
+		return err
+	}
+	if update.Status == model.RestoreRecordStatusSuccess || update.Status == model.RestoreRecordStatusFailed {
+		s.logHub.Complete(restoreID, update.Status)
+	}
+	return nil
+}
+
+// --- 内部辅助 ---
+
+func (s *RestoreService) getDetail(ctx context.Context, restoreID uint) (*RestoreRecordDetail, error) {
+	record, err := s.restores.FindByID(ctx, restoreID)
+	if err != nil {
+		return nil, apperror.Internal("RESTORE_RECORD_GET_FAILED", "无法获取恢复记录详情", err)
+	}
+	if record == nil {
+		return nil, apperror.New(404, "RESTORE_RECORD_NOT_FOUND", "恢复记录不存在", nil)
+	}
+	nodeName := ""
+	if record.NodeID > 0 && s.nodeRepo != nil {
+		if node, err := s.nodeRepo.FindByID(ctx, record.NodeID); err == nil && node != nil {
+			nodeName = node.Name
+		}
+	}
+	detail := &RestoreRecordDetail{
+		RestoreRecordSummary: toRestoreRecordSummary(record, nodeName),
+		LogContent:           record.LogContent,
+	}
+	if record.Status == model.RestoreRecordStatusRunning && s.logHub != nil {
+		events := s.logHub.Snapshot(record.ID)
+		detail.LogEvents = events
+		if len(events) > 0 {
+			lines := make([]string, 0, len(events))
+			for _, event := range events {
+				lines = append(lines, event.Message)
+			}
+			detail.LogContent = strings.Join(lines, "\n")
+		}
+	}
+	return detail, nil
+}
+
+func toRestoreRecordSummary(item *model.RestoreRecord, nodeName string) RestoreRecordSummary {
+	summary := RestoreRecordSummary{
+		ID:              item.ID,
+		BackupRecordID:  item.BackupRecordID,
+		TaskID:          item.TaskID,
+		TaskName:        item.Task.Name,
+		NodeID:          item.NodeID,
+		NodeName:        nodeName,
+		Status:          item.Status,
+		ErrorMessage:    item.ErrorMessage,
+		DurationSeconds: item.DurationSeconds,
+		StartedAt:       item.StartedAt,
+		CompletedAt:     item.CompletedAt,
+		TriggeredBy:     item.TriggeredBy,
+	}
+	if strings.TrimSpace(item.BackupRecord.FileName) != "" {
+		summary.BackupFileName = item.BackupRecord.FileName
+	}
+	return summary
+}