refactor(layout): consolidate backend codebase into backend/ package and clean root directory

- Moved cmd/, core/, plugins/, pkg/, downstream/, and main.go into backend/ directory
- Batch updated all Go source files to import github.com/Rain-kl/Wavelet/backend/...
- Updated Makefile, scripts/swagger.sh, architecture guards, and platform skills
- Passed all quality gates (100% tests, 0 lint issues, clean build)

backend/plugins/domain/upload/cache/access_cache.go

@@ -0,0 +1,145 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cache provides in-process upload access-control caches.
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+	cachepkg "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+const fileAccessInvalidationChannel = "upload:file_access_invalidation"
+
+var (
+	accessCacheOnce sync.Once
+
+	fileAccessWhitelistMu        sync.RWMutex
+	fileAccessWhitelistTypes     map[string]struct{}
+	fileAccessWhitelistValid     bool
+	fileAccessWhitelistCheckedAt time.Time
+)
+
+// ResetAccessCaches clears in-process upload access caches.
+func ResetAccessCaches() {
+	uploadstorage.ResetMigrationAccessCache()
+
+	fileAccessWhitelistMu.Lock()
+	fileAccessWhitelistValid = false
+	fileAccessWhitelistTypes = nil
+	fileAccessWhitelistMu.Unlock()
+}
+
+// PublishAccessCacheInvalidation broadcasts upload access cache eviction to all nodes.
+func PublishAccessCacheInvalidation(ctx context.Context) {
+	if cachepkg.Redis != nil {
+		_ = cachepkg.Redis.Publish(ctx, fileAccessInvalidationChannel, "reset").Err()
+	}
+}
+
+func ensureAccessCacheListener() {
+	accessCacheOnce.Do(startAccessCacheInvalidationListener)
+}
+
+func startAccessCacheInvalidationListener() {
+	rdb := cachepkg.Redis
+	if rdb == nil {
+		return
+	}
+
+	util.Go(func() {
+		pubsub := rdb.Subscribe(
+			context.Background(),
+			objectstore.ConfigInvalidationChannel,
+			fileAccessInvalidationChannel,
+		)
+		defer func() {
+			_ = pubsub.Close()
+		}()
+
+		for range pubsub.Channel() {
+			ResetAccessCaches()
+		}
+	})
+}
+
+// IsFilePublic reports whether uploadType is in the public access whitelist.
+func IsFilePublic(ctx context.Context, uploadType string) bool {
+	whitelist := loadFileAccessWhitelist(ctx)
+	_, ok := whitelist[strings.ToLower(uploadType)]
+	return ok
+}
+
+func loadFileAccessWhitelist(ctx context.Context) map[string]struct{} {
+	ensureAccessCacheListener()
+
+	fileAccessWhitelistMu.RLock()
+	if fileAccessWhitelistValid && time.Since(fileAccessWhitelistCheckedAt) < time.Duration(shared.AccessCacheTTL)*time.Second {
+		types := fileAccessWhitelistTypes
+		fileAccessWhitelistMu.RUnlock()
+		return types
+	}
+	fileAccessWhitelistMu.RUnlock()
+
+	fileAccessWhitelistMu.Lock()
+	defer fileAccessWhitelistMu.Unlock()
+
+	if fileAccessWhitelistValid && time.Since(fileAccessWhitelistCheckedAt) < time.Duration(shared.AccessCacheTTL)*time.Second {
+		return fileAccessWhitelistTypes
+	}
+
+	fileAccessWhitelistTypes = fetchFileAccessWhitelist(ctx)
+	fileAccessWhitelistValid = true
+	fileAccessWhitelistCheckedAt = time.Now()
+	return fileAccessWhitelistTypes
+}
+
+func fetchFileAccessWhitelist(ctx context.Context) map[string]struct{} {
+	whitelist := parseFileAccessWhitelist(ctx)
+	types := make(map[string]struct{}, len(whitelist))
+	for _, item := range whitelist {
+		types[strings.ToLower(item)] = struct{}{}
+	}
+	return types
+}
+
+func parseFileAccessWhitelist(ctx context.Context) []string {
+	var sc struct{ Value string }
+	err := database.DB(ctx).Table("w_system_configs").Where("key = ?", "file_access_whitelist").First(&sc).Error
+	if err != nil || sc.Value == "" {
+		return []string{shared.DefaultPublicUploadType}
+	}
+
+	var whitelist []string
+	if err := json.Unmarshal([]byte(sc.Value), &whitelist); err == nil && len(whitelist) > 0 {
+		return whitelist
+	}
+
+	whitelist = parseCommaSeparatedWhitelist(sc.Value)
+	if len(whitelist) == 0 {
+		return []string{shared.DefaultPublicUploadType}
+	}
+	return whitelist
+}
+
+func parseCommaSeparatedWhitelist(value string) []string {
+	parts := strings.Split(value, ",")
+	whitelist := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part != "" {
+			whitelist = append(whitelist, part)
+		}
+	}
+	return whitelist
+}

backend/plugins/domain/upload/cache/access_cache_test.go

@@ -0,0 +1,89 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+)
+
+func TestLoadMigrationAccessStateCachesResult(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetAccessCaches()
+
+	ctx := context.Background()
+	first := uploadstorage.LoadMigrationAccessState(ctx)
+	second := uploadstorage.LoadMigrationAccessState(ctx)
+
+	if first.ReadOnly != second.ReadOnly {
+		t.Fatalf("readOnly mismatch: first=%v second=%v", first.ReadOnly, second.ReadOnly)
+	}
+	if first.HasTarget != second.HasTarget {
+		t.Fatalf("hasTarget mismatch: first=%v second=%v", first.HasTarget, second.HasTarget)
+	}
+}
+
+func TestIsFilePublicUsesCachedWhitelist(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetAccessCaches()
+
+	ctx := context.Background()
+	if !IsFilePublic(ctx, "avatar") {
+		t.Fatal("expected avatar to be public by default")
+	}
+	if IsFilePublic(ctx, "attachment") {
+		t.Fatal("expected attachment to be private by default")
+	}
+	if !IsFilePublic(ctx, "AVATAR") {
+		t.Fatal("expected whitelist lookup to be case-insensitive")
+	}
+}
+
+func TestResetAccessCachesRefreshesWhitelist(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetAccessCaches()
+
+	ctx := context.Background()
+	if !IsFilePublic(ctx, "avatar") {
+		t.Fatal("expected seeded avatar whitelist before reset")
+	}
+
+	if err := dbConn.Table("w_system_configs").Where("key = ?", "file_access_whitelist").Update("value", `["attachment"]`).Error; err != nil {
+		t.Fatalf("update whitelist config: %v", err)
+	}
+
+	ResetAccessCaches()
+	if !IsFilePublic(ctx, "attachment") {
+		t.Fatal("expected attachment to be public after whitelist refresh")
+	}
+	if IsFilePublic(ctx, "avatar") {
+		t.Fatal("expected avatar to be private after whitelist refresh")
+	}
+}
+
+func TestAccessCacheTTLExpires(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetAccessCaches()
+
+	ctx := context.Background()
+	_ = loadFileAccessWhitelist(ctx)
+
+	fileAccessWhitelistMu.Lock()
+	fileAccessWhitelistCheckedAt = time.Now().Add(-time.Duration(shared.AccessCacheTTL)*time.Second - time.Second)
+	fileAccessWhitelistMu.Unlock()
+
+	// Should still work after TTL by reloading from config.
+	if !IsFilePublic(ctx, "avatar") {
+		t.Fatal("expected whitelist reload after TTL expiration")
+	}
+}

backend/plugins/domain/upload/cache/meta_cache.go

@@ -0,0 +1,161 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sync"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/cache/ram"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	cachepkg "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+const (
+	uploadMetaRedisCacheTTL    = 30 * 60 // seconds
+	uploadMetaRAMMaximumSize   = 4096
+	uploadMetaInvalidationChan = "upload:meta_invalidation"
+)
+
+type uploadMetaInvalidationMessage struct {
+	ID uint64 `json:"id"`
+}
+
+var (
+	uploadMetaRAM            = ram.MustNew[uint64, models.Upload](ram.Options{MaximumSize: uploadMetaRAMMaximumSize})
+	uploadMetaListenerOnce   sync.Once
+	uploadMetaListenerCtx    context.Context
+	uploadMetaListenerCancel context.CancelFunc
+	uploadMetaListenerDone   chan struct{}
+)
+
+func uploadMetaRedisKey(id uint64) string {
+	return fmt.Sprintf("upload:meta:%d", id)
+}
+
+func cloneUpload(u models.Upload) models.Upload {
+	return u
+}
+
+func ensureUploadMetaCacheListener() {
+	if cachepkg.Redis == nil {
+		return
+	}
+	uploadMetaListenerOnce.Do(startUploadMetaCacheInvalidationListener)
+}
+
+func startUploadMetaCacheInvalidationListener() {
+	uploadMetaListenerCtx, uploadMetaListenerCancel = context.WithCancel(context.Background())
+	uploadMetaListenerDone = make(chan struct{})
+
+	redisClient := cachepkg.Redis // 捕获当前客户端：goroutine 不读可变全局，避免与测试置空 cachepkg.Redis 竞争
+	util.Go(func() {
+		defer close(uploadMetaListenerDone)
+		pubsub := redisClient.Subscribe(uploadMetaListenerCtx, uploadMetaInvalidationChan)
+		defer func() {
+			_ = pubsub.Close()
+		}()
+
+		util.Go(func() {
+			<-uploadMetaListenerCtx.Done()
+			_ = pubsub.Close()
+		})
+
+		for msg := range pubsub.Channel() {
+			var payload uploadMetaInvalidationMessage
+			if err := json.Unmarshal([]byte(msg.Payload), &payload); err != nil || payload.ID == 0 {
+				uploadMetaRAM.InvalidateAll()
+				continue
+			}
+			uploadMetaRAM.Invalidate(payload.ID)
+		}
+	})
+}
+
+func publishUploadMetaRAMInvalidation(ctx context.Context, id uint64) {
+	if cachepkg.Redis == nil {
+		return
+	}
+	payload, err := json.Marshal(uploadMetaInvalidationMessage{ID: id})
+	if err != nil {
+		return
+	}
+	_ = cachepkg.Redis.Publish(ctx, uploadMetaInvalidationChan, payload).Err()
+}
+
+// GetUploadByID loads upload metadata from RAM, Redis, or the database.
+func GetUploadByID(ctx context.Context, id uint64) (models.Upload, error) {
+	ensureUploadMetaCacheListener()
+
+	if u, ok := uploadMetaRAM.GetIfPresent(id); ok {
+		return cloneUpload(u), nil
+	}
+
+	key := uploadMetaRedisKey(id)
+	if cachepkg.Redis != nil {
+		var u models.Upload
+		if err := cachepkg.GetJSON(ctx, key, &u); err == nil {
+			uploadMetaRAM.Set(id, cloneUpload(u))
+			return u, nil
+		}
+	}
+
+	var u models.Upload
+	if err := database.DB(ctx).
+		Where("id = ? AND status IN (?, ?)", id, models.UploadStatusPending, models.UploadStatusUsed).
+		First(&u).Error; err != nil {
+		return models.Upload{}, err
+	}
+
+	SetUploadMetaCache(ctx, &u)
+	return u, nil
+}
+
+// SetUploadMetaCache populates RAM and Redis upload metadata caches.
+func SetUploadMetaCache(ctx context.Context, u *models.Upload) {
+	ensureUploadMetaCacheListener()
+
+	if u == nil {
+		return
+	}
+
+	cloned := cloneUpload(*u)
+	uploadMetaRAM.Set(u.ID, cloned)
+	if cachepkg.Redis != nil {
+		_ = cachepkg.SetJSON(ctx, uploadMetaRedisKey(u.ID), cloned, uploadMetaRedisCacheTTL)
+	}
+}
+
+// InvalidateUploadMetaCache clears RAM and Redis upload metadata caches and notifies peer nodes.
+func InvalidateUploadMetaCache(ctx context.Context, id uint64) {
+	ensureUploadMetaCacheListener()
+
+	uploadMetaRAM.Invalidate(id)
+	if cachepkg.Redis != nil {
+		_ = cachepkg.Redis.Del(ctx, cachepkg.PrefixedKey(uploadMetaRedisKey(id))).Err()
+		publishUploadMetaRAMInvalidation(ctx, id)
+	}
+}
+
+// ResetUploadMetaCacheForTest clears the in-process upload metadata RAM cache.
+func ResetUploadMetaCacheForTest() {
+	uploadMetaRAM.InvalidateAll()
+}
+
+// StopUploadMetaCacheListener stops the Redis Pub/Sub subscription listener and resets the sync.Once guard.
+func StopUploadMetaCacheListener() {
+	if uploadMetaListenerCancel != nil {
+		uploadMetaListenerCancel()
+		if uploadMetaListenerDone != nil {
+			<-uploadMetaListenerDone // 等待 goroutine 退出，保证之后置空 cachepkg.Redis 不再竞争
+		}
+		uploadMetaListenerCancel = nil
+		uploadMetaListenerDone = nil
+	}
+	uploadMetaListenerOnce = sync.Once{}
+}

backend/plugins/domain/upload/cache/meta_cache_test.go

@@ -0,0 +1,287 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	cachepkg "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	"gorm.io/gorm"
+)
+
+func init() {
+	testhelper.RegisterCleanup(func() {
+		StopUploadMetaCacheListener()
+		ResetUploadMetaCacheForTest()
+	})
+}
+
+func seedUpload(t *testing.T, dbConn *gorm.DB, upload models.Upload) {
+	t.Helper()
+	if err := dbConn.Create(&upload).Error; err != nil {
+		t.Fatalf("create upload: %v", err)
+	}
+}
+
+func TestGetUploadByIDLoadsFromDBAndPopulatesCache(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetUploadMetaCacheForTest()
+
+	ctx := context.Background()
+	upload := models.Upload{
+		ID:         91001,
+		UserID:     1,
+		FileName:   "cached.png",
+		FilePath:   "cached.png",
+		FileSize:   12,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+	seedUpload(t, dbConn, upload)
+
+	got, err := GetUploadByID(ctx, upload.ID)
+	if err != nil {
+		t.Fatalf("GetUploadByID: %v", err)
+	}
+	if got.ID != upload.ID || got.FileName != upload.FileName {
+		t.Fatalf("unexpected upload: %+v", got)
+	}
+
+	var redisUpload models.Upload
+	if err := cachepkg.GetJSON(ctx, uploadMetaRedisKey(upload.ID), &redisUpload); err != nil {
+		t.Fatalf("redis cache miss after DB load: %v", err)
+	}
+	if redisUpload.ID != upload.ID {
+		t.Fatalf("redis upload id mismatch: got=%d want=%d", redisUpload.ID, upload.ID)
+	}
+
+	if err := dbConn.Delete(&models.Upload{}, upload.ID).Error; err != nil {
+		t.Fatalf("delete upload from db: %v", err)
+	}
+
+	gotCached, err := GetUploadByID(ctx, upload.ID)
+	if err != nil {
+		t.Fatalf("GetUploadByID from RAM cache: %v", err)
+	}
+	if gotCached.ID != upload.ID {
+		t.Fatalf("expected RAM cache hit for upload %d", upload.ID)
+	}
+}
+
+func TestGetUploadByIDReadsFromRedisWhenRAMEmpty(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetUploadMetaCacheForTest()
+
+	ctx := context.Background()
+	upload := models.Upload{
+		ID:         91002,
+		UserID:     1,
+		FileName:   "redis.png",
+		FilePath:   "redis.png",
+		FileSize:   8,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusPending,
+		AccessMode: 0,
+	}
+	seedUpload(t, dbConn, upload)
+	SetUploadMetaCache(ctx, &upload)
+	ResetUploadMetaCacheForTest()
+
+	if err := dbConn.Delete(&models.Upload{}, upload.ID).Error; err != nil {
+		t.Fatalf("delete upload from db: %v", err)
+	}
+
+	got, err := GetUploadByID(ctx, upload.ID)
+	if err != nil {
+		t.Fatalf("GetUploadByID from redis: %v", err)
+	}
+	if got.ID != upload.ID || got.FileName != upload.FileName {
+		t.Fatalf("unexpected upload from redis: %+v", got)
+	}
+}
+
+func TestInvalidateUploadMetaCacheClearsRAMAndRedis(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetUploadMetaCacheForTest()
+
+	ctx := context.Background()
+	upload := models.Upload{
+		ID:         91003,
+		UserID:     1,
+		FileName:   "invalidate.png",
+		FilePath:   "invalidate.png",
+		FileSize:   4,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+	seedUpload(t, dbConn, upload)
+	SetUploadMetaCache(ctx, &upload)
+
+	InvalidateUploadMetaCache(ctx, upload.ID)
+
+	var redisUpload models.Upload
+	if err := cachepkg.GetJSON(ctx, uploadMetaRedisKey(upload.ID), &redisUpload); err == nil {
+		t.Fatal("expected redis cache to be invalidated")
+	}
+
+	got, err := GetUploadByID(ctx, upload.ID)
+	if err != nil {
+		t.Fatalf("GetUploadByID after invalidate should reload from DB: %v", err)
+	}
+	if got.ID != upload.ID {
+		t.Fatalf("unexpected upload reloaded from DB: %+v", got)
+	}
+}
+
+func TestUploadMetaInvalidationPubSubClearsPeerRAM(t *testing.T) {
+	StopUploadMetaCacheListener()
+	defer StopUploadMetaCacheListener()
+
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetUploadMetaCacheForTest()
+
+	ctx := context.Background()
+	upload := models.Upload{
+		ID:         91006,
+		UserID:     1,
+		FileName:   "pubsub.png",
+		FilePath:   "pubsub.png",
+		FileSize:   4,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+	seedUpload(t, dbConn, upload)
+
+	if _, err := GetUploadByID(ctx, upload.ID); err != nil {
+		t.Fatalf("GetUploadByID: %v", err)
+	}
+	time.Sleep(50 * time.Millisecond) // allow pub/sub listener to subscribe
+	if err := dbConn.Delete(&models.Upload{}, upload.ID).Error; err != nil {
+		t.Fatalf("delete upload from db: %v", err)
+	}
+	if _, err := GetUploadByID(ctx, upload.ID); err != nil {
+		t.Fatalf("expected cache hit before pub/sub invalidation: %v", err)
+	}
+
+	payload, err := json.Marshal(uploadMetaInvalidationMessage{ID: upload.ID})
+	if err != nil {
+		t.Fatalf("marshal invalidation payload: %v", err)
+	}
+	if err := cachepkg.Redis.Publish(ctx, uploadMetaInvalidationChan, string(payload)).Err(); err != nil {
+		t.Fatalf("publish invalidation: %v", err)
+	}
+
+	deadline := time.Now().Add(2 * time.Second)
+	ramCleared := false
+	for time.Now().Before(deadline) {
+		if _, ok := uploadMetaRAM.GetIfPresent(upload.ID); !ok {
+			ramCleared = true
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if !ramCleared {
+		t.Fatal("expected peer RAM cache to be cleared by pub/sub")
+	}
+
+	if err := cachepkg.Redis.Del(ctx, cachepkg.PrefixedKey(uploadMetaRedisKey(upload.ID))).Err(); err != nil {
+		t.Fatalf("delete redis cache: %v", err)
+	}
+	if _, err := GetUploadByID(ctx, upload.ID); err == nil {
+		t.Fatal("expected cache miss after pub/sub RAM eviction and redis delete")
+	}
+}
+
+func TestGetUploadByIDSkipsDeletedUploads(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetUploadMetaCacheForTest()
+
+	ctx := context.Background()
+	upload := models.Upload{
+		ID:         91004,
+		UserID:     1,
+		FileName:   "deleted.png",
+		FilePath:   "deleted.png",
+		FileSize:   4,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusDeleted,
+		AccessMode: 1,
+	}
+	seedUpload(t, dbConn, upload)
+
+	if _, err := GetUploadByID(ctx, upload.ID); err == nil {
+		t.Fatal("expected error for deleted upload")
+	}
+}
+
+func TestGetUploadByIDWorksWithRedisDisabled(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ResetUploadMetaCacheForTest()
+
+	redisClient := cachepkg.Redis
+	cachepkg.Redis = nil
+	t.Cleanup(func() {
+		cachepkg.Redis = redisClient
+		StopUploadMetaCacheListener()
+	})
+
+	ctx := context.Background()
+	upload := models.Upload{
+		ID:         91005,
+		UserID:     1,
+		FileName:   "ram-only.png",
+		FilePath:   "ram-only.png",
+		FileSize:   6,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+	seedUpload(t, dbConn, upload)
+
+	got, err := GetUploadByID(ctx, upload.ID)
+	if err != nil {
+		t.Fatalf("GetUploadByID without redis: %v", err)
+	}
+	if got.ID != upload.ID {
+		t.Fatalf("unexpected upload: %+v", got)
+	}
+
+	if err := dbConn.Delete(&models.Upload{}, upload.ID).Error; err != nil {
+		t.Fatalf("delete upload from db: %v", err)
+	}
+
+	gotCached, err := GetUploadByID(ctx, upload.ID)
+	if err != nil {
+		t.Fatalf("GetUploadByID from RAM without redis: %v", err)
+	}
+	if gotCached.ID != upload.ID {
+		t.Fatal("expected RAM cache hit when redis is disabled")
+	}
+}

backend/plugins/domain/upload/errs.go

@@ -0,0 +1,39 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package upload 提供文件上传与下载功能
+package upload
+
+import "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+
+// 文件管理常量
+const (
+	ErrNoFileSelected               = shared.ErrNoFileSelected
+	ErrUnsupportedFormat            = shared.ErrUnsupportedFormat
+	ErrProcessFileFailed            = shared.ErrProcessFileFailed
+	ErrSaveFileFailed               = shared.ErrSaveFileFailed
+	ErrOpenFileFailed               = shared.ErrOpenFileFailed
+	ErrSaveUploadRecordFailed       = shared.ErrSaveUploadRecordFailed
+	ErrGenericFileTooLarge          = shared.ErrGenericFileTooLarge
+	ErrFileContentExtensionMismatch = shared.ErrFileContentExtensionMismatch
+	ErrFileValidationFailed         = shared.ErrFileValidationFailed
+	ErrInvalidMetadataJSON          = shared.ErrInvalidMetadataJSON
+	ErrInvalidFileID                = shared.ErrInvalidFileID
+	ErrQueryUploadRecordFailed      = shared.ErrQueryUploadRecordFailed
+	ErrInvalidBatchDownloadRequest  = shared.ErrInvalidBatchDownloadRequest
+	ErrInvalidIDValueFormat         = shared.ErrInvalidIDValueFormat
+	ErrRetrieveUploadRecordsFailed  = shared.ErrRetrieveUploadRecordsFailed
+	ErrNoValidFilesForArchive       = shared.ErrNoValidFilesForArchive
+	ErrInvalidParams                = shared.ErrInvalidParams
+	ErrQueryFileCountFailed         = shared.ErrQueryFileCountFailed
+	ErrQueryFileListFailed          = shared.ErrQueryFileListFailed
+	ErrDeleteFileFailed             = shared.ErrDeleteFileFailed
+	ErrStorageReadOnly              = shared.ErrStorageReadOnly
+	ErrS3KeyRequired                = shared.ErrS3KeyRequired
+	ErrS3KeyTooLongFormat           = shared.ErrS3KeyTooLongFormat
+	ErrS3KeyStartsWithSlash         = shared.ErrS3KeyStartsWithSlash
+	ErrS3KeyContainsNullBytes       = shared.ErrS3KeyContainsNullBytes
+	ErrQueryUnusedUploadsFailed     = shared.ErrQueryUnusedUploadsFailed
+	ErrUnauthorized                 = shared.ErrUnauthorized
+)

backend/plugins/domain/upload/exports.go

@@ -0,0 +1,126 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package upload
+
+import (
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/filesrv"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/handler"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/ingest"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	uploadtask "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/task"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+)
+
+// HTTP handlers
+var (
+	UploadFile             = handler.UploadFile
+	DownloadFile           = handler.DownloadFile
+	BatchDownloadFiles     = handler.BatchDownloadFiles
+	ListFiles              = handler.ListFiles
+	DeleteFile             = handler.DeleteFile
+	GetDistinctUploadTypes = handler.GetDistinctUploadTypes
+	ListMyFiles            = handler.ListMyFiles
+	DeleteMyFile           = handler.DeleteMyFile
+	UpdateMyFile           = handler.UpdateMyFile
+	GetFileStats           = handler.GetFileStats
+	ServeFileByID          = filesrv.ServeFileByID
+)
+
+// Programmatic ingest API
+var (
+	Ingest      = ingest.Ingest
+	Remove      = ingest.Remove
+	RemoveOwned = ingest.RemoveOwned
+	FindByHash  = ingest.FindByHash
+)
+
+// Ingest policy constants
+const (
+	PolicyCreate          = ingest.PolicyCreate
+	PolicyDedupNewRecord  = ingest.PolicyDedupNewRecord
+	PolicyResolveExisting = ingest.PolicyResolveExisting
+)
+
+type (
+	// IngestRequest is the programmatic upload ingest payload.
+	IngestRequest = ingest.Request
+	// IngestResult reports ingest side effects.
+	IngestResult = ingest.Result
+	// IngestPolicy controls hash-collision behavior during ingest.
+	IngestPolicy = ingest.Policy
+)
+
+// Ingest errors
+var (
+	ErrIngestForbidden       = ingest.ErrForbidden
+	ErrIngestStorageReadOnly = ingest.ErrStorageReadOnly
+)
+
+// Cache management
+var (
+	ResetAccessCaches              = cache.ResetAccessCaches
+	PublishAccessCacheInvalidation = cache.PublishAccessCacheInvalidation
+)
+
+// Stats
+var (
+	// Deprecated: use upload.Ingest or upload.Remove; stats are applied internally.
+	ApplyUploadStatsAdd = uploadstats.ApplyUploadStatsAdd
+	// Deprecated: use upload.Ingest or upload.Remove; stats are applied internally.
+	ApplyUploadStatsRemove = uploadstats.ApplyUploadStatsRemove
+	RebuildUploadStats     = uploadstats.RebuildUploadStats
+)
+
+// Utilities
+var (
+	CompressImageToWebP = util.CompressImageToWebP
+	ValidateS3Key       = util.ValidateS3Key
+)
+
+// Task identifiers and metadata
+const (
+	StorageMigrationTask   = uploadtask.StorageMigrationTask
+	SystemCleanupTask      = uploadtask.SystemCleanupTask
+	WarmImageCacheTask     = uploadtask.WarmImageCacheTask
+	RebuildUploadStatsTask = uploadtask.RebuildUploadStatsTask
+)
+
+var (
+	// StorageMigrationMeta describes the storage migration async task.
+	StorageMigrationMeta = uploadtask.StorageMigrationMeta
+	// SystemCleanupMeta describes the orphaned upload cleanup task.
+	SystemCleanupMeta = uploadtask.SystemCleanupMeta
+	// WarmImageCacheMeta describes the image compression cache warmup task.
+	WarmImageCacheMeta = uploadtask.WarmImageCacheMeta
+	// RebuildUploadStatsMeta describes the upload stats rebuild task.
+	RebuildUploadStatsMeta = uploadtask.RebuildUploadStatsMeta
+)
+
+// MigrationHandler executes storage migration tasks.
+type MigrationHandler = uploadtask.MigrationHandler
+
+// SystemCleanupHandler removes orphaned upload files.
+type SystemCleanupHandler = uploadtask.SystemCleanupHandler
+
+// WarmImageCacheHandler pre-warms compressed image caches.
+type WarmImageCacheHandler = uploadtask.WarmImageCacheHandler
+
+// RebuildUploadStatsHandler rebuilds upload stats from active records.
+type RebuildUploadStatsHandler = uploadtask.RebuildUploadStatsHandler
+
+// WarmImageCachePayload is the payload for image cache warmup tasks.
+type WarmImageCachePayload = uploadtask.WarmImageCachePayload
+
+// Ensure task handler types implement required interfaces.
+var (
+	_ driver_asynq_worker.TaskHandler = (*MigrationHandler)(nil)
+	_ driver_asynq_worker.TaskHandler = (*SystemCleanupHandler)(nil)
+	_ driver_asynq_worker.TaskHandler = (*RebuildUploadStatsHandler)(nil)
+	_ interface {
+		driver_asynq_worker.TaskHandler
+		ValidatePayload([]byte) ([]byte, error)
+	} = (*WarmImageCacheHandler)(nil)
+)

backend/plugins/domain/upload/filesrv/file_server.go

@@ -0,0 +1,322 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package filesrv serves uploaded files with access control and image compression.
+package filesrv
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	pkgutil "github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/auth"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/diskcache"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	"github.com/gin-gonic/gin"
+	"golang.org/x/sync/singleflight"
+	"gorm.io/gorm"
+)
+
+var compressedImageFlight singleflight.Group
+
+type compressedImageCacheResult struct {
+	bytes  []byte
+	cached bool
+	err    error
+}
+
+type fileTypeCategory string
+
+const (
+	fileTypeImage fileTypeCategory = "image"
+	fileTypeVideo fileTypeCategory = "video"
+	fileTypeAudio fileTypeCategory = "audio"
+	fileTypeOther fileTypeCategory = "other"
+)
+
+// ServeFileByID 根据 ID 获取并提供已上传的文件
+// @Summary 获取已上传文件
+// @Description 根据文件 ID 获取并提供已上传的临时或正式文件，若配置了缓存则优先走本地缓存，否则从 S3 等后端存储读取并流式返回
+// @Tags upload
+// @Produce octet-stream
+// @Param id path string true "文件 ID"
+// @Param quality query string false "图片质量 (low, medium, high, origin)，默认为 origin"
+// @Success 200 {file} file "成功获取文件内容"
+// @Failure 400 {object} response.Any "文件 ID 格式错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "文件未找到"
+// @Failure 500 {object} response.Any "服务内部错误"
+// @Router /f/{id} [get]
+func ServeFileByID(c *gin.Context) {
+	upload, err := GetUploadRecordByID(c)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "文件记录未找到")
+			return
+		}
+		if _, ok := err.(*strconv.NumError); ok {
+			response.AbortBadRequest(c, "无效的上传ID")
+			return
+		}
+		response.AbortInternal(c, "服务器内部错误")
+		return
+	}
+
+	if err := CheckFileAccessPermission(c, upload); err != nil {
+		response.AbortUnauthorized(c, shared.ErrUnauthorized)
+		return
+	}
+
+	ServeUpload(c, upload)
+}
+
+// GetUploadRecordByID 从请求路径参数中解析文件 ID 并从数据库中检索处于 Pending 或 Used 状态的上传记录。
+func GetUploadRecordByID(c *gin.Context) (*models.Upload, error) {
+	c.Header("X-Content-Type-Options", "nosniff")
+	c.Header("Content-Security-Policy", "sandbox")
+
+	idStr := c.Param("id")
+	uploadID, err := strconv.ParseUint(idStr, 10, 64)
+	if err != nil {
+		return nil, err
+	}
+
+	upload, err := cache.GetUploadByID(c.Request.Context(), uploadID)
+	if err != nil {
+		return nil, err
+	}
+
+	return &upload, nil
+}
+
+func getFileTypeCategory(upload *models.Upload) fileTypeCategory {
+	mime := strings.ToLower(upload.MimeType)
+	ext := strings.ToLower(upload.Extension)
+
+	if strings.HasPrefix(mime, "image/") || util.IsImageExtension(ext) {
+		return fileTypeImage
+	}
+	if strings.HasPrefix(mime, "video/") {
+		return fileTypeVideo
+	}
+	if strings.HasPrefix(mime, "audio/") {
+		return fileTypeAudio
+	}
+	return fileTypeOther
+}
+
+// ServeUpload 将已存在的文件内容读取并流式响应给客户端。
+func ServeUpload(c *gin.Context, upload *models.Upload) {
+	setCacheHeaders(c, upload)
+
+	category := getFileTypeCategory(upload)
+	quality := util.NormalizeImageQuality(c.Query("quality"))
+
+	switch category {
+	case fileTypeImage:
+		if quality != shared.ImageQualityOrigin {
+			serveCompressedImage(c, upload, quality)
+			return
+		}
+		fallthrough
+	default:
+		serveOriginalWithConditionalCheck(c, upload)
+	}
+}
+
+func setCacheHeaders(c *gin.Context, upload *models.Upload) {
+	if cache.IsFilePublic(c.Request.Context(), upload.Type) {
+		c.Header("Cache-Control", "public, max-age=31536000")
+	} else {
+		c.Header("Cache-Control", "private, no-cache")
+	}
+}
+
+func serveOriginalWithConditionalCheck(c *gin.Context, upload *models.Upload) {
+	etag := fmt.Sprintf(`W/"%s"`, upload.Hash)
+	c.Header("ETag", etag)
+
+	if c.GetHeader("If-None-Match") == etag {
+		c.AbortWithStatus(http.StatusNotModified)
+		return
+	}
+
+	serveOriginal(c, upload)
+}
+
+func serveCompressedImage(c *gin.Context, upload *models.Upload, quality string) {
+	etag := fmt.Sprintf(`W/"%s-%s"`, upload.Hash, quality)
+	c.Header("ETag", etag)
+
+	if c.GetHeader("If-None-Match") == etag {
+		c.AbortWithStatus(http.StatusNotModified)
+		return
+	}
+
+	webpBytes, hit, err := EnsureCompressedImageCache(c.Request.Context(), upload, quality)
+	if hit {
+		c.Header("X-Cache", "HIT")
+	} else {
+		c.Header("X-Cache", "MISS")
+	}
+	if err != nil {
+		if len(webpBytes) > 0 {
+			logger.WarnF(c.Request.Context(), "failed to cache compressed image: %v", err)
+			c.Data(http.StatusOK, "image/webp", webpBytes)
+			return
+		}
+		logger.ErrorF(c.Request.Context(), "failed to prepare compressed image cache: %v", err)
+		serveOriginal(c, upload)
+		return
+	}
+
+	c.Data(http.StatusOK, "image/webp", webpBytes)
+}
+
+// EnsureCompressedImageCache returns cached or freshly generated WebP bytes for an upload.
+func EnsureCompressedImageCache(
+	ctx context.Context,
+	upload *models.Upload,
+	quality string,
+) ([]byte, bool, error) {
+	cacheStore := diskcache.GetGlobalCache()
+	cacheKey := ImageCompressionCacheKey(upload, quality)
+	webpBytes, err := cacheStore.Get(cacheKey)
+	if err == nil {
+		return webpBytes, true, nil
+	}
+	if !errors.Is(err, diskcache.ErrCacheMiss) {
+		return nil, false, fmt.Errorf("read compressed image cache: %w", err)
+	}
+
+	result, err, _ := compressedImageFlight.Do(cacheKey, func() (any, error) {
+		return generateCompressedImageCache(ctx, upload, quality, cacheKey)
+	})
+	if err != nil {
+		return nil, false, err
+	}
+
+	res := result.(compressedImageCacheResult)
+	return res.bytes, res.cached, res.err
+}
+
+func generateCompressedImageCache(
+	ctx context.Context,
+	upload *models.Upload,
+	quality string,
+	cacheKey string,
+) (compressedImageCacheResult, error) {
+	cacheStore := diskcache.GetGlobalCache()
+
+	webpBytes, err := cacheStore.Get(cacheKey)
+	if err == nil {
+		return compressedImageCacheResult{bytes: webpBytes, cached: true}, nil
+	}
+	if !errors.Is(err, diskcache.ErrCacheMiss) {
+		return compressedImageCacheResult{}, fmt.Errorf("read compressed image cache: %w", err)
+	}
+
+	origBytes, err := getOriginalFileBytes(ctx, upload)
+	if err != nil {
+		return compressedImageCacheResult{}, fmt.Errorf("read original image: %w", err)
+	}
+
+	webpBytes, err = util.CompressImageToWebP(bytes.NewReader(origBytes), quality)
+	if err != nil {
+		return compressedImageCacheResult{}, fmt.Errorf("compress image to WebP: %w", err)
+	}
+
+	if err := cacheStore.Set(cacheKey, webpBytes, diskcache.NoExpiration); err != nil {
+		return compressedImageCacheResult{
+			bytes: webpBytes,
+			err:   fmt.Errorf("write compressed image cache: %w", err),
+		}, nil
+	}
+
+	return compressedImageCacheResult{bytes: webpBytes}, nil
+}
+
+// ImageCompressionCacheKey returns the disk cache key for a compressed upload image.
+func ImageCompressionCacheKey(upload *models.Upload, quality string) string {
+	return fmt.Sprintf(
+		"upload_webp_v1_%d_%d_%d_%s_%s",
+		upload.ID,
+		upload.UpdatedAt.UnixNano(),
+		upload.FileSize,
+		upload.Hash,
+		quality,
+	)
+}
+
+func serveOriginal(c *gin.Context, upload *models.Upload) {
+	obj, err := uploadstorage.OpenStoredObject(c.Request.Context(), upload)
+	if err != nil {
+		response.AbortNotFound(c, "文件未找到")
+		return
+	}
+	defer func() { _ = obj.Body.Close() }()
+	c.DataFromReader(http.StatusOK, obj.ContentLength, obj.ContentType, obj.Body, nil)
+}
+
+func getOriginalFileBytes(ctx context.Context, upload *models.Upload) ([]byte, error) {
+	obj, err := uploadstorage.OpenStoredObject(ctx, upload)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = obj.Body.Close() }()
+	return io.ReadAll(obj.Body)
+}
+
+func checkPrivateFileOwner(c *gin.Context, ownerID uint64) error {
+	var currUserID uint64
+	var isAdmin bool
+	if u, ok := pkgutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey); ok && u != nil {
+		currUserID = u.ID
+		isAdmin = u.IsAdmin
+	} else {
+		u, err := auth.GetUserFromRequest(c)
+		if err != nil {
+			return err
+		}
+		currUserID = u.ID
+		isAdmin = u.IsAdmin
+	}
+	if isAdmin {
+		return nil
+	}
+	if currUserID != ownerID {
+		return errors.New("forbidden: cross-user access denied")
+	}
+	return nil
+}
+
+// CheckFileAccessPermission 校验文件是否可以被当前请求访问
+func CheckFileAccessPermission(c *gin.Context, upload *models.Upload) error {
+	if upload.AccessMode == 0 {
+		return checkPrivateFileOwner(c, upload.UserID)
+	}
+
+	if !cache.IsFilePublic(c.Request.Context(), upload.Type) {
+		if _, ok := pkgutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey); !ok {
+			if _, err := auth.GetUserFromRequest(c); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}

backend/plugins/domain/upload/filesrv/file_server_test.go

@@ -0,0 +1,380 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package filesrv
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/json"
+	"fmt"
+	"image"
+	"image/color"
+	"image/png"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-contrib/sessions/cookie"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadutil "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/diskcache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+func init() {
+	testhelper.RegisterCleanup(cache.ResetUploadMetaCacheForTest)
+}
+
+func TestServeFileByIDAccessControl(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	cache.ResetAccessCaches()
+
+	tempDir := t.TempDir()
+	configureLocalStorageRoot(t, dbConn, tempDir)
+
+	// Create a user in DB
+	user := contracts.UserDTO{
+		ID:       12345,
+		Username: "file_test_user",
+		IsActive: true,
+	}
+	if err := dbConn.Table("w_users").Create(&user).Error; err != nil {
+		t.Fatalf("failed to create user: %v", err)
+	}
+
+	// Create an access token for this user
+	tokenStr := "test-secret-token-123"
+	tokenHash := fmt.Sprintf("%x", sha256.Sum256([]byte(tokenStr)))
+	tokenRecord := map[string]any{
+		"user_id":      user.ID,
+		"name":         "test_token",
+		"token_hash":   tokenHash,
+		"masked_token": "test-***",
+	}
+	if err := dbConn.Table("w_access_tokens").Create(&tokenRecord).Error; err != nil {
+		t.Fatalf("failed to create token: %v", err)
+	}
+
+	// Create two files: one in whitelist (avatar), one not in whitelist (attachment)
+	avatarFile := models.Upload{
+		ID:         8001,
+		UserID:     user.ID,
+		FileName:   "avatar.png",
+		FilePath:   "avatar.png",
+		FileSize:   5,
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar",
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+	attachmentFile := models.Upload{
+		ID:         8002,
+		UserID:     user.ID,
+		FileName:   "doc.pdf",
+		FilePath:   "doc.pdf",
+		FileSize:   5,
+		MimeType:   "application/pdf",
+		Extension:  "pdf",
+		Type:       "attachment",
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+
+	if err := os.WriteFile(filepath.Join(tempDir, "avatar.png"), []byte("image"), 0644); err != nil {
+		t.Fatalf("failed to write avatar file: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(tempDir, "doc.pdf"), []byte("bytes"), 0644); err != nil {
+		t.Fatalf("failed to write attachment file: %v", err)
+	}
+
+	dbConn.Create(&avatarFile)
+	dbConn.Create(&attachmentFile)
+
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.Use(response.ErrorHandlerMiddleware())
+	store := cookie.NewStore([]byte("secret"))
+	r.Use(sessions.Sessions("wavelet_session_id", store))
+	r.GET("/f/:id", ServeFileByID)
+
+	t.Run("public access allowed for whitelist type (avatar)", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/8001", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200 for public file, got %d", w.Code)
+		}
+		if w.Body.String() != "image" {
+			t.Fatalf("expected body 'image', got '%s'", w.Body.String())
+		}
+	})
+
+	t.Run("public access rejected for non-whitelist type (attachment)", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/8002", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusUnauthorized {
+			t.Fatalf("expected status 401 for private file without auth, got %d", w.Code)
+		}
+	})
+
+	t.Run("authenticated access allowed for non-whitelist type (attachment)", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/8002", nil)
+		req.Header.Set("Authorization", "Bearer "+tokenStr)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200 for authenticated request, got %d", w.Code)
+		}
+		if w.Body.String() != "bytes" {
+			t.Fatalf("expected body 'bytes', got '%s'", w.Body.String())
+		}
+	})
+
+	t.Run("non-existent file returns 404", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/99999", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Fatalf("expected status 404 for non-existent file, got %d", w.Code)
+		}
+	})
+
+	t.Run("invalid id format returns 400", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/invalid-id", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Fatalf("expected status 400 for invalid ID, got %d", w.Code)
+		}
+	})
+}
+
+func TestServeFileByIDImageCompression(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	cache.ResetAccessCaches()
+
+	tempDir := t.TempDir()
+	configureLocalStorageRoot(t, dbConn, tempDir)
+
+	cache := diskcache.GetGlobalCache()
+	if err := cache.Clear(); err != nil {
+		t.Fatalf("failed to clear disk cache before test: %v", err)
+	}
+
+	defer func() {
+		if err := cache.Clear(); err != nil {
+			t.Errorf("failed to clear disk cache after test: %v", err)
+		}
+	}()
+
+	// Create test user
+	user := contracts.UserDTO{
+		ID:       555,
+		Username: "compress_tester",
+		IsActive: true,
+	}
+	dbConn.Table("w_users").Create(&user)
+
+	// Create a 1x1 pixel PNG image
+	img := image.NewRGBA(image.Rect(0, 0, 1, 1))
+	img.Set(0, 0, color.RGBA{R: 255, G: 0, B: 0, A: 255})
+	var pngBuf bytes.Buffer
+	if err := png.Encode(&pngBuf, img); err != nil {
+		t.Fatalf("failed to encode test png: %v", err)
+	}
+
+	filePath := filepath.Join(tempDir, "test_image.png")
+	if err := os.WriteFile(filePath, pngBuf.Bytes(), 0644); err != nil {
+		t.Fatalf("failed to write test png: %v", err)
+	}
+
+	// Save upload record to DB
+	uploadRecord := models.Upload{
+		ID:         3001,
+		UserID:     user.ID,
+		FileName:   "test_image.png",
+		FilePath:   "test_image.png",
+		FileSize:   int64(pngBuf.Len()),
+		MimeType:   "image/png",
+		Extension:  "png",
+		Type:       "avatar", // Whitelisted by default
+		Status:     models.UploadStatusUsed,
+		AccessMode: 1,
+	}
+	dbConn.Create(&uploadRecord)
+
+	// Setup Router
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.GET("/f/:id", ServeFileByID)
+
+	t.Run("serve original file without compress parameter", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/3001", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d", w.Code)
+		}
+		// Content-Type should be image/png (default local serving type)
+		if w.Header().Get("Content-Type") != "image/png" {
+			t.Errorf("expected Content-Type image/png, got %s", w.Header().Get("Content-Type"))
+		}
+		if w.Header().Get("X-Cache") != "" {
+			t.Errorf("expected no X-Cache header for original file, got %s", w.Header().Get("X-Cache"))
+		}
+		if w.Header().Get("ETag") == "" {
+			t.Errorf("expected ETag header for original file")
+		}
+	})
+
+	t.Run("first request with quality=medium produces cache MISS and converts to WebP", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/3001?quality=medium", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d", w.Code)
+		}
+		if w.Header().Get("Content-Type") != "image/webp" {
+			t.Errorf("expected Content-Type image/webp, got %s", w.Header().Get("Content-Type"))
+		}
+		if w.Header().Get("X-Cache") != "MISS" {
+			t.Errorf("expected X-Cache MISS on first compress request, got %s", w.Header().Get("X-Cache"))
+		}
+		if w.Header().Get("ETag") == "" {
+			t.Errorf("expected ETag header")
+		}
+		if len(w.Body.Bytes()) == 0 {
+			t.Errorf("expected non-empty body")
+		}
+	})
+
+	t.Run("second request with quality=medium produces cache HIT", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/3001?quality=medium", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d", w.Code)
+		}
+		if w.Header().Get("Content-Type") != "image/webp" {
+			t.Errorf("expected Content-Type image/webp, got %s", w.Header().Get("Content-Type"))
+		}
+		if w.Header().Get("X-Cache") != "HIT" {
+			t.Errorf("expected X-Cache HIT on second compress request, got %s", w.Header().Get("X-Cache"))
+		}
+	})
+
+	t.Run("request with quality=origin behaves like original request", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/3001?quality=origin", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d", w.Code)
+		}
+		if w.Header().Get("Content-Type") != "image/png" {
+			t.Errorf("expected Content-Type image/png, got %s", w.Header().Get("Content-Type"))
+		}
+		if w.Header().Get("X-Cache") != "" {
+			t.Errorf("expected no X-Cache header for origin quality, got %s", w.Header().Get("X-Cache"))
+		}
+	})
+
+	t.Run("conditional GET with matching If-None-Match returns 304", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/f/3001?quality=medium", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		etag := w.Header().Get("ETag")
+		if etag == "" {
+			t.Fatalf("expected ETag header from initial request")
+		}
+
+		// Second request with If-None-Match
+		req2, _ := http.NewRequest("GET", "/f/3001?quality=medium", nil)
+		req2.Header.Set("If-None-Match", etag)
+		w2 := httptest.NewRecorder()
+		r.ServeHTTP(w2, req2)
+
+		if w2.Code != http.StatusNotModified {
+			t.Fatalf("expected status 304 Not Modified, got %d", w2.Code)
+		}
+		if w2.Body.Len() != 0 {
+			t.Errorf("expected empty body on 304 response, got %d bytes", w2.Body.Len())
+		}
+	})
+}
+
+func TestNormalizeImageQuality(t *testing.T) {
+	tests := []struct {
+		name    string
+		quality string
+		want    string
+	}{
+		{name: "empty quality returns origin", quality: "", want: shared.ImageQualityOrigin},
+		{name: "origin returns origin", quality: "origin", want: shared.ImageQualityOrigin},
+		{name: "ORIGIN case-insensitive returns origin", quality: "ORIGIN", want: shared.ImageQualityOrigin},
+		{name: "low returns low", quality: "low", want: shared.ImageQualityLow},
+		{name: "LOW returns low", quality: "LOW", want: shared.ImageQualityLow},
+		{name: "medium returns medium", quality: "medium", want: shared.ImageQualityMedium},
+		{name: "high returns high", quality: "high", want: shared.ImageQualityHigh},
+		{name: "unknown quality defaults to origin", quality: "ultra_hd", want: shared.ImageQualityOrigin},
+		{name: "whitespace padded quality is trimmed", quality: "  medium  ", want: shared.ImageQualityMedium},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := uploadutil.NormalizeImageQuality(tt.quality); got != tt.want {
+				t.Errorf("NormalizeImageQuality(%q) = %q, want %q", tt.quality, got, tt.want)
+			}
+		})
+	}
+}
+
+func configureLocalStorageRoot(t *testing.T, dbConn *gorm.DB, tempDir string) {
+	var sc struct {
+		Key   string
+		Value string
+	}
+	if err := dbConn.Table("w_system_configs").Where("key = ?", "storage_config").First(&sc).Error; err != nil {
+		t.Fatalf("failed to find storage config: %v", err)
+	}
+	var cfg objectstore.Config
+	if err := json.Unmarshal([]byte(sc.Value), &cfg); err != nil {
+		t.Fatalf("failed to unmarshal storage config: %v", err)
+	}
+	cfg.Local.Root = tempDir
+	newVal, err := json.Marshal(cfg)
+	if err != nil {
+		t.Fatalf("failed to marshal storage config: %v", err)
+	}
+	sc.Value = string(newVal)
+	if err := dbConn.Table("w_system_configs").Where("key = ?", "storage_config").Update("value", sc.Value).Error; err != nil {
+		t.Fatalf("failed to save storage config: %v", err)
+	}
+	objectstore.ResetCache()
+}

backend/plugins/domain/upload/handler/file_management.go

@@ -0,0 +1,299 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/ingest"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/repository"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+)
+
+type listFilesRequest struct {
+	Page      int    `form:"page"`
+	PageSize  int    `form:"page_size"`
+	Keyword   string `form:"keyword"`
+	Type      string `form:"type"`
+	Extension string `form:"extension"`
+	UserID    uint64 `form:"user_id"`
+}
+
+type listFilesResponse struct {
+	Total    int64           `json:"total"`
+	Page     int             `json:"page"`
+	PageSize int             `json:"page_size"`
+	Items    []models.Upload `json:"items"`
+}
+
+// ListFiles 获取系统上传的文件列表
+// @Summary 获取文件列表
+// @Description 分页获取系统上传的文件列表，支持文件名关键词、业务类型、扩展名、上传用户ID过滤
+// @Tags admin
+// @Produce json
+// @Param page query int false "页码（默认 1）"
+// @Param page_size query int false "每页数量（默认 20，最大 100）"
+// @Param keyword query string false "文件名关键词（模糊匹配）"
+// @Param type query string false "业务分类过滤"
+// @Param extension query string false "扩展名过滤"
+// @Param user_id query int false "上传用户 ID 过滤"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=listFilesResponse} "查询成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/admin/uploads/files [get]
+func ListFiles(c *gin.Context) {
+	ctx := c.Request.Context()
+
+	var req listFilesRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidParams)
+		return
+	}
+	if req.Page <= 0 {
+		req.Page = 1
+	}
+	if req.PageSize <= 0 || req.PageSize > 100 {
+		req.PageSize = 20
+	}
+
+	total, items, err := listUploadFiles(ctx, repository.UploadListFilter{
+		UserID:    req.UserID,
+		Keyword:   req.Keyword,
+		Type:      req.Type,
+		Extension: req.Extension,
+		Page:      req.Page,
+		PageSize:  req.PageSize,
+	})
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrQueryFileListFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(listFilesResponse{
+		Total:    total,
+		Page:     req.Page,
+		PageSize: req.PageSize,
+		Items:    items,
+	}))
+}
+
+// DeleteFile 软删除指定的文件记录
+// @Summary 删除文件
+// @Description 将指定 ID 的文件状态置为 deleted（软删除）
+// @Tags admin
+// @Produce json
+// @Param id path string true "文件 ID"
+// @Security SessionCookie
+// @Success 200 {object} response.Any "删除成功"
+// @Failure 404 {object} response.Any "文件不存在"
+// @Router /api/v1/admin/uploads/files/{id} [delete]
+func DeleteFile(c *gin.Context) {
+	ctx := c.Request.Context()
+	if uploadstorage.ReadOnly(ctx) {
+		response.AbortConflict(c, shared.ErrStorageReadOnly)
+		return
+	}
+
+	uploadID, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidFileID)
+		return
+	}
+
+	if _, err := softDeleteUpload(ctx, uploadID); err != nil {
+		if isRecordNotFound(err) {
+			response.AbortNotFound(c, "文件记录未找到")
+			return
+		}
+		response.AbortBadRequest(c, shared.ErrDeleteFileFailed)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// GetDistinctUploadTypes 获取所有已存在的文件业务分类列表
+// @Summary 获取业务分类列表
+// @Description 查询系统内所有不重复的上传业务分类标识（如 avatar, doc 等）
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]string} "查询成功"
+// @Router /api/v1/admin/uploads/types [get]
+func GetDistinctUploadTypes(c *gin.Context) {
+	ctx := c.Request.Context()
+	types, err := listDistinctUploadTypes(ctx)
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrQueryTypeListFailed)
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(types))
+}
+
+type listMyFilesRequest struct {
+	Page      int    `form:"page"`
+	PageSize  int    `form:"page_size"`
+	Keyword   string `form:"keyword"`
+	Type      string `form:"type"`
+	Extension string `form:"extension"`
+}
+
+type listMyFilesResponse struct {
+	Total    int64           `json:"total"`
+	Page     int             `json:"page"`
+	PageSize int             `json:"page_size"`
+	Items    []models.Upload `json:"items"`
+}
+
+// ListMyFiles 获取当前用户上传的文件列表
+// @Summary 获取我的文件列表
+// @Description 分页获取当前登录用户上传的文件，支持文件名关键词、业务类型、扩展名过滤
+// @Tags upload
+// @Produce json
+// @Param page query int false "页码（默认 1）"
+// @Param page_size query int false "每页数量（默认 20，最大 100）"
+// @Param keyword query string false "文件名关键词（模糊匹配）"
+// @Param type query string false "业务分类过滤"
+// @Param extension query string false "扩展名过滤"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=listMyFilesResponse} "查询成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/upload/my [get]
+func ListMyFiles(c *gin.Context) {
+	currUser, _ := util.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	ctx := c.Request.Context()
+
+	var req listMyFilesRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidParams)
+		return
+	}
+	if req.Page <= 0 {
+		req.Page = 1
+	}
+	if req.PageSize <= 0 || req.PageSize > 100 {
+		req.PageSize = 20
+	}
+
+	total, items, err := listMyUploadFiles(ctx, currUser.ID, repository.UploadListFilter{
+		Keyword:   req.Keyword,
+		Type:      req.Type,
+		Extension: req.Extension,
+		Page:      req.Page,
+		PageSize:  req.PageSize,
+	})
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrQueryFileListFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(listMyFilesResponse{
+		Total:    total,
+		Page:     req.Page,
+		PageSize: req.PageSize,
+		Items:    items,
+	}))
+}
+
+// DeleteMyFile 软删除当前用户本人的文件
+// @Summary 删除我的文件
+// @Description 将当前用户本人的文件状态置为 deleted（软删除）
+// @Tags upload
+// @Produce json
+// @Param id path string true "文件 ID"
+// @Security SessionCookie
+// @Success 200 {object} response.Any "删除成功"
+// @Failure 403 {object} response.Any "无权操作"
+// @Failure 404 {object} response.Any "文件不存在"
+// @Router /api/v1/upload/{id} [delete]
+func DeleteMyFile(c *gin.Context) {
+	currUser, _ := util.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	ctx := c.Request.Context()
+	if uploadstorage.ReadOnly(ctx) {
+		response.AbortConflict(c, shared.ErrStorageReadOnly)
+		return
+	}
+
+	uploadID, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidFileID)
+		return
+	}
+
+	if _, err := softDeleteOwnedUpload(ctx, currUser.ID, uploadID); err != nil {
+		if isRecordNotFound(err) {
+			response.AbortNotFound(c, "文件记录未找到")
+			return
+		}
+		if err == ingest.ErrForbidden {
+			response.AbortForbidden(c, "无权操作")
+			return
+		}
+		response.AbortBadRequest(c, shared.ErrDeleteFileFailed)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+type updateMyFileRequest struct {
+	FileName   string `json:"file_name" binding:"max=255"`
+	AccessMode *int   `json:"access_mode" binding:"omitempty,oneof=0 1"`
+}
+
+// UpdateMyFile 更新当前用户本人的文件信息
+// @Summary 更新我的文件信息
+// @Description 更新当前用户本人的文件名或访问权限模式 (AccessMode)
+// @Tags upload
+// @Accept json
+// @Produce json
+// @Param id path string true "文件 ID"
+// @Param request body updateMyFileRequest true "更新字段"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=models.Upload} "更新成功"
+// @Failure 403 {object} response.Any "无权操作"
+// @Failure 404 {object} response.Any "文件不存在"
+// @Router /api/v1/upload/{id} [put]
+func UpdateMyFile(c *gin.Context) {
+	currUser, _ := util.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	ctx := c.Request.Context()
+	if uploadstorage.ReadOnly(ctx) {
+		response.AbortConflict(c, shared.ErrStorageReadOnly)
+		return
+	}
+
+	uploadID, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidFileID)
+		return
+	}
+
+	var req updateMyFileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidParams)
+		return
+	}
+
+	updated, err := updateOwnedUpload(ctx, currUser.ID, uploadID, updateMyUploadInput(req))
+	if err != nil {
+		if isRecordNotFound(err) {
+			response.AbortNotFound(c, "文件记录未找到")
+			return
+		}
+		if err == ingest.ErrForbidden {
+			response.AbortForbidden(c, "无权操作")
+			return
+		}
+		response.AbortBadRequest(c, shared.ErrUpdateFileFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(updated))
+}

backend/plugins/domain/upload/handler/file_management_test.go

@@ -0,0 +1,66 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+)
+
+func TestGetDistinctUploadTypes(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	user := contracts.UserDTO{ID: 2222, Username: "test_user_2"}
+	dbConn.Table("w_users").Create(&user)
+
+	customUpload := models.Upload{
+		ID:        9001,
+		UserID:    user.ID,
+		FileName:  "custom.txt",
+		FilePath:  "uploads/custom.txt",
+		FileSize:  10,
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Type:      "custom_type_xyz",
+		Status:    models.UploadStatusUsed,
+	}
+	dbConn.Create(&customUpload)
+
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.GET("/api/v1/admin/uploads/types", GetDistinctUploadTypes)
+
+	req, _ := http.NewRequest("GET", "/api/v1/admin/uploads/types", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var resp struct {
+		ErrorMsg string   `json:"error_msg"`
+		Data     []string `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse JSON: %v", err)
+	}
+
+	if resp.ErrorMsg != "" {
+		t.Fatalf("unexpected error: %s", resp.ErrorMsg)
+	}
+
+	if len(resp.Data) != 1 || resp.Data[0] != "custom_type_xyz" {
+		t.Errorf("expected only custom_type_xyz in types list, got: %v", resp.Data)
+	}
+}

backend/plugins/domain/upload/handler/logics.go

@@ -0,0 +1,87 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"context"
+	"errors"
+	"sort"
+
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/ingest"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/repository"
+)
+
+func listUploadFiles(ctx context.Context, filter repository.UploadListFilter) (int64, []models.Upload, error) {
+	return repository.ListUploads(ctx, filter)
+}
+
+func listMyUploadFiles(ctx context.Context, userID uint64, filter repository.UploadListFilter) (int64, []models.Upload, error) {
+	filter.UserID = userID
+	return repository.ListUploads(ctx, filter)
+}
+
+func softDeleteUpload(ctx context.Context, uploadID uint64) (models.Upload, error) {
+	return ingest.Remove(ctx, uploadID)
+}
+
+func softDeleteOwnedUpload(ctx context.Context, userID, uploadID uint64) (models.Upload, error) {
+	return ingest.RemoveOwned(ctx, userID, uploadID)
+}
+
+func listDistinctUploadTypes(ctx context.Context) ([]string, error) {
+	types, err := repository.ListDistinctUploadTypes(ctx)
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(types)
+	return types, nil
+}
+
+type updateMyUploadInput struct {
+	FileName   string
+	AccessMode *int
+}
+
+func updateOwnedUpload(ctx context.Context, userID, uploadID uint64, input updateMyUploadInput) (models.Upload, error) {
+	u, err := repository.GetActiveUploadByID(ctx, uploadID)
+	if err != nil {
+		return models.Upload{}, err
+	}
+	if u.UserID != userID {
+		return models.Upload{}, ingest.ErrForbidden
+	}
+
+	updates := make(map[string]any)
+	if input.FileName != "" {
+		updates["file_name"] = input.FileName
+	}
+	if input.AccessMode != nil {
+		updates["access_mode"] = *input.AccessMode
+	}
+	if err := repository.UpdateUpload(ctx, &u, updates); err != nil {
+		return models.Upload{}, err
+	}
+	if name, ok := updates["file_name"].(string); ok {
+		u.FileName = name
+	}
+	if mode, ok := updates["access_mode"].(int); ok {
+		u.AccessMode = mode
+	}
+	return u, nil
+}
+
+func listUploadsForBatchDownload(ctx context.Context, ids []uint64) ([]models.Upload, error) {
+	return repository.ListUploadsByIDs(ctx, ids)
+}
+
+func loadUploadStats(ctx context.Context) ([]models.UploadStat, error) {
+	return repository.ListUploadStats(ctx)
+}
+
+func isRecordNotFound(err error) bool {
+	return errors.Is(err, gorm.ErrRecordNotFound)
+}

backend/plugins/domain/upload/handler/routers.go

@@ -0,0 +1,333 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package handler provides upload HTTP API handlers.
+package handler
+
+import (
+	"archive/zip"
+	"bufio"
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/url"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	pkgutil "github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/filesrv"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/ingest"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/util"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+type batchDownloadRequest struct {
+	IDs []string `json:"ids" binding:"required,min=1"`
+}
+
+// UploadFile 通用上传文件接口
+// @Summary 上传文件
+// @Description 支持各种类型的通用文件上传，支持自动文件类型检测、哈希计算与“秒传”去重
+// @Tags upload
+// @Accept multipart/form-data
+// @Produce json
+// @Param file formData file true "要上传的文件"
+// @Param type formData string false "业务分类 (例如: avatar, attachment, doc，默认为 generic)"
+// @Param metadata formData string false "额外的 JSON 格式元数据"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=models.Upload} "上传成功"
+// @Failure 400 {object} response.Any "请求参数错误或文件受限"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/upload [post]
+//
+//nolint:revive
+func UploadFile(c *gin.Context) {
+	c.Header("X-Content-Type-Options", "nosniff")
+	c.Header("Content-Security-Policy", "sandbox")
+
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, shared.MaxUploadSize)
+
+	currUser, _ := pkgutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	ctx := c.Request.Context()
+
+	header, err := c.FormFile("file")
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrNoFileSelected)
+		return
+	}
+
+	file, err := header.Open()
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrOpenFileFailed)
+		return
+	}
+	defer func() { _ = file.Close() }()
+
+	if header.Size > shared.MaxUploadSize {
+		response.AbortBadRequest(c, shared.ErrGenericFileTooLarge)
+		return
+	}
+
+	origName := header.Filename
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(origName), "."))
+	if ext == "" {
+		ext = "bin"
+	}
+
+	hashWriter := sha256.New()
+	var buf bytes.Buffer
+	size, err := io.Copy(&buf, io.TeeReader(file, hashWriter))
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrProcessFileFailed)
+		return
+	}
+
+	fileHash := hex.EncodeToString(hashWriter.Sum(nil))
+	mimeType := detectMimeType(&buf, header, size)
+
+	if util.IsImageExtension(ext) && !strings.HasPrefix(mimeType, "image/") {
+		response.AbortBadRequest(c, shared.ErrFileContentExtensionMismatch)
+		return
+	}
+
+	uploadType := c.DefaultPostForm("type", "generic")
+
+	accessMode, errMsg := resolveUploadAccessMode(c, uploadType)
+	if errMsg != "" {
+		response.AbortBadRequest(c, errMsg)
+		return
+	}
+
+	meta, errMsg := parseUploadMetadata(c, mimeType)
+	if errMsg != "" {
+		response.AbortBadRequest(c, errMsg)
+		return
+	}
+
+	result, err := ingest.Ingest(ctx, ingest.Request{
+		UserID:     currUser.ID,
+		Reader:     bytes.NewReader(buf.Bytes()),
+		Size:       size,
+		FileName:   origName,
+		MimeType:   mimeType,
+		Extension:  ext,
+		Hash:       fileHash,
+		Type:       uploadType,
+		AccessMode: &accessMode,
+		Metadata:   meta,
+		Policy:     ingest.PolicyDedupNewRecord,
+	})
+	if err != nil {
+		if errors.Is(err, ingest.ErrStorageReadOnly) {
+			response.AbortConflict(c, shared.ErrStorageReadOnly)
+			return
+		}
+		if err.Error() == shared.ErrUnsupportedFormat {
+			response.AbortBadRequest(c, shared.ErrUnsupportedFormat)
+			return
+		}
+		if err.Error() == shared.ErrSaveFileFailed {
+			response.AbortBadRequest(c, shared.ErrSaveFileFailed)
+			return
+		}
+		response.AbortBadRequest(c, shared.ErrSaveUploadRecordFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(result.Upload))
+}
+
+// DownloadFile 通用单文件下载接口
+// @Summary 下载单文件
+// @Description 根据文件 ID 获取文件，以附件形式 (Attachment) 强制开启客户端浏览器下载
+// @Tags admin
+// @Produce octet-stream
+// @Param id path string true "文件 ID"
+// @Param quality query string false "图片质量 (low, medium, high, origin)，默认为 origin"
+// @Security SessionCookie
+// @Success 200 {file} file "成功下载文件"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 404 {object} response.Any "文件不存在"
+// @Failure 500 {object} response.Any "服务内部错误"
+// @Router /api/v1/admin/uploads/download/{id} [get]
+func DownloadFile(c *gin.Context) {
+	upload, err := filesrv.GetUploadRecordByID(c)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "文件记录未找到")
+			return
+		}
+		if _, ok := err.(*strconv.NumError); ok {
+			response.AbortBadRequest(c, shared.ErrInvalidFileID)
+			return
+		}
+		response.AbortBadRequest(c, shared.ErrQueryUploadRecordFailed)
+		return
+	}
+
+	if err := filesrv.CheckFileAccessPermission(c, upload); err != nil {
+		response.AbortUnauthorized(c, shared.ErrUnauthorized)
+		return
+	}
+
+	fileName := upload.FileName
+	quality := util.NormalizeImageQuality(c.Query("quality"))
+	isImage := strings.HasPrefix(strings.ToLower(upload.MimeType), "image/") || util.IsImageExtension(strings.ToLower(upload.Extension))
+
+	if quality != shared.ImageQualityOrigin && isImage {
+		ext := filepath.Ext(fileName)
+		if ext != "" {
+			fileName = strings.TrimSuffix(fileName, ext) + ".webp"
+		} else {
+			fileName += ".webp"
+		}
+	}
+
+	c.Header("Content-Disposition", fmt.Sprintf("attachment; filename*=UTF-8''%s", url.PathEscape(fileName)))
+	filesrv.ServeUpload(c, upload)
+}
+
+// BatchDownloadFiles 批量打包 ZIP 下载接口
+// @Summary 批量打包下载
+// @Description 传入多个文件 ID，后台实时将其打包压缩为 ZIP 流并输出，自动处理文件名重复冲突
+// @Tags admin
+// @Accept json
+// @Produce octet-stream
+// @Param request body handler.batchDownloadRequest true "包含文件 ID 数组 of string 的请求体"
+// @Security SessionCookie
+// @Success 200 {file} file "成功下载打包后的 ZIP"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 500 {object} response.Any "打包失败"
+// @Router /api/v1/admin/uploads/download/batch [post]
+func BatchDownloadFiles(c *gin.Context) {
+	ctx := c.Request.Context()
+
+	var req batchDownloadRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, shared.ErrInvalidBatchDownloadRequest)
+		return
+	}
+
+	var ids []uint64
+	for _, idStr := range req.IDs {
+		id, err := strconv.ParseUint(idStr, 10, 64)
+		if err != nil {
+			response.AbortBadRequest(c, fmt.Sprintf(shared.ErrInvalidIDValueFormat, idStr))
+			return
+		}
+		ids = append(ids, id)
+	}
+
+	uploads, err := listUploadsForBatchDownload(ctx, ids)
+	if err != nil {
+		response.AbortBadRequest(c, shared.ErrRetrieveUploadRecordsFailed)
+		return
+	}
+
+	if len(uploads) == 0 {
+		response.AbortBadRequest(c, shared.ErrNoValidFilesForArchive)
+		return
+	}
+
+	c.Header("Content-Type", "application/zip")
+	c.Header("Content-Disposition", "attachment; filename=\"batch_download.zip\"")
+
+	bufferedWriter := bufio.NewWriter(c.Writer)
+	zipWriter := zip.NewWriter(bufferedWriter)
+	defer func() {
+		_ = zipWriter.Close()
+		_ = bufferedWriter.Flush()
+	}()
+
+	usedNames := make(map[string]int)
+
+	for _, upload := range uploads {
+		if err := filesrv.CheckFileAccessPermission(c, &upload); err != nil {
+			logger.WarnF(ctx, "Batch download: skip file %d due to permission denied: %v", upload.ID, err)
+			continue
+		}
+
+		fileName := upload.FileName
+		if count, exists := usedNames[fileName]; exists {
+			usedNames[fileName] = count + 1
+			ext := filepath.Ext(fileName)
+			base := strings.TrimSuffix(fileName, ext)
+			fileName = fmt.Sprintf("%s_%d%s", base, count, ext)
+		} else {
+			usedNames[fileName] = 1
+		}
+
+		zipFileEntry, err := zipWriter.Create(fileName)
+		if err != nil {
+			logger.ErrorF(ctx, "ZIP 添加条目失败 [%s]: %v", fileName, err)
+			continue
+		}
+
+		obj, err := uploadstorage.OpenStoredObject(ctx, &upload)
+		if err != nil {
+			logger.ErrorF(ctx, "打包时读取文件失败: %v", err)
+			continue
+		}
+		rc := obj.Body
+
+		_, err = io.Copy(zipFileEntry, rc)
+		_ = rc.Close()
+		if err != nil {
+			logger.ErrorF(ctx, "写入 ZIP 流失败: %v", err)
+		}
+	}
+}
+
+func resolveUploadAccessMode(c *gin.Context, uploadType string) (int, string) {
+	accessModeStr := c.PostForm("access_mode")
+	if accessModeStr == "" {
+		if uploadType == shared.DefaultPublicUploadType {
+			return 1, ""
+		}
+		return 0, ""
+	}
+
+	accessMode, err := strconv.Atoi(accessModeStr)
+	if err != nil || (accessMode != 0 && accessMode != 1) {
+		return 0, "无效的 access_mode 参数"
+	}
+	return accessMode, ""
+}
+
+func parseUploadMetadata(c *gin.Context, mimeType string) (models.UploadMetadata, string) {
+	var meta models.UploadMetadata
+	metadataStr := c.DefaultPostForm("metadata", "")
+	if metadataStr != "" {
+		if err := json.Unmarshal([]byte(metadataStr), &meta); err != nil {
+			return meta, shared.ErrInvalidMetadataJSON
+		}
+	}
+	meta.OriginalMime = mimeType
+	meta.UserAgent = c.Request.UserAgent()
+	meta.ClientIP = c.ClientIP()
+	return meta, ""
+}
+
+func detectMimeType(buf *bytes.Buffer, header *multipart.FileHeader, size int64) string {
+	mimeType := http.DetectContentType(buf.Bytes()[:min(shared.DetectContentBytes, int(size))])
+	if mimeType == "application/octet-stream" && header.Header.Get("Content-Type") != "" {
+		mimeType = header.Header.Get("Content-Type")
+	}
+	return mimeType
+}

backend/plugins/domain/upload/handler/routers_test.go

@@ -0,0 +1,973 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+	"github.com/gin-gonic/gin"
+)
+
+type testResponse struct {
+	ErrorMsg string          `json:"error_msg"`
+	Data     json.RawMessage `json:"data"`
+}
+
+func setupTestRouter(authUser *contracts.UserDTO) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.Use(response.ErrorHandlerMiddleware())
+
+	authMiddleware := func(c *gin.Context) {
+		if authUser != nil {
+			util.SetToContext[*contracts.UserDTO](c, contracts.AuthUserObjKey, authUser)
+		}
+		c.Next()
+	}
+
+	uploadGroup := r.Group("/api/v1/upload")
+	uploadGroup.Use(authMiddleware)
+	{
+		uploadGroup.POST("", UploadFile)
+		uploadGroup.GET("/my", ListMyFiles)
+		uploadGroup.DELETE("/:id", DeleteMyFile)
+		uploadGroup.PUT("/:id", UpdateMyFile)
+		uploadGroup.GET("/download/:id", DownloadFile)
+		uploadGroup.POST("/download/batch", BatchDownloadFiles)
+	}
+
+	adminGroup := r.Group("/api/v1/admin/uploads")
+	adminGroup.Use(authMiddleware)
+	{
+		adminGroup.GET("", ListFiles)
+		adminGroup.GET("/stats", GetFileStats)
+		adminGroup.DELETE("/:id", DeleteFile)
+		adminGroup.GET("/download/:id", DownloadFile)
+		adminGroup.POST("/download/batch", BatchDownloadFiles)
+	}
+
+	return r
+}
+
+func createMultipartRequest(t *testing.T, fieldName, fileName string, fileContent []byte, extraFields map[string]string) (string, *bytes.Buffer) {
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+
+	part, err := writer.CreateFormFile(fieldName, fileName)
+	if err != nil {
+		t.Fatalf("failed to create form file: %v", err)
+	}
+
+	_, err = part.Write(fileContent)
+	if err != nil {
+		t.Fatalf("failed to write file content: %v", err)
+	}
+
+	for k, v := range extraFields {
+		err = writer.WriteField(k, v)
+		if err != nil {
+			t.Fatalf("failed to write form field: %v", err)
+		}
+	}
+
+	err = writer.Close()
+	if err != nil {
+		t.Fatalf("failed to close multipart writer: %v", err)
+	}
+
+	return writer.FormDataContentType(), body
+}
+
+func TestUploadFile(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	defer func() { _ = os.RemoveAll("uploads") }() // Clean up local files created during tests
+
+	authUser := &contracts.UserDTO{ID: 1001, Username: "test_user"}
+	router := setupTestRouter(authUser)
+
+	// Mock Storage Client
+	mockFiles := make(map[string][]byte)
+	var putCount int
+
+	restoreStorage := objectstore.MockStorage(
+		func(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+			data, err := io.ReadAll(body)
+			if err != nil {
+				return err
+			}
+			mockFiles[key] = data
+			putCount++
+			return nil
+		},
+		func(ctx context.Context, key string) (*objectstore.Object, error) {
+			data, ok := mockFiles[key]
+			if !ok {
+				return nil, os.ErrNotExist
+			}
+			return &objectstore.Object{
+				Body:          io.NopCloser(bytes.NewReader(data)),
+				ContentLength: int64(len(data)),
+				ContentType:   "application/octet-stream",
+			}, nil
+		},
+		func(ctx context.Context, key string) error {
+			delete(mockFiles, key)
+			return nil
+		},
+	)
+	defer restoreStorage()
+
+	// 开启 S3 Storage
+	objectstore.IsEnabledFunc = func() bool { return true }
+	defer func() {
+		objectstore.IsEnabledFunc = func() bool { return false }
+	}()
+
+	t.Run("upload allowed image file successfully", func(t *testing.T) {
+		putCount = 0
+		imgContent := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89") // Valid PNG header
+		contentType, body := createMultipartRequest(t, "file", "test.png", imgContent, map[string]string{
+			"type":     "avatar",
+			"metadata": `{"extra":{"source":"test_runner"}}`,
+		})
+
+		req, _ := http.NewRequest("POST", "/api/v1/upload", body)
+		req.Header.Set("Content-Type", contentType)
+
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp testResponse
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to unmarshal response: %v", err)
+		}
+
+		if resp.ErrorMsg != "" {
+			t.Fatalf("expected success response, got failure: %s", resp.ErrorMsg)
+		}
+
+		// Verify database record
+		var uploadRecord models.Upload
+		if err := json.Unmarshal(resp.Data, &uploadRecord); err != nil {
+			t.Fatalf("failed to unmarshal upload record: %v", err)
+		}
+
+		var dbRecord models.Upload
+		if err := dbConn.First(&dbRecord, uploadRecord.ID).Error; err != nil {
+			t.Fatalf("failed to retrieve database record: %v", err)
+		}
+
+		if dbRecord.FileName != "test.png" || dbRecord.Extension != "png" {
+			t.Errorf("incorrect filename or extension: %s, %s", dbRecord.FileName, dbRecord.Extension)
+		}
+
+		if dbRecord.MimeType != "image/png" {
+			t.Errorf("incorrect mime type detected: %s", dbRecord.MimeType)
+		}
+
+		if dbRecord.Metadata.Extra["source"] != "test_runner" {
+			t.Errorf("expected extra meta 'source' to be 'test_runner', got %v", dbRecord.Metadata.Extra)
+		}
+
+		if putCount != 1 {
+			t.Errorf("expected 1 storage Put operation, got %d", putCount)
+		}
+	})
+
+	t.Run("upload blocked extension file", func(t *testing.T) {
+		// System config allowed: jpg,png,webp. Uploading docx should be blocked.
+		contentType, body := createMultipartRequest(t, "file", "contract.docx", []byte("fake docx content"), nil)
+		req, _ := http.NewRequest("POST", "/api/v1/upload", body)
+		req.Header.Set("Content-Type", contentType)
+
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Fatalf("expected status 400, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp testResponse
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg == "" || !strings.Contains(resp.ErrorMsg, shared.ErrUnsupportedFormat) {
+			t.Errorf("expected unsupported format error, got: %v", resp)
+		}
+	})
+
+	t.Run("instant upload deduplication (秒传)", func(t *testing.T) {
+		putCount = 0
+		imgContent := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01")
+
+		// Upload first time
+		contentType1, body1 := createMultipartRequest(t, "file", "avatar1.png", imgContent, map[string]string{"type": "avatar"})
+		req1, _ := http.NewRequest("POST", "/api/v1/upload", body1)
+		req1.Header.Set("Content-Type", contentType1)
+		w1 := httptest.NewRecorder()
+		router.ServeHTTP(w1, req1)
+
+		if w1.Code != http.StatusOK {
+			t.Fatalf("first upload failed: %s", w1.Body.String())
+		}
+		if putCount != 1 {
+			t.Errorf("expected 1 put count on first upload, got %d", putCount)
+		}
+
+		// Upload same file second time (different filename, same content)
+		contentType2, body2 := createMultipartRequest(t, "file", "avatar2.png", imgContent, map[string]string{"type": "avatar"})
+		req2, _ := http.NewRequest("POST", "/api/v1/upload", body2)
+		req2.Header.Set("Content-Type", contentType2)
+		w2 := httptest.NewRecorder()
+		router.ServeHTTP(w2, req2)
+
+		if w2.Code != http.StatusOK {
+			t.Fatalf("second upload failed: %s", w2.Body.String())
+		}
+
+		var resp2 testResponse
+		_ = json.Unmarshal(w2.Body.Bytes(), &resp2)
+
+		if resp2.ErrorMsg != "" {
+			t.Fatalf("second upload was unsuccessful: %s", resp2.ErrorMsg)
+		}
+
+		var uploadRecord2 models.Upload
+		if err := json.Unmarshal(resp2.Data, &uploadRecord2); err != nil {
+			t.Fatalf("failed to unmarshal second upload record: %v", err)
+		}
+
+		// Check if it triggered another storage put
+		if putCount != 1 {
+			t.Errorf("PutObject was triggered again! Expected deduplication (putCount=1), got putCount=%d", putCount)
+		}
+
+		// Check if database contains both records sharing the same FilePath
+		var records []models.Upload
+		dbConn.Where("hash = ?", uploadRecord2.Hash).Find(&records)
+		if len(records) != 2 {
+			t.Errorf("expected 2 database records sharing the same hash, got %d", len(records))
+		}
+		if records[0].FilePath != records[1].FilePath {
+			t.Errorf("file paths are different: %s vs %s", records[0].FilePath, records[1].FilePath)
+		}
+		if records[0].ID == records[1].ID {
+			t.Error("database record IDs should be unique")
+		}
+
+		t.Logf("Instant upload success. Record 1: %d, Record 2: %d", records[0].ID, records[1].ID)
+	})
+
+	t.Run("upload in local storage fallback mode", func(t *testing.T) {
+		// Turn off S3
+		objectstore.IsEnabledFunc = func() bool { return false }
+
+		// Seed allowed extensions configuration to allow txt files
+		dbConn.Table("w_system_configs").Where("key = ?", "upload_allowed_extensions").Update("value", "jpg,png,webp,txt")
+
+		contentType, body := createMultipartRequest(t, "file", "doc.txt", []byte("hello world generic document file"), map[string]string{
+			"type": "document",
+		})
+		req, _ := http.NewRequest("POST", "/api/v1/upload", body)
+		req.Header.Set("Content-Type", contentType)
+
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp testResponse
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		if resp.ErrorMsg != "" {
+			t.Fatalf("local upload failed: %s", resp.ErrorMsg)
+		}
+
+		var localRecord models.Upload
+		if err := json.Unmarshal(resp.Data, &localRecord); err != nil {
+			t.Fatalf("failed to unmarshal local upload record: %v", err)
+		}
+
+		// Confirm file was actually written to local disk
+		fileContent, err := os.ReadFile(localRecord.FilePath)
+		if err != nil {
+			t.Fatalf("failed to read local file: %v", err)
+		}
+
+		if string(fileContent) != "hello world generic document file" {
+			t.Errorf("unexpected local file contents: %s", string(fileContent))
+		}
+	})
+}
+
+func TestDownloadFile(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	defer func() { _ = os.RemoveAll("uploads") }()
+
+	authUser := &contracts.UserDTO{ID: 1001, Username: "test_user"}
+	router := setupTestRouter(authUser)
+
+	// Seed upload records in DB
+	localUpload := models.Upload{
+		ID:        2001,
+		UserID:    1001,
+		FileName:  "中文文件名.txt",
+		FilePath:  "uploads/test_download.txt",
+		FileSize:  12,
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Status:    models.UploadStatusUsed,
+	}
+
+	// Create local file
+	err := os.MkdirAll("uploads", 0755)
+	if err != nil {
+		t.Fatalf("failed to create directory: %v", err)
+	}
+	err = os.WriteFile(localUpload.FilePath, []byte("hello download"), 0644)
+	if err != nil {
+		t.Fatalf("failed to write file: %v", err)
+	}
+
+	dbConn.Create(&localUpload)
+
+	t.Run("download file successfully", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/uploads/download/2001", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		if w.Body.String() != "hello download" {
+			t.Errorf("expected body 'hello download', got '%s'", w.Body.String())
+		}
+
+		// Verify Content-Disposition header (supports UTF-8 escaping)
+		contentDisp := w.Header().Get("Content-Disposition")
+		expectedDisp := "attachment; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6%E5%90%8D.txt"
+		if contentDisp != expectedDisp {
+			t.Errorf("expected Content-Disposition header %q, got %q", expectedDisp, contentDisp)
+		}
+
+		if !strings.HasPrefix(w.Header().Get("Content-Type"), "text/plain") {
+			t.Errorf("expected Content-Type starting with text/plain, got %s", w.Header().Get("Content-Type"))
+		}
+	})
+
+	t.Run("download non-existent file", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/uploads/download/9999", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected status 404, got %d", w.Code)
+		}
+	})
+}
+
+func TestListFiles(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	authUser := &contracts.UserDTO{ID: 1001, Username: "test_user"}
+	router := setupTestRouter(authUser)
+
+	uploads := []models.Upload{
+		{
+			ID:        2101,
+			UserID:    authUser.ID,
+			FileName:  "first-report.txt",
+			FilePath:  "uploads/first-report.txt",
+			FileSize:  10,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        2102,
+			UserID:    authUser.ID,
+			FileName:  "Second-Photo.PNG",
+			FilePath:  "uploads/second-photo.png",
+			FileSize:  20,
+			MimeType:  "image/png",
+			Extension: "png",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        2103,
+			UserID:    authUser.ID,
+			FileName:  "third-notes.md",
+			FilePath:  "uploads/third-notes.md",
+			FileSize:  30,
+			MimeType:  "text/markdown",
+			Extension: "md",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        2104,
+			UserID:    2002,
+			FileName:  "other-user.txt",
+			FilePath:  "uploads/other-user.txt",
+			FileSize:  40,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Status:    models.UploadStatusUsed,
+		},
+	}
+	for i := range uploads {
+		if err := dbConn.Create(&uploads[i]).Error; err != nil {
+			t.Fatalf("failed to create upload %d: %v", uploads[i].ID, err)
+		}
+	}
+
+	t.Run("returns requested page", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/uploads?page=2&page_size=2", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp testResponse
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+		if resp.ErrorMsg != "" {
+			t.Fatalf("ListFiles() error = %q, want empty", resp.ErrorMsg)
+		}
+
+		var got listFilesResponse
+		if err := json.Unmarshal(resp.Data, &got); err != nil {
+			t.Fatalf("failed to parse list response: %v", err)
+		}
+		if got.Page != 2 {
+			t.Errorf("ListFiles(page=2).Page = %d, want 2", got.Page)
+		}
+		if got.PageSize != 2 {
+			t.Errorf("ListFiles(page_size=2).PageSize = %d, want 2", got.PageSize)
+		}
+		if got.Total != 4 {
+			t.Errorf("ListFiles().Total = %d, want 4", got.Total)
+		}
+		if len(got.Items) != 2 {
+			t.Fatalf("ListFiles(page=2, page_size=2) returned %d items, want 2", len(got.Items))
+		}
+	})
+
+	t.Run("filters filename case insensitively", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/uploads?keyword=photo", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp testResponse
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+		if resp.ErrorMsg != "" {
+			t.Fatalf("ListFiles(keyword=photo) error = %q, want empty", resp.ErrorMsg)
+		}
+
+		var got listFilesResponse
+		if err := json.Unmarshal(resp.Data, &got); err != nil {
+			t.Fatalf("failed to parse list response: %v", err)
+		}
+		if got.Total != 1 {
+			t.Errorf("ListFiles(keyword=photo).Total = %d, want 1", got.Total)
+		}
+		if len(got.Items) != 1 {
+			t.Fatalf("ListFiles(keyword=photo) returned %d items, want 1", len(got.Items))
+		}
+		if got.Items[0].FileName != "Second-Photo.PNG" {
+			t.Errorf("ListFiles(keyword=photo).Items[0].FileName = %q, want %q", got.Items[0].FileName, "Second-Photo.PNG")
+		}
+	})
+
+	t.Run("filters by user_id", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/uploads?user_id=1001", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp testResponse
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+		if resp.ErrorMsg != "" {
+			t.Fatalf("ListFiles(user_id=1001) error = %q, want empty", resp.ErrorMsg)
+		}
+
+		var got listFilesResponse
+		if err := json.Unmarshal(resp.Data, &got); err != nil {
+			t.Fatalf("failed to parse list response: %v", err)
+		}
+		if got.Total != 3 {
+			t.Errorf("ListFiles(user_id=1001).Total = %d, want 3", got.Total)
+		}
+		if len(got.Items) != 3 {
+			t.Fatalf("ListFiles(user_id=1001) returned %d items, want 3", len(got.Items))
+		}
+	})
+}
+
+func TestBatchDownloadFiles(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	defer func() { _ = os.RemoveAll("uploads") }()
+
+	authUser := &contracts.UserDTO{ID: 1001, Username: "test_user"}
+	router := setupTestRouter(authUser)
+
+	// Create and write files locally
+	err := os.MkdirAll("uploads", 0755)
+	if err != nil {
+		t.Fatalf("failed to create local dir: %v", err)
+	}
+
+	_ = os.WriteFile("uploads/f1.txt", []byte("file1 content"), 0644)
+	_ = os.WriteFile("uploads/f2.txt", []byte("file2 content"), 0644)
+	_ = os.WriteFile("uploads/f3.txt", []byte("duplicate name file content"), 0644)
+
+	// Seed upload records. Note f2 and f3 have the same FileName "file_a.txt" to trigger name collision resolution.
+	uploads := []models.Upload{
+		{
+			ID:        3001,
+			UserID:    1001,
+			FileName:  "file_a.txt",
+			FilePath:  "uploads/f1.txt",
+			FileSize:  13,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        3002,
+			UserID:    1001,
+			FileName:  "file_b.txt",
+			FilePath:  "uploads/f2.txt",
+			FileSize:  13,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        3003,
+			UserID:    1001,
+			FileName:  "file_a.txt", // COLLISION with 3001!
+			FilePath:  "uploads/f3.txt",
+			FileSize:  28,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Status:    models.UploadStatusUsed,
+		},
+	}
+
+	for _, up := range uploads {
+		dbConn.Create(&up)
+	}
+
+	t.Run("batch download zip successfully and check duplicate renaming", func(t *testing.T) {
+		reqBody, _ := json.Marshal(batchDownloadRequest{
+			IDs: []string{"3001", "3002", "3003"},
+		})
+		req, _ := http.NewRequest("POST", "/api/v1/admin/uploads/download/batch", bytes.NewReader(reqBody))
+		req.Header.Set("Content-Type", "application/json")
+
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		if w.Header().Get("Content-Type") != "application/zip" {
+			t.Errorf("expected Content-Type application/zip, got %s", w.Header().Get("Content-Type"))
+		}
+
+		// Unzip in-memory
+		zipReader, err := zip.NewReader(bytes.NewReader(w.Body.Bytes()), int64(w.Body.Len()))
+		if err != nil {
+			t.Fatalf("failed to read zip buffer: %v", err)
+		}
+
+		if len(zipReader.File) != 3 {
+			t.Errorf("expected 3 files inside the ZIP, got %d", len(zipReader.File))
+		}
+
+		// Extract files to check their contents and name collision resolutions
+		extracted := make(map[string]string)
+		for _, f := range zipReader.File {
+			rc, err := f.Open()
+			if err != nil {
+				t.Fatalf("failed to open zip file entry %s: %v", f.Name, err)
+			}
+			content, _ := io.ReadAll(rc)
+			_ = rc.Close()
+			extracted[f.Name] = string(content)
+		}
+
+		// Checks
+		if extracted["file_a.txt"] != "file1 content" {
+			t.Errorf("file_a.txt content incorrect: %q", extracted["file_a.txt"])
+		}
+		if extracted["file_b.txt"] != "file2 content" {
+			t.Errorf("file_b.txt content incorrect: %q", extracted["file_b.txt"])
+		}
+		// The second file_a.txt should be renamed to file_a_1.txt
+		if extracted["file_a_1.txt"] != "duplicate name file content" {
+			t.Errorf("file_a_1.txt content incorrect: %q. Extracted files: %v", extracted["file_a_1.txt"], extracted)
+		}
+
+		t.Logf("Successfully unzipped batch. Extracted files: %+v", extracted)
+	})
+}
+
+func TestUploadAccessModeAccessControl(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	defer func() { _ = os.RemoveAll("uploads") }()
+
+	user1 := &contracts.UserDTO{ID: 1001, Username: "user1"}
+	user2 := &contracts.UserDTO{ID: 1002, Username: "user2"}
+
+	// Seed user1
+	if err := dbConn.Create(user1).Error; err != nil {
+		t.Fatalf("create test user1 failed: %v", err)
+	}
+	// Seed user2
+	if err := dbConn.Create(user2).Error; err != nil {
+		t.Fatalf("create test user2 failed: %v", err)
+	}
+
+	router := setupTestRouter(user1)
+
+	// 1. Upload private file for user1 (explicitly specifying access_mode = 0)
+	imgContent := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89")
+	contentType, body := createMultipartRequest(t, "file", "private.png", imgContent, map[string]string{
+		"type":        "generic",
+		"access_mode": "0",
+	})
+	req, _ := http.NewRequest("POST", "/api/v1/upload", body)
+	req.Header.Set("Content-Type", contentType)
+
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("Upload failed: %d, %s", w.Code, w.Body.String())
+	}
+	t.Logf("Raw upload response: %s", w.Body.String())
+	var resp1 testResponse
+	_ = json.Unmarshal(w.Body.Bytes(), &resp1)
+	var upload1 models.Upload
+	_ = json.Unmarshal(resp1.Data, &upload1)
+
+	if upload1.AccessMode != 0 {
+		t.Errorf("expected access_mode 0, got %d", upload1.AccessMode)
+	}
+
+	// 2. Upload public file for user1 (type avatar, should default to public 1)
+	contentType2, body2 := createMultipartRequest(t, "file", "public.png", []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89"), map[string]string{
+		"type": "avatar",
+	})
+	req2, _ := http.NewRequest("POST", "/api/v1/upload", body2)
+	req2.Header.Set("Content-Type", contentType2)
+
+	w2 := httptest.NewRecorder()
+	router.ServeHTTP(w2, req2)
+	var resp2 testResponse
+	_ = json.Unmarshal(w2.Body.Bytes(), &resp2)
+	var upload2 models.Upload
+	_ = json.Unmarshal(resp2.Data, &upload2)
+
+	if upload2.AccessMode != 1 {
+		t.Errorf("expected access_mode 1 (public) for avatar, got %d", upload2.AccessMode)
+	}
+
+	// 3. Verify accessing private file as user1 (owner) succeeds
+	wAccessOwner := httptest.NewRecorder()
+	reqAccessOwner, _ := http.NewRequest("GET", "/api/v1/admin/uploads/download/"+strconv.FormatUint(upload1.ID, 10), nil)
+	router.ServeHTTP(wAccessOwner, reqAccessOwner)
+	if wAccessOwner.Code != http.StatusOK {
+		t.Errorf("owner should be allowed to download private file, got status %d", wAccessOwner.Code)
+	}
+
+	// 4. Verify accessing private file as user2 (non-owner) fails
+	routerUser2 := setupTestRouter(user2)
+	wAccessOther := httptest.NewRecorder()
+	reqAccessOther, _ := http.NewRequest("GET", "/api/v1/admin/uploads/download/"+strconv.FormatUint(upload1.ID, 10), nil)
+	routerUser2.ServeHTTP(wAccessOther, reqAccessOther)
+	if wAccessOther.Code != http.StatusUnauthorized {
+		t.Errorf("non-owner should be denied download of private file, got status %d, want 401", wAccessOther.Code)
+	}
+
+	// 5. Verify accessing public file as user2 (non-owner) succeeds
+	wAccessPublic := httptest.NewRecorder()
+	reqAccessPublic, _ := http.NewRequest("GET", "/api/v1/admin/uploads/download/"+strconv.FormatUint(upload2.ID, 10), nil)
+	routerUser2.ServeHTTP(wAccessPublic, reqAccessPublic)
+	if wAccessPublic.Code != http.StatusOK {
+		t.Errorf("any logged-in user should be allowed to download public file, got status %d", wAccessPublic.Code)
+	}
+}
+
+func TestGetFileStats(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	authUser := &contracts.UserDTO{ID: 1001, Username: "test_user"}
+	router := setupTestRouter(authUser)
+
+	// Insert some dummy uploads
+	uploads := []models.Upload{
+		{
+			ID:        3101,
+			UserID:    authUser.ID,
+			FileName:  "photo.png",
+			FilePath:  "uploads/photo.png",
+			FileSize:  100,
+			MimeType:  "image/png",
+			Extension: "png",
+			Type:      "generic",
+			Status:    models.UploadStatusUsed,
+			CreatedAt: time.Now(),
+		},
+		{
+			ID:        3102,
+			UserID:    authUser.ID,
+			FileName:  "video.mp4",
+			FilePath:  "uploads/video.mp4",
+			FileSize:  500,
+			MimeType:  "video/mp4",
+			Extension: "mp4",
+			Type:      "generic",
+			Status:    models.UploadStatusUsed,
+			CreatedAt: time.Now().AddDate(0, 0, -2), // 2 days ago
+		},
+		{
+			ID:        3103,
+			UserID:    authUser.ID,
+			FileName:  "document.pdf",
+			FilePath:  "uploads/document.pdf",
+			FileSize:  200,
+			MimeType:  "application/pdf",
+			Extension: "pdf",
+			Type:      "avatar", // different type
+			Status:    models.UploadStatusUsed,
+			CreatedAt: time.Now().AddDate(0, 0, -10), // older than 7 days
+		},
+	}
+
+	for i := range uploads {
+		if err := dbConn.Create(&uploads[i]).Error; err != nil {
+			t.Fatalf("failed to create upload: %v", err)
+		}
+	}
+	if err := uploadstats.RebuildUploadStats(context.Background()); err != nil {
+		t.Fatalf("failed to rebuild upload stats: %v", err)
+	}
+
+	req, _ := http.NewRequest("GET", "/api/v1/admin/uploads/stats", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d, body: %s", w.Code, w.Body.String())
+	}
+
+	var resp struct {
+		ErrorMsg string            `json:"error_msg"`
+		Data     fileStatsResponse `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal response: %v", err)
+	}
+
+	if resp.ErrorMsg != "" {
+		t.Fatalf("expected no error, got: %s", resp.ErrorMsg)
+	}
+
+	// Verify total count and size
+	if resp.Data.TotalCount != 3 {
+		t.Errorf("expected 3 total files, got %d", resp.Data.TotalCount)
+	}
+	if resp.Data.TotalSize != 800 {
+		t.Errorf("expected 800 total size, got %d", resp.Data.TotalSize)
+	}
+
+	// Verify trend (last 7 days should include photo.png (100) and video.mp4 (500), but NOT pdf (older))
+	// Total size in trend should be 600
+	var trendSizeSum int64
+	for _, trendItem := range resp.Data.Trend {
+		trendSizeSum += trendItem.Size
+	}
+	if trendSizeSum != 600 {
+		t.Errorf("expected 7-day trend size sum to be 600, got %d", trendSizeSum)
+	}
+
+	// Verify categories
+	categoryMap := make(map[string]int64)
+	for _, cat := range resp.Data.Categories {
+		categoryMap[cat.Name] = cat.Count
+	}
+	if categoryMap["图片"] != 1 {
+		t.Errorf("expected 1 image category, got %d", categoryMap["图片"])
+	}
+	if categoryMap["视频"] != 1 {
+		t.Errorf("expected 1 video category, got %d", categoryMap["视频"])
+	}
+	if categoryMap["文档"] != 1 {
+		t.Errorf("expected 1 document category, got %d", categoryMap["文档"])
+	}
+}
+
+func TestUserUploadManagement(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	user1 := &contracts.UserDTO{ID: 1001, Username: "user1"}
+	user2 := &contracts.UserDTO{ID: 1002, Username: "user2"}
+
+	_ = dbConn.Create(user1)
+	_ = dbConn.Create(user2)
+
+	router1 := setupTestRouter(user1)
+	router2 := setupTestRouter(user2)
+
+	// Seed upload records
+	upload1 := models.Upload{
+		ID:        4001,
+		UserID:    1001,
+		FileName:  "user1-file.txt",
+		FilePath:  "uploads/user1-file.txt",
+		FileSize:  100,
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+	upload2 := models.Upload{
+		ID:        4002,
+		UserID:    1002,
+		FileName:  "user2-file.png",
+		FilePath:  "uploads/user2-file.png",
+		FileSize:  200,
+		MimeType:  "image/png",
+		Extension: "png",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+
+	_ = dbConn.Create(&upload1)
+	_ = dbConn.Create(&upload2)
+
+	t.Run("ListMyFiles only returns own files", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/upload/my", nil)
+		w := httptest.NewRecorder()
+		router1.ServeHTTP(w, req)
+
+		var resp struct {
+			ErrorMsg string              `json:"error_msg"`
+			Data     listMyFilesResponse `json:"data"`
+		}
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		if resp.ErrorMsg != "" {
+			t.Fatalf("ListMyFiles error: %s", resp.ErrorMsg)
+		}
+		if resp.Data.Total != 1 {
+			t.Errorf("expected 1 file for user1, got %d", resp.Data.Total)
+		}
+		if len(resp.Data.Items) != 1 || resp.Data.Items[0].ID != 4001 {
+			t.Errorf("expected file 4001, got items: %+v", resp.Data.Items)
+		}
+	})
+
+	t.Run("UpdateMyFile updates file name and access mode successfully", func(t *testing.T) {
+		newMode := 1
+		reqBody, _ := json.Marshal(updateMyFileRequest{
+			FileName:   "renamed.txt",
+			AccessMode: &newMode,
+		})
+		req, _ := http.NewRequest("PUT", "/api/v1/upload/4001", bytes.NewReader(reqBody))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router1.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var updated models.Upload
+		dbConn.First(&updated, 4001)
+		if updated.FileName != "renamed.txt" {
+			t.Errorf("expected file name renamed.txt, got %s", updated.FileName)
+		}
+		if updated.AccessMode != 1 {
+			t.Errorf("expected access mode 1, got %d", updated.AccessMode)
+		}
+	})
+
+	t.Run("UpdateMyFile blocks non-owners", func(t *testing.T) {
+		reqBody, _ := json.Marshal(updateMyFileRequest{
+			FileName: "hack.txt",
+		})
+		req, _ := http.NewRequest("PUT", "/api/v1/upload/4001", bytes.NewReader(reqBody))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router2.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Errorf("expected status 403, got %d", w.Code)
+		}
+	})
+
+	t.Run("DeleteMyFile blocks non-owners", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/upload/4001", nil)
+		w := httptest.NewRecorder()
+		router2.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Errorf("expected status 403, got %d", w.Code)
+		}
+	})
+
+	t.Run("DeleteMyFile deletes file successfully", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/upload/4001", nil)
+		w := httptest.NewRecorder()
+		router1.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d", w.Code)
+		}
+
+		var deleted models.Upload
+		dbConn.First(&deleted, 4001)
+		if deleted.Status != models.UploadStatusDeleted {
+			t.Errorf("expected status deleted, got %s", deleted.Status)
+		}
+	})
+}

backend/plugins/domain/upload/handler/stats.go

@@ -0,0 +1,126 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+)
+
+type trendItem struct {
+	Date  string `json:"date"`
+	Count int64  `json:"count"`
+	Size  int64  `json:"size"`
+}
+
+type distributionItem struct {
+	Name  string `json:"name"`
+	Count int64  `json:"count"`
+	Size  int64  `json:"size"`
+}
+
+type fileStatsResponse struct {
+	TotalCount int64              `json:"total_count"`
+	TotalSize  int64              `json:"total_size"`
+	Trend      []trendItem        `json:"trend"`
+	Categories []distributionItem `json:"categories"`
+	Types      []distributionItem `json:"types"`
+}
+
+// GetFileStats 获取系统上传的文件统计数据
+// @Summary 获取文件统计数据
+// @Description 返回系统级的总文件数、占用大小、最近 7 天新增趋势、文件类型/格式分布等数据
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=fileStatsResponse} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/uploads/stats [get]
+func GetFileStats(c *gin.Context) {
+	ctx := c.Request.Context()
+
+	stats, err := loadUploadStats(ctx)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	now := time.Now()
+	trendDates := make([]string, 0, shared.FileStatsTrendDays)
+	trendCountMap := make(map[string]int64, shared.FileStatsTrendDays)
+	trendSizeMap := make(map[string]int64, shared.FileStatsTrendDays)
+	for i := shared.FileStatsTrendDays - 1; i >= 0; i-- {
+		date := now.AddDate(0, 0, -i).Format("2006-01-02")
+		trendDates = append(trendDates, date)
+		trendCountMap[date] = 0
+		trendSizeMap[date] = 0
+	}
+
+	var (
+		totalCount int64
+		totalSize  int64
+		types      []distributionItem
+		categories []distributionItem
+	)
+
+	categoriesList := []string{"图片", "视频", "音频", "文档", "压缩包", "其他"}
+	categoryMap := make(map[string]distributionItem, len(categoriesList))
+	for _, cat := range categoriesList {
+		categoryMap[cat] = distributionItem{Name: cat}
+	}
+
+	for _, stat := range stats {
+		switch stat.Dimension {
+		case shared.UploadStatDimensionTotal:
+			totalCount = stat.FileCount
+			totalSize = stat.FileSize
+		case shared.UploadStatDimensionType:
+			types = append(types, distributionItem{
+				Name:  stat.StatKey,
+				Count: stat.FileCount,
+				Size:  stat.FileSize,
+			})
+		case shared.UploadStatDimensionCategory:
+			if item, ok := categoryMap[stat.StatKey]; ok {
+				item.Count = stat.FileCount
+				item.Size = stat.FileSize
+				categoryMap[stat.StatKey] = item
+			}
+		case shared.UploadStatDimensionTrend:
+			if _, ok := trendCountMap[stat.StatKey]; ok {
+				trendCountMap[stat.StatKey] = stat.FileCount
+				trendSizeMap[stat.StatKey] = stat.FileSize
+			}
+		}
+	}
+
+	categories = make([]distributionItem, 0, len(categoriesList))
+	for _, cat := range categoriesList {
+		categories = append(categories, categoryMap[cat])
+	}
+
+	trend := make([]trendItem, 0, len(trendDates))
+	for _, date := range trendDates {
+		trend = append(trend, trendItem{
+			Date:  date,
+			Count: trendCountMap[date],
+			Size:  trendSizeMap[date],
+		})
+	}
+
+	c.JSON(http.StatusOK, response.OK(fileStatsResponse{
+		TotalCount: totalCount,
+		TotalSize:  totalSize,
+		Trend:      trend,
+		Categories: categories,
+		Types:      types,
+	}))
+}

backend/plugins/domain/upload/ingest/errors.go

@@ -0,0 +1,16 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"errors"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+)
+
+// ErrForbidden indicates the caller is not allowed to mutate the upload record.
+var ErrForbidden = errors.New("upload forbidden")
+
+// ErrStorageReadOnly indicates the storage backend is in migration read-only mode.
+var ErrStorageReadOnly = errors.New(shared.ErrStorageReadOnly)

backend/plugins/domain/upload/ingest/helpers.go

@@ -0,0 +1,211 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/idgen"
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	uploadcache "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/repository"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+	"gorm.io/gorm"
+)
+
+func normalizeRequest(req *Request) {
+	req.Extension = strings.ToLower(strings.TrimSpace(req.Extension))
+	if req.Extension == "" {
+		req.Extension = "bin"
+	}
+	if req.Type == "" {
+		req.Type = "generic"
+	}
+	if req.Status == "" {
+		req.Status = models.UploadStatusUsed
+	}
+}
+
+func resolveAccessMode(uploadType string, explicit *int) int {
+	if explicit != nil {
+		return *explicit
+	}
+	if uploadType == shared.DefaultPublicUploadType {
+		return 1
+	}
+	return 0
+}
+
+func validateAllowedExtension(ctx context.Context, ext string) error {
+	var val string
+	err := database.DB(ctx).Table("w_system_configs").Where("key = ?", "upload_allowed_extensions").Pluck("value", &val).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		logger.WarnF(ctx, "failed to query upload_allowed_extensions: %v", err)
+		return nil
+	}
+	if val == "" {
+		return nil
+	}
+
+	var list []string
+	if err := json.Unmarshal([]byte(val), &list); err == nil {
+		for _, allowedExt := range list {
+			if strings.EqualFold(strings.TrimSpace(allowedExt), ext) {
+				return nil
+			}
+		}
+		return errors.New(shared.ErrUnsupportedFormat)
+	}
+
+	allowedExts := strings.Split(strings.ToLower(val), ",")
+	for _, allowedExt := range allowedExts {
+		if strings.TrimSpace(allowedExt) == ext {
+			return nil
+		}
+	}
+	return errors.New(shared.ErrUnsupportedFormat)
+}
+
+func defaultObjectKey(id uint64, ext string) string {
+	return fmt.Sprintf("uploads/%s/%d.%s", time.Now().Format("2006/01/02"), id, ext)
+}
+
+func buildObjectKey(req Request, id uint64) string {
+	if req.ObjectKeyFn != nil {
+		return req.ObjectKeyFn(id, req.Extension)
+	}
+	return defaultObjectKey(id, req.Extension)
+}
+
+func storeObject(ctx context.Context, objectKey string, reader io.Reader, size int64, mimeType string, meta *models.UploadMetadata) (string, error) {
+	if uploadstorage.ReadOnly(ctx) {
+		return "", ErrStorageReadOnly
+	}
+
+	driver, backend, err := objectstore.Active(ctx)
+	if err != nil {
+		logger.ErrorF(ctx, "初始化活动存储失败: %v", err)
+		return "", errors.New(shared.ErrSaveFileFailed)
+	}
+
+	result, err := backend.Put(ctx, objectKey, reader, size, mimeType)
+	if err != nil {
+		logger.ErrorF(ctx, "写入 %s 存储失败: %v", driver, err)
+		return "", errors.New(shared.ErrSaveFileFailed)
+	}
+
+	meta.Bucket = result.Bucket
+	return result.Key, nil
+}
+
+func persistUploadRecord(ctx context.Context, upload *models.Upload, objectKey string) error {
+	if err := createUploadWithStats(ctx, upload); err != nil {
+		_, backend, backendErr := objectstore.Active(ctx)
+		if backendErr == nil {
+			if deleteErr := backend.Delete(ctx, objectKey); deleteErr != nil {
+				logger.WarnF(ctx, "清理未写入数据库的上传对象失败: %v", deleteErr)
+			}
+		}
+		return err
+	}
+	uploadcache.SetUploadMetaCache(ctx, upload)
+	return nil
+}
+
+func createUploadWithStats(ctx context.Context, upload *models.Upload) error {
+	return database.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := repository.CreateUploadTx(tx, upload); err != nil {
+			return err
+		}
+		return uploadstats.ApplyUploadStatsDeltaTx(tx, upload, 1)
+	})
+}
+
+func createDedupRecord(ctx context.Context, existing models.Upload, req Request) (Result, error) {
+	accessMode := resolveAccessMode(req.Type, req.AccessMode)
+	newUpload := models.Upload{
+		ID:         idgen.NextUint64ID(),
+		UserID:     req.UserID,
+		FileName:   req.FileName,
+		FilePath:   existing.FilePath,
+		FileSize:   req.Size,
+		MimeType:   req.MimeType,
+		Extension:  req.Extension,
+		Hash:       req.Hash,
+		Type:       req.Type,
+		Status:     req.Status,
+		AccessMode: accessMode,
+		Metadata:   existing.Metadata,
+	}
+	if err := persistUploadRecord(ctx, &newUpload, existing.FilePath); err != nil {
+		return Result{}, err
+	}
+	logger.InfoF(ctx, "文件触发秒传成功! ID: %d, Path: %s", newUpload.ID, existing.FilePath)
+	return Result{
+		Upload:  newUpload,
+		Created: true,
+		Stored:  false,
+	}, nil
+}
+
+func uploadstorageReadOnly(ctx context.Context) bool {
+	return uploadstorage.ReadOnly(ctx)
+}
+
+func createNewUpload(ctx context.Context, req Request) (Result, error) {
+	if uploadstorageReadOnly(ctx) {
+		return Result{}, ErrStorageReadOnly
+	}
+	if !req.SkipExtensionCheck {
+		if err := validateAllowedExtension(ctx, req.Extension); err != nil {
+			return Result{}, err
+		}
+	}
+
+	id := idgen.NextUint64ID()
+	objectKey := buildObjectKey(req, id)
+	storedKey, err := storeObject(ctx, objectKey, req.Reader, req.Size, req.MimeType, &req.Metadata)
+	if err != nil {
+		return Result{}, err
+	}
+
+	accessMode := resolveAccessMode(req.Type, req.AccessMode)
+	upload := models.Upload{
+		ID:         id,
+		UserID:     req.UserID,
+		FileName:   req.FileName,
+		FilePath:   storedKey,
+		FileSize:   req.Size,
+		MimeType:   req.MimeType,
+		Extension:  req.Extension,
+		Hash:       req.Hash,
+		Type:       req.Type,
+		Status:     req.Status,
+		AccessMode: accessMode,
+		Metadata:   req.Metadata,
+	}
+	if err := persistUploadRecord(ctx, &upload, storedKey); err != nil {
+		return Result{}, err
+	}
+
+	return Result{
+		Upload:  upload,
+		Created: true,
+		Stored:  true,
+	}, nil
+}

backend/plugins/domain/upload/ingest/ingest.go

@@ -0,0 +1,64 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"context"
+	"errors"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/repository"
+	"gorm.io/gorm"
+)
+
+// Ingest stores or resolves an upload using the configured policy and side effects.
+func Ingest(ctx context.Context, req Request) (Result, error) {
+	normalizeRequest(&req)
+	if req.Hash == "" {
+		return Result{}, errors.New("ingest hash is required")
+	}
+	if req.Reader == nil {
+		return Result{}, errors.New("ingest reader is required")
+	}
+	if req.Size < 0 {
+		return Result{}, errors.New("ingest size must be non-negative")
+	}
+
+	switch req.Policy {
+	case PolicyDedupNewRecord, PolicyResolveExisting:
+		return ingestWithHashPolicy(ctx, req)
+	case PolicyCreate:
+		return createNewUpload(ctx, req)
+	default:
+		return Result{}, errors.New("unsupported ingest policy")
+	}
+}
+
+// FindByHash returns a reusable active upload with the same hash and size.
+func FindByHash(ctx context.Context, hash string, size int64) (models.Upload, error) {
+	return repository.FindReusableUploadByHash(ctx, hash, size)
+}
+
+func ingestWithHashPolicy(ctx context.Context, req Request) (Result, error) {
+	existing, err := repository.FindReusableUploadByHash(ctx, req.Hash, req.Size)
+	if err == nil {
+		switch req.Policy {
+		case PolicyResolveExisting:
+			return Result{
+				Upload:   existing,
+				Resolved: true,
+			}, nil
+		case PolicyDedupNewRecord:
+			if uploadstorageReadOnly(ctx) {
+				return Result{}, ErrStorageReadOnly
+			}
+			return createDedupRecord(ctx, existing, req)
+		}
+	}
+	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+		return Result{}, err
+	}
+
+	return createNewUpload(ctx, req)
+}

backend/plugins/domain/upload/ingest/ingest_test.go

@@ -0,0 +1,329 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+func TestIngestPolicyCreateIncrementsStats(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01")
+	hash := sha256.Sum256(content)
+
+	restoreStorage, disableStorage := setupMockStorage(t, nil)
+	defer restoreStorage()
+	defer disableStorage()
+
+	result, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "mirror.png",
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hex.EncodeToString(hash[:]),
+		Type:      "pixez_mirror",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("Ingest(PolicyCreate) returned error: %v", err)
+	}
+	if !result.Created || !result.Stored || result.Resolved {
+		t.Fatalf("Ingest(PolicyCreate) = %+v, want Created+Stored without Resolved", result)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats returned error: %v", err)
+	}
+	if stats.TotalCount != 1 || stats.TotalSize != int64(len(content)) {
+		t.Fatalf("loadTotalStats() = count %d size %d, want count 1 size %d", stats.TotalCount, stats.TotalSize, len(content))
+	}
+}
+
+func TestIngestPolicyResolveExistingSkipsStatsOnHit(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01")
+	hash := sha256.Sum256(content)
+	hashStr := hex.EncodeToString(hash[:])
+
+	existing := models.Upload{
+		ID:        88001,
+		UserID:    42,
+		FileName:  "existing.png",
+		FilePath:  "uploads/existing.png",
+		FileSize:  int64(len(content)),
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hashStr,
+		Type:      "pixez_mirror",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+	if err := dbConn.Create(&existing).Error; err != nil {
+		t.Fatalf("seed upload failed: %v", err)
+	}
+
+	restoreStorage, disableStorage := setupMockStorage(t, nil)
+	defer restoreStorage()
+	defer disableStorage()
+
+	result, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "mirror.png",
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hashStr,
+		Type:      "pixez_mirror",
+		Policy:    PolicyResolveExisting,
+	})
+	if err != nil {
+		t.Fatalf("Ingest(PolicyResolveExisting) returned error: %v", err)
+	}
+	if !result.Resolved || result.Created || result.Stored {
+		t.Fatalf("Ingest(PolicyResolveExisting) = %+v, want Resolved only", result)
+	}
+	if result.Upload.ID != existing.ID {
+		t.Fatalf("Ingest(PolicyResolveExisting).Upload.ID = %d, want %d", result.Upload.ID, existing.ID)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats returned error: %v", err)
+	}
+	if stats.TotalCount != 0 || stats.TotalSize != 0 {
+		t.Fatalf("loadTotalStats() = count %d size %d, want zero stats for resolved upload", stats.TotalCount, stats.TotalSize)
+	}
+}
+
+func TestIngestPolicyDedupNewRecordCreatesSecondRecord(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01")
+	hash := sha256.Sum256(content)
+	hashStr := hex.EncodeToString(hash[:])
+	putCount := 0
+
+	restoreStorage, disableStorage := setupMockStorage(t, &putCount)
+	defer restoreStorage()
+	defer disableStorage()
+
+	first, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "first.png",
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hashStr,
+		Type:      "avatar",
+		Policy:    PolicyDedupNewRecord,
+	})
+	if err != nil {
+		t.Fatalf("first Ingest returned error: %v", err)
+	}
+	if putCount != 1 {
+		t.Fatalf("putCount after first ingest = %d, want 1", putCount)
+	}
+
+	second, err := Ingest(ctx, Request{
+		UserID:    1002,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "second.png",
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hashStr,
+		Type:      "avatar",
+		Policy:    PolicyDedupNewRecord,
+	})
+	if err != nil {
+		t.Fatalf("second Ingest returned error: %v", err)
+	}
+	if putCount != 1 {
+		t.Fatalf("putCount after dedup ingest = %d, want 1", putCount)
+	}
+	if first.Upload.FilePath != second.Upload.FilePath {
+		t.Fatalf("dedup file paths differ: %s vs %s", first.Upload.FilePath, second.Upload.FilePath)
+	}
+	if first.Upload.ID == second.Upload.ID {
+		t.Fatal("dedup records should have unique IDs")
+	}
+
+	var count int64
+	if err := dbConn.Model(&models.Upload{}).Where("hash = ?", hashStr).Count(&count).Error; err != nil {
+		t.Fatalf("count uploads failed: %v", err)
+	}
+	if count != 2 {
+		t.Fatalf("upload count = %d, want 2", count)
+	}
+}
+
+func TestCreateUploadWithStatsRollsBackOnCreateFailure(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	existing := models.Upload{
+		ID:        99001,
+		UserID:    1001,
+		FileName:  "existing.png",
+		FilePath:  "uploads/existing.png",
+		FileSize:  64,
+		MimeType:  "image/png",
+		Extension: "png",
+		Type:      "generic",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+	if err := dbConn.Create(&existing).Error; err != nil {
+		t.Fatalf("seed upload failed: %v", err)
+	}
+
+	duplicate := &models.Upload{
+		ID:        existing.ID,
+		UserID:    1002,
+		FileName:  "duplicate.png",
+		FilePath:  "uploads/duplicate.png",
+		FileSize:  128,
+		MimeType:  "image/png",
+		Extension: "png",
+		Type:      "generic",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+	if err := createUploadWithStats(ctx, duplicate); err == nil {
+		t.Fatal("createUploadWithStats with duplicate ID expected error")
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats returned error: %v", err)
+	}
+	if stats.TotalCount != 0 || stats.TotalSize != 0 {
+		t.Fatalf("loadTotalStats() = count %d size %d, want zero after rolled-back stats", stats.TotalCount, stats.TotalSize)
+	}
+}
+
+func TestRemoveDecrementsStats(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01")
+	hash := sha256.Sum256(content)
+
+	restoreStorage, disableStorage := setupMockStorage(t, nil)
+	defer restoreStorage()
+	defer disableStorage()
+
+	result, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "delete-me.png",
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hex.EncodeToString(hash[:]),
+		Type:      "generic",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("Ingest returned error: %v", err)
+	}
+
+	if _, err := Remove(ctx, result.Upload.ID); err != nil {
+		t.Fatalf("Remove(%d) returned error: %v", result.Upload.ID, err)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats returned error: %v", err)
+	}
+	if stats.TotalCount != 0 || stats.TotalSize != 0 {
+		t.Fatalf("loadTotalStats() after remove = count %d size %d, want zero", stats.TotalCount, stats.TotalSize)
+	}
+}
+
+type totalStatsSnapshot struct {
+	TotalCount int64
+	TotalSize  int64
+}
+
+func loadTotalStats(ctx context.Context) (totalStatsSnapshot, error) {
+	var rows []models.UploadStat
+	if err := database.DB(ctx).Where("dimension = ?", models.UploadStatDimensionTotal).Find(&rows).Error; err != nil {
+		return totalStatsSnapshot{}, err
+	}
+	if len(rows) == 0 {
+		return totalStatsSnapshot{}, nil
+	}
+	return totalStatsSnapshot{
+		TotalCount: rows[0].FileCount,
+		TotalSize:  rows[0].FileSize,
+	}, nil
+}
+
+func setupMockStorage(t *testing.T, putCount *int) (restore func(), disable func()) {
+	t.Helper()
+	mockFiles := make(map[string][]byte)
+	restore = objectstore.MockStorage(
+		func(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+			data, err := io.ReadAll(body)
+			if err != nil {
+				return err
+			}
+			mockFiles[key] = data
+			if putCount != nil {
+				*putCount++
+			}
+			return nil
+		},
+		func(ctx context.Context, key string) (*objectstore.Object, error) {
+			data, ok := mockFiles[key]
+			if !ok {
+				return nil, os.ErrNotExist
+			}
+			return &objectstore.Object{
+				Body:          io.NopCloser(bytes.NewReader(data)),
+				ContentLength: int64(len(data)),
+				ContentType:   "application/octet-stream",
+			}, nil
+		},
+		func(ctx context.Context, key string) error {
+			delete(mockFiles, key)
+			return nil
+		},
+	)
+	objectstore.IsEnabledFunc = func() bool { return true }
+	objectstore.ResetCache()
+	disable = func() {
+		objectstore.IsEnabledFunc = func() bool { return false }
+		objectstore.ResetCache()
+	}
+	return restore, disable
+}

backend/plugins/domain/upload/ingest/remove.go

@@ -0,0 +1,58 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"context"
+
+	uploadcache "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/repository"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"gorm.io/gorm"
+)
+
+// Remove soft-deletes an upload and decrements incremental stats.
+func Remove(ctx context.Context, uploadID uint64) (models.Upload, error) {
+	upload, err := repository.GetActiveUploadByID(ctx, uploadID)
+	if err != nil {
+		return models.Upload{}, err
+	}
+	if err := softDeleteUploadWithStats(ctx, &upload); err != nil {
+		return models.Upload{}, err
+	}
+	upload.Status = models.UploadStatusDeleted
+	return upload, nil
+}
+
+// RemoveOwned soft-deletes an upload owned by userID and decrements incremental stats.
+func RemoveOwned(ctx context.Context, userID, uploadID uint64) (models.Upload, error) {
+	upload, err := repository.GetActiveUploadByID(ctx, uploadID)
+	if err != nil {
+		return models.Upload{}, err
+	}
+	if upload.UserID != userID {
+		return models.Upload{}, ErrForbidden
+	}
+	if err := softDeleteUploadWithStats(ctx, &upload); err != nil {
+		return models.Upload{}, err
+	}
+	upload.Status = models.UploadStatusDeleted
+	return upload, nil
+}
+
+func softDeleteUploadWithStats(ctx context.Context, upload *models.Upload) error {
+	statsSnapshot := *upload
+	if err := database.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := repository.SoftDeleteUploadTx(tx, upload); err != nil {
+			return err
+		}
+		return uploadstats.ApplyUploadStatsDeltaTx(tx, &statsSnapshot, -1)
+	}); err != nil {
+		return err
+	}
+	uploadcache.InvalidateUploadMetaCache(ctx, upload.ID)
+	return nil
+}

backend/plugins/domain/upload/ingest/types.go

@@ -0,0 +1,60 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package ingest provides the programmatic upload domain service for Wavelet.
+package ingest
+
+import (
+	"io"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+)
+
+// Policy controls how ingest handles hash collisions and record creation.
+type Policy int
+
+const (
+	// PolicyCreate always stores a new object and creates a new upload record.
+	PolicyCreate Policy = iota
+
+	// PolicyDedupNewRecord reuses an existing object path on hash match but creates a new record and stats delta.
+	PolicyDedupNewRecord
+
+	// PolicyResolveExisting returns an existing upload on hash match without creating a record or stats delta.
+	PolicyResolveExisting
+)
+
+// ObjectKeyFn builds the storage object key for a new upload.
+type ObjectKeyFn func(id uint64, ext string) string
+
+// Request describes a programmatic file ingest operation.
+type Request struct {
+	UserID uint64
+	Type   string
+
+	AccessMode *int
+	Status     models.UploadStatus
+
+	Reader    io.Reader
+	Size      int64
+	FileName  string
+	MimeType  string
+	Extension string
+	Hash      string
+
+	Metadata models.UploadMetadata
+	Policy   Policy
+
+	ObjectKeyFn ObjectKeyFn
+
+	// SkipExtensionCheck bypasses the configured upload extension whitelist.
+	SkipExtensionCheck bool
+}
+
+// Result reports the outcome of an ingest operation.
+type Result struct {
+	Upload   models.Upload
+	Created  bool
+	Stored   bool
+	Resolved bool
+}

backend/plugins/domain/upload/migrations/00001_initial.sql

@@ -0,0 +1,49 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE IF NOT EXISTS w_upload_stats (
+    dimension VARCHAR(32) NOT NULL,
+    stat_key VARCHAR(64) NOT NULL DEFAULT '',
+    file_count BIGINT NOT NULL DEFAULT 0,
+    file_size BIGINT NOT NULL DEFAULT 0,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (dimension, stat_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_w_uploads_status_created_at ON w_uploads (status, created_at);
+CREATE INDEX IF NOT EXISTS idx_w_uploads_hash_file_size_status ON w_uploads (hash, file_size, status);
+
+ALTER TABLE w_uploads ADD COLUMN IF NOT EXISTS access_mode INTEGER NOT NULL DEFAULT 0;
+UPDATE w_uploads SET access_mode = 1 WHERE type = 'avatar';
+
+-- Backfill upload stats
+INSERT INTO w_upload_stats (dimension, stat_key, file_count, file_size)
+SELECT 'total', '', COUNT(*), COALESCE(SUM(file_size), 0)
+FROM w_uploads
+WHERE status != 'deleted'
+ON CONFLICT (dimension, stat_key) DO UPDATE SET
+    file_count = EXCLUDED.file_count,
+    file_size = EXCLUDED.file_size,
+    updated_at = CURRENT_TIMESTAMP;
+
+INSERT INTO w_upload_stats (dimension, stat_key, file_count, file_size)
+SELECT
+    'type',
+    COALESCE(NULLIF(type, ''), 'generic'),
+    COUNT(*),
+    COALESCE(SUM(file_size), 0)
+FROM w_uploads
+WHERE status != 'deleted'
+GROUP BY COALESCE(NULLIF(type, ''), 'generic')
+ON CONFLICT (dimension, stat_key) DO UPDATE SET
+    file_count = EXCLUDED.file_count,
+    file_size = EXCLUDED.file_size,
+    updated_at = CURRENT_TIMESTAMP;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DROP TABLE IF EXISTS w_upload_stats;
+DROP INDEX IF EXISTS idx_w_uploads_hash_file_size_status;
+DROP INDEX IF EXISTS idx_w_uploads_status_created_at;
+ALTER TABLE w_uploads DROP COLUMN IF EXISTS access_mode;
+-- +goose StatementEnd

backend/plugins/domain/upload/models.go

@@ -0,0 +1,34 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package upload 提供上传域的门面与类型重导出。
+package upload
+
+import (
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+)
+
+// UploadStatus 上传状态类型别名
+//
+//nolint:revive
+type UploadStatus = models.UploadStatus
+
+// UploadMetadata 上传元数据类型别名
+//
+//nolint:revive
+type UploadMetadata = models.UploadMetadata
+
+// Upload 上传实体类型别名
+type Upload = models.Upload
+
+// UploadStat 上传统计实体类型别名
+//
+//nolint:revive
+type UploadStat = models.UploadStat
+
+// 上传状态常量别名
+const (
+	UploadStatusPending = models.UploadStatusPending
+	UploadStatusUsed    = models.UploadStatusUsed
+	UploadStatusDeleted = models.UploadStatusDeleted
+)

backend/plugins/domain/upload/models/models.go

@@ -0,0 +1,77 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package models 提供上传域核心数据模型。
+package models
+
+import (
+	"time"
+)
+
+// UploadStatus 上传状态
+type UploadStatus string
+
+// 上传状态
+const (
+	UploadStatusPending UploadStatus = "pending" // 待使用
+	UploadStatusUsed    UploadStatus = "used"    // 已使用
+	UploadStatusDeleted UploadStatus = "deleted" // 已删除
+)
+
+// UploadMetadata 自定义可扩展的 JSON 字段存储非核心或可选的文件元数据
+type UploadMetadata struct {
+	Width        int            `json:"width,omitempty"`
+	Height       int            `json:"height,omitempty"`
+	Duration     float64        `json:"duration,omitempty"`
+	OriginalMime string         `json:"original_mime,omitempty"`
+	UserAgent    string         `json:"user_agent,omitempty"`
+	ClientIP     string         `json:"client_ip,omitempty"`
+	Bucket       string         `json:"bucket,omitempty"`
+	Extra        map[string]any `json:"extra,omitempty"`
+}
+
+// Upload 上传文件记录
+type Upload struct {
+	ID         uint64         `json:"id,string" gorm:"primaryKey"`
+	UserID     uint64         `json:"user_id,string" gorm:"index;not null"`
+	FileName   string         `json:"file_name" gorm:"size:255;not null"`
+	FilePath   string         `json:"file_path" gorm:"size:500;not null;index"`
+	FileSize   int64          `json:"file_size" gorm:"not null"`
+	MimeType   string         `json:"mime_type" gorm:"size:100;not null"`
+	Extension  string         `json:"extension" gorm:"size:50;not null"`
+	Hash       string         `json:"hash" gorm:"size:64;index"`
+	Type       string         `json:"type" gorm:"column:type;size:50;not null;index"`
+	Status     UploadStatus   `json:"status" gorm:"type:varchar(20);not null"`
+	AccessMode int            `json:"access_mode" gorm:"column:access_mode;not null;default:0"`
+	Metadata   UploadMetadata `json:"metadata" gorm:"serializer:json;type:jsonb"`
+	CreatedAt  time.Time      `json:"created_at" gorm:"autoCreateTime"`
+	UpdatedAt  time.Time      `json:"updated_at" gorm:"autoUpdateTime"`
+}
+
+// TableName 表名
+func (Upload) TableName() string {
+	return "w_uploads"
+}
+
+// Upload stats dimension keys stored in w_upload_stats.dimension.
+const (
+	UploadStatDimensionTotal    = "total"
+	UploadStatDimensionType     = "type"
+	UploadStatDimensionCategory = "category"
+	UploadStatDimensionTrend    = "trend"
+)
+
+// UploadStat 聚合统计记录
+type UploadStat struct {
+	Dimension string    `json:"dimension" gorm:"primaryKey;size:32;not null"`
+	StatKey   string    `json:"stat_key" gorm:"primaryKey;size:64;not null;default:''"`
+	FileCount int64     `json:"file_count" gorm:"not null;default:0"`
+	FileSize  int64     `json:"file_size" gorm:"not null;default:0"`
+	UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime"`
+}
+
+// TableName 表名
+func (UploadStat) TableName() string {
+	return "w_upload_stats"
+}

backend/plugins/domain/upload/plugin.go

@@ -0,0 +1,132 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package upload provides file uploading, storage abstraction, image transcoding, and caching domain plugin for Cordis.
+package upload
+
+import (
+	"context"
+	"embed"
+
+	"github.com/Rain-kl/Wavelet/backend/core"
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/core/extpoints"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/filesrv"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/handler"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/task"
+	"github.com/gin-gonic/gin"
+	"github.com/hibiken/asynq"
+)
+
+//go:embed migrations/*.sql
+var uploadMigrations embed.FS
+
+// Plugin implements core.Plugin to provide file upload and media serving domain services.
+type Plugin struct{}
+
+// New creates a new upload domain plugin.
+func New() *Plugin {
+	return &Plugin{}
+}
+
+// Name returns the unique identifier for the upload domain plugin.
+func (p *Plugin) Name() string {
+	return "upload"
+}
+
+// Manifest returns the plugin metadata.
+func (p *Plugin) Manifest() core.Manifest {
+	return core.Manifest{
+		Name:        "upload",
+		Version:     "1.0.0",
+		Description: "File upload, secure delivery, image transcoding, and storage management domain plugin",
+		Author:      "Wavelet Team",
+	}
+}
+
+// Apply registers upload routes, tasks, and settings into the Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	// 0. Resolve auth service for middleware (via IoC, not direct import)
+	var authSvc contracts.AuthService
+	if err := core.Using[contracts.AuthService](ctx, func(svc contracts.AuthService) { authSvc = svc }); err != nil {
+		return err
+	}
+	loginMW := authSvc.RequireAuthMiddleware().(gin.HandlerFunc)
+
+	// 0a. Register migrations
+	ctx.Migrations().Register("upload", uploadMigrations)
+
+	// 1. Register File Server Routes
+	ctx.Router().GET("/f/:id", filesrv.ServeFileByID)
+
+	// 2. Register User/Admin Upload HTTP Routes
+	uploadGroup := ctx.Router().Group("/api/v1/upload", loginMW)
+	{
+		uploadGroup.POST("", handler.UploadFile)
+		uploadGroup.GET("", handler.ListFiles)
+		uploadGroup.DELETE("/:id", handler.DeleteFile)
+		uploadGroup.POST("/batch-download", handler.BatchDownloadFiles)
+	}
+
+	adminUploadGroup := ctx.Router().Group("/api/v1/admin/uploads", loginMW)
+	{
+		adminUploadGroup.GET("", handler.ListFiles)
+		adminUploadGroup.GET("/stats", handler.GetFileStats)
+		adminUploadGroup.DELETE("/:id", handler.DeleteFile)
+		adminUploadGroup.GET("/download/:id", handler.DownloadFile)
+		adminUploadGroup.POST("/download/batch", handler.BatchDownloadFiles)
+		adminUploadGroup.GET("/types", handler.GetDistinctUploadTypes)
+	}
+
+	const (
+		defaultCleanupRetry = 3
+		defaultStatsRetry   = 2
+		defaultSingleRetry  = 1
+	)
+
+	// 3. Register Asynq tasks
+	cleanupHandler := &task.SystemCleanupHandler{}
+	ctx.Task().Register(task.SystemCleanupTask, func(c context.Context, t *asynq.Task) error {
+		_, err := cleanupHandler.Execute(c, t.Payload())
+		return err
+	}, extpoints.WithTaskRetry(defaultCleanupRetry))
+
+	rebuildStatsHandler := &task.RebuildUploadStatsHandler{}
+	ctx.Task().Register(task.RebuildUploadStatsTask, func(c context.Context, t *asynq.Task) error {
+		_, err := rebuildStatsHandler.Execute(c, t.Payload())
+		return err
+	}, extpoints.WithTaskRetry(defaultStatsRetry))
+
+	migrationHandler := &task.MigrationHandler{}
+	ctx.Task().Register(task.StorageMigrationTask, func(c context.Context, t *asynq.Task) error {
+		_, err := migrationHandler.Execute(c, t.Payload())
+		return err
+	}, extpoints.WithTaskRetry(defaultSingleRetry))
+
+	warmHandler := &task.WarmImageCacheHandler{}
+	ctx.Task().Register(task.WarmImageCacheTask, func(c context.Context, t *asynq.Task) error {
+		_, err := warmHandler.Execute(c, t.Payload())
+		return err
+	}, extpoints.WithTaskRetry(1))
+
+	// 4. Register Cron Schedule
+	ctx.Schedule().RegisterCron("0 3 * * *", task.SystemCleanupTask, nil)
+
+	// 5. Register Settings Schemas
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "upload.max_file_size_mb",
+		Default:     100,
+		Description: "Maximum upload file size limit in MB",
+		Type:        "integer",
+		Category:    "storage",
+	})
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "upload.allowed_extensions",
+		Default:     "png,jpg,jpeg,gif,webp,svg,pdf,zip,tar,gz",
+		Description: "Allowed upload file extensions separated by commas",
+		Type:        "string",
+		Category:    "storage",
+	})
+
+	return nil
+}

backend/plugins/domain/upload/repository.go

@@ -0,0 +1,147 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package upload
+
+import (
+	"context"
+	"strings"
+
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/idgen"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+// UploadListFilter filters paginated upload queries.
+//
+//nolint:revive
+type UploadListFilter struct {
+	UserID    uint64
+	Keyword   string
+	Type      string
+	Extension string
+	Page      int
+	PageSize  int
+}
+
+// ListUploads returns paginated upload records matching the filter.
+func ListUploads(ctx context.Context, filter UploadListFilter) (int64, []Upload, error) {
+	query := database.DB(ctx).Model(&Upload{}).
+		Where("status != ?", UploadStatusDeleted)
+
+	if filter.UserID != 0 {
+		query = query.Where("user_id = ?", filter.UserID)
+	}
+	if filter.Keyword != "" {
+		query = query.Where("LOWER(file_name) LIKE ? ESCAPE '\\'", "%"+util.EscapeLike(strings.ToLower(filter.Keyword))+"%")
+	}
+	if filter.Type != "" {
+		query = query.Where("type = ?", filter.Type)
+	}
+	if filter.Extension != "" {
+		query = query.Where("extension = ?", strings.ToLower(filter.Extension))
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return 0, nil, err
+	}
+
+	var items []Upload
+	offset := (filter.Page - 1) * filter.PageSize
+	if err := query.Order("created_at DESC").Offset(offset).Limit(filter.PageSize).Find(&items).Error; err != nil {
+		return 0, nil, err
+	}
+	return total, items, nil
+}
+
+// GetActiveUploadByID loads a non-deleted upload by ID.
+func GetActiveUploadByID(ctx context.Context, id uint64) (Upload, error) {
+	var upload Upload
+	if err := database.DB(ctx).Where("id = ? AND status != ?", id, UploadStatusDeleted).First(&upload).Error; err != nil {
+		return Upload{}, err
+	}
+	return upload, nil
+}
+
+// SoftDeleteUpload marks an upload as deleted.
+// External modules must use upload.Remove or upload.RemoveOwned; only internal/apps/upload may call this.
+func SoftDeleteUpload(ctx context.Context, upload *Upload) error {
+	return SoftDeleteUploadTx(database.DB(ctx), upload)
+}
+
+// SoftDeleteUploadTx marks an upload as deleted within an existing transaction.
+func SoftDeleteUploadTx(tx *gorm.DB, upload *Upload) error {
+	return tx.Model(upload).Update("status", UploadStatusDeleted).Error
+}
+
+// UpdateUpload applies partial field updates to an upload record.
+func UpdateUpload(ctx context.Context, upload *Upload, updates map[string]any) error {
+	if len(updates) == 0 {
+		return nil
+	}
+	return database.DB(ctx).Model(upload).Updates(updates).Error
+}
+
+// ListDistinctUploadTypes returns all distinct non-empty upload business types.
+func ListDistinctUploadTypes(ctx context.Context) ([]string, error) {
+	var types []string
+	if err := database.DB(ctx).Model(&Upload{}).
+		Where("type IS NOT NULL AND type != ''").
+		Distinct().
+		Pluck("type", &types).Error; err != nil {
+		return nil, err
+	}
+	return types, nil
+}
+
+// FindReusableUploadByHash finds an existing upload with the same hash and size.
+func FindReusableUploadByHash(ctx context.Context, hash string, size int64) (Upload, error) {
+	var existing Upload
+	err := database.DB(ctx).
+		Where("hash = ? AND file_size = ? AND status IN (?, ?)", hash, size, UploadStatusPending, UploadStatusUsed).
+		First(&existing).Error
+	return existing, err
+}
+
+// CreateUpload persists a new upload record.
+func CreateUpload(ctx context.Context, upload *Upload) error {
+	return CreateUploadTx(database.DB(ctx), upload)
+}
+
+// CreateUploadTx persists a new upload record within an existing transaction.
+func CreateUploadTx(tx *gorm.DB, upload *Upload) error {
+	if upload.ID == 0 {
+		upload.ID = idgen.NextUint64ID()
+	}
+	return tx.Create(upload).Error
+}
+
+// ListUploadsByIDs returns active uploads matching the given IDs.
+func ListUploadsByIDs(ctx context.Context, ids []uint64) ([]Upload, error) {
+	var uploads []Upload
+	if err := database.DB(ctx).
+		Where("id IN ? AND status IN (?, ?)", ids, UploadStatusPending, UploadStatusUsed).
+		Find(&uploads).Error; err != nil {
+		return nil, err
+	}
+	return uploads, nil
+}
+
+// UploadQuery returns a scoped GORM query for uploads.
+//
+//nolint:revive
+func UploadQuery(ctx context.Context) *gorm.DB {
+	return database.DB(ctx).Model(&Upload{})
+}
+
+// ListUploadStats returns all upload statistics rows.
+func ListUploadStats(ctx context.Context) ([]UploadStat, error) {
+	var stats []UploadStat
+	if err := database.DB(ctx).Find(&stats).Error; err != nil {
+		return nil, err
+	}
+	return stats, nil
+}

backend/plugins/domain/upload/repository/repository.go

@@ -0,0 +1,140 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package repository 提供上传域数据库仓储层操作。
+package repository
+
+import (
+	"context"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"gorm.io/gorm"
+)
+
+// UploadListFilter filters paginated upload queries.
+type UploadListFilter struct {
+	UserID    uint64
+	Keyword   string
+	Type      string
+	Extension string
+	Page      int
+	PageSize  int
+}
+
+// ListUploads returns paginated upload records matching the filter.
+func ListUploads(ctx context.Context, filter UploadListFilter) (int64, []models.Upload, error) {
+	query := database.DB(ctx).Model(&models.Upload{}).
+		Where("status != ?", models.UploadStatusDeleted)
+
+	if filter.UserID != 0 {
+		query = query.Where("user_id = ?", filter.UserID)
+	}
+	if filter.Keyword != "" {
+		query = query.Where("LOWER(file_name) LIKE ? ESCAPE '\\'", "%"+util.EscapeLike(strings.ToLower(filter.Keyword))+"%")
+	}
+	if filter.Type != "" {
+		query = query.Where("type = ?", filter.Type)
+	}
+	if filter.Extension != "" {
+		query = query.Where("extension = ?", strings.ToLower(filter.Extension))
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return 0, nil, err
+	}
+
+	var items []models.Upload
+	offset := (filter.Page - 1) * filter.PageSize
+	if err := query.Order("created_at DESC").Offset(offset).Limit(filter.PageSize).Find(&items).Error; err != nil {
+		return 0, nil, err
+	}
+	return total, items, nil
+}
+
+// GetActiveUploadByID loads a non-deleted upload by ID.
+func GetActiveUploadByID(ctx context.Context, id uint64) (models.Upload, error) {
+	var upload models.Upload
+	if err := database.DB(ctx).Where("id = ? AND status != ?", id, models.UploadStatusDeleted).First(&upload).Error; err != nil {
+		return models.Upload{}, err
+	}
+	return upload, nil
+}
+
+// SoftDeleteUpload marks an upload as deleted.
+func SoftDeleteUpload(ctx context.Context, upload *models.Upload) error {
+	return SoftDeleteUploadTx(database.DB(ctx), upload)
+}
+
+// SoftDeleteUploadTx marks an upload as deleted within an existing transaction.
+func SoftDeleteUploadTx(tx *gorm.DB, upload *models.Upload) error {
+	return tx.Model(upload).Update("status", models.UploadStatusDeleted).Error
+}
+
+// UpdateUpload applies partial field updates to an upload record.
+func UpdateUpload(ctx context.Context, upload *models.Upload, updates map[string]any) error {
+	if len(updates) == 0 {
+		return nil
+	}
+	return database.DB(ctx).Model(upload).Updates(updates).Error
+}
+
+// ListDistinctUploadTypes returns all distinct non-empty upload business types.
+func ListDistinctUploadTypes(ctx context.Context) ([]string, error) {
+	var types []string
+	if err := database.DB(ctx).Model(&models.Upload{}).
+		Where("type IS NOT NULL AND type != ''").
+		Distinct().
+		Pluck("type", &types).Error; err != nil {
+		return nil, err
+	}
+	return types, nil
+}
+
+// FindReusableUploadByHash finds an existing upload with the same hash and size.
+func FindReusableUploadByHash(ctx context.Context, hash string, size int64) (models.Upload, error) {
+	var existing models.Upload
+	err := database.DB(ctx).
+		Where("hash = ? AND file_size = ? AND status IN (?, ?)", hash, size, models.UploadStatusPending, models.UploadStatusUsed).
+		First(&existing).Error
+	return existing, err
+}
+
+// CreateUpload persists a new upload record.
+func CreateUpload(ctx context.Context, upload *models.Upload) error {
+	return CreateUploadTx(database.DB(ctx), upload)
+}
+
+// CreateUploadTx persists a new upload record within an existing transaction.
+func CreateUploadTx(tx *gorm.DB, upload *models.Upload) error {
+	return tx.Create(upload).Error
+}
+
+// ListUploadsByIDs returns active uploads matching the given IDs.
+func ListUploadsByIDs(ctx context.Context, ids []uint64) ([]models.Upload, error) {
+	var uploads []models.Upload
+	if err := database.DB(ctx).
+		Where("id IN ? AND status IN (?, ?)", ids, models.UploadStatusPending, models.UploadStatusUsed).
+		Find(&uploads).Error; err != nil {
+		return nil, err
+	}
+	return uploads, nil
+}
+
+// UploadQuery returns a scoped GORM query for uploads.
+func UploadQuery(ctx context.Context) *gorm.DB {
+	return database.DB(ctx).Model(&models.Upload{})
+}
+
+// ListUploadStats returns all upload statistics rows.
+func ListUploadStats(ctx context.Context) ([]models.UploadStat, error) {
+	var stats []models.UploadStat
+	if err := database.DB(ctx).Find(&stats).Error; err != nil {
+		return nil, err
+	}
+	return stats, nil
+}

backend/plugins/domain/upload/shared/constants.go

@@ -0,0 +1,25 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package shared
+
+// Upload size, path, media quality, and cache constants shared across subpackages.
+const (
+	MaxUploadSize           = 32 * 1024 * 1024 // 32MB
+	DetectContentBytes      = 512              // http.DetectContentType 需要的最小字节数
+	UploadDirPerm           = 0755             // 上传目录权限
+	UploadFilePerm          = 0644             // 上传文件权限
+	ImageQualityLow         = "low"
+	ImageQualityMedium      = "medium"
+	ImageQualityHigh        = "high"
+	ImageQualityOrigin      = "origin"
+	DefaultPublicUploadType = "avatar"
+	FileStatsTrendDays      = 7
+	MaxS3KeyLength          = 1024
+	AccessCacheTTL          = 5 // seconds; multiplied by time.Second at use site
+
+	UploadStatDimensionTotal    = "total"
+	UploadStatDimensionType     = "type"
+	UploadStatDimensionCategory = "category"
+	UploadStatDimensionTrend    = "trend"
+)

backend/plugins/domain/upload/shared/errs.go

@@ -0,0 +1,44 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package shared holds upload error and configuration constants shared across subpackages.
+package shared
+
+// 文件管理常量
+const (
+	ErrNoFileSelected                  = "请选择要上传的文件"
+	ErrUnsupportedFormat               = "只支持 JPG、PNG、WEBP 格式的图片"
+	ErrProcessFileFailed               = "处理文件失败"
+	ErrSaveFileFailed                  = "保存文件失败"
+	ErrOpenFileFailed                  = "打开文件失败"
+	ErrSaveUploadRecordFailed          = "保存上传记录失败"
+	ErrGenericFileTooLarge             = "文件大小不能超过 32MB"
+	ErrFileContentExtensionMismatch    = "文件内容与扩展名不匹配，可能包含安全风险"
+	ErrFileValidationFailed            = "文件校验失败"
+	ErrInvalidMetadataJSON             = "元数据 JSON 格式不合法"
+	ErrInvalidFileID                   = "无效的文件 ID"
+	ErrQueryUploadRecordFailed         = "查询文件记录失败"
+	ErrInvalidBatchDownloadRequest     = "参数绑定失败，请传入有效的文件 ID 数组"
+	ErrInvalidIDValueFormat            = "无效的 ID 值: %s"
+	ErrRetrieveUploadRecordsFailed     = "检索文件记录失败"
+	ErrNoValidFilesForArchive          = "没有找到任何有效的文件记录进行打包"
+	ErrInvalidParams                   = "参数错误"
+	ErrQueryFileCountFailed            = "查询文件数量失败"
+	ErrQueryFileListFailed             = "查询文件列表失败"
+	ErrDeleteFileFailed                = "删除文件失败"
+	ErrStorageReadOnly                 = "存储迁移维护中，当前仅允许读取文件"
+	ErrS3KeyRequired                   = "s3 key must not be empty"
+	ErrS3KeyTooLongFormat              = "s3 key exceeds maximum length of %d"
+	ErrS3KeyStartsWithSlash            = "s3 key must not start with /"
+	ErrS3KeyContainsNullBytes          = "s3 key must not contain null bytes"
+	ErrQueryUnusedUploadsFailed        = "查询未使用的上传文件失败: %w"
+	ErrImageCacheWarmupPayloadRequired = "图片缓存预热参数不能为空"
+	ErrInvalidImageCacheWarmupPayload  = "图片缓存预热参数格式无效: %w"
+	ErrInvalidImageCacheWarmupQuality  = "图片质量仅支持 low、medium、high"
+	ErrParseImageCacheWarmupPayload    = "解析图片缓存预热参数失败: %w"
+	ErrQueryImagesForCacheWarmup       = "查询待预热图片失败: %w"
+	ErrQueryTypeListFailed             = "查询文件类型列表失败"
+	ErrUpdateFileFailed                = "更新文件失败"
+	ErrUnauthorized                    = "未登录"
+)

backend/plugins/domain/upload/stats/category.go

@@ -0,0 +1,43 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package stats maintains incremental upload statistics and aggregations.
+package stats
+
+import (
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/util"
+)
+
+const (
+	catImage    = "图片"
+	catVideo    = "视频"
+	catAudio    = "音频"
+	catDocument = "文档"
+	catArchive  = "压缩包"
+	catOther    = "其他"
+)
+
+// GetFileCategory classifies a file by mime type and extension.
+func GetFileCategory(mimeType, ext string) string {
+	mimeType = strings.ToLower(mimeType)
+	ext = strings.ToLower(ext)
+
+	if strings.HasPrefix(mimeType, "image/") || util.IsImageExtension(ext) {
+		return catImage
+	}
+	if strings.HasPrefix(mimeType, "video/") {
+		return catVideo
+	}
+	if strings.HasPrefix(mimeType, "audio/") {
+		return catAudio
+	}
+	if util.IsArchiveExtension(ext) || strings.Contains(mimeType, "zip") || strings.Contains(mimeType, "tar") || strings.Contains(mimeType, "gzip") {
+		return catArchive
+	}
+	if util.IsDocumentExtension(ext) || strings.HasPrefix(mimeType, "text/") || mimeType == "application/pdf" {
+		return catDocument
+	}
+	return catOther
+}

backend/plugins/domain/upload/stats/stats_counter.go

@@ -0,0 +1,131 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package stats
+
+import (
+	"context"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// ApplyUploadStatsAdd increments incremental stats for a newly active upload record.
+func ApplyUploadStatsAdd(ctx context.Context, upload *models.Upload) error {
+	return applyUploadStatsDelta(ctx, upload, 1)
+}
+
+// ApplyUploadStatsRemove decrements incremental stats for a removed active upload record.
+func ApplyUploadStatsRemove(ctx context.Context, upload *models.Upload) error {
+	return applyUploadStatsDelta(ctx, upload, -1)
+}
+
+// RebuildUploadStats rebuilds all incremental stats from current upload records.
+func RebuildUploadStats(ctx context.Context) error {
+	return database.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where("1 = 1").Delete(&models.UploadStat{}).Error; err != nil {
+			return err
+		}
+
+		var uploads []models.Upload
+		if err := tx.Where("status != ?", models.UploadStatusDeleted).Find(&uploads).Error; err != nil {
+			return err
+		}
+
+		for i := range uploads {
+			if err := ApplyUploadStatsDeltaTx(tx, &uploads[i], 1); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
+func applyUploadStatsDelta(ctx context.Context, upload *models.Upload, sign int64) error {
+	if upload == nil || !isActiveUploadStatus(upload.Status) {
+		return nil
+	}
+	return database.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		return ApplyUploadStatsDeltaTx(tx, upload, sign)
+	})
+}
+
+// ApplyUploadStatsDeltaTx applies incremental upload stats within an existing transaction.
+func ApplyUploadStatsDeltaTx(tx *gorm.DB, upload *models.Upload, sign int64) error {
+	if upload == nil || !isActiveUploadStatus(upload.Status) || sign == 0 {
+		return nil
+	}
+
+	countDelta := sign
+	sizeDelta := sign * upload.FileSize
+	typeKey := upload.Type
+	if typeKey == "" {
+		typeKey = "generic"
+	}
+
+	entries := []struct {
+		dimension string
+		key       string
+	}{
+		{models.UploadStatDimensionTotal, ""},
+		{models.UploadStatDimensionType, typeKey},
+		{models.UploadStatDimensionCategory, GetFileCategory(upload.MimeType, upload.Extension)},
+		{models.UploadStatDimensionTrend, upload.CreatedAt.Format("2006-01-02")},
+	}
+
+	for _, entry := range entries {
+		if err := upsertUploadStatDelta(tx, entry.dimension, entry.key, countDelta, sizeDelta); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func upsertUploadStatDelta(tx *gorm.DB, dimension, key string, countDelta, sizeDelta int64) error {
+	return tx.Clauses(clause.OnConflict{
+		Columns: []clause.Column{
+			{Name: "dimension"},
+			{Name: "stat_key"},
+		},
+		DoUpdates: clause.Assignments(map[string]any{
+			"file_count": gorm.Expr(
+				"CASE WHEN w_upload_stats.file_count + ? < 0 THEN 0 ELSE w_upload_stats.file_count + ? END",
+				countDelta,
+				countDelta,
+			),
+			"file_size": gorm.Expr(
+				"CASE WHEN w_upload_stats.file_size + ? < 0 THEN 0 ELSE w_upload_stats.file_size + ? END",
+				sizeDelta,
+				sizeDelta,
+			),
+			"updated_at": time.Now(),
+		}),
+	}).Create(&models.UploadStat{
+		Dimension: dimension,
+		StatKey:   key,
+		FileCount: countDelta,
+		FileSize:  sizeDelta,
+	}).Error
+}
+
+// RecordUploadStatsAdd logs and applies upload stats increment.
+func RecordUploadStatsAdd(ctx context.Context, upload *models.Upload) {
+	if err := ApplyUploadStatsAdd(ctx, upload); err != nil {
+		logger.WarnF(ctx, "increment upload stats failed: %v", err)
+	}
+}
+
+// RecordUploadStatsRemove logs and applies upload stats decrement.
+func RecordUploadStatsRemove(ctx context.Context, upload *models.Upload) {
+	if err := ApplyUploadStatsRemove(ctx, upload); err != nil {
+		logger.WarnF(ctx, "decrement upload stats failed: %v", err)
+	}
+}
+
+func isActiveUploadStatus(status models.UploadStatus) bool {
+	return status == models.UploadStatusPending || status == models.UploadStatusUsed
+}

backend/plugins/domain/upload/stats/stats_counter_test.go

@@ -0,0 +1,103 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package stats
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"gorm.io/gorm"
+)
+
+func TestApplyUploadStatsDeltaTxWithinTransaction(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	upload := &models.Upload{
+		ID:        42002,
+		FileSize:  256,
+		MimeType:  "image/jpeg",
+		Extension: "jpg",
+		Type:      "avatar",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+
+	if err := database.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		return ApplyUploadStatsDeltaTx(tx, upload, 1)
+	}); err != nil {
+		t.Fatalf("ApplyUploadStatsDeltaTx returned error: %v", err)
+	}
+
+	stats, err := loadUploadStats(ctx)
+	if err != nil {
+		t.Fatalf("loadUploadStats returned error: %v", err)
+	}
+	if stats.TotalCount != 1 || stats.TotalSize != 256 {
+		t.Fatalf("unexpected total stats: count=%d size=%d", stats.TotalCount, stats.TotalSize)
+	}
+}
+
+func TestApplyUploadStatsAddAndRemove(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	upload := &models.Upload{
+		ID:        42001,
+		FileSize:  128,
+		MimeType:  "image/png",
+		Extension: "png",
+		Type:      "avatar",
+		Status:    models.UploadStatusUsed,
+		CreatedAt: time.Now(),
+	}
+	if err := ApplyUploadStatsAdd(ctx, upload); err != nil {
+		t.Fatalf("ApplyUploadStatsAdd returned error: %v", err)
+	}
+
+	stats, err := loadUploadStats(ctx)
+	if err != nil {
+		t.Fatalf("loadUploadStats returned error: %v", err)
+	}
+	if stats.TotalCount != 1 || stats.TotalSize != 128 {
+		t.Fatalf("unexpected total stats: count=%d size=%d", stats.TotalCount, stats.TotalSize)
+	}
+
+	if err := ApplyUploadStatsRemove(ctx, upload); err != nil {
+		t.Fatalf("ApplyUploadStatsRemove returned error: %v", err)
+	}
+
+	stats, err = loadUploadStats(ctx)
+	if err != nil {
+		t.Fatalf("loadUploadStats after remove returned error: %v", err)
+	}
+	if stats.TotalCount != 0 || stats.TotalSize != 0 {
+		t.Fatalf("expected zeroed total stats, got count=%d size=%d", stats.TotalCount, stats.TotalSize)
+	}
+}
+
+type uploadStatsSnapshot struct {
+	TotalCount int64
+	TotalSize  int64
+}
+
+func loadUploadStats(ctx context.Context) (uploadStatsSnapshot, error) {
+	var rows []models.UploadStat
+	if err := database.DB(ctx).Where("dimension = ?", models.UploadStatDimensionTotal).Find(&rows).Error; err != nil {
+		return uploadStatsSnapshot{}, err
+	}
+	if len(rows) == 0 {
+		return uploadStatsSnapshot{}, nil
+	}
+	return uploadStatsSnapshot{
+		TotalCount: rows[0].FileCount,
+		TotalSize:  rows[0].FileSize,
+	}, nil
+}

backend/plugins/domain/upload/storage/access_state.go

@@ -0,0 +1,88 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package storage provides upload storage backend operations and migration state.
+package storage
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+// MigrationAccessState captures cached migration maintenance state.
+type MigrationAccessState struct {
+	ReadOnly  bool
+	Target    objectstore.Config
+	HasTarget bool
+	TargetErr error
+	LoadErr   error
+}
+
+var (
+	migrationAccessMu        sync.RWMutex
+	migrationAccessCached    MigrationAccessState
+	migrationAccessValid     bool
+	migrationAccessCheckedAt time.Time
+)
+
+// ResetMigrationAccessCache clears the in-process migration access cache.
+func ResetMigrationAccessCache() {
+	migrationAccessMu.Lock()
+	migrationAccessValid = false
+	migrationAccessMu.Unlock()
+}
+
+// LoadMigrationAccessState returns cached migration maintenance state.
+func LoadMigrationAccessState(ctx context.Context) MigrationAccessState {
+	migrationAccessMu.RLock()
+	if migrationAccessValid && time.Since(migrationAccessCheckedAt) < time.Duration(shared.AccessCacheTTL)*time.Second {
+		state := migrationAccessCached
+		migrationAccessMu.RUnlock()
+		return state
+	}
+	migrationAccessMu.RUnlock()
+
+	migrationAccessMu.Lock()
+	defer migrationAccessMu.Unlock()
+
+	if migrationAccessValid && time.Since(migrationAccessCheckedAt) < time.Duration(shared.AccessCacheTTL)*time.Second {
+		return migrationAccessCached
+	}
+
+	migrationAccessCached = buildMigrationAccessState(ctx)
+	migrationAccessValid = true
+	migrationAccessCheckedAt = time.Now()
+	return migrationAccessCached
+}
+
+func buildMigrationAccessState(ctx context.Context) MigrationAccessState {
+	execution, ok, err := LatestMigrationExecution(ctx)
+	if err != nil {
+		return MigrationAccessState{LoadErr: err, ReadOnly: true}
+	}
+	if !ok {
+		return MigrationAccessState{}
+	}
+
+	state := MigrationAccessState{
+		ReadOnly: execution.Status != driver_asynq_worker.TaskExecutionStatusSucceeded,
+	}
+	if execution.Status == driver_asynq_worker.TaskExecutionStatusSucceeded {
+		return state
+	}
+
+	target, err := ParseMigrationTargetConfig(ctx, []byte(execution.Payload))
+	if err != nil {
+		state.TargetErr = err
+		return state
+	}
+
+	state.Target = target
+	state.HasTarget = true
+	return state
+}

backend/plugins/domain/upload/storage/migration.go

@@ -0,0 +1,80 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package storage
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+// StorageMigrationTask is the Asynq task name for storage migration.
+const StorageMigrationTask = "storage:migrate"
+
+// LatestMigrationExecution returns the most recent storage migration task execution.
+func LatestMigrationExecution(ctx context.Context) (*driver_asynq_worker.TaskExecution, bool, error) {
+	return driver_asynq_worker.GetLatestTaskExecutionByTaskType(ctx, StorageMigrationTask)
+}
+
+// ParseMigrationTargetConfig parses and validates a storage migration target payload.
+func ParseMigrationTargetConfig(ctx context.Context, payload []byte) (objectstore.Config, error) {
+	if strings.TrimSpace(string(payload)) == "" {
+		return objectstore.Config{}, errors.New("storage migration target payload is required")
+	}
+
+	var raw struct {
+		Target json.RawMessage `json:"target"`
+	}
+	if err := json.Unmarshal(payload, &raw); err != nil {
+		return objectstore.Config{}, fmt.Errorf("parse storage migration payload envelope: %w", err)
+	}
+
+	if len(raw.Target) == 0 {
+		return objectstore.Config{}, errors.New("storage migration target payload is required")
+	}
+
+	var targetBytes []byte
+	var targetStr string
+	if err := json.Unmarshal(raw.Target, &targetStr); err == nil {
+		targetBytes = []byte(targetStr)
+	} else {
+		targetBytes = raw.Target
+	}
+
+	var target objectstore.Config
+	if err := json.Unmarshal(targetBytes, &target); err != nil {
+		return objectstore.Config{}, fmt.Errorf("parse target storage config: %w", err)
+	}
+
+	current, err := objectstore.LoadConfig(ctx)
+	if err != nil {
+		return objectstore.Config{}, fmt.Errorf("load active storage config: %w", err)
+	}
+	target = objectstore.MergeMaskedSecrets(target, current)
+	if err := objectstore.ValidateConfig(target); err != nil {
+		return objectstore.Config{}, fmt.Errorf("validate target storage config: %w", err)
+	}
+	return target, nil
+}
+
+// NormalizeMigrationPayload validates and normalizes a storage migration payload.
+func NormalizeMigrationPayload(ctx context.Context, payload []byte) ([]byte, objectstore.Config, error) {
+	target, err := ParseMigrationTargetConfig(ctx, payload)
+	if err != nil {
+		return nil, objectstore.Config{}, err
+	}
+	type storageMigrationPayload struct {
+		Target objectstore.Config `json:"target"`
+	}
+	normalized, err := json.Marshal(storageMigrationPayload{Target: target})
+	if err != nil {
+		return nil, objectstore.Config{}, fmt.Errorf("marshal storage migration payload: %w", err)
+	}
+	return normalized, target, nil
+}

backend/plugins/domain/upload/storage/storage_ops.go

@@ -0,0 +1,31 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package storage
+
+import (
+	"context"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+// ReadOnly checks if the storage system is in read-only maintenance mode.
+func ReadOnly(ctx context.Context) bool {
+	state := LoadMigrationAccessState(ctx)
+	if state.LoadErr != nil {
+		logger.ErrorF(ctx, "读取存储维护状态失败: %v", state.LoadErr)
+		return true
+	}
+	return state.ReadOnly
+}
+
+// OpenStoredObject opens a stored upload object from the active storage backend.
+func OpenStoredObject(ctx context.Context, upload *models.Upload) (*objectstore.Object, error) {
+	_, backend, err := objectstore.Active(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return backend.Get(ctx, upload.FilePath)
+}

backend/plugins/domain/upload/task/cleanup.go

@@ -0,0 +1,160 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package task provides upload-related async background task handlers.
+package task
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	logstore "github.com/Rain-kl/Wavelet/backend/plugins/domain/risk_control/logstore"
+	uploadcache "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+const (
+	// SystemCleanupTask 系统定期垃圾清理任务标识
+	SystemCleanupTask = "system:cleanup"
+	// TaskTypeSystemCleanup 系统定期垃圾清理管理类型
+	TaskTypeSystemCleanup = "system_cleanup"
+)
+
+// SystemCleanupMeta represents the task metadata.
+var SystemCleanupMeta = driver_asynq_worker.TaskMeta{
+	Type:         TaskTypeSystemCleanup,
+	AsynqTask:    SystemCleanupTask,
+	Name:         "系统垃圾清理",
+	Description:  "定期清理未使用上传文件、历史推送记录和过期任务执行日志",
+	SupportsTime: false,
+	MaxRetry:     driver_asynq_worker.DefaultMaxRetry,
+	Queue:        driver_asynq_worker.QueueDefault,
+	Retryable:    true,
+}
+
+// SystemCleanupHandler 系统定期垃圾清理异步任务处理器
+type SystemCleanupHandler struct{}
+
+// Execute 执行系统清理（包含文件清理、历史推送日志和任务执行日志清理）
+func (h *SystemCleanupHandler) Execute(ctx context.Context, _ []byte) (*driver_asynq_worker.TaskResult, error) {
+	if uploadstorage.ReadOnly(ctx) {
+		return nil, errors.New(shared.ErrStorageReadOnly)
+	}
+	const batchSize = 100
+	var lastID uint64
+	var totalProcessed int
+	var totalDeleted int
+
+	oneHourAgo := time.Now().Add(-1 * time.Hour)
+
+	driver_asynq_worker.AppendLog(ctx, "开始扫描未使用上传文件，阈值: %s", oneHourAgo.Format(time.RFC3339))
+
+	for {
+		var unusedUploads []models.Upload
+		if err := database.DB(ctx).
+			Where("id > ? AND status = ? AND created_at < ?", lastID, models.UploadStatusPending, oneHourAgo).
+			Order("id ASC").
+			Limit(batchSize).
+			Find(&unusedUploads).Error; err != nil {
+			driver_asynq_worker.AppendLog(ctx, "查询未使用的上传文件失败: %v", err)
+			return nil, fmt.Errorf(shared.ErrQueryUnusedUploadsFailed, err)
+		}
+
+		if len(unusedUploads) == 0 {
+			break
+		}
+
+		driver_asynq_worker.AppendLog(ctx, "本批次找到 %d 个需要清理的上传文件", len(unusedUploads))
+
+		for _, u := range unusedUploads {
+			totalProcessed++
+
+			if err := database.DB(ctx).Transaction(func(tx *gorm.DB) error {
+				if err := tx.Model(&models.Upload{}).
+					Where("id = ? AND status = ?", u.ID, models.UploadStatusPending).
+					Update("status", models.UploadStatusDeleted).Error; err != nil {
+					return err
+				}
+
+				_, backend, err := objectstore.Active(ctx)
+				if err != nil {
+					return err
+				}
+				if err := backend.Delete(ctx, u.FilePath); err != nil {
+					return err
+				}
+
+				return nil
+			}); err != nil {
+				driver_asynq_worker.AppendLog(ctx, "清理上传文件失败 [ID:%d]: %v", u.ID, err)
+				lastID = u.ID
+				continue
+			}
+
+			uploadstats.RecordUploadStatsRemove(ctx, &u)
+			uploadcache.InvalidateUploadMetaCache(ctx, u.ID)
+			totalDeleted++
+			lastID = u.ID
+		}
+	}
+
+	driver_asynq_worker.AppendLog(ctx, "开始清理历史推送审计日志，只保留最近7天数据...")
+	cutoff := time.Now().AddDate(0, 0, -7)
+	var pushHistoryCount int64
+	if err := database.DB(ctx).Table("w_push_histories").Where("created_at < ?", cutoff).Count(&pushHistoryCount).Error; err != nil {
+		driver_asynq_worker.AppendLog(ctx, "统计待清理的历史推送记录失败: %v", err)
+	} else if pushHistoryCount > 0 {
+		if err := database.DB(ctx).Table("w_push_histories").Where("created_at < ?", cutoff).Delete(map[string]any{}).Error; err != nil {
+			driver_asynq_worker.AppendLog(ctx, "删除历史推送记录失败: %v", err)
+		} else {
+			driver_asynq_worker.AppendLog(ctx, "成功删除 %d 条历史推送记录 (截止时间: %s)", pushHistoryCount, cutoff.Format("2006-01-02 15:04:05"))
+		}
+	} else {
+		driver_asynq_worker.AppendLog(ctx, "没有需要清理的历史推送记录 (截止时间: %s)", cutoff.Format("2006-01-02 15:04:05"))
+	}
+
+	driver_asynq_worker.AppendLog(ctx, "开始清理任务执行日志：高频任务保留最近3天，低频任务保留最近30天...")
+	taskLogStats, err := driver_asynq_worker.CleanupTaskExecutionLogs(ctx, time.Now())
+	if err != nil {
+		driver_asynq_worker.AppendLog(ctx, "清理任务执行日志失败: %v", err)
+		logger.ErrorF(ctx, "清理任务执行日志失败: %v", err)
+	} else {
+		driver_asynq_worker.AppendLog(ctx, "成功清理任务执行日志 %d 条（高频 %d 条，低频 %d 条）",
+			taskLogStats.HighFrequencyDeleted+taskLogStats.LowFrequencyDeleted,
+			taskLogStats.HighFrequencyDeleted,
+			taskLogStats.LowFrequencyDeleted,
+		)
+	}
+
+	var logDeleted int64
+	logSummary, logErr := logstore.CleanupExpired(ctx)
+	if logErr != nil {
+		driver_asynq_worker.AppendLog(ctx, "清理过期用户访问日志失败: %v", logErr)
+		logger.ErrorF(ctx, "清理过期用户访问日志失败: %v", logErr)
+	} else {
+		logDeleted = logSummary.Deleted
+		driver_asynq_worker.AppendLog(ctx, "成功清理过期用户访问日志 %d 条（%s 保留 %d 天）",
+			logSummary.Deleted, logSummary.ActiveDatabase, logSummary.RetentionDays)
+	}
+
+	msg := fmt.Sprintf("系统清理完成。成功清理未使用的上传文件 %d/%d 个；清理历史推送审计日志 %d 条；清理任务执行日志 %d 条；清理过期访问日志 %d 条。",
+		totalDeleted,
+		totalProcessed,
+		pushHistoryCount,
+		taskLogStats.HighFrequencyDeleted+taskLogStats.LowFrequencyDeleted,
+		logDeleted,
+	)
+	driver_asynq_worker.AppendLog(ctx, "%s", msg)
+	return &driver_asynq_worker.TaskResult{Message: msg}, nil
+}

backend/plugins/domain/upload/task/rebuild_stats.go

@@ -0,0 +1,72 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+const (
+	// RebuildUploadStatsTask is the Asynq task name for rebuilding upload stats.
+	RebuildUploadStatsTask = "upload:rebuild_stats"
+	// TaskTypeRebuildUploadStats is the admin-dispatchable task type.
+	TaskTypeRebuildUploadStats = "rebuild_upload_stats"
+)
+
+// RebuildUploadStatsMeta describes the upload stats rebuild task.
+var RebuildUploadStatsMeta = driver_asynq_worker.TaskMeta{
+	Type:         TaskTypeRebuildUploadStats,
+	AsynqTask:    RebuildUploadStatsTask,
+	Name:         "重算文件存储统计",
+	Description:  "根据当前 w_uploads 活跃记录全量重建 w_upload_stats（总量、类型、分类、趋势）",
+	SupportsTime: false,
+	MaxRetry:     driver_asynq_worker.DefaultMaxRetry,
+	Queue:        driver_asynq_worker.QueueDefault,
+	Retryable:    true,
+}
+
+// RebuildUploadStatsHandler rebuilds incremental upload stats from active upload records.
+type RebuildUploadStatsHandler struct{}
+
+// Execute scans active uploads and rebuilds all upload stat dimensions.
+func (h *RebuildUploadStatsHandler) Execute(ctx context.Context, _ []byte) (*driver_asynq_worker.TaskResult, error) {
+	var activeCount int64
+	if err := database.DB(ctx).
+		Model(&models.Upload{}).
+		Where("status != ?", models.UploadStatusDeleted).
+		Count(&activeCount).Error; err != nil {
+		driver_asynq_worker.AppendLog(ctx, "统计活跃上传记录失败: %v", err)
+		return nil, fmt.Errorf("count active uploads: %w", err)
+	}
+
+	driver_asynq_worker.AppendLog(ctx, "开始重算文件存储统计，活跃记录数: %d", activeCount)
+
+	if err := uploadstats.RebuildUploadStats(ctx); err != nil {
+		driver_asynq_worker.AppendLog(ctx, "重算文件存储统计失败: %v", err)
+		return nil, fmt.Errorf("rebuild upload stats: %w", err)
+	}
+
+	var totalStat models.UploadStat
+	if err := database.DB(ctx).
+		Where("dimension = ? AND stat_key = ?", models.UploadStatDimensionTotal, "").
+		First(&totalStat).Error; err != nil {
+		driver_asynq_worker.AppendLog(ctx, "读取总量统计失败: %v", err)
+		return nil, fmt.Errorf("load total upload stats: %w", err)
+	}
+
+	msg := fmt.Sprintf(
+		"文件存储统计重算完成，活跃记录 %d 条，统计文件数 %d，总大小 %d 字节",
+		activeCount,
+		totalStat.FileCount,
+		totalStat.FileSize,
+	)
+	driver_asynq_worker.AppendLog(ctx, "%s", msg)
+	return &driver_asynq_worker.TaskResult{Message: msg}, nil
+}

backend/plugins/domain/upload/task/rebuild_stats_test.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+func TestRebuildUploadStatsHandler_Execute(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	uploads := []models.Upload{
+		{
+			UserID: 1001, FileName: "a.jpg", FilePath: "uploads/a.jpg",
+			FileSize: 100, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash-a",
+			Type: "pixez_mirror", Status: models.UploadStatusUsed, CreatedAt: now,
+		},
+		{
+			UserID: 1001, FileName: "b.png", FilePath: "uploads/b.png",
+			FileSize: 200, MimeType: "image/png", Extension: "png", Hash: "hash-b",
+			Type: "attachment", Status: models.UploadStatusUsed, CreatedAt: now,
+		},
+	}
+	for i := range uploads {
+		if err := database.DB(ctx).Create(&uploads[i]).Error; err != nil {
+			t.Fatalf("seed upload failed: %v", err)
+		}
+	}
+
+	// Corrupt stats to ensure rebuild recalculates from uploads.
+	if err := database.DB(ctx).Create(&models.UploadStat{
+		Dimension: models.UploadStatDimensionTotal,
+		StatKey:   "",
+		FileCount: 0,
+		FileSize:  0,
+	}).Error; err != nil {
+		t.Fatalf("seed broken total stat failed: %v", err)
+	}
+
+	handler := &RebuildUploadStatsHandler{}
+	result, err := handler.Execute(ctx, nil)
+	if err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if result == nil || result.Message == "" {
+		t.Fatalf("Execute() returned empty result: %+v", result)
+	}
+
+	var totalStat models.UploadStat
+	if err := database.DB(ctx).
+		Where("dimension = ? AND stat_key = ?", models.UploadStatDimensionTotal, "").
+		First(&totalStat).Error; err != nil {
+		t.Fatalf("load total stat failed: %v", err)
+	}
+	if totalStat.FileCount != 2 || totalStat.FileSize != 300 {
+		t.Fatalf("total stat = count %d size %d, want 2 / 300", totalStat.FileCount, totalStat.FileSize)
+	}
+}

backend/plugins/domain/upload/task/storage_migration.go

@@ -0,0 +1,380 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"golang.org/x/sync/errgroup"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	uploadstats "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/stats"
+	uploadstorage "github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/storage"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	cache "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+)
+
+const (
+	// StorageMigrationTask is the Asynq task name for storage migration.
+	StorageMigrationTask = uploadstorage.StorageMigrationTask
+	// TaskTypeStorageMigration is the task metadata type for storage migration.
+	TaskTypeStorageMigration = "storage_migration"
+)
+
+// StorageMigrationMeta describes the manually dispatchable migration task.
+var StorageMigrationMeta = driver_asynq_worker.TaskMeta{
+	Type:         TaskTypeStorageMigration,
+	AsynqTask:    StorageMigrationTask,
+	Name:         "迁移文件存储",
+	Description:  "将活动存储中的文件迁移到待切换的目标存储，迁移期间文件系统保持只读",
+	SupportsTime: false,
+	MaxRetry:     driver_asynq_worker.DefaultMaxRetry,
+	Queue:        driver_asynq_worker.QueueDefault,
+	Retryable:    true,
+	Params: []driver_asynq_worker.TaskParam{
+		{
+			Name:        "target",
+			Label:       "目标存储配置 (JSON)",
+			Type:        "text",
+			Required:    true,
+			Placeholder: `{"driver": "s3", "local": {"root": "."}, "s3": {"bucket": "my-bucket", ...}}`,
+			Description: "待迁移到的目标存储引擎完整配置 JSON 字符串",
+		},
+	},
+}
+
+// MigrationHandler copies stored objects and activates the target backend.
+type MigrationHandler struct{}
+
+// ValidatePayload rejects duplicate active migrations through the task framework.
+func (h *MigrationHandler) ValidatePayload(payload []byte) ([]byte, error) {
+	normalized, _, err := uploadstorage.NormalizeMigrationPayload(context.Background(), payload)
+	if err != nil {
+		return payload, err
+	}
+	active, err := hasUnresolvedMigrationTask(context.Background())
+	if err != nil {
+		return payload, err
+	}
+	if active {
+		return payload, fmt.Errorf("storage migration task is already unresolved")
+	}
+	return normalized, nil
+}
+
+// Execute migrates all unique active-storage objects to the pending backend.
+func (h *MigrationHandler) Execute(ctx context.Context, payload []byte) (*driver_asynq_worker.TaskResult, error) {
+	if cache.Redis != nil {
+		const (
+			cleanupTimeout  = 5 * time.Second
+			renewalInterval = 10 * time.Minute
+		)
+
+		lockKey := cache.PrefixedKey("lock:storage:migrate")
+		ok, err := cache.Redis.SetNX(ctx, lockKey, "locked", time.Hour).Result()
+		if err != nil {
+			return nil, fmt.Errorf("acquire migration lock: %w", err)
+		}
+		if !ok {
+			return nil, errors.New("另一个存储迁移任务正在运行中")
+		}
+
+		stopRenewal := make(chan struct{})
+		//nolint:contextcheck
+		defer func() {
+			close(stopRenewal)
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_ = cache.Redis.Del(cleanupCtx, lockKey)
+		}()
+
+		//nolint:contextcheck,gosec
+		util.Go(func() {
+			ticker := time.NewTicker(renewalInterval)
+			defer ticker.Stop()
+			for {
+				select {
+				case <-ticker.C:
+					renewCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+					_ = cache.Redis.Expire(renewCtx, lockKey, time.Hour).Err()
+					cancel()
+				case <-stopRenewal:
+					return
+				case <-ctx.Done():
+					return
+				}
+			}
+		})
+	}
+
+	active, err := objectstore.LoadConfig(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("load active storage config: %w", err)
+	}
+	target, err := uploadstorage.ParseMigrationTargetConfig(ctx, payload)
+	if err != nil {
+		return nil, err
+	}
+	if target.Driver == active.Driver {
+		if err := objectstore.SaveActiveConfig(ctx, target); err != nil {
+			return nil, fmt.Errorf("activate same-driver storage config: %w", err)
+		}
+		message := fmt.Sprintf("存储配置已更新，活动存储保持为 %s", target.Driver)
+		driver_asynq_worker.AppendLog(ctx, "%s", message)
+		return &driver_asynq_worker.TaskResult{Message: message}, nil
+	}
+
+	total, err := countStorageObjects(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("count source objects: %w", err)
+	}
+	if total == 0 {
+		if err := objectstore.SaveActiveConfig(ctx, target); err != nil {
+			return nil, fmt.Errorf("activate empty storage config: %w", err)
+		}
+		message := fmt.Sprintf("当前存储没有需要迁移的对象，活动存储已切换为 %s", target.Driver)
+		driver_asynq_worker.AppendLog(ctx, "%s", message)
+		return &driver_asynq_worker.TaskResult{Message: message}, nil
+	}
+
+	sourceBackend, err := objectstore.NewBackend(ctx, active, active.Driver)
+	if err != nil {
+		return nil, fmt.Errorf("create source storage: %w", err)
+	}
+	targetBackend, err := objectstore.NewBackend(ctx, target, target.Driver)
+	if err != nil {
+		return nil, fmt.Errorf("create target storage: %w", err)
+	}
+
+	driver_asynq_worker.AppendLog(ctx, "开始存储迁移: %s -> %s，总对象数: %d", active.Driver, target.Driver, total)
+	migrated, err := migrateObjects(ctx, sourceBackend, targetBackend, total)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := objectstore.SaveActiveConfig(ctx, target); err != nil {
+		return nil, fmt.Errorf("activate target storage: %w", err)
+	}
+	message := fmt.Sprintf("存储迁移完成，共迁移 %d 个对象，活动存储已切换为 %s", migrated, target.Driver)
+	driver_asynq_worker.AppendLog(ctx, "%s", message)
+	return &driver_asynq_worker.TaskResult{Message: message}, nil
+}
+
+func countStorageObjects(ctx context.Context) (int64, error) {
+	var count int64
+	err := database.DB(ctx).Model(&models.Upload{}).
+		Where("status != ?", models.UploadStatusDeleted).
+		Distinct("file_path").
+		Count(&count).Error
+	return count, err
+}
+
+func hasUnresolvedMigrationTask(ctx context.Context) (bool, error) {
+	execution, ok, err := uploadstorage.LatestMigrationExecution(ctx)
+	if err != nil || !ok {
+		return false, err
+	}
+	return execution.Status == driver_asynq_worker.TaskExecutionStatusPending || execution.Status == driver_asynq_worker.TaskExecutionStatusRunning, nil
+}
+
+type migrationObject struct {
+	FilePath string `gorm:"column:file_path"`
+	FileSize int64  `gorm:"column:file_size"`
+	MimeType string `gorm:"column:mime_type"`
+	Hash     string `gorm:"column:hash"`
+}
+
+func migrateObjects(
+	ctx context.Context,
+	sourceBackend objectstore.Backend,
+	targetBackend objectstore.Backend,
+	total int64,
+) (int64, error) {
+	const batchSize = 50
+	const migrationConcurrency = 10
+	const sha256HexLength = 64
+	var migrated int64
+	var lastFilePath string
+	for {
+		if err := ctx.Err(); err != nil {
+			return atomic.LoadInt64(&migrated), fmt.Errorf("storage migration canceled: %w", err)
+		}
+
+		driver_asynq_worker.AppendLog(ctx, "正在查询待迁移对象批次，当前已完成迁移: %d/%d", atomic.LoadInt64(&migrated), total)
+
+		var objects []migrationObject
+		query := database.DB(ctx).Model(&models.Upload{}).
+			Select("file_path, MAX(file_size) AS file_size, MAX(mime_type) AS mime_type, MAX(hash) AS hash").
+			Where("status != ?", models.UploadStatusDeleted)
+		if lastFilePath != "" {
+			query = query.Where("file_path > ?", lastFilePath)
+		}
+		if err := query.Group("file_path").
+			Order("file_path ASC").
+			Limit(batchSize).
+			Scan(&objects).Error; err != nil {
+			return atomic.LoadInt64(&migrated), fmt.Errorf("query source objects: %w", err)
+		}
+		if len(objects) == 0 {
+			driver_asynq_worker.AppendLog(ctx, "所有对象迁移完毕")
+			break
+		}
+
+		lastFilePath = objects[len(objects)-1].FilePath
+		driver_asynq_worker.AppendLog(ctx, "获取当前批次迁移对象，批次大小: %d，实际获取对象数: %d", batchSize, len(objects))
+
+		var g errgroup.Group
+		g.SetLimit(migrationConcurrency)
+
+		for _, object := range objects {
+			obj := object
+			g.Go(func() error {
+				if err := migrateSingleObject(ctx, sourceBackend, targetBackend, obj, sha256HexLength); err != nil {
+					return err
+				}
+				atomic.AddInt64(&migrated, 1)
+				return nil
+			})
+		}
+
+		if err := g.Wait(); err != nil {
+			return atomic.LoadInt64(&migrated), err
+		}
+
+		driver_asynq_worker.AppendLog(ctx, "当前批次迁移完成。迁移进度: %d/%d", atomic.LoadInt64(&migrated), total)
+	}
+	return atomic.LoadInt64(&migrated), nil
+}
+
+func migrateSingleObject(
+	ctx context.Context,
+	sourceBackend objectstore.Backend,
+	targetBackend objectstore.Backend,
+	obj migrationObject,
+	sha256HexLength int,
+) error {
+	if shouldSkipMigration(ctx, targetBackend, obj) {
+		driver_asynq_worker.AppendLog(ctx, "[跳过迁移] 目标存储已存在相同文件: %s", obj.FilePath)
+		return nil
+	}
+
+	driver_asynq_worker.AppendLog(ctx, "[迁移开始] 正在从源存储读取文件: %s", obj.FilePath)
+	source, err := sourceBackend.Get(ctx, obj.FilePath)
+	if err != nil {
+		if isNotFoundError(err) {
+			return markMissingMigrationObjectDeleted(ctx, obj.FilePath, err)
+		}
+		return fmt.Errorf("open source object %q: %w", obj.FilePath, err)
+	}
+	driver_asynq_worker.AppendLog(ctx, "[传输中] 正在向目标存储上传文件: %s (大小: %d 字节, 类型: %s)", obj.FilePath, obj.FileSize, obj.MimeType)
+	targetResult, putErr := targetBackend.Put(ctx, obj.FilePath, source.Body, obj.FileSize, obj.MimeType)
+	closeErr := source.Body.Close()
+	if putErr != nil {
+		return fmt.Errorf("copy object %q: %w", obj.FilePath, putErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close source object %q: %w", obj.FilePath, closeErr)
+	}
+
+	if len(obj.Hash) == sha256HexLength {
+		driver_asynq_worker.AppendLog(ctx, "[校验中] 正在对目标文件进行数据一致性校验 (SHA-256): %s", targetResult.Key)
+		targetObj, getErr := targetBackend.Get(ctx, targetResult.Key)
+		if getErr != nil {
+			return fmt.Errorf("retrieve target object for verification %q: %w", obj.FilePath, getErr)
+		}
+		if targetObj == nil || targetObj.Body == nil {
+			return fmt.Errorf("retrieve target object for verification %q: object or body is nil", obj.FilePath)
+		}
+		h := sha256.New()
+		if _, copyErr := io.Copy(h, targetObj.Body); copyErr != nil {
+			_ = targetObj.Body.Close()
+			return fmt.Errorf("read target object for verification %q: %w", obj.FilePath, copyErr)
+		}
+		_ = targetObj.Body.Close()
+		computedHash := hex.EncodeToString(h.Sum(nil))
+		if computedHash != obj.Hash {
+			return fmt.Errorf("integrity check failed for %q: got hash %s, want %s", obj.FilePath, computedHash, obj.Hash)
+		}
+		driver_asynq_worker.AppendLog(ctx, "[校验通过] 文件一致性校验成功: %s", targetResult.Key)
+	}
+
+	if targetResult.Key != obj.FilePath {
+		driver_asynq_worker.AppendLog(ctx, "[更新数据库] 正在更新文件路径: %s -> %s", obj.FilePath, targetResult.Key)
+		if err := database.DB(ctx).Model(&models.Upload{}).
+			Where("file_path = ? AND status != ?", obj.FilePath, models.UploadStatusDeleted).
+			Update("file_path", targetResult.Key).Error; err != nil {
+			return fmt.Errorf("update migrated object %q: %w", obj.FilePath, err)
+		}
+	}
+	driver_asynq_worker.AppendLog(ctx, "[迁移成功] 文件已完成迁移: %s", targetResult.Key)
+	return nil
+}
+
+func shouldSkipMigration(
+	ctx context.Context,
+	targetBackend objectstore.Backend,
+	obj migrationObject,
+) bool {
+	targetObj, err := targetBackend.Get(ctx, obj.FilePath)
+	if err != nil || targetObj == nil || targetObj.Body == nil {
+		return false
+	}
+	defer func() {
+		_ = targetObj.Body.Close()
+	}()
+
+	return targetObj.ContentLength == obj.FileSize
+}
+
+func markMissingMigrationObjectDeleted(
+	ctx context.Context,
+	filePath string,
+	sourceErr error,
+) error {
+	driver_asynq_worker.AppendLog(ctx, "警告: 源存储中物理文件不存在，标记为已删除并跳过: %s (错误: %v)", filePath, sourceErr)
+
+	var affectedUploads []models.Upload
+	if err := database.DB(ctx).
+		Where("file_path = ? AND status != ?", filePath, models.UploadStatusDeleted).
+		Find(&affectedUploads).Error; err != nil {
+		return fmt.Errorf("load missing object uploads %q: %w", filePath, err)
+	}
+	if err := database.DB(ctx).Model(&models.Upload{}).
+		Where("file_path = ?", filePath).
+		Update("status", models.UploadStatusDeleted).Error; err != nil {
+		return fmt.Errorf("update missing object %q: %w", filePath, err)
+	}
+	for i := range affectedUploads {
+		uploadstats.RecordUploadStatsRemove(ctx, &affectedUploads[i])
+	}
+	return nil
+}
+
+func isNotFoundError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, os.ErrNotExist) {
+		return true
+	}
+	errStr := strings.ToLower(err.Error())
+	for _, sub := range []string{"not found", "nosuchkey", "nosuchbucket", "404", "does not exist"} {
+		if strings.Contains(errStr, sub) {
+			return true
+		}
+	}
+	return false
+}

backend/plugins/domain/upload/task/storage_migration_task_test.go

@@ -0,0 +1,286 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	cache "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+	"github.com/alicebob/miniredis/v2"
+	"github.com/redis/go-redis/v9"
+)
+
+func TestMigrationHandlerExecute(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	sourceRoot := t.TempDir()
+	sourcePath := filepath.Join(sourceRoot, "uploads", "test.txt")
+	if err := os.MkdirAll(filepath.Dir(sourcePath), 0755); err != nil {
+		t.Fatalf("MkdirAll(%q) returned error: %v", sourcePath, err)
+	}
+	const content = "storage migration"
+	if err := os.WriteFile(sourcePath, []byte(content), 0644); err != nil {
+		t.Fatalf("WriteFile(%q) returned error: %v", sourcePath, err)
+	}
+
+	ctx := context.Background()
+	active := objectstore.DefaultConfig()
+	active.Local.Root = sourceRoot
+	if err := objectstore.SaveActiveConfig(ctx, active); err != nil {
+		t.Fatalf("SaveActiveConfig() returned error: %v", err)
+	}
+	target := objectstore.DefaultConfig()
+	target.Driver = objectstore.DriverS3
+	target.S3 = objectstore.ObjectConfig{
+		Region:          "us-east-1",
+		Bucket:          "target",
+		AccessKeyID:     "key",
+		SecretAccessKey: "secret",
+	}
+	payload, err := json.Marshal(struct {
+		Target objectstore.Config `json:"target"`
+	}{Target: target})
+	if err != nil {
+		t.Fatalf("Marshal(storageMigrationPayload) returned error: %v", err)
+	}
+
+	upload := models.Upload{
+		ID:        99101,
+		UserID:    1,
+		FileName:  "test.txt",
+		FilePath:  "uploads/test.txt",
+		FileSize:  int64(len(content)),
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      "hash",
+		Type:      "attachment",
+		Status:    models.UploadStatusUsed,
+	}
+	if err := dbConn.Create(&upload).Error; err != nil {
+		t.Fatalf("Create(upload) returned error: %v", err)
+	}
+
+	var copied bytes.Buffer
+	restore := objectstore.MockStorage(
+		func(_ context.Context, _ string, body io.Reader, _ int64, _ string) error {
+			_, err := io.Copy(&copied, body)
+			return err
+		},
+		func(context.Context, string) (*objectstore.Object, error) {
+			return nil, nil
+		},
+		func(context.Context, string) error {
+			return nil
+		},
+	)
+	defer restore()
+
+	result, err := (&MigrationHandler{}).Execute(ctx, payload)
+	if err != nil {
+		t.Fatalf("Execute() returned error: %v", err)
+	}
+	if result == nil {
+		t.Fatal("Execute() result = nil, want non-nil")
+	}
+	if copied.String() != content {
+		t.Errorf("migrated content = %q, want %q", copied.String(), content)
+	}
+
+	var migrated models.Upload
+	if err := dbConn.First(&migrated, upload.ID).Error; err != nil {
+		t.Fatalf("First(upload) returned error: %v", err)
+	}
+	current, err := objectstore.LoadConfig(ctx)
+	if err != nil {
+		t.Fatalf("LoadConfig() returned error: %v", err)
+	}
+	if current.Driver != objectstore.DriverS3 {
+		t.Errorf("active driver = %q, want %q", current.Driver, objectstore.DriverS3)
+	}
+}
+
+func TestMigrationHandlerExecuteWithHashValidation(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	sourceRoot := t.TempDir()
+	sourcePath := filepath.Join(sourceRoot, "uploads", "test-hash.txt")
+	if err := os.MkdirAll(filepath.Dir(sourcePath), 0755); err != nil {
+		t.Fatalf("MkdirAll(%q) returned error: %v", sourcePath, err)
+	}
+	const content = "storage migration integrity check content"
+	if err := os.WriteFile(sourcePath, []byte(content), 0644); err != nil {
+		t.Fatalf("WriteFile(%q) returned error: %v", sourcePath, err)
+	}
+
+	// Calculate correct SHA-256 hash
+	h := sha256.New()
+	h.Write([]byte(content))
+	correctHash := hex.EncodeToString(h.Sum(nil))
+
+	ctx := context.Background()
+	active := objectstore.DefaultConfig()
+	active.Local.Root = sourceRoot
+	if err := objectstore.SaveActiveConfig(ctx, active); err != nil {
+		t.Fatalf("SaveActiveConfig() returned error: %v", err)
+	}
+
+	target := objectstore.DefaultConfig()
+	target.Driver = objectstore.DriverS3
+	target.S3 = objectstore.ObjectConfig{
+		Region:          "us-east-1",
+		Bucket:          "target",
+		AccessKeyID:     "key",
+		SecretAccessKey: "secret",
+	}
+	payload, err := json.Marshal(struct {
+		Target objectstore.Config `json:"target"`
+	}{Target: target})
+	if err != nil {
+		t.Fatalf("Marshal(storageMigrationPayload) returned error: %v", err)
+	}
+
+	// Case 1: Incorrect Hash (should fail validation)
+	uploadIncorrect := models.Upload{
+		ID:        99102,
+		UserID:    1,
+		FileName:  "test-hash.txt",
+		FilePath:  "uploads/test-hash.txt",
+		FileSize:  int64(len(content)),
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", // Invalid hash
+		Type:      "attachment",
+		Status:    models.UploadStatusUsed,
+	}
+	if err := dbConn.Create(&uploadIncorrect).Error; err != nil {
+		t.Fatalf("Create(uploadIncorrect) returned error: %v", err)
+	}
+
+	var copied bytes.Buffer
+	restore := objectstore.MockStorage(
+		func(_ context.Context, _ string, body io.Reader, _ int64, _ string) error {
+			copied.Reset()
+			_, err := io.Copy(&copied, body)
+			return err
+		},
+		func(context.Context, string) (*objectstore.Object, error) {
+			return &objectstore.Object{
+				Body:          io.NopCloser(bytes.NewBuffer(copied.Bytes())),
+				ContentLength: int64(copied.Len()),
+				ContentType:   "text/plain",
+			}, nil
+		},
+		func(context.Context, string) error {
+			return nil
+		},
+	)
+	defer restore()
+
+	// Running execution with incorrect hash should fail with integrity error
+	_, err = (&MigrationHandler{}).Execute(ctx, payload)
+	if err == nil {
+		t.Fatal("Execute() succeeded with incorrect hash, want error")
+	}
+	if !strings.Contains(err.Error(), "integrity check failed") {
+		t.Errorf("expected integrity check failed error, got: %v", err)
+	}
+
+	// Case 2: Correct Hash (should succeed)
+	if err := dbConn.Model(&models.Upload{}).Where("id = ?", uploadIncorrect.ID).Update("hash", correctHash).Error; err != nil {
+		t.Fatalf("Update hash to correct value returned error: %v", err)
+	}
+
+	// Run execution with correct hash should succeed
+	result, err := (&MigrationHandler{}).Execute(ctx, payload)
+	if err != nil {
+		t.Fatalf("Execute() with correct hash failed: %v", err)
+	}
+	if result == nil {
+		t.Fatal("Execute() result = nil, want non-nil")
+	}
+
+	var migrated models.Upload
+	if err := dbConn.First(&migrated, uploadIncorrect.ID).Error; err != nil {
+		t.Fatalf("First(upload) returned error: %v", err)
+	}
+	if migrated.FilePath != "uploads/test-hash.txt" {
+		t.Errorf("FilePath = %q, want %q", migrated.FilePath, "uploads/test-hash.txt")
+	}
+}
+
+func TestMigrationHandlerExecuteWithRedisLock(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	mr, err := miniredis.Run()
+	if err != nil {
+		t.Fatalf("Failed to run miniredis: %v", err)
+	}
+	defer mr.Close()
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr: mr.Addr(),
+	})
+	defer rdb.Close()
+
+	oldRedis := cache.Redis
+	cache.Redis = rdb
+	defer func() {
+		cache.Redis = oldRedis
+	}()
+
+	ctx := context.Background()
+
+	// Acquire lock manually
+	lockKey := cache.PrefixedKey("lock:storage:migrate")
+	if err := rdb.Set(ctx, lockKey, "locked", time.Hour).Err(); err != nil {
+		t.Fatalf("Failed to set manual lock in Redis: %v", err)
+	}
+
+	active := objectstore.DefaultConfig()
+	if err := objectstore.SaveActiveConfig(ctx, active); err != nil {
+		t.Fatalf("SaveActiveConfig() returned error: %v", err)
+	}
+
+	payload, err := json.Marshal(struct {
+		Target objectstore.Config `json:"target"`
+	}{Target: active})
+	if err != nil {
+		t.Fatalf("Marshal payload failed: %v", err)
+	}
+
+	// Execution should fail because lock is already acquired
+	_, err = (&MigrationHandler{}).Execute(ctx, payload)
+	if err == nil {
+		t.Fatal("Execute() succeeded when lock was held, want error")
+	}
+	if !strings.Contains(err.Error(), "另一个存储迁移任务正在运行中") {
+		t.Errorf("expected lock warning, got: %v", err)
+	}
+
+	// Release lock and run again, should succeed
+	if err := rdb.Del(ctx, lockKey).Err(); err != nil {
+		t.Fatalf("Failed to delete lock: %v", err)
+	}
+
+	_, err = (&MigrationHandler{}).Execute(ctx, payload)
+	if err != nil {
+		t.Fatalf("Execute() failed after lock released: %v", err)
+	}
+}

backend/plugins/domain/upload/task/tasks.go

@@ -0,0 +1,184 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/filesrv"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+const (
+	// WarmImageCacheTask 图片压缩缓存预热任务标识
+	WarmImageCacheTask = "upload:warm_image_cache"
+	// TaskTypeWarmImageCache 图片压缩缓存预热管理类型
+	TaskTypeWarmImageCache = "warm_image_cache"
+)
+
+var warmImageCacheMu sync.Mutex
+
+// WarmImageCacheMeta represents the image cache warmup task metadata.
+var WarmImageCacheMeta = driver_asynq_worker.TaskMeta{
+	Type:         TaskTypeWarmImageCache,
+	AsynqTask:    WarmImageCacheTask,
+	Name:         "预热图片压缩缓存",
+	Description:  "串行将文件管理中的图片转换为指定质量的 WebP 并写入永久缓存",
+	SupportsTime: false,
+	MaxRetry:     driver_asynq_worker.DefaultMaxRetry,
+	Queue:        driver_asynq_worker.QueueDefault,
+	Retryable:    true,
+	Params: []driver_asynq_worker.TaskParam{
+		{
+			Name:        "quality",
+			Label:       "图片质量",
+			Type:        "string",
+			Required:    true,
+			Placeholder: "low / medium / high",
+			Description: "WebP 压缩质量，仅支持 low、medium、high",
+		},
+	},
+}
+
+// WarmImageCachePayload is the image cache warmup task payload.
+type WarmImageCachePayload struct {
+	Quality string `json:"quality"`
+}
+
+// WarmImageCacheHandler serially warms compressed image cache entries.
+type WarmImageCacheHandler struct{}
+
+// ValidatePayload validates and normalizes image cache warmup parameters.
+func (h *WarmImageCacheHandler) ValidatePayload(payload []byte) ([]byte, error) {
+	if len(payload) == 0 {
+		return nil, errors.New(shared.ErrImageCacheWarmupPayloadRequired)
+	}
+
+	var req WarmImageCachePayload
+	if err := json.Unmarshal(payload, &req); err != nil {
+		return nil, fmt.Errorf(shared.ErrInvalidImageCacheWarmupPayload, err)
+	}
+
+	req.Quality = strings.ToLower(strings.TrimSpace(req.Quality))
+	if req.Quality != shared.ImageQualityLow &&
+		req.Quality != shared.ImageQualityMedium &&
+		req.Quality != shared.ImageQualityHigh {
+		return nil, errors.New(shared.ErrInvalidImageCacheWarmupQuality)
+	}
+
+	return json.Marshal(req)
+}
+
+// Execute serially converts all managed images to WebP cache entries.
+func (h *WarmImageCacheHandler) Execute(ctx context.Context, payload []byte) (*driver_asynq_worker.TaskResult, error) {
+	normalizedPayload, err := h.ValidatePayload(payload)
+	if err != nil {
+		driver_asynq_worker.AppendLog(ctx, "图片缓存预热参数无效: %v", err)
+		return nil, err
+	}
+
+	var req WarmImageCachePayload
+	if err := json.Unmarshal(normalizedPayload, &req); err != nil {
+		return nil, fmt.Errorf(shared.ErrParseImageCacheWarmupPayload, err)
+	}
+
+	driver_asynq_worker.AppendLog(ctx, "等待获取图片缓存预热执行锁，质量: %s", req.Quality)
+	warmImageCacheMu.Lock()
+	defer warmImageCacheMu.Unlock()
+
+	const (
+		batchSize      = 50
+		maxFailureLogs = 5
+	)
+	var lastID uint64
+	var totalProcessed int
+	var totalCached int
+	var totalGenerated int
+	var totalFailed int
+
+	driver_asynq_worker.AppendLog(ctx, "开始串行预热图片压缩缓存，质量: %s，每批: %d", req.Quality, batchSize)
+
+	for {
+		if err := ctx.Err(); err != nil {
+			return nil, fmt.Errorf("image cache warmup canceled: %w", err)
+		}
+
+		var uploads []models.Upload
+		if err := database.DB(ctx).
+			Where("id > ? AND status != ? AND (LOWER(mime_type) LIKE ? OR LOWER(extension) IN ?)",
+				lastID,
+				models.UploadStatusDeleted,
+				"image/%",
+				[]string{"jpg", "jpeg", "png", "webp", "gif"},
+			).
+			Order("id ASC").
+			Limit(batchSize).
+			Find(&uploads).Error; err != nil {
+			driver_asynq_worker.AppendLog(ctx, "查询图片上传记录失败: %v", err)
+			return nil, fmt.Errorf(shared.ErrQueryImagesForCacheWarmup, err)
+		}
+
+		if len(uploads) == 0 {
+			break
+		}
+
+		batchGenerated := 0
+		batchCached := 0
+		batchFailed := 0
+		for i := range uploads {
+			if err := ctx.Err(); err != nil {
+				return nil, fmt.Errorf("image cache warmup canceled: %w", err)
+			}
+
+			upload := &uploads[i]
+			totalProcessed++
+			lastID = upload.ID
+
+			_, cacheHit, err := filesrv.EnsureCompressedImageCache(ctx, upload, req.Quality)
+			if err != nil {
+				totalFailed++
+				batchFailed++
+				if totalFailed <= maxFailureLogs {
+					driver_asynq_worker.AppendLog(ctx, "图片处理失败 [ID:%d]: %v", upload.ID, err)
+				}
+				continue
+			}
+			if cacheHit {
+				totalCached++
+				batchCached++
+				continue
+			}
+			totalGenerated++
+			batchGenerated++
+		}
+
+		driver_asynq_worker.AppendLog(
+			ctx,
+			"批次完成，末尾 ID: %d，生成: %d，命中: %d，失败: %d",
+			lastID,
+			batchGenerated,
+			batchCached,
+			batchFailed,
+		)
+	}
+
+	msg := fmt.Sprintf(
+		"图片缓存预热完成，共处理 %d 张，生成 %d 张，命中 %d 张，失败 %d 张",
+		totalProcessed,
+		totalGenerated,
+		totalCached,
+		totalFailed,
+	)
+	driver_asynq_worker.AppendLog(ctx, "%s", msg)
+	return &driver_asynq_worker.TaskResult{Message: msg}, nil
+}

backend/plugins/domain/upload/task/tasks_test.go

@@ -0,0 +1,386 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"image"
+	"image/color"
+	"image/png"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+	msg "github.com/Rain-kl/Wavelet/backend/plugins/domain/message_gateway"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/filesrv"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/models"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	"github.com/Rain-kl/Wavelet/backend/plugins/drivers/driver_asynq_worker"
+	database "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/diskcache"
+	"github.com/Rain-kl/Wavelet/backend/plugins/infra/storage/objectstore"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSystemCleanupHandler_Execute(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Mock S3 存储（让 DeleteObject 总是成功）
+	storageMock := objectstore.MockStorage(
+		func(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+			return nil
+		},
+		func(ctx context.Context, key string) (*objectstore.Object, error) { return nil, nil },
+		func(ctx context.Context, key string) error { return nil },
+	)
+	defer storageMock()
+	objectstore.IsEnabledFunc = func() bool { return true }
+	defer func() { objectstore.IsEnabledFunc = func() bool { return false } }()
+	objectstore.ResetCache()
+
+	ctx := context.Background()
+	err := database.DB(ctx).AutoMigrate(&msg.PushHistory{})
+	require.NoError(t, err)
+
+	// 准备测试数据：创建一些上传记录
+	now := time.Now()
+	twoHoursAgo := now.Add(-2 * time.Hour)
+
+	records := []*models.Upload{
+		// 超过1小时且状态为 pending 的记录 —— 应被清理
+		{
+			UserID: 1001, FileName: "old_file_1.jpg", FilePath: "uploads/old_1.jpg",
+			FileSize: 1024, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash1",
+			Type: "attachment", Status: models.UploadStatusPending,
+			CreatedAt: twoHoursAgo,
+		},
+		{
+			UserID: 1001, FileName: "old_file_2.png", FilePath: "uploads/old_2.png",
+			FileSize: 2048, MimeType: "image/png", Extension: "png", Hash: "hash2",
+			Type: "attachment", Status: models.UploadStatusPending,
+			CreatedAt: twoHoursAgo,
+		},
+		// 状态为 used 的记录 —— 不应被清理
+		{
+			UserID: 1001, FileName: "used_file.jpg", FilePath: "uploads/used.jpg",
+			FileSize: 512, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash3",
+			Type: "attachment", Status: models.UploadStatusUsed,
+			CreatedAt: twoHoursAgo,
+		},
+		// 不到1小时的 pending 记录 —— 不应被清理
+		{
+			UserID: 1001, FileName: "recent_file.jpg", FilePath: "uploads/recent.jpg",
+			FileSize: 256, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash4",
+			Type: "attachment", Status: models.UploadStatusPending,
+			CreatedAt: now.Add(-10 * time.Minute),
+		},
+	}
+	for _, r := range records {
+		err := database.DB(ctx).Create(r).Error
+		require.NoError(t, err)
+	}
+
+	// 准备推送历史测试数据：1个旧的（应删除），1个新的（应保留）
+	oldPush := &msg.PushHistory{
+		EventKey:  "admin_login",
+		Channel:   "email",
+		Target:    "admin@test.com",
+		Title:     "Old Login",
+		Content:   "Old Content",
+		Level:     "INFO",
+		Status:    "success",
+		CreatedAt: now.AddDate(0, 0, -10),
+	}
+	newPush := &msg.PushHistory{
+		EventKey:  "admin_login",
+		Channel:   "lark",
+		Target:    "http://webhook.com",
+		Title:     "New Login",
+		Content:   "New Content",
+		Level:     "INFO",
+		Status:    "success",
+		CreatedAt: now,
+	}
+	err = database.DB(ctx).Create(oldPush).Error
+	require.NoError(t, err)
+	err = database.DB(ctx).Create(newPush).Error
+	require.NoError(t, err)
+
+	oldTaskLog := &driver_asynq_worker.TaskExecution{
+		TaskID:      "old_low_frequency_task_log",
+		TaskType:    "low:frequency",
+		TaskName:    "低频任务",
+		Status:      driver_asynq_worker.TaskExecutionStatusSucceeded,
+		CreatedAt:   now.AddDate(0, 0, -31),
+		UpdatedAt:   now.AddDate(0, 0, -31),
+		TriggeredBy: "system",
+	}
+	err = driver_asynq_worker.CreateTaskExecution(ctx, oldTaskLog)
+	require.NoError(t, err)
+
+	// 执行 handler
+	handler := &SystemCleanupHandler{}
+	result, err := handler.Execute(ctx, nil)
+
+	// 验证结果
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.Contains(t, result.Message, "系统清理完成。成功清理未使用的上传文件 2/2 个；清理历史推送审计日志 1 条；清理任务执行日志 1 条；清理过期访问日志 0 条。")
+
+	// 验证数据库状态：pending 且超过1小时的应被标记为 deleted
+	var pendingCount int64
+	database.DB(ctx).Model(&models.Upload{}).Where("status = ?", models.UploadStatusPending).Count(&pendingCount)
+	assert.Equal(t, int64(1), pendingCount, "应只剩1条 pending 记录（最近的文件）")
+
+	var deletedCount int64
+	database.DB(ctx).Model(&models.Upload{}).Where("status = ?", models.UploadStatusDeleted).Count(&deletedCount)
+	assert.Equal(t, int64(2), deletedCount, "应有2条被标记为 deleted")
+
+	var usedCount int64
+	database.DB(ctx).Model(&models.Upload{}).Where("status = ?", models.UploadStatusUsed).Count(&usedCount)
+	assert.Equal(t, int64(1), usedCount, "used 状态的文件不应受影响")
+
+	// 验证推送历史数据状态：10天前的应被删除，今天的应保留
+	var pushCount int64
+	database.DB(ctx).Model(&msg.PushHistory{}).Count(&pushCount)
+	assert.Equal(t, int64(1), pushCount, "应只剩1条推送历史记录")
+
+	var remainingPush msg.PushHistory
+	err = database.DB(ctx).First(&remainingPush).Error
+	require.NoError(t, err)
+	assert.Equal(t, "New Login", remainingPush.Title)
+
+	var taskLogCount int64
+	err = database.DB(ctx).Model(&driver_asynq_worker.TaskExecution{}).Where("task_id = ?", "old_low_frequency_task_log").Count(&taskLogCount).Error
+	require.NoError(t, err)
+	assert.Equal(t, int64(0), taskLogCount, "过期低频任务日志应被清理")
+}
+
+func TestSystemCleanupHandler_ExecuteNoFiles(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Mock S3 存储
+	storageMock := objectstore.MockStorage(
+		func(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+			return nil
+		},
+		func(ctx context.Context, key string) (*objectstore.Object, error) { return nil, nil },
+		func(ctx context.Context, key string) error { return nil },
+	)
+	defer storageMock()
+
+	ctx := context.Background()
+	err := database.DB(ctx).AutoMigrate(&msg.PushHistory{})
+	require.NoError(t, err)
+
+	// 没有任何上传记录
+	handler := &SystemCleanupHandler{}
+	result, err := handler.Execute(ctx, nil)
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.Contains(t, result.Message, "系统清理完成。成功清理未使用的上传文件 0/0 个；清理历史推送审计日志 0 条；清理任务执行日志 0 条；清理过期访问日志 0 条。")
+}
+
+func TestSystemCleanupHandler_ImplementsTaskHandler(t *testing.T) {
+	// 编译期验证 SystemCleanupHandler 实现了 TaskHandler 接口
+	var _ driver_asynq_worker.TaskHandler = (*SystemCleanupHandler)(nil)
+}
+
+func TestWarmImageCacheHandlerValidatePayload(t *testing.T) {
+	tests := []struct {
+		name        string
+		payload     []byte
+		wantQuality string
+		wantErr     bool
+	}{
+		{
+			name:        "normalizes quality",
+			payload:     []byte(`{"quality":" HIGH "}`),
+			wantQuality: shared.ImageQualityHigh,
+		},
+		{
+			name:    "empty payload",
+			wantErr: true,
+		},
+		{
+			name:    "invalid json",
+			payload: []byte(`{`),
+			wantErr: true,
+		},
+		{
+			name:    "origin is not a compressed quality",
+			payload: []byte(`{"quality":"origin"}`),
+			wantErr: true,
+		},
+		{
+			name:    "unsupported quality",
+			payload: []byte(`{"quality":"maximum"}`),
+			wantErr: true,
+		},
+	}
+
+	handler := &WarmImageCacheHandler{}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotPayload, err := handler.ValidatePayload(tt.payload)
+			if gotErr := err != nil; gotErr != tt.wantErr {
+				t.Fatalf("ValidatePayload(%s) error = %v, want error presence = %t", tt.payload, err, tt.wantErr)
+			}
+			if tt.wantErr {
+				return
+			}
+
+			var got WarmImageCachePayload
+			if err := json.Unmarshal(gotPayload, &got); err != nil {
+				t.Fatalf("json.Unmarshal(%s) returned error: %v", gotPayload, err)
+			}
+			if got.Quality != tt.wantQuality {
+				t.Errorf("ValidatePayload(%s).Quality = %q, want %q", tt.payload, got.Quality, tt.wantQuality)
+			}
+		})
+	}
+}
+
+func TestWarmImageCacheHandlerExecute(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	cache := diskcache.GetGlobalCache()
+	if err := cache.Clear(); err != nil {
+		t.Fatalf("Clear() before test returned error: %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cache.Clear(); err != nil {
+			t.Errorf("Clear() after test returned error: %v", err)
+		}
+	})
+
+	testDir := t.TempDir()
+	ctx := context.Background()
+	active := objectstore.DefaultConfig()
+	active.Local.Root = testDir
+	if err := objectstore.SaveActiveConfig(ctx, active); err != nil {
+		t.Fatalf("SaveActiveConfig() returned error: %v", err)
+	}
+
+	firstPath := filepath.Join(testDir, "first.png")
+	secondPath := filepath.Join(testDir, "second.jpg")
+	writeTaskTestPNG(t, firstPath, color.RGBA{R: 255, A: 255})
+	writeTaskTestPNG(t, secondPath, color.RGBA{G: 255, A: 255})
+
+	records := []models.Upload{
+		{
+			ID:        4101,
+			UserID:    1001,
+			FileName:  "first.png",
+			FilePath:  firstPath,
+			MimeType:  "image/png",
+			Extension: "png",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        4102,
+			UserID:    1001,
+			FileName:  "second.jpg",
+			FilePath:  secondPath,
+			MimeType:  "application/octet-stream",
+			Extension: "jpg",
+			Status:    models.UploadStatusPending,
+		},
+		{
+			ID:        4103,
+			UserID:    1001,
+			FileName:  "notes.txt",
+			FilePath:  filepath.Join(testDir, "notes.txt"),
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Status:    models.UploadStatusUsed,
+		},
+		{
+			ID:        4104,
+			UserID:    1001,
+			FileName:  "deleted.png",
+			FilePath:  firstPath,
+			MimeType:  "image/png",
+			Extension: "png",
+			Status:    models.UploadStatusDeleted,
+		},
+	}
+	for i := range records {
+		if info, err := os.Stat(records[i].FilePath); err == nil {
+			records[i].FileSize = info.Size()
+		}
+		if err := dbConn.Create(&records[i]).Error; err != nil {
+			t.Fatalf("failed to create upload %d: %v", records[i].ID, err)
+		}
+	}
+
+	handler := &WarmImageCacheHandler{}
+	payload := []byte(`{"quality":"low"}`)
+
+	result, err := handler.Execute(context.Background(), payload)
+	if err != nil {
+		t.Fatalf("Execute(%s) returned error: %v", payload, err)
+	}
+	if result == nil {
+		t.Fatal("Execute() result = nil, want non-nil")
+	}
+	if result.Message != "图片缓存预热完成，共处理 2 张，生成 2 张，命中 0 张，失败 0 张" {
+		t.Errorf("Execute() message = %q, want generated summary", result.Message)
+	}
+
+	for i := range records[:2] {
+		key := filesrv.ImageCompressionCacheKey(&records[i], shared.ImageQualityLow)
+		got, err := cache.Get(key)
+		if err != nil {
+			t.Errorf("cache.Get(%q) returned error: %v", key, err)
+			continue
+		}
+		if len(got) == 0 {
+			t.Errorf("cache.Get(%q) returned empty WebP data", key)
+		}
+	}
+
+	secondResult, err := handler.Execute(context.Background(), payload)
+	if err != nil {
+		t.Fatalf("second Execute(%s) returned error: %v", payload, err)
+	}
+	if secondResult.Message != "图片缓存预热完成，共处理 2 张，生成 0 张，命中 2 张，失败 0 张" {
+		t.Errorf("second Execute() message = %q, want cache-hit summary", secondResult.Message)
+	}
+}
+
+func TestWarmImageCacheHandlerImplementsTaskInterfaces(t *testing.T) {
+	var _ driver_asynq_worker.TaskHandler = (*WarmImageCacheHandler)(nil)
+	var _ driver_asynq_worker.PayloadValidator = (*WarmImageCacheHandler)(nil)
+}
+
+func writeTaskTestPNG(t *testing.T, path string, fill color.RGBA) {
+	t.Helper()
+
+	img := image.NewRGBA(image.Rect(0, 0, 2, 2))
+	for y := 0; y < 2; y++ {
+		for x := 0; x < 2; x++ {
+			img.Set(x, y, fill)
+		}
+	}
+
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, img); err != nil {
+		t.Fatalf("png.Encode() returned error: %v", err)
+	}
+	if err := os.WriteFile(path, buf.Bytes(), 0o600); err != nil {
+		t.Fatalf("os.WriteFile(%q) returned error: %v", path, err)
+	}
+}

backend/plugins/domain/upload/util/media.go

@@ -0,0 +1,51 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+)
+
+// IsImageExtension reports whether ext is a common image format.
+func IsImageExtension(ext string) bool {
+	for _, imgExt := range []string{"jpg", "jpeg", "png", "webp", "gif"} {
+		if ext == imgExt {
+			return true
+		}
+	}
+	return false
+}
+
+// IsArchiveExtension reports whether ext is a common archive format.
+func IsArchiveExtension(ext string) bool {
+	for _, e := range []string{"zip", "rar", "7z", "tar", "gz", "tgz", "bz2", "xz"} {
+		if ext == e {
+			return true
+		}
+	}
+	return false
+}
+
+// IsDocumentExtension reports whether ext is a common document format.
+func IsDocumentExtension(ext string) bool {
+	for _, e := range []string{"pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "md", "csv", "json", "yaml", "yml", "xml"} {
+		if ext == e {
+			return true
+		}
+	}
+	return false
+}
+
+// NormalizeImageQuality normalizes the requested image quality query parameter.
+func NormalizeImageQuality(quality string) string {
+	q := strings.TrimSpace(strings.ToLower(quality))
+	switch q {
+	case shared.ImageQualityLow, shared.ImageQualityMedium, shared.ImageQualityHigh:
+		return q
+	default:
+		return shared.ImageQualityOrigin
+	}
+}

backend/plugins/domain/upload/util/utils.go

@@ -0,0 +1,75 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package util provides upload media helpers and image utilities.
+package util
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"image"
+	_ "image/gif"  // Register GIF decoder for image.Decode
+	_ "image/jpeg" // Register JPEG decoder for image.Decode
+	_ "image/png"  // Register PNG decoder for image.Decode
+	"io"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/upload/shared"
+	"github.com/deepteams/webp"
+	_ "golang.org/x/image/webp" // Register WebP decoder for image.Decode
+)
+
+// ValidateS3Key validates an S3 object key for safety.
+func ValidateS3Key(key string) error {
+	if key == "" {
+		return errors.New(shared.ErrS3KeyRequired)
+	}
+
+	if len(key) > shared.MaxS3KeyLength {
+		return fmt.Errorf(shared.ErrS3KeyTooLongFormat, shared.MaxS3KeyLength)
+	}
+
+	if strings.HasPrefix(key, "/") {
+		return errors.New(shared.ErrS3KeyStartsWithSlash)
+	}
+
+	if strings.Contains(key, "\x00") {
+		return errors.New(shared.ErrS3KeyContainsNullBytes)
+	}
+
+	return nil
+}
+
+// CompressImageToWebP decodes an image from srcReader and encodes it into WebP format
+// using the specified quality (low -> 60, medium -> 75, high -> 85).
+func CompressImageToWebP(srcReader io.Reader, quality string) ([]byte, error) {
+	img, format, err := image.Decode(srcReader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode image (format: %s): %w", format, err)
+	}
+
+	var qualityScore float32
+	switch strings.ToLower(quality) {
+	case shared.ImageQualityLow:
+		qualityScore = 60
+	case shared.ImageQualityMedium:
+		qualityScore = 75
+	case shared.ImageQualityHigh, "":
+		qualityScore = 85
+	default:
+		qualityScore = 85
+	}
+
+	var buf bytes.Buffer
+	err = webp.Encode(&buf, img, &webp.EncoderOptions{
+		Quality: qualityScore,
+		Method:  4,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to encode WebP: %w", err)
+	}
+
+	return buf.Bytes(), nil
+}