feat(backup): 新增 CDC 内容寻址仓库模式

使用内容定义分块、不可变 pack 与快照索引实现跨文件和跨快照去重。接入多目标上传、软配额、恢复、下载、校验、保留和安全垃圾回收，并补充前端入口、中英文文档及端到端测试。 Closes #94
2026-09-05 23:47:33 +08:00 · 2026-08-07 05:53:16 +08:00
parent 50ce6587d8
commit 05dd1baa61
21 changed files with 2391 additions and 45 deletions
@@ -2,11 +2,13 @@ package retention

 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"sort"
 	"strings"
 	"time"

+	"backupx/server/internal/backup"
 	"backupx/server/internal/model"
 	"backupx/server/internal/repository"
 	"backupx/server/internal/storage"
@@ -40,16 +42,48 @@ type CleanupResult struct {
 	Warnings       []string
 }

-type Service struct {
-	records repository.BackupRecordRepository
-	now     func() time.Time
+type cleanupObject struct {
+	targetID uint
+	path     string
 }

-func NewService(records repository.BackupRecordRepository) *Service {
-	return &Service{records: records, now: func() time.Time { return time.Now().UTC() }}
+type storedUploadResult struct {
+	StorageTargetID uint   `json:"storageTargetId"`
+	Status          string `json:"status"`
+	StoragePath     string `json:"storagePath"`
+}
+
+type Service struct {
+	records       repository.BackupRecordRepository
+	repositoryKey []byte
+	now           func() time.Time
+}
+
+func NewService(records repository.BackupRecordRepository, repositoryKey ...[]byte) *Service {
+	var key []byte
+	if len(repositoryKey) > 0 {
+		key = append([]byte(nil), repositoryKey[0]...)
+	}
+	return &Service{records: records, repositoryKey: key, now: func() time.Time { return time.Now().UTC() }}
 }

 func (s *Service) Cleanup(ctx context.Context, task *model.BackupTask, provider storage.StorageProvider) (*CleanupResult, error) {
+	return s.cleanup(ctx, task, func(uint) (storage.StorageProvider, bool) {
+		return provider, provider != nil
+	})
+}
+
+// CleanupProviders applies one retention decision to every successful copy of
+// a record before deleting its database row. This prevents multi-target tasks
+// from leaving stale objects after the first target removes the shared record.
+func (s *Service) CleanupProviders(ctx context.Context, task *model.BackupTask, providers map[uint]storage.StorageProvider) (*CleanupResult, error) {
+	return s.cleanup(ctx, task, func(targetID uint) (storage.StorageProvider, bool) {
+		provider, ok := providers[targetID]
+		return provider, ok && provider != nil
+	})
+}
+
+func (s *Service) cleanup(ctx context.Context, task *model.BackupTask, resolveProvider func(uint) (storage.StorageProvider, bool)) (*CleanupResult, error) {
 	if task == nil {
 		return nil, fmt.Errorf("backup task is required")
 	}
@@ -67,17 +101,35 @@ func (s *Service) Cleanup(ctx context.Context, task *model.BackupTask, provider
 	// 差异链保护：保留仍被存活差异依赖的全量，避免删除基线后差异无法恢复。
 	candidates = protectDifferentialBases(records, candidates)
 	result := &CleanupResult{}
+	repositoryProviders := make(map[uint]storage.StorageProvider)
+	touchedProviders := make(map[uint]storage.StorageProvider)
 	for _, record := range candidates {
-		if strings.TrimSpace(record.StoragePath) != "" {
-			if provider == nil {
-				result.Warnings = append(result.Warnings, fmt.Sprintf("record %d missing storage provider for cleanup", record.ID))
+		objects, objectErr := cleanupObjectsForRecord(record)
+		if objectErr != nil {
+			result.Warnings = append(result.Warnings, fmt.Sprintf("decode storage copies for record %d failed: %v", record.ID, objectErr))
+			continue
+		}
+		allObjectsDeleted := true
+		for _, object := range objects {
+			provider, ok := resolveProvider(object.targetID)
+			if !ok {
+				result.Warnings = append(result.Warnings, fmt.Sprintf("record %d missing storage provider %d for cleanup", record.ID, object.targetID))
+				allObjectsDeleted = false
 				continue
 			}
-			if err := provider.Delete(ctx, record.StoragePath); err != nil {
-				result.Warnings = append(result.Warnings, fmt.Sprintf("delete storage object %s failed: %v", record.StoragePath, err))
+			if err := provider.Delete(ctx, object.path); err != nil {
+				result.Warnings = append(result.Warnings, fmt.Sprintf("delete storage object %s from target %d failed: %v", object.path, object.targetID, err))
+				allObjectsDeleted = false
 				continue
 			}
 			result.DeletedObjects++
+			touchedProviders[object.targetID] = provider
+			if record.BackupKind == model.BackupKindRepository {
+				repositoryProviders[object.targetID] = provider
+			}
+		}
+		if !allObjectsDeleted {
+			continue
 		}
 		if err := s.records.Delete(ctx, record.ID); err != nil {
 			result.Warnings = append(result.Warnings, fmt.Sprintf("delete backup record %d failed: %v", record.ID, err))
@@ -85,13 +137,25 @@ func (s *Service) Cleanup(ctx context.Context, task *model.BackupTask, provider
 		}
 		result.DeletedRecords++
 	}
+	for targetID, provider := range repositoryProviders {
+		pruned, pruneErr := backup.NewRepositoryStore(s.repositoryKey).Prune(ctx, provider)
+		if pruneErr != nil {
+			result.Warnings = append(result.Warnings, fmt.Sprintf("prune CDC repository on target %d failed: %v", targetID, pruneErr))
+		} else {
+			result.DeletedObjects += pruned.DeletedPacks + pruned.DeletedIndexes
+		}
+	}

 	// 清理空目录：收集被删除文件的父目录，尝试移除空目录
-	if dirCleaner, ok := provider.(storage.StorageDirCleaner); ok && result.DeletedObjects > 0 {
+	for targetID, provider := range touchedProviders {
+		dirCleaner, ok := provider.(storage.StorageDirCleaner)
+		if !ok {
+			continue
+		}
 		prefixes := collectDirPrefixes(candidates)
 		for _, prefix := range prefixes {
 			if err := dirCleaner.RemoveEmptyDirs(ctx, prefix); err != nil {
-				result.Warnings = append(result.Warnings, fmt.Sprintf("cleanup empty dirs for %s: %v", prefix, err))
+				result.Warnings = append(result.Warnings, fmt.Sprintf("cleanup empty dirs for %s on target %d: %v", prefix, targetID, err))
 			}
 		}
 	}
@@ -99,6 +163,43 @@ func (s *Service) Cleanup(ctx context.Context, task *model.BackupTask, provider
 	return result, nil
 }

+func cleanupObjectsForRecord(record model.BackupRecord) ([]cleanupObject, error) {
+	defaultPath := strings.TrimSpace(record.StoragePath)
+	if strings.TrimSpace(record.StorageUploadResults) == "" {
+		if defaultPath == "" {
+			return nil, nil
+		}
+		return []cleanupObject{{targetID: record.StorageTargetID, path: defaultPath}}, nil
+	}
+	var results []storedUploadResult
+	if err := json.Unmarshal([]byte(record.StorageUploadResults), &results); err != nil {
+		return nil, err
+	}
+	objects := make([]cleanupObject, 0, len(results))
+	seen := make(map[uint]struct{}, len(results))
+	for _, result := range results {
+		if !strings.EqualFold(strings.TrimSpace(result.Status), model.BackupRecordStatusSuccess) {
+			continue
+		}
+		objectPath := strings.TrimSpace(result.StoragePath)
+		if objectPath == "" {
+			objectPath = defaultPath
+		}
+		if objectPath == "" {
+			continue
+		}
+		if _, exists := seen[result.StorageTargetID]; exists {
+			continue
+		}
+		seen[result.StorageTargetID] = struct{}{}
+		objects = append(objects, cleanupObject{targetID: result.StorageTargetID, path: objectPath})
+	}
+	if len(objects) == 0 && defaultPath != "" {
+		return nil, fmt.Errorf("successful record has no successful storage copy")
+	}
+	return objects, nil
+}
+
 // protectDifferentialBases 从删除候选中剔除「仍被存活差异依赖的全量」，
 // 避免删除基线后其差异备份失去依据、无法恢复。全量仅当其全部差异都已过期/删除时才会被清理。
 func protectDifferentialBases(all []model.BackupRecord, candidates []model.BackupRecord) []model.BackupRecord {
@@ -221,3 +221,66 @@ func TestCleanupDeletesExpiredRecords(t *testing.T) {
 		t.Fatalf("unexpected deleted objects: %#v", provider.deleted)
 	}
 }
+
+func TestCleanupProvidersDeletesEverySuccessfulCopyBeforeRecord(t *testing.T) {
+	now := time.Date(2026, 3, 7, 16, 0, 0, 0, time.UTC)
+	completedNew := now.Add(-time.Hour)
+	completedOld := now.Add(-24 * time.Hour)
+	repo := &fakeRecordRepository{records: []model.BackupRecord{
+		{ID: 2, TaskID: 1, StoragePath: "records/2", Status: model.BackupRecordStatusSuccess, CompletedAt: &completedNew},
+		{
+			ID: 1, TaskID: 1, StoragePath: "records/1", Status: model.BackupRecordStatusSuccess, CompletedAt: &completedOld,
+			StorageUploadResults: `[{"storageTargetId":11,"status":"success","storagePath":"first/1"},{"storageTargetId":12,"status":"success","storagePath":"second/1"},{"storageTargetId":13,"status":"failed"}]`,
+		},
+	}}
+	first := &fakeProvider{}
+	second := &fakeProvider{}
+	service := NewService(repo)
+	service.now = func() time.Time { return now }
+
+	result, err := service.CleanupProviders(context.Background(), &model.BackupTask{ID: 1, MaxBackups: 1}, map[uint]storage.StorageProvider{
+		11: first,
+		12: second,
+	})
+	if err != nil {
+		t.Fatalf("CleanupProviders returned error: %v", err)
+	}
+	if result.DeletedRecords != 1 || result.DeletedObjects != 2 || len(result.Warnings) != 0 {
+		t.Fatalf("unexpected cleanup result: %#v", result)
+	}
+	if len(repo.deleted) != 1 || repo.deleted[0] != 1 {
+		t.Fatalf("unexpected deleted records: %#v", repo.deleted)
+	}
+	if len(first.deleted) != 1 || first.deleted[0] != "first/1" {
+		t.Fatalf("unexpected first-target deletes: %#v", first.deleted)
+	}
+	if len(second.deleted) != 1 || second.deleted[0] != "second/1" {
+		t.Fatalf("unexpected second-target deletes: %#v", second.deleted)
+	}
+}
+
+func TestCleanupProvidersKeepsRecordWhenCopyProviderIsUnavailable(t *testing.T) {
+	now := time.Date(2026, 3, 7, 16, 0, 0, 0, time.UTC)
+	completedNew := now.Add(-time.Hour)
+	completedOld := now.Add(-24 * time.Hour)
+	repo := &fakeRecordRepository{records: []model.BackupRecord{
+		{ID: 2, TaskID: 1, StoragePath: "records/2", Status: model.BackupRecordStatusSuccess, CompletedAt: &completedNew},
+		{
+			ID: 1, TaskID: 1, StoragePath: "records/1", Status: model.BackupRecordStatusSuccess, CompletedAt: &completedOld,
+			StorageUploadResults: `[{"storageTargetId":11,"status":"success","storagePath":"first/1"},{"storageTargetId":12,"status":"success","storagePath":"second/1"}]`,
+		},
+	}}
+	first := &fakeProvider{}
+	service := NewService(repo)
+
+	result, err := service.CleanupProviders(context.Background(), &model.BackupTask{ID: 1, MaxBackups: 1}, map[uint]storage.StorageProvider{11: first})
+	if err != nil {
+		t.Fatalf("CleanupProviders returned error: %v", err)
+	}
+	if result.DeletedRecords != 0 || result.DeletedObjects != 1 || len(result.Warnings) != 1 {
+		t.Fatalf("unexpected safe partial-cleanup result: %#v", result)
+	}
+	if len(repo.deleted) != 0 {
+		t.Fatalf("record must remain until all copies are deleted: %#v", repo.deleted)
+	}
+}