fix(persistence): migrate all pkg/persistence imports to plugins/infra/database and plugins/infra/cache

- Replace db.DB(ctx) with database.DB(ctx) from plugins/infra/database
- Replace db.Redis/db.PrefixedKey/db.GetJSON/db.SetJSON with cachepkg.* from plugins/infra/cache
- Replace pkg/persistence/idgen with pkg/idgen (already exists)
- Replace pkg/persistence/batchwriter with pkg/batchwriter (already exists)
- Replace pkg/persistence/migrator with pkg/migrator (already exists)
- Replace pkg/persistence/logstore with plugins/domain/risk_control/logstore
- Delete defunct pkg/{persistence,cap,message_gateway,push,shared,task}
- Fix vet issues: db alias in domain_test.go, driver_asynq_worker.TaskHandler reference
- Update Makefile architecture guard
- Update docs and skill references
- Update go.mod: gorilla/sessions promotion to direct dependency

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"
+)

plugins/infra/cache/plugin.go

@@ -14,7 +14,6 @@ import (
 	"github.com/Rain-kl/Wavelet/core"
 	"github.com/Rain-kl/Wavelet/core/contracts"
 	"github.com/Rain-kl/Wavelet/pkg/cache/ram"
-	"github.com/Rain-kl/Wavelet/pkg/persistence"
 	"github.com/Rain-kl/Wavelet/pkg/util"
 	"github.com/redis/go-redis/v9"
 )
@@ -82,7 +81,7 @@ func (p *Plugin) Name() string {
 func (p *Plugin) Apply(ctx *core.Context) error {
 	redisClient := p.redisClient
 	if redisClient == nil {
-		redisClient = db.Redis
+		redisClient = Redis
 	}
 
 	ramCache, err := ram.New[string, ramEntry](ram.Options{
@@ -128,7 +127,7 @@ func (s *cacheServiceImpl) prefixedKey(key string) string {
 	if s.keyPrefix != "" {
 		return s.keyPrefix + key
 	}
-	return db.PrefixedKey(key)
+	return PrefixedKey(key)
 }
 
 func (s *cacheServiceImpl) startPubSubListener() {

plugins/infra/cache/redis.go

@@ -0,0 +1,198 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/pkg/config"
+	"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
+)
+
+func init() {
+	cfg := config.Config.Redis
+
+	if !cfg.Enabled {
+		log.Println("[Redis] is disabled, skipping Redis initialization")
+		return
+	}
+
+	if cfg.ClusterMode {
+		// Cluster 模式
+		Redis = 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 != "" {
+			client := redis.NewFailoverClient(options.Failover())
+			// FailoverOptions 暂不暴露该配置，在首次建连前写入客户端选项。
+			client.Options().MaintNotificationsConfig = redisMaintNotificationsConfig(cfg.MaintNotifications)
+			Redis = client
+			log.Println("[Redis] initialized in Sentinel mode")
+		} else {
+			Redis = redis.NewUniversalClient(options)
+			log.Println("[Redis] initialized in Standalone mode")
+		}
+	}
+
+	// OpenTelemetry 追踪（UniversalClient 兼容）
+	if err := redisotel.InstrumentTracing(
+		Redis,
+		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 {
+		log.Fatalf("[Redis] failed to init trace: %v\n", err)
+	}
+
+	// 测试连接
+	_, err := Redis.Ping(context.Background()).Result()
+	if err != nil {
+		log.Fatalf("[Redis] failed to connect to redis: %v\n", err)
+	}
+}
+
+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 := config.Config.Redis.KeyPrefix
+	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
+}

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)
+			}
+		})
+	}
+}

plugins/infra/database/clickhouse.go

@@ -0,0 +1,155 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package database 提供数据库连接与基础设施
+package database
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/ClickHouse/clickhouse-go/v2"
+	"github.com/ClickHouse/clickhouse-go/v2/lib/driver"
+	"github.com/Rain-kl/Wavelet/pkg/config"
+	"go.opentelemetry.io/otel/attribute"
+	clickhouseDriver "gorm.io/driver/clickhouse"
+	"gorm.io/gorm"
+	"gorm.io/plugin/opentelemetry/tracing"
+)
+
+const (
+	clickhouseMaxExecTime       = 60 // ClickHouse 最大执行时间（秒）
+	clickhouseReadTimeoutFactor = 2  // ReadTimeout 为 DialTimeout 的倍数
+)
+
+var (
+	// ChConn ClickHouse 原生连接实例，用于批量写入
+	ChConn driver.Conn
+
+	chDB *gorm.DB
+)
+
+func init() {
+	if !config.Config.ClickHouse.Enabled {
+		return
+	}
+
+	cfg := config.Config.ClickHouse
+	if cfg.Database == "" {
+		log.Fatalf("[ClickHouse] database name is required (expected: wavelet)\n")
+	}
+
+	opts := buildClickHouseOptions()
+
+	var err error
+	ChConn, err = clickhouse.Open(opts)
+	if err != nil {
+		log.Fatalf("[ClickHouse] init connection failed: %v\n", err)
+	}
+
+	if err = ChConn.Ping(context.Background()); err != nil {
+		log.Fatalf("[ClickHouse] ping failed: %v\n", err)
+	}
+
+	chDB, err = gorm.Open(clickhouseDriver.New(clickhouseDriver.Config{
+		DSN: buildClickHouseDSN(),
+	}), &gorm.Config{
+		SkipDefaultTransaction: true,
+	})
+	if err != nil {
+		log.Fatalf("[ClickHouse] init gorm connection failed: %v\n", err)
+	}
+
+	if err = chDB.Use(
+		tracing.NewPlugin(
+			tracing.WithoutMetrics(),
+			tracing.WithAttributes(
+				attribute.String("db.instance", cfg.Database),
+				attribute.String("db.system", "ClickHouse"),
+			),
+		),
+	); err != nil {
+		log.Fatalf("[ClickHouse] init trace failed: %v\n", err)
+	}
+
+	sqlDB, err := chDB.DB()
+	if err != nil {
+		log.Fatalf("[ClickHouse] load sql db failed: %v\n", err)
+	}
+
+	sqlDB.SetMaxIdleConns(cfg.MaxIdleConn)
+	sqlDB.SetMaxOpenConns(cfg.MaxOpenConn)
+	sqlDB.SetConnMaxLifetime(time.Duration(cfg.ConnMaxLifetime) * time.Second)
+
+	log.Println("[ClickHouse] connection established successfully")
+}
+
+func buildClickHouseOptions() *clickhouse.Options {
+	cfg := config.Config.ClickHouse
+
+	return &clickhouse.Options{
+		Addr: cfg.Hosts,
+		Auth: clickhouse.Auth{
+			Database: cfg.Database,
+			Username: cfg.Username,
+			Password: cfg.Password,
+		},
+		Settings: clickhouse.Settings{
+			"max_execution_time": clickhouseMaxExecTime,
+		},
+		Compression: &clickhouse.Compression{
+			Method: clickhouse.CompressionLZ4,
+		},
+		DialTimeout:     time.Duration(cfg.DialTimeout) * time.Second,
+		MaxOpenConns:    cfg.MaxOpenConn,
+		MaxIdleConns:    cfg.MaxIdleConn,
+		ConnMaxLifetime: time.Duration(cfg.ConnMaxLifetime) * time.Second,
+		ReadTimeout:     time.Duration(cfg.DialTimeout*clickhouseReadTimeoutFactor) * time.Second,
+		BlockBufferSize: cfg.BlockBufferSize,
+	}
+}
+
+func buildClickHouseDSN() string {
+	cfg := config.Config.ClickHouse
+
+	chURL := &url.URL{
+		Scheme: "clickhouse",
+		Host:   strings.Join(cfg.Hosts, ","),
+		Path:   "/" + cfg.Database,
+	}
+	if cfg.Username != "" || cfg.Password != "" {
+		chURL.User = url.UserPassword(cfg.Username, cfg.Password)
+	}
+
+	query := chURL.Query()
+	query.Set("dial_timeout", fmt.Sprintf("%ds", cfg.DialTimeout))
+	query.Set("read_timeout", fmt.Sprintf("%ds", cfg.DialTimeout*clickhouseReadTimeoutFactor))
+	query.Set("max_execution_time", strconv.Itoa(clickhouseMaxExecTime))
+	chURL.RawQuery = query.Encode()
+
+	return chURL.String()
+}
+
+// ChDB returns a context-aware GORM ClickHouse instance.
+func ChDB(ctx context.Context) *gorm.DB {
+	if chDB == nil {
+		return nil
+	}
+	return chDB.WithContext(ctx)
+}
+
+// SetChDBForTest sets the package-level ClickHouse GORM instance for testing.
+func SetChDBForTest(d *gorm.DB) {
+	chDB = d
+}
+
+// SetChConnForTest sets the package-level native ClickHouse connection for testing.
+func SetChConnForTest(c driver.Conn) {
+	ChConn = c
+}

plugins/infra/database/plugin.go

@@ -9,7 +9,6 @@ import (
 
 	"github.com/Rain-kl/Wavelet/core"
 	"github.com/Rain-kl/Wavelet/core/contracts"
-	"github.com/Rain-kl/Wavelet/pkg/persistence"
 	"gorm.io/gorm"
 )
 
@@ -61,7 +60,7 @@ func (p *Plugin) Name() string {
 func (p *Plugin) Apply(ctx *core.Context) error {
 	targetDB := p.db
 	if targetDB == nil {
-		targetDB = db.DB(context.Background())
+		targetDB = DB(context.Background())
 	}
 
 	svc := &dbServiceImpl{
@@ -82,14 +81,14 @@ func (s *dbServiceImpl) GORM() *gorm.DB {
 	if s.primary != nil {
 		return s.primary
 	}
-	return db.DB(context.Background())
+	return DB(context.Background())
 }
 
 func (s *dbServiceImpl) DB(ctx context.Context) *gorm.DB {
 	if s.primary != nil {
 		return s.primary.WithContext(ctx)
 	}
-	return db.DB(ctx)
+	return DB(ctx)
 }
 
 func (s *dbServiceImpl) Named(name string) *gorm.DB {

plugins/infra/database/postgres.go

@@ -0,0 +1,216 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package database
+
+import (
+	"context"
+	"log"
+	"net"
+	"net/url"
+	"strconv"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/pkg/config"
+	"github.com/glebarez/sqlite"
+	"go.opentelemetry.io/otel/attribute"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/plugin/dbresolver"
+	"gorm.io/plugin/opentelemetry/tracing"
+)
+
+var (
+	db *gorm.DB
+)
+
+func init() {
+	if !config.Config.Database.Enabled {
+		// PostgreSQL 禁用，使用 SQLite
+		initSQLite()
+		return
+	}
+
+	initPostgres()
+}
+
+// initSQLite 初始化 SQLite 数据库（PostgreSQL 禁用时的后备方案）
+func initSQLite() {
+	sqlitePath := config.Config.Database.SQLitePath
+	if sqlitePath == "" {
+		sqlitePath = "./data/wavelet.db"
+	}
+
+	var err error
+	db, err = gorm.Open(sqlite.Open(sqlitePath), &gorm.Config{
+		DisableForeignKeyConstraintWhenMigrating: true,
+		Logger: &gormZapLogger{
+			logLevel:                  parseLogLevel(config.Config.Database.LogLevel),
+			slowThreshold:             config.Config.Database.SlowThreshold,
+			ignoreRecordNotFoundError: config.Config.App.IsProduction(),
+		},
+	})
+	if err != nil {
+		log.Fatalf("[SQLite] init connection failed: %v\n", err)
+	}
+
+	// Trace 注入
+	if err = db.Use(
+		tracing.NewPlugin(
+			tracing.WithoutMetrics(),
+			tracing.WithAttributes(
+				attribute.String("db.instance", sqlitePath),
+				attribute.String("db.system", "SQLite"),
+			),
+		),
+	); err != nil {
+		log.Fatalf("[SQLite] init trace failed: %v\n", err)
+	}
+
+	log.Printf("[SQLite] initialized (path: %s)\n", sqlitePath)
+}
+
+// initPostgres 初始化 PostgreSQL 数据库
+func initPostgres() {
+	var err error
+	dbConfig := config.Config.Database
+
+	// 构建主库 DSN 并连接
+	primaryDSN := buildDSN(dbConfig.Host, dbConfig.Port, dbConfig.Username, dbConfig.Password)
+
+	pgConfig := postgres.Config{
+		DSN:                  primaryDSN,
+		PreferSimpleProtocol: dbConfig.PreferSimpleProtocol,
+	}
+
+	db, err = gorm.Open(postgres.New(pgConfig), &gorm.Config{
+		DisableForeignKeyConstraintWhenMigrating: true,
+		Logger: &gormZapLogger{
+			logLevel:                  parseLogLevel(config.Config.Database.LogLevel),
+			slowThreshold:             config.Config.Database.SlowThreshold,
+			ignoreRecordNotFoundError: config.Config.App.IsProduction(),
+		},
+	})
+	if err != nil {
+		log.Fatalf("[PostgreSQL] init connection failed: %v\n", err)
+	}
+
+	// Trace 注入
+	if err = db.Use(
+		tracing.NewPlugin(
+			tracing.WithoutMetrics(),
+			tracing.WithAttributes(
+				attribute.String("db.instance", dbConfig.Database),
+				attribute.String("db.ip", dbConfig.Host),
+				attribute.String("server.address", net.JoinHostPort(dbConfig.Host, strconv.Itoa(dbConfig.Port))),
+				attribute.String("db.system", "PostgreSQL"),
+			),
+		),
+	); err != nil {
+		log.Fatalf("[PostgreSQL] init trace failed: %v\n", err)
+	}
+
+	if len(dbConfig.Replicas) > 0 {
+		var replicaDialectors []gorm.Dialector
+		for _, replica := range dbConfig.Replicas {
+			username := replica.Username
+			if username == "" {
+				username = dbConfig.Username
+			}
+			password := replica.Password
+			if password == "" {
+				password = dbConfig.Password
+			}
+			replicaDSN := buildDSN(replica.Host, replica.Port, username, password)
+			replicaDialectors = append(replicaDialectors, postgres.New(postgres.Config{
+				DSN:                  replicaDSN,
+				PreferSimpleProtocol: dbConfig.PreferSimpleProtocol,
+			}))
+		}
+
+		resolver := dbresolver.Register(dbresolver.Config{
+			Replicas: replicaDialectors,
+			Policy:   dbresolver.RandomPolicy{},
+		})
+
+		resolver.SetMaxIdleConns(dbConfig.MaxIdleConn).
+			SetMaxOpenConns(dbConfig.MaxOpenConn).
+			SetConnMaxLifetime(time.Duration(dbConfig.ConnMaxLifetime) * time.Second).
+			SetConnMaxIdleTime(time.Duration(dbConfig.ConnMaxIdleTime) * time.Second)
+
+		if err = db.Use(resolver); err != nil {
+			log.Fatalf("[PostgreSQL] init dbresolver failed: %v\n", err)
+		}
+		log.Printf("[PostgreSQL] initialized in Primary-Replica mode (%d replicas)\n", len(dbConfig.Replicas))
+	} else {
+		log.Println("[PostgreSQL] initialized in Standalone mode")
+	}
+
+	// 获取通用数据库对象设置连接池
+	sqlDB, err := db.DB()
+	if err != nil {
+		log.Fatalf("[PostgreSQL] load sql db failed: %v\n", err)
+	}
+
+	sqlDB.SetMaxIdleConns(dbConfig.MaxIdleConn)
+	sqlDB.SetMaxOpenConns(dbConfig.MaxOpenConn)
+	sqlDB.SetConnMaxLifetime(time.Duration(dbConfig.ConnMaxLifetime) * time.Second)
+	sqlDB.SetConnMaxIdleTime(time.Duration(dbConfig.ConnMaxIdleTime) * time.Second)
+}
+
+// buildDSN 构建 PostgreSQL DSN
+func buildDSN(host string, port int, username, password string) string {
+	cfg := config.Config.Database
+	pqURL := &url.URL{
+		Scheme: "postgres",
+		Host:   net.JoinHostPort(host, strconv.Itoa(port)),
+		Path:   cfg.Database,
+	}
+	if username != "" {
+		pqURL.User = url.UserPassword(username, password)
+	}
+
+	query := pqURL.Query()
+	sslMode := cfg.SSLMode
+	if sslMode == "" {
+		sslMode = "disable"
+	}
+	query.Set("sslmode", sslMode)
+	if cfg.ApplicationName != "" {
+		query.Set("application_name", cfg.ApplicationName)
+	}
+	if cfg.SearchPath != "" {
+		query.Set("search_path", cfg.SearchPath)
+	}
+	if cfg.DefaultQueryExecMode != "" {
+		query.Set("default_query_exec_mode", cfg.DefaultQueryExecMode)
+	}
+	if cfg.StatementCacheCapacity > 0 {
+		query.Set("statement_cache_capacity", strconv.Itoa(cfg.StatementCacheCapacity))
+	}
+
+	rawQuery := query.Encode()
+	if cfg.TimeZone != "" {
+		if rawQuery != "" {
+			rawQuery += "&"
+		}
+		rawQuery += "TimeZone=" + cfg.TimeZone
+	}
+	pqURL.RawQuery = rawQuery
+
+	return pqURL.String()
+}
+
+// DB 返回带上下文追踪的 GORM 数据库实例
+func DB(ctx context.Context) *gorm.DB {
+	if db == nil {
+		return nil
+	}
+	return db.WithContext(ctx)
+}
+
+// SetDB sets the package-level database instance for testing.
+func SetDB(d *gorm.DB) {
+	db = d
+}

plugins/infra/database/postgres_logger.go

@@ -0,0 +1,91 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package database
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"gorm.io/gorm"
+	gormLogger "gorm.io/gorm/logger"
+)
+
+// nanoToMilli 纳秒转毫秒的除数
+const nanoToMilli = 1e6
+
+type gormZapLogger struct {
+	logLevel                  gormLogger.LogLevel
+	ignoreRecordNotFoundError bool
+	slowThreshold             time.Duration
+}
+
+func (l *gormZapLogger) LogMode(level gormLogger.LogLevel) gormLogger.Interface {
+	clone := *l
+	clone.logLevel = level
+	return &clone
+}
+
+func (l *gormZapLogger) Info(ctx context.Context, fmt string, args ...interface{}) {
+	if l.logLevel >= gormLogger.Info {
+		logger.InfoF(ctx, fmt, args...)
+	}
+}
+
+func (l *gormZapLogger) Warn(ctx context.Context, fmt string, args ...interface{}) {
+	if l.logLevel >= gormLogger.Warn {
+		logger.WarnF(ctx, fmt, args...)
+	}
+}
+
+func (l *gormZapLogger) Error(ctx context.Context, fmt string, args ...interface{}) {
+	if l.logLevel >= gormLogger.Error {
+		logger.ErrorF(ctx, fmt, args...)
+	}
+}
+
+func (l *gormZapLogger) Trace(ctx context.Context, begin time.Time, fc func() (sql string, rowsAffected int64), err error) {
+	elapsed := time.Since(begin)
+	switch {
+	case err != nil && l.logLevel >= gormLogger.Error && (!errors.Is(err, gorm.ErrRecordNotFound) || !l.ignoreRecordNotFoundError):
+		_, rows := fc()
+		logger.ErrorF(ctx, "database query failed: %s [%.3fms] [rows:%v]", err, float64(elapsed.Nanoseconds())/nanoToMilli, formatRows(rows))
+	case elapsed > l.slowThreshold && l.slowThreshold != 0 && l.logLevel >= gormLogger.Warn:
+		_, rows := fc()
+		slowLog := fmt.Sprintf("SLOW SQL >= %v", l.slowThreshold)
+		logger.WarnF(ctx, "%s [%.3fms] [rows:%v]", slowLog, float64(elapsed.Nanoseconds())/nanoToMilli, formatRows(rows))
+	case l.logLevel == gormLogger.Info:
+		sql, rows := fc()
+		logger.DebugF(ctx, "[%.3fms] [rows:%v] %s", float64(elapsed.Nanoseconds())/nanoToMilli, formatRows(rows), sql)
+	}
+}
+
+func formatRows(rows int64) interface{} {
+	if rows == -1 {
+		return "-"
+	}
+	return rows
+}
+
+func parseLogLevel(level string) gormLogger.LogLevel {
+	level = strings.ToLower(level)
+	switch level {
+	case "silent":
+		return gormLogger.Silent
+	case "error":
+		return gormLogger.Error
+	case "warn":
+		return gormLogger.Warn
+	case "info":
+		return gormLogger.Info
+	case "debug":
+		return gormLogger.Info
+	default:
+		return gormLogger.Info
+	}
+}

plugins/infra/database/postgres_logger_test.go

@@ -0,0 +1,39 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package database
+
+import (
+	"testing"
+
+	gormLogger "gorm.io/gorm/logger"
+)
+
+func TestParseLogLevel(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name            string
+		configuredLevel string
+		want            gormLogger.LogLevel
+	}{
+		{
+			name:            "debug enables SQL trace processing",
+			configuredLevel: "debug",
+			want:            gormLogger.Info,
+		},
+		{
+			name:            "development preserves configured level",
+			configuredLevel: "warn",
+			want:            gormLogger.Warn,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := parseLogLevel(tt.configuredLevel); got != tt.want {
+				t.Fatalf("parseLogLevel() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

plugins/infra/storage/diskcache/cache.go

@@ -11,7 +11,7 @@ import (
 	"time"
 
 	pkgcache "github.com/Rain-kl/Wavelet/pkg/cache/disk"
-	db "github.com/Rain-kl/Wavelet/pkg/persistence"
+	database "github.com/Rain-kl/Wavelet/plugins/infra/database"
 )
 
 // Status represents the runtime cache statistics.
@@ -63,14 +63,14 @@ func New(basePath string) *DiskCache {
 // ReloadConfig reloads policies from database configs dynamically.
 func (c *DiskCache) ReloadConfig(ctx context.Context) {
 	// Ensure DB is initialized before querying
-	if db.DB(ctx) == nil {
+	if database.DB(ctx) == nil {
 		return
 	}
 
 	// 1. Max Size
 	maxSizeMB := int64(defaultMaxSizeMB)
 	var maxVal string
-	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "disk_cache_max_size_mb").Pluck("value", &maxVal).Error; err == nil && maxVal != "" {
+	if err := database.DB(ctx).Table("w_system_configs").Where("key = ?", "disk_cache_max_size_mb").Pluck("value", &maxVal).Error; err == nil && maxVal != "" {
 		if val, err := strconv.ParseInt(maxVal, 10, 64); err == nil && val > 0 {
 			maxSizeMB = val
 		}
@@ -79,7 +79,7 @@ func (c *DiskCache) ReloadConfig(ctx context.Context) {
 	// 2. Default TTL
 	ttlMinutes := int64(defaultTTLMinutes)
 	var ttlVal string
-	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "disk_cache_ttl_minutes").Pluck("value", &ttlVal).Error; err == nil && ttlVal != "" {
+	if err := database.DB(ctx).Table("w_system_configs").Where("key = ?", "disk_cache_ttl_minutes").Pluck("value", &ttlVal).Error; err == nil && ttlVal != "" {
 		if val, err := strconv.ParseInt(ttlVal, 10, 64); err == nil && val >= 0 {
 			ttlMinutes = val
 		}
@@ -88,7 +88,7 @@ func (c *DiskCache) ReloadConfig(ctx context.Context) {
 	// 3. LRU Enabled
 	lruEnabled := true
 	var lruVal string
-	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "disk_cache_lru_enabled").Pluck("value", &lruVal).Error; err == nil && lruVal != "" {
+	if err := database.DB(ctx).Table("w_system_configs").Where("key = ?", "disk_cache_lru_enabled").Pluck("value", &lruVal).Error; err == nil && lruVal != "" {
 		if val, err := strconv.ParseBool(lruVal); err == nil {
 			lruEnabled = val
 		}

plugins/infra/storage/diskcache/cache_test.go

@@ -8,7 +8,7 @@ import (
 	"os"
 	"testing"
 
-	db "github.com/Rain-kl/Wavelet/pkg/persistence"
+	cache "github.com/Rain-kl/Wavelet/plugins/infra/cache"
 	"github.com/Rain-kl/Wavelet/pkg/testhelper"
 )
 
@@ -29,8 +29,8 @@ func TestDiskCacheReloadConfig(t *testing.T) {
 	dbConn.Table("w_system_configs").Where("key = ?", "disk_cache_lru_enabled").Update("value", "false")
 
 	// Invalidate Redis config cache to force DB reload
-	if db.Redis != nil {
-		db.Redis.Del(context.Background(), db.PrefixedKey("system_configs"))
+	if cache.Redis != nil {
+		cache.Redis.Del(context.Background(), cache.PrefixedKey("system_configs"))
 	}
 
 	// Reload config

plugins/infra/storage/objectstore/config.go

@@ -12,7 +12,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/Rain-kl/Wavelet/pkg/persistence"
+	database "github.com/Rain-kl/Wavelet/plugins/infra/database"
 
 	"gorm.io/gorm"
 )
@@ -110,7 +110,7 @@ func LoadConfig(ctx context.Context) (Config, error) {
 
 func loadConfigByKey(ctx context.Context, key string, fallback Config) (Config, error) {
 	var val string
-	err := db.DB(ctx).Table("w_system_configs").Where("key = ?", key).Pluck("value", &val).Error
+	err := database.DB(ctx).Table("w_system_configs").Where("key = ?", key).Pluck("value", &val).Error
 	if err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
 			return fallback, nil
@@ -182,7 +182,7 @@ func SaveActiveConfig(ctx context.Context, cfg Config) error {
 }
 
 func saveSystemConfig(ctx context.Context, key string, value any, description string) error {
-	err := db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+	err := database.DB(ctx).Transaction(func(tx *gorm.DB) error {
 		return upsertSystemConfig(ctx, tx, key, value, description)
 	})
 	if err == nil && key == "storage_config" {

plugins/infra/storage/objectstore/storage.go

@@ -13,7 +13,8 @@ import (
 	"sync"
 	"time"
 
-	"github.com/Rain-kl/Wavelet/pkg/persistence"
+	cache "github.com/Rain-kl/Wavelet/plugins/infra/cache"
+	database "github.com/Rain-kl/Wavelet/plugins/infra/database"
 
 	"github.com/Rain-kl/Wavelet/pkg/util"
 	"gorm.io/gorm"
@@ -76,14 +77,14 @@ func ResetCache() {
 
 // PublishCacheInvalidation broadcasts cache eviction to all nodes in the cluster via Redis.
 func PublishCacheInvalidation(ctx context.Context) {
-	if db.Redis != nil {
-		_ = db.Redis.Publish(ctx, ConfigInvalidationChannel, "reset").Err()
+	if cache.Redis != nil {
+		_ = cache.Redis.Publish(ctx, ConfigInvalidationChannel, "reset").Err()
 	}
 }
 
 // startPubSubListener starts the background subscriber for cache invalidations.
 func startPubSubListener() {
-	rdb := db.Redis
+	rdb := cache.Redis
 	if rdb == nil {
 		return
 	}
@@ -126,7 +127,7 @@ func Active(ctx context.Context) (Driver, Backend, error) {
 	}
 
 	var val string
-	err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "storage_config").Pluck("value", &val).Error
+	err := database.DB(ctx).Table("w_system_configs").Where("key = ?", "storage_config").Pluck("value", &val).Error
 	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
 		return "", nil, err
 	}

plugins/infra/storage/objectstore/storage_test.go

@@ -11,7 +11,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/Rain-kl/Wavelet/pkg/persistence"
+	cache "github.com/Rain-kl/Wavelet/plugins/infra/cache"
 	"github.com/alicebob/miniredis/v2"
 	"github.com/redis/go-redis/v9"
 )
@@ -91,11 +91,11 @@ func TestStorageCachePubSub(t *testing.T) {
 	})
 	defer rdb.Close()
 
-	// 3. Set db.Redis to our client
-	oldRedis := db.Redis
-	db.Redis = rdb
+	// 3. Set cache.Redis to our client
+	oldRedis := cache.Redis
+	cache.Redis = rdb
 	defer func() {
-		db.Redis = oldRedis
+		cache.Redis = oldRedis
 	}()
 
 	// Reset cache and set some cached config