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/infra/cache/config.go

@@ -0,0 +1,25 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+// RedisConfig declares the configuration read by the Redis cache provider.
+type RedisConfig struct {
+	Enabled            bool     `config:"enabled" env:"REDIS_ENABLED" default:"false" autoEnable:"REDIS_ADDR"`
+	Addrs              []string `config:"addrs" env:"REDIS_ADDR"`
+	Username           string   `config:"username" env:"REDIS_USERNAME"`
+	Password           string   `config:"password" env:"REDIS_PASSWORD" secret:"true"`
+	DB                 int      `config:"db" env:"REDIS_DB"`
+	ClusterMode        bool     `config:"cluster_mode" env:"REDIS_CLUSTER_MODE"`
+	MasterName         string   `config:"master_name" env:"REDIS_MASTER_NAME"`
+	KeyPrefix          string   `config:"key_prefix" env:"REDIS_KEY_PREFIX"`
+	PoolSize           int      `config:"pool_size" env:"REDIS_POOL_SIZE"`
+	MinIdleConn        int      `config:"min_idle_conn" env:"REDIS_MIN_IDLE_CONN"`
+	DialTimeout        int      `config:"dial_timeout" env:"REDIS_DIAL_TIMEOUT"`
+	ReadTimeout        int      `config:"read_timeout" env:"REDIS_READ_TIMEOUT"`
+	WriteTimeout       int      `config:"write_timeout" env:"REDIS_WRITE_TIMEOUT"`
+	MaxRetries         int      `config:"max_retries" env:"REDIS_MAX_RETRIES"`
+	PoolTimeout        int      `config:"pool_timeout" env:"REDIS_POOL_TIMEOUT"`
+	ConnMaxIdleTime    int      `config:"conn_max_idle_time" env:"REDIS_CONN_MAX_IDLE_TIME"`
+	MaintNotifications bool     `config:"maint_notifications" env:"REDIS_MAINT_NOTIFICATIONS" default:"false"`
+}

backend/plugins/infra/cache/errs.go

@@ -0,0 +1,12 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+const (
+	errRedisHashSetFailed    = "failed to set redis hash: %w"
+	errRedisHashDeleteFailed = "failed to delete redis hash field: %w"
+	errUnmarshalDataFailed   = "failed to unmarshal data: %w"
+	errMarshalDataFailed     = "failed to marshal data: %w"
+	errRedisKeySetFailed     = "failed to set redis key: %w"
+)

backend/plugins/infra/cache/plugin.go

@@ -0,0 +1,298 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cache provides the multi-tier caching infrastructure plugin for Cordis.
+package cache
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/cache/ram"
+	"Wavelet/pkg/util"
+	"context"
+	"encoding/json"
+	"errors"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	defaultRAMCapacity   = 10000
+	defaultPubSubChannel = "wavelet:cache:invalidation"
+)
+
+type ramEntry struct {
+	data     []byte
+	expireAt time.Time
+}
+
+// Option configures the cache plugin.
+type Option func(*Plugin)
+
+// WithRedis sets an explicit Redis client instance.
+func WithRedis(client redis.UniversalClient) Option {
+	return func(p *Plugin) {
+		p.redisClient = client
+	}
+}
+
+// WithKeyPrefix sets a custom Redis key prefix.
+func WithKeyPrefix(prefix string) Option {
+	return func(p *Plugin) {
+		p.keyPrefix = prefix
+	}
+}
+
+// WithRAMCapacity sets the maximum capacity for the L1 RAM cache.
+func WithRAMCapacity(capacity int) Option {
+	return func(p *Plugin) {
+		p.ramCapacity = capacity
+	}
+}
+
+// Plugin implements core.Plugin to provide contracts.CacheService.
+type Plugin struct {
+	redisClient redis.UniversalClient
+	keyPrefix   string
+	ramCapacity int
+}
+
+// New creates a new cache infrastructure plugin.
+func New(opts ...Option) *Plugin {
+	p := &Plugin{
+		ramCapacity: defaultRAMCapacity,
+	}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+	return p
+}
+
+// Name returns the unique identifier of the cache plugin.
+func (p *Plugin) Name() string {
+	return "cache"
+}
+
+// DeclareConfig declares the configuration bindings consumed by this plugin.
+func (p *Plugin) DeclareConfig() []core.ConfigBinding {
+	return []core.ConfigBinding{
+		{Prefix: "redis", Target: &RedisConfig{}},
+	}
+}
+
+// ConfigEnabled gates plugin activation based on whether Redis is enabled.
+func (p *Plugin) ConfigEnabled(view core.ConfigView) bool {
+	return view.Bool("redis.enabled", false)
+}
+
+// Apply mounts the multi-layer cache service into the Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	var cfg RedisConfig
+	if err := ctx.Config().Bind("redis", &cfg); err != nil {
+		return err
+	}
+
+	redisClient := p.redisClient
+	if redisClient == nil {
+		if Redis == nil {
+			var err error
+			redisClient, err = InitRedisWithConfig(cfg)
+			if err != nil {
+				return err
+			}
+		} else {
+			redisClient = Redis
+		}
+	}
+
+	ramCache, err := ram.New[string, ramEntry](ram.Options{
+		MaximumSize: p.ramCapacity,
+	})
+	if err != nil {
+		return err
+	}
+
+	svc := &cacheServiceImpl{
+		ramCache:      ramCache,
+		redisClient:   redisClient,
+		keyPrefix:     p.keyPrefix,
+		pubSubChannel: defaultPubSubChannel,
+		stopCh:        make(chan struct{}),
+	}
+
+	if redisClient != nil {
+		svc.startPubSubListener()
+		ctx.OnDispose(func() error {
+			svc.stopPubSubListener()
+			if p.redisClient == nil {
+				Redis = nil
+				if closeErr := redisClient.Close(); closeErr != nil && !errors.Is(closeErr, redis.ErrClosed) {
+					return closeErr
+				}
+			}
+			return nil
+		})
+	}
+
+	core.Provide[contracts.CacheService](ctx, svc)
+	return nil
+}
+
+type cacheServiceImpl struct {
+	ramCache      *ram.Cache[string, ramEntry]
+	redisClient   redis.UniversalClient
+	keyPrefix     string
+	pubSubChannel string
+
+	subOnce  sync.Once
+	stopOnce sync.Once
+	stopCh   chan struct{}
+	pubsub   *redis.PubSub
+}
+
+func (s *cacheServiceImpl) prefixedKey(key string) string {
+	if s.keyPrefix != "" {
+		return s.keyPrefix + key
+	}
+	return PrefixedKey(key)
+}
+
+func (s *cacheServiceImpl) startPubSubListener() {
+	if s.redisClient == nil {
+		return
+	}
+
+	s.subOnce.Do(func() {
+		pubsub := s.redisClient.Subscribe(context.Background(), s.pubSubChannel)
+		s.pubsub = pubsub
+
+		util.Go(func() {
+			ch := pubsub.Channel()
+			for {
+				select {
+				case <-s.stopCh:
+					return
+				case msg, ok := <-ch:
+					if !ok {
+						return
+					}
+					if msg != nil && msg.Payload != "" {
+						s.ramCache.Invalidate(msg.Payload)
+					}
+				}
+			}
+		})
+	})
+}
+
+func (s *cacheServiceImpl) stopPubSubListener() {
+	s.stopOnce.Do(func() {
+		close(s.stopCh)
+		if s.pubsub != nil {
+			_ = s.pubsub.Close()
+		}
+	})
+}
+
+func (s *cacheServiceImpl) Get(ctx context.Context, key string, target any) error {
+	// 1. Check L1 RAM cache
+	if entry, ok := s.ramCache.GetIfPresent(key); ok {
+		if entry.expireAt.IsZero() || time.Now().Before(entry.expireAt) {
+			return json.Unmarshal(entry.data, target)
+		}
+		// Expired in L1 RAM
+		s.ramCache.Invalidate(key)
+	}
+
+	// 2. Check L2 Redis cache
+	if s.redisClient != nil {
+		data, err := s.redisClient.Get(ctx, s.prefixedKey(key)).Bytes()
+		if err == nil {
+			// Backfill L1 RAM cache
+			s.ramCache.Set(key, ramEntry{
+				data: data,
+			})
+			return json.Unmarshal(data, target)
+		} else if !errors.Is(err, redis.Nil) {
+			return err
+		}
+	}
+
+	return contracts.ErrCacheMiss
+}
+
+func (s *cacheServiceImpl) Set(ctx context.Context, key string, value any, ttl time.Duration) error {
+	data, err := json.Marshal(value)
+	if err != nil {
+		return err
+	}
+
+	var expireAt time.Time
+	if ttl > 0 {
+		expireAt = time.Now().Add(ttl)
+	}
+
+	// 1. Write L1 RAM cache
+	s.ramCache.Set(key, ramEntry{
+		data:     data,
+		expireAt: expireAt,
+	})
+
+	// 2. Write L2 Redis cache
+	if s.redisClient != nil {
+		if err := s.redisClient.Set(ctx, s.prefixedKey(key), data, ttl).Err(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (s *cacheServiceImpl) Delete(ctx context.Context, key string) error {
+	// 1. Evict L1 RAM
+	s.ramCache.Invalidate(key)
+
+	// 2. Evict L2 Redis and broadcast invalidation to cluster nodes
+	if s.redisClient != nil {
+		if err := s.redisClient.Del(ctx, s.prefixedKey(key)).Err(); err != nil && !errors.Is(err, redis.Nil) {
+			return err
+		}
+		_ = s.redisClient.Publish(ctx, s.pubSubChannel, key).Err()
+	}
+
+	return nil
+}
+
+func (s *cacheServiceImpl) Invalidate(ctx context.Context, key string) error {
+	return s.Delete(ctx, key)
+}
+
+func (s *cacheServiceImpl) GetOrSet(ctx context.Context, key string, target any, ttl time.Duration, loader func() (any, error)) error {
+	err := s.Get(ctx, key, target)
+	if err == nil {
+		return nil
+	}
+	if !errors.Is(err, contracts.ErrCacheMiss) {
+		return err
+	}
+
+	val, err := loader()
+	if err != nil {
+		return err
+	}
+
+	if err := s.Set(ctx, key, val, ttl); err != nil {
+		return err
+	}
+
+	data, err := json.Marshal(val)
+	if err != nil {
+		return err
+	}
+
+	return json.Unmarshal(data, target)
+}

backend/plugins/infra/cache/plugin_test.go

@@ -0,0 +1,83 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/plugins/infra/cache"
+	"context"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCachePluginOperations(t *testing.T) {
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+	defer mr.Close()
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr: mr.Addr(),
+	})
+	defer func() { _ = rdb.Close() }()
+
+	p := cache.New(
+		cache.WithRedis(rdb),
+		cache.WithKeyPrefix("app:"),
+		cache.WithRAMCapacity(500),
+	)
+	ctx := core.NewContext(context.Background())
+	ctx.Config().SetSource(core.NewMapSource(map[string]any{
+		"redis.enabled": true,
+	}))
+	require.NoError(t, ctx.Config().Resolve())
+	require.NoError(t, p.Apply(ctx))
+
+	svc, err := core.Inject[contracts.CacheService](ctx)
+	require.NoError(t, err)
+
+	type Data struct {
+		Value string `json:"value"`
+	}
+
+	testCtx := context.Background()
+
+	// 1. ErrCacheMiss
+	var out Data
+	err = svc.Get(testCtx, "missing", &out)
+	assert.ErrorIs(t, err, contracts.ErrCacheMiss)
+
+	// 2. Set & Get
+	in := Data{Value: "hello"}
+	require.NoError(t, svc.Set(testCtx, "key1", in, 5*time.Minute))
+
+	require.NoError(t, svc.Get(testCtx, "key1", &out))
+	assert.Equal(t, "hello", out.Value)
+
+	// 3. GetOrSet
+	var target Data
+	err = svc.GetOrSet(testCtx, "key1", &target, time.Minute, func() (any, error) {
+		return Data{Value: "from_loader"}, nil
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "hello", target.Value)
+
+	err = svc.GetOrSet(testCtx, "key2", &target, time.Minute, func() (any, error) {
+		return Data{Value: "from_loader"}, nil
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "from_loader", target.Value)
+
+	// 4. Invalidate / Delete
+	require.NoError(t, svc.Invalidate(testCtx, "key1"))
+	err = svc.Get(testCtx, "key1", &out)
+	assert.ErrorIs(t, err, contracts.ErrCacheMiss)
+
+	require.NoError(t, ctx.Dispose())
+}

backend/plugins/infra/cache/redis.go

@@ -0,0 +1,223 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/extra/redisotel/v9"
+	"github.com/redis/go-redis/v9"
+	"github.com/redis/go-redis/v9/maintnotifications"
+	"go.opentelemetry.io/otel/attribute"
+)
+
+var (
+	// Redis 全局 Redis 客户端实例
+	Redis redis.UniversalClient
+
+	keyPrefixMu sync.RWMutex
+	keyPrefix   string
+)
+
+// SetKeyPrefix sets the package-level key prefix.
+func SetKeyPrefix(prefix string) {
+	keyPrefixMu.Lock()
+	defer keyPrefixMu.Unlock()
+	keyPrefix = prefix
+}
+
+// GetKeyPrefix returns the package-level key prefix.
+func GetKeyPrefix() string {
+	keyPrefixMu.RLock()
+	defer keyPrefixMu.RUnlock()
+	return keyPrefix
+}
+
+// InitRedisWithConfig initializes the Redis client using the provided RedisConfig.
+func InitRedisWithConfig(cfg RedisConfig) (redis.UniversalClient, error) {
+	if !cfg.Enabled {
+		log.Println("[Redis] is disabled, skipping Redis initialization")
+		return nil, nil
+	}
+
+	SetKeyPrefix(cfg.KeyPrefix)
+
+	var client redis.UniversalClient
+
+	if cfg.ClusterMode {
+		// Cluster 模式
+		client = redis.NewClusterClient(&redis.ClusterOptions{
+			Addrs:                    cfg.Addrs,
+			Username:                 cfg.Username,
+			Password:                 cfg.Password,
+			PoolSize:                 cfg.PoolSize,
+			MinIdleConns:             cfg.MinIdleConn,
+			DialTimeout:              time.Duration(cfg.DialTimeout) * time.Second,
+			ReadTimeout:              time.Duration(cfg.ReadTimeout) * time.Second,
+			WriteTimeout:             time.Duration(cfg.WriteTimeout) * time.Second,
+			MaxRetries:               cfg.MaxRetries,
+			PoolTimeout:              time.Duration(cfg.PoolTimeout) * time.Second,
+			ConnMaxIdleTime:          time.Duration(cfg.ConnMaxIdleTime) * time.Second,
+			MaintNotificationsConfig: redisMaintNotificationsConfig(cfg.MaintNotifications),
+		})
+		log.Println("[Redis] initialized in Cluster mode")
+	} else {
+		// Standalone 或 Sentinel 模式
+		options := &redis.UniversalOptions{
+			Addrs:                    cfg.Addrs,
+			MasterName:               cfg.MasterName, // 非空时启用 Sentinel
+			Username:                 cfg.Username,
+			Password:                 cfg.Password,
+			DB:                       cfg.DB,
+			PoolSize:                 cfg.PoolSize,
+			MinIdleConns:             cfg.MinIdleConn,
+			DialTimeout:              time.Duration(cfg.DialTimeout) * time.Second,
+			ReadTimeout:              time.Duration(cfg.ReadTimeout) * time.Second,
+			WriteTimeout:             time.Duration(cfg.WriteTimeout) * time.Second,
+			MaxRetries:               cfg.MaxRetries,
+			PoolTimeout:              time.Duration(cfg.PoolTimeout) * time.Second,
+			ConnMaxIdleTime:          time.Duration(cfg.ConnMaxIdleTime) * time.Second,
+			MaintNotificationsConfig: redisMaintNotificationsConfig(cfg.MaintNotifications),
+		}
+		if cfg.MasterName != "" {
+			failoverClient := redis.NewFailoverClient(options.Failover())
+			failoverClient.Options().MaintNotificationsConfig = redisMaintNotificationsConfig(cfg.MaintNotifications)
+			client = failoverClient
+			log.Println("[Redis] initialized in Sentinel mode")
+		} else {
+			client = redis.NewUniversalClient(options)
+			log.Println("[Redis] initialized in Standalone mode")
+		}
+	}
+
+	// OpenTelemetry 追踪（UniversalClient 兼容）
+	if err := redisotel.InstrumentTracing(
+		client,
+		redisotel.WithAttributes(
+			attribute.String("db.instance", fmt.Sprintf("%v", cfg.DB)),
+			attribute.String("db.ip", strings.Join(cfg.Addrs, ",")),
+			attribute.String("db.system", "Redis"),
+		),
+	); err != nil {
+		return nil, fmt.Errorf("redis: init trace: %w", err)
+	}
+
+	// 测试连接
+	if err := client.Ping(context.Background()).Err(); err != nil {
+		return nil, fmt.Errorf("redis: ping: %w", err)
+	}
+
+	Redis = client
+	return client, nil
+}
+
+// SetRedisClient 设置包级 Redis 客户端（主要用于测试）
+func SetRedisClient(client redis.UniversalClient) {
+	Redis = client
+}
+
+func redisMaintNotificationsConfig(enabled bool) *maintnotifications.Config {
+	mode := maintnotifications.ModeDisabled
+	if enabled {
+		mode = maintnotifications.ModeAuto
+	}
+	return &maintnotifications.Config{Mode: mode}
+}
+
+// PrefixedKey 返回带前缀的 Key
+func PrefixedKey(key string) string {
+	prefix := GetKeyPrefix()
+	if prefix == "" {
+		return key
+	}
+	return prefix + key
+}
+
+// HSetJSON 将泛型数据序列化为 JSON 并设置到 Redis Hash
+// ctx: 上下文
+// hashKey: Redis Hash key
+// fieldKey: Hash field key
+// data: 要存储的数据（泛型）
+func HSetJSON[T any](ctx context.Context, hashKey, fieldKey string, data T) error {
+	jsonData, err := json.Marshal(data)
+	if err != nil {
+		return err
+	}
+
+	if err := Redis.HSet(ctx, PrefixedKey(hashKey), fieldKey, jsonData).Err(); err != nil {
+		return fmt.Errorf(errRedisHashSetFailed, err)
+	}
+
+	return nil
+}
+
+// HDel removes one or more fields from a Redis Hash.
+func HDel(ctx context.Context, hashKey string, fieldKeys ...string) error {
+	if Redis == nil || len(fieldKeys) == 0 {
+		return nil
+	}
+	if err := Redis.HDel(ctx, PrefixedKey(hashKey), fieldKeys...).Err(); err != nil {
+		return fmt.Errorf(errRedisHashDeleteFailed, err)
+	}
+	return nil
+}
+
+// HGetJSON 从 Redis Hash 获取数据并反序列化为泛型类型
+// ctx: 上下文
+// hashKey: Redis Hash key
+// fieldKey: Hash field key
+// data: 用于接收数据的指针（泛型）
+func HGetJSON[T any](ctx context.Context, hashKey, fieldKey string, data *T) error {
+	val, err := Redis.HGet(ctx, PrefixedKey(hashKey), fieldKey).Result()
+	if err != nil {
+		return err
+	}
+
+	if err := json.Unmarshal([]byte(val), data); err != nil {
+		return fmt.Errorf(errUnmarshalDataFailed, err)
+	}
+
+	return nil
+}
+
+// GetJSON 从Redis获取数据并反序列化为泛型类型
+// ctx: 上下文
+// key: Redis key
+// data: 用于接收数据的指针（泛型）
+func GetJSON[T any](ctx context.Context, key string, data *T) error {
+	val, err := Redis.Get(ctx, PrefixedKey(key)).Bytes()
+	if err != nil {
+		return err
+	}
+
+	if err := json.Unmarshal(val, data); err != nil {
+		return fmt.Errorf(errUnmarshalDataFailed, err)
+	}
+
+	return nil
+}
+
+// SetJSON 将泛型数据序列化为JSON并设置到Redis
+// ctx: 上下文
+// key: Redis key
+// data: 要存储的数据（泛型）
+// expiration: 过期时间
+func SetJSON[T any](ctx context.Context, key string, data T, expiration time.Duration) error {
+	jsonData, err := json.Marshal(data)
+	if err != nil {
+		return fmt.Errorf(errMarshalDataFailed, err)
+	}
+
+	if err := Redis.Set(ctx, PrefixedKey(key), jsonData, expiration).Err(); err != nil {
+		return fmt.Errorf(errRedisKeySetFailed, err)
+	}
+
+	return nil
+}

backend/plugins/infra/cache/redis_test.go

@@ -0,0 +1,28 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"testing"
+
+	"github.com/redis/go-redis/v9/maintnotifications"
+)
+
+func TestRedisMaintNotificationsConfig(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		enabled bool
+		want    maintnotifications.Mode
+	}{
+		{name: "disabled by default", enabled: false, want: maintnotifications.ModeDisabled},
+		{name: "auto when enabled", enabled: true, want: maintnotifications.ModeAuto},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			cfg := redisMaintNotificationsConfig(test.enabled)
+			if cfg.Mode != test.want {
+				t.Fatalf("maintenance notifications mode = %v, want %v", cfg.Mode, test.want)
+			}
+		})
+	}
+}