feat(cordis): add OpenFlare Cordis 架构改造设计

docs(changelog): 修正表述笔误

refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本

按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），
本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到
Wavelet/pkg/cache/disk，同步后与上游零漂移。

验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与
232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。

docs(cordis): 记录 T1 清理结果与五个复用阻塞点

refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本

按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import：
shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→
上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异：
httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort*
一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。

两处非等价差异按语义处理：
- batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，
  避免 model 反向依赖基础设施类型；
- 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地
  副本，待与 infra 初始化一并迁移（已登记在清理计划）。

验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异；
make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为
response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。

chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染

按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手
属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为
纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。

同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被
gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与
driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh
现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。

AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束
（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、
internal/cmd）改到当前插件路径。

验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条
操作与基线逐条一致；make build-all 四进制；gofmt 干净。

feat(cordis): server 插件化并改由内核挂载控制面路由

新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix)
声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为
core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留
尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。
删除 router.Serve 与 registerRoutes，装配根改为 core.App +
driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；
前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。

路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条
(方法 路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的
openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线
逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend
标签编译通过；前端零改动。

已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与
改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。

feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由

server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达
/resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list
端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增
HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；
并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，
新增路由表导出 harness，固化 256 条 (方法 路径) 基线供插件化对拍。
上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录
前缀输出差异并在同步后提醒确认补丁是否仍在。

验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。

docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口

feat(cordis): agent/relay/flared 落地为内核驱动插件

三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver
（自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入
Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、
openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式
runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。

入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持
-config 旗标、默认路径、退出码与启动/停止日志不变。

验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份
与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置
均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。

refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层

backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared}
加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与
repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；
被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。
同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与
2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon
入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。

验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且
232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制
strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0
时报错（防门禁静默失效）；前端零改动。

feat(cordis): 落地 backend/share 共享层与上游同步脚本

跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包
移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向
引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖
backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。

go build 通过，go test ./... exit 0（142 包 ok），前端零改动。

refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核

按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare
全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持
Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至
backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。

行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API
操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，
待 P4 挂载上游路由后再纳入 plugins/。

style: 修正模块路径改写导致的 import 分组排序漂移

refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare

对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与
平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend，
swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费，
Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。

行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，
四进制产物正常，前端零改动。

chore(cordis): 落地改造计划与 schema/路由基线

新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序
（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与
版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单
与 foundation 实施计划。

docs(cordis): add OpenFlare Cordis 架构改造设计

明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件
(server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose
迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，
确保已部署库不重跑历史、不丢数据。

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

@@ -0,0 +1,154 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cache provides in-process upload access-control caches.
+package cache
+
+import (
+	"Wavelet/pkg/logger"
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"gorm.io/gorm"
+
+	uploadstorage "Wavelet/plugins/domain/upload/storage"
+)
+
+const fileAccessInvalidationChannel = "upload:file_access_invalidation"
+
+var (
+	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 cache := shared.GetCache(ctx); cache != nil {
+		_ = cache.Invalidate(ctx, fileAccessInvalidationChannel)
+	}
+	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{} {
+	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
+	}
+
+	types, err := fetchFileAccessWhitelist(ctx)
+	if err != nil {
+		logger.ErrorF(ctx, "[Upload] 读取公开访问白名单失败: %v", err)
+		if fileAccessWhitelistTypes != nil {
+			// A previously loaded list is still the best answer; keep it until its
+			// TTL rather than narrowing access because one read failed.
+			fileAccessWhitelistValid = true
+			fileAccessWhitelistCheckedAt = time.Now()
+			return fileAccessWhitelistTypes
+		}
+		// Nothing cached yet: serve the restricted default but stay invalid so the
+		// next request retries instead of pinning it for the whole TTL.
+		return fallbackFileAccessWhitelist()
+	}
+
+	fileAccessWhitelistTypes = types
+	fileAccessWhitelistValid = true
+	fileAccessWhitelistCheckedAt = time.Now()
+	return types
+}
+
+// fallbackFileAccessWhitelist is the restricted default used when nothing better is known.
+func fallbackFileAccessWhitelist() map[string]struct{} {
+	return map[string]struct{}{strings.ToLower(shared.DefaultPublicUploadType): {}}
+}
+
+func fetchFileAccessWhitelist(ctx context.Context) (map[string]struct{}, error) {
+	whitelist, err := parseFileAccessWhitelist(ctx)
+	if err != nil {
+		return nil, err
+	}
+	types := make(map[string]struct{}, len(whitelist))
+	for _, item := range whitelist {
+		types[strings.ToLower(item)] = struct{}{}
+	}
+	return types, nil
+}
+
+// parseFileAccessWhitelist reads the configured public access types.
+//
+// A missing row or an empty value is a real answer and yields the default; only a
+// read that actually fails is reported as an error, so a database outage is no
+// longer mistaken for "the admin never configured a whitelist".
+func parseFileAccessWhitelist(ctx context.Context) ([]string, error) {
+	var sc struct{ Value string }
+	db := shared.GetDB(ctx)
+	if db == nil {
+		return nil, errors.New("database not available")
+	}
+	if err := db.Table("w_system_configs").Where("key = ?", "file_access_whitelist").First(&sc).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return []string{shared.DefaultPublicUploadType}, nil
+		}
+		return nil, fmt.Errorf("read file_access_whitelist: %w", err)
+	}
+	if sc.Value == "" {
+		return []string{shared.DefaultPublicUploadType}, nil
+	}
+
+	var whitelist []string
+	if err := json.Unmarshal([]byte(sc.Value), &whitelist); err == nil && len(whitelist) > 0 {
+		return whitelist, nil
+	}
+
+	whitelist = parseCommaSeparatedWhitelist(sc.Value)
+	if len(whitelist) == 0 {
+		return []string{shared.DefaultPublicUploadType}, nil
+	}
+	return whitelist, nil
+}
+
+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_retry_test.go

@@ -0,0 +1,56 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+	"testing"
+)
+
+// configRow mirrors just enough of w_system_configs to rebuild it mid-test.
+type configRow struct {
+	Key   string `gorm:"primaryKey;size:64"`
+	Value string `gorm:"type:text;not null"`
+	Type  string `gorm:"size:32;not null"`
+}
+
+// TableName returns the system config table.
+func (configRow) TableName() string { return "w_system_configs" }
+
+// TestWhitelistReadFailureIsNotCachedAsConfigured pins the defect where a failed
+// read of the public access whitelist was discarded and the resulting restricted
+// default was then cached as though the admin had configured it, narrowing access
+// for the whole TTL with nothing to retry it sooner.
+func TestWhitelistReadFailureIsNotCachedAsConfigured(t *testing.T) {
+	db, cleanup := shared.SetupTestEnv(t)
+	defer cleanup()
+	ResetAccessCaches()
+	t.Cleanup(ResetAccessCaches)
+
+	ctx := context.Background()
+
+	// Make the config unreadable, then take one sample through the failure path.
+	if err := db.Exec("DROP TABLE w_system_configs").Error; err != nil {
+		t.Fatalf("drop config table: %v", err)
+	}
+	if IsFilePublic(ctx, "document") {
+		t.Fatal(`document reported public while the whitelist cannot be read`)
+	}
+
+	// Restore a configured whitelist that includes document.
+	if err := db.AutoMigrate(&configRow{}); err != nil {
+		t.Fatalf("recreate config table: %v", err)
+	}
+	row := configRow{Key: "file_access_whitelist", Value: `["avatar","document"]`, Type: "system"}
+	if err := db.Create(&row).Error; err != nil {
+		t.Fatalf("seed whitelist: %v", err)
+	}
+
+	// A failed first read must not have been cached as a real answer, so this call
+	// has to re-read and see the configured list.
+	if !IsFilePublic(ctx, "document") {
+		t.Error("whitelist stayed pinned to the default after a read failure; the failed lookup must be retried")
+	}
+}

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

@@ -0,0 +1,88 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+	"testing"
+	"time"
+
+	uploadstorage "Wavelet/plugins/domain/upload/storage"
+)
+
+func TestLoadMigrationAccessStateCachesResult(t *testing.T) {
+	_, cleanup := shared.SetupTestEnv(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 := shared.SetupTestEnv(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 := shared.SetupTestEnv(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 := shared.SetupTestEnv(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,131 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"Wavelet/pkg/cache/ram"
+	"Wavelet/plugins/domain/upload/models"
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+	"fmt"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+const (
+	uploadMetaRedisCacheTTL    = 30 * 60 // seconds
+	uploadMetaRAMMaximumSize   = 4096
+	uploadMetaInvalidationChan = "upload:meta_invalidation"
+)
+
+var uploadMetaRAM = ram.MustNew[uint64, models.Upload](ram.Options{MaximumSize: uploadMetaRAMMaximumSize})
+
+func uploadMetaRedisKey(id uint64) string {
+	return fmt.Sprintf("upload:meta:%d", id)
+}
+
+func cloneUpload(u models.Upload) models.Upload {
+	return u
+}
+
+// PublishUploadMetaInvalidation broadcasts upload metadata cache eviction.
+func PublishUploadMetaInvalidation(ctx context.Context, id uint64) {
+	if cache := shared.GetCache(ctx); cache != nil {
+		_ = cache.Invalidate(ctx, uploadMetaInvalidationChan)
+	}
+	EvictUploadMetaLocal(id)
+}
+
+// GetUploadByID loads upload metadata from RAM, Redis, or the database.
+func GetUploadByID(ctx context.Context, id uint64) (models.Upload, error) {
+	if id == 0 {
+		return models.Upload{}, gorm.ErrRecordNotFound
+	}
+
+	// 1. RAM L1 Cache
+	if u, ok := uploadMetaRAM.GetIfPresent(id); ok {
+		return cloneUpload(u), nil
+	}
+
+	key := uploadMetaRedisKey(id)
+
+	// 2. Redis L2 Cache
+	if cache := shared.GetCache(ctx); cache != nil {
+		var u models.Upload
+		if err := cache.Get(ctx, key, &u); err == nil {
+			uploadMetaRAM.Set(id, u)
+			return cloneUpload(u), nil
+		}
+	}
+
+	// 3. Database L3 Source of Truth
+	var upload models.Upload
+	db := shared.GetDB(ctx)
+	if db == nil {
+		return models.Upload{}, gorm.ErrRecordNotFound
+	}
+	if err := db.
+		Where("id = ? AND status != ?", id, models.UploadStatusDeleted).
+		First(&upload).Error; err != nil {
+		return models.Upload{}, err
+	}
+
+	SetUploadMeta(ctx, upload)
+	return cloneUpload(upload), nil
+}
+
+// SetUploadMeta populates RAM and Redis caches with the provided upload metadata.
+func SetUploadMeta(ctx context.Context, u models.Upload) {
+	if u.ID == 0 {
+		return
+	}
+	cloned := cloneUpload(u)
+	uploadMetaRAM.Set(u.ID, cloned)
+
+	if cache := shared.GetCache(ctx); cache != nil {
+		_ = cache.Set(ctx, uploadMetaRedisKey(u.ID), cloned, uploadMetaRedisCacheTTL*time.Second)
+	}
+}
+
+// EvictUploadMeta evicts an upload metadata record from RAM, Redis, and broadcasts eviction.
+func EvictUploadMeta(ctx context.Context, id uint64) {
+	EvictUploadMetaLocal(id)
+
+	if cache := shared.GetCache(ctx); cache != nil {
+		_ = cache.Delete(ctx, uploadMetaRedisKey(id))
+	}
+
+	PublishUploadMetaInvalidation(ctx, id)
+}
+
+// EvictUploadMetaLocal removes upload metadata from the local process RAM cache only.
+func EvictUploadMetaLocal(id uint64) {
+	uploadMetaRAM.Invalidate(id)
+}
+
+// ResetUploadMetaCache cleans up local memory cache.
+func ResetUploadMetaCache() {
+	uploadMetaRAM.InvalidateAll()
+}
+
+// ResetUploadMetaCacheForTest clears the in-memory cache for tests.
+func ResetUploadMetaCacheForTest() {
+	ResetUploadMetaCache()
+}
+
+// SetUploadMetaCache is a backward-compatible alias for SetUploadMeta.
+func SetUploadMetaCache(ctx context.Context, u *models.Upload) {
+	if u != nil {
+		SetUploadMeta(ctx, *u)
+	}
+}
+
+// InvalidateUploadMetaCache is an alias for EvictUploadMeta.
+func InvalidateUploadMetaCache(ctx context.Context, id uint64) {
+	EvictUploadMeta(ctx, id)
+}
+
+// StopUploadMetaCacheListener stops listener for tests.
+func StopUploadMetaCacheListener() {}

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

@@ -0,0 +1,160 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"Wavelet/pkg/testhelper"
+	"Wavelet/plugins/domain/upload/models"
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func init() {
+	testhelper.RegisterCleanup(func() {
+		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 := shared.SetupTestEnv(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)
+	}
+
+	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 := shared.SetupTestEnv(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 := shared.SetupTestEnv(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)
+
+	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 TestGetUploadByIDSkipsDeletedUploads(t *testing.T) {
+	dbConn, cleanup := shared.SetupTestEnv(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")
+	}
+}