feat(log): decouple log storage from ClickHouse with switchable logstore

- New internal/repository/logstore abstraction: exported domain interfaces
  (AccessLogStore/ObservabilityStore/UserAccessLogStore/StatusStore),
  config-driven provider (Active/Build/Migrating/SetConfigReader), GORM
  implementation for PostgreSQL/SQLite (incl. hourly rollups computed in
  real time, migration listers, PG partition maintenance), and a ClickHouse
  wrapper preserving the native batch path; repository facade delegates to
  logstore; import-lint test enforces apps never import analyticsrepo.
- ClickHouse is now optional: the log DB is either the main DB (postgres
  when database.enabled, else sqlite) or clickhouse; boot validation +
  first-run seed; log_database / log_db_migration are protected keys.
- New user task 切换日志数据库 (of_log_db_switch): freeze log writes,
  drain batch writers, copy all 6 raw log tables by id (preserving IDs)
  with target-partition pre-creation for PG, flip log_database on success,
  clear the freeze flag on failure.
- Per-store retention (log_retention_days_*) with expiry cleanup folded
  into the daily system_cleanup task; legacy database_auto_cleanup_* and
  of_database_auto_cleanup decommissioned.
- goose migrations: 6 log tables in PG (2 monthly-partitioned) + SQLite,
  retention config seeds, schedule cleanup; GET
  /api/v1/admin/status/log-database endpoint; frontend retention settings,
  switch-task UI and status badge; changelog and docs updated.

docs(plan): log database decoupling implementation plan

docs(design): log database decoupling design (ClickHouse optional)

internal/apps/admin/logs/routers.go

@@ -14,10 +14,9 @@ import (
 	"time"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/admin"
-	"github.com/Rain-kl/Wavelet/internal/infra/config"
-	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
+	analyticsmodel "github.com/Rain-kl/Wavelet/internal/model/analytics"
 	"github.com/Rain-kl/Wavelet/internal/repository"
-	analyticsrepo "github.com/Rain-kl/Wavelet/internal/repository/analytics"
+	"github.com/Rain-kl/Wavelet/internal/repository/logstore"
 	"github.com/Rain-kl/Wavelet/pkg/logger"
 	"github.com/gin-gonic/gin"
 
@@ -158,8 +157,8 @@ type accessLogsResponse struct {
 	List  []accessLogItem `json:"list"`
 }
 
-func buildAccessLogFilter(ctx context.Context, c *gin.Context) (analyticsrepo.AccessLogFilter, error) {
-	filter := analyticsrepo.AccessLogFilter{}
+func buildAccessLogFilter(ctx context.Context, c *gin.Context) (analyticsmodel.AccessLogFilter, error) {
+	filter := analyticsmodel.AccessLogFilter{}
 
 	username := c.Query("username")
 	if username != "" {
@@ -227,7 +226,7 @@ func enrichAccessLogsWithUsers(ctx context.Context, list []accessLogItem) {
 
 // GetAccessLogs 获取 ClickHouse 异步采集的访问日志
 // @Summary 获取用户访问日志
-// @Description 分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）
+// @Description 分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限，日志存储未启用时报错）
 // @Tags admin
 // @Produce json
 // @Security SessionCookie
@@ -244,8 +243,9 @@ func enrichAccessLogsWithUsers(ctx context.Context, list []accessLogItem) {
 // @Router /api/v1/admin/logs/access [get]
 func GetAccessLogs(c *gin.Context) {
 	ctx := c.Request.Context()
-	if !config.Config.ClickHouse.Enabled || !db.ChConnReady() {
-		response.AbortWithError(c, http.StatusBadRequest, "ClickHouse 存储服务未启用，无法检索访问日志")
+	store, err := logstore.Active(ctx)
+	if err != nil {
+		response.AbortWithError(c, http.StatusBadRequest, "日志存储未启用，无法检索访问日志")
 		return
 	}
 
@@ -271,7 +271,7 @@ func GetAccessLogs(c *gin.Context) {
 		return
 	}
 
-	logs, total, err := analyticsrepo.ListAccessLogs(ctx, filter, page, pageSize)
+	logs, total, err := store.UserAccessLogs.List(ctx, filter, page, pageSize)
 	if err != nil {
 		response.AbortWithError(c, http.StatusInternalServerError, err.Error())
 		return
@@ -333,25 +333,26 @@ type logsAnalyticsResponse struct {
 
 // GetLogsAnalytics 获取 ClickHouse 访问日志图表聚合指标
 // @Summary 获取访问日志分析数据
-// @Description 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）
+// @Description 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，日志存储未启用时报错）
 // @Tags admin
 // @Produce json
 // @Security SessionCookie
 // @Success 200 {object} response.Any{data=logs.logsAnalyticsResponse} "分析统计数据"
-// @Failure 400 {object} response.Any "ClickHouse 未启用"
+// @Failure 400 {object} response.Any "日志存储未启用"
 // @Failure 401 {object} response.Any "未登录"
 // @Failure 403 {object} response.Any "无管理员权限"
 // @Router /api/v1/admin/logs/analytics [get]
 func GetLogsAnalytics(c *gin.Context) {
 	ctx := c.Request.Context()
-	if !config.Config.ClickHouse.Enabled || !db.ChConnReady() {
-		response.AbortWithError(c, http.StatusBadRequest, "ClickHouse 存储服务未启用，无法获取分析数据")
+	store, err := logstore.Active(ctx)
+	if err != nil {
+		response.AbortWithError(c, http.StatusBadRequest, "日志存储未启用，无法获取分析数据")
 		return
 	}
 
 	startTime := time.Now().AddDate(0, 0, -(analyticsDays - 1)).Truncate(hoursInDay * time.Hour)
 
-	trendPoints, err := analyticsrepo.GetDailyTrend(ctx, analyticsDays)
+	trendPoints, err := store.UserAccessLogs.GetDailyTrend(ctx, analyticsDays)
 	if err != nil {
 		response.AbortWithError(c, http.StatusInternalServerError, "查询访问趋势失败: "+err.Error())
 		return
@@ -364,7 +365,7 @@ func GetLogsAnalytics(c *gin.Context) {
 		}
 	}
 
-	browserPoints, err := analyticsrepo.GetBrowserDistribution(ctx, startTime)
+	browserPoints, err := store.UserAccessLogs.GetBrowserDistribution(ctx, startTime)
 	if err != nil {
 		response.AbortWithError(c, http.StatusInternalServerError, "查询浏览器分布失败: "+err.Error())
 		return
@@ -377,7 +378,7 @@ func GetLogsAnalytics(c *gin.Context) {
 		}
 	}
 
-	topUserPoints, err := analyticsrepo.GetTopActiveUsers(ctx, startTime, topActiveLimit)
+	topUserPoints, err := store.UserAccessLogs.GetTopActiveUsers(ctx, startTime, topActiveLimit)
 	if err != nil {
 		response.AbortWithError(c, http.StatusInternalServerError, "查询活跃用户失败: "+err.Error())
 		return

internal/apps/admin/status/clickhouse.go

@@ -4,43 +4,117 @@
 package status
 
 import (
+	"context"
 	"net/http"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/openflare/chwriter"
 	"github.com/Rain-kl/Wavelet/internal/apps/risk_control"
 	"github.com/Rain-kl/Wavelet/internal/infra/config"
-	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
 	"github.com/Rain-kl/Wavelet/internal/infra/persistence/batchwriter"
-	analyticsrepo "github.com/Rain-kl/Wavelet/internal/repository/analytics"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	analyticsmodel "github.com/Rain-kl/Wavelet/internal/model/analytics"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/repository/logstore"
 	"github.com/Rain-kl/Wavelet/internal/shared/response"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
 	"github.com/gin-gonic/gin"
 )
 
-// GetClickHouseStatus returns ClickHouse operational metrics for administrators.
-// @Summary 获取 ClickHouse 运行指标
-// @Description 返回 ClickHouse parts、mutation、async_insert 队列及进程内 batch writer 指标，需要管理员权限
+// 日志库名取值（与 model 配置值、logstore provider 分支保持一致）。
+const (
+	logDBNamePostgres   = "postgres"
+	logDBNameSQLite     = "sqlite"
+	logDBNameClickHouse = "clickhouse"
+)
+
+// defaultLogRetentionDays 日志保留天数配置缺失时的兜底值（与 seed 默认一致）。
+const defaultLogRetentionDays = 90
+
+// LogDatabaseStatus 日志库状态。
+type LogDatabaseStatus struct {
+	ActiveDatabase   string                                     `json:"active_database"`
+	Migration        string                                     `json:"migration"` // idle | migrating
+	RetentionDays    map[string]int                             `json:"retention_days"`
+	AvailableTargets []string                                   `json:"available_targets"`
+	ClickHouse       *analyticsmodel.ClickHouseOperationalStats `json:"clickhouse,omitempty"`
+}
+
+// GetLogDatabaseStatus 返回当前日志库状态。
+// @Summary 获取日志数据库状态
+// @Description 返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限
 // @Tags admin
 // @Produce json
 // @Security SessionCookie
-// @Success 200 {object} response.Any{data=analyticsrepo.ClickHouseOperationalStats} "获取成功"
-// @Failure 400 {object} response.Any "ClickHouse 未启用"
+// @Success 200 {object} response.Any{data=status.LogDatabaseStatus} "获取成功"
 // @Failure 401 {object} response.Any "未登录"
 // @Failure 403 {object} response.Any "无管理员权限"
 // @Failure 500 {object} response.Any "内部错误"
-// @Router /api/v1/admin/status/clickhouse [get]
-func GetClickHouseStatus(c *gin.Context) {
-	if !config.Config.ClickHouse.Enabled || !db.ChConnReady() {
-		response.AbortWithError(c, http.StatusBadRequest, "ClickHouse 存储服务未启用")
+// @Router /api/v1/admin/status/log-database [get]
+func GetLogDatabaseStatus(c *gin.Context) {
+	ctx := c.Request.Context()
+	store, err := logstore.Active(ctx)
+	if err != nil {
+		response.AbortInternal(c, "日志存储初始化失败")
 		return
 	}
 
-	stats, err := analyticsrepo.GetClickHouseOperationalStats(c.Request.Context())
+	// 分支判定复用同一 store 实例的 ActiveDatabase，避免与 Active 解析之间出现 TOCTOU。
+	activeDB, err := store.Status.ActiveDatabase(ctx)
 	if err != nil {
-		response.AbortInternal(c, "获取 ClickHouse 运行指标失败")
+		response.AbortInternal(c, "获取日志库状态失败")
 		return
 	}
-	stats.BatchWriters = collectBatchWriterStats()
-	c.JSON(http.StatusOK, response.OK(stats))
+	migration := "idle"
+	if logstore.Migrating(ctx) {
+		migration = "migrating"
+	}
+
+	out := LogDatabaseStatus{
+		ActiveDatabase: activeDB,
+		Migration:      migration,
+		RetentionDays: map[string]int{
+			logDBNamePostgres:   retentionOr(ctx, model.ConfigKeyLogRetentionDaysPostgres),
+			logDBNameSQLite:     retentionOr(ctx, model.ConfigKeyLogRetentionDaysSQLite),
+			logDBNameClickHouse: retentionOr(ctx, model.ConfigKeyLogRetentionDaysClickHouse),
+		},
+		AvailableTargets: availableTargets(activeDB),
+	}
+
+	if activeDB == logDBNameClickHouse {
+		stats, err := store.Status.ClickHouseOperationalStats(ctx)
+		if err != nil {
+			logger.ErrorF(ctx, "获取 ClickHouse 运行指标失败: %v", err)
+		} else {
+			stats.BatchWriters = collectBatchWriterStats()
+			out.ClickHouse = stats
+		}
+	}
+
+	c.JSON(http.StatusOK, response.OK(out))
+}
+
+// retentionOr 读取保留天数配置，缺失或非法时返回默认值。
+func retentionOr(ctx context.Context, key string) int {
+	v, err := repository.GetIntByKey(ctx, key)
+	if err != nil {
+		return defaultLogRetentionDays
+	}
+	return v
+}
+
+// availableTargets 返回当前日志主库的合法迁移目标（复用调用方已解析的 active）：
+// 当前为 clickhouse 时目标为主库（postgres/sqlite 按启动配置）；当前为主库时目标为 clickhouse（仅 CH 启用时）。
+func availableTargets(active string) []string {
+	if active == logDBNameClickHouse {
+		if config.Config.Database.Enabled {
+			return []string{logDBNamePostgres}
+		}
+		return []string{logDBNameSQLite}
+	}
+	if config.Config.ClickHouse.Enabled {
+		return []string{logDBNameClickHouse}
+	}
+	return []string{}
 }
 
 func collectBatchWriterStats() []batchwriter.Stats {

internal/apps/admin/status/clickhouse_test.go

@@ -0,0 +1,115 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package status
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/infra/config"
+	"github.com/Rain-kl/Wavelet/internal/repository/logstore"
+	"github.com/gin-gonic/gin"
+)
+
+// restoreConfig 恢复测试中临时修改的全局配置。
+func restoreConfig(t *testing.T) {
+	t.Helper()
+	dbEnabled := config.Config.Database.Enabled
+	chEnabled := config.Config.ClickHouse.Enabled
+	t.Cleanup(func() {
+		config.Config.Database.Enabled = dbEnabled
+		config.Config.ClickHouse.Enabled = chEnabled
+	})
+}
+
+func TestAvailableTargets(t *testing.T) {
+	restoreConfig(t)
+	logstore.ResetForTest()
+	t.Cleanup(logstore.ResetForTest)
+
+	// 当前 clickhouse → 主库（postgres/sqlite 按启动配置）。
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == "log_database" {
+			return logDBNameClickHouse, nil
+		}
+		return "", nil
+	})
+	config.Config.Database.Enabled = true
+	config.Config.ClickHouse.Enabled = true
+	if got := availableTargets(logDBNameClickHouse); !reflect.DeepEqual(got, []string{logDBNamePostgres}) {
+		t.Fatalf("clickhouse active + postgres main: got %v, want [postgres]", got)
+	}
+
+	config.Config.Database.Enabled = false
+	if got := availableTargets(logDBNameClickHouse); !reflect.DeepEqual(got, []string{logDBNameSQLite}) {
+		t.Fatalf("clickhouse active + sqlite main: got %v, want [sqlite]", got)
+	}
+
+	// 当前主库 → clickhouse（CH 启用时）。
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == "log_database" {
+			return logDBNamePostgres, nil
+		}
+		return "", nil
+	})
+	config.Config.ClickHouse.Enabled = true
+	if got := availableTargets(logDBNamePostgres); !reflect.DeepEqual(got, []string{logDBNameClickHouse}) {
+		t.Fatalf("postgres active: got %v, want [clickhouse]", got)
+	}
+
+	// CH 禁用时排除 clickhouse。
+	config.Config.ClickHouse.Enabled = false
+	if got := availableTargets(logDBNamePostgres); len(got) != 0 {
+		t.Fatalf("CH disabled: got %v, want empty", got)
+	}
+}
+
+// TestGetLogDatabaseStatusSmoke 覆盖 handler 的 CH 激活分支（无需 DB/CH 连接）。
+func TestGetLogDatabaseStatusSmoke(t *testing.T) {
+	restoreConfig(t)
+	logstore.ResetForTest()
+	t.Cleanup(logstore.ResetForTest)
+
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == "log_database" {
+			return logDBNameClickHouse, nil
+		}
+		return "", nil
+	})
+
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/admin/status/log-database", nil)
+
+	GetLogDatabaseStatus(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status code = %d, want 200; body=%s", w.Code, w.Body.String())
+	}
+	var resp struct {
+		Data LogDatabaseStatus `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal body: %v", err)
+	}
+	if resp.Data.ActiveDatabase != logDBNameClickHouse {
+		t.Fatalf("active_database = %q, want clickhouse", resp.Data.ActiveDatabase)
+	}
+	if resp.Data.Migration != "idle" {
+		t.Fatalf("migration = %q, want idle", resp.Data.Migration)
+	}
+	for _, key := range []string{logDBNamePostgres, logDBNameSQLite, logDBNameClickHouse} {
+		if got := resp.Data.RetentionDays[key]; got != defaultLogRetentionDays {
+			t.Fatalf("retention_days[%s] = %d, want default %d", key, got, defaultLogRetentionDays)
+		}
+	}
+	if got := resp.Data.AvailableTargets; !reflect.DeepEqual(got, []string{logDBNameSQLite}) {
+		t.Fatalf("available_targets = %v, want [sqlite] (test main DB disabled)", got)
+	}
+}

internal/apps/admin/system_config/logics.go

@@ -17,6 +17,11 @@ import (
 )
 
 func createSystemConfig(ctx context.Context, req CreateSystemConfigRequest) error {
+	// 防御：受保护 key（log_database / log_db_migration）仅允许内部写入，Handler 已拦截。
+	if isProtectedConfigKey(req.Key) {
+		return errors.New(protectedConfigKeyMessage)
+	}
+
 	exists, err := repository.SystemConfigExists(ctx, req.Key)
 	if err != nil {
 		return err

internal/apps/admin/system_config/routers.go

@@ -27,6 +27,17 @@ import (
 
 const maskedConfigValue = "******"
 
+// protectedConfigKeyMessage 命中受保护 key 时返回给管理员的业务错误文案。
+const protectedConfigKeyMessage = "该配置项由系统任务管理，禁止手动修改"
+
+// protectedConfigKeys 仅允许内部（迁移任务/bootstrap）写入的 key。
+var protectedConfigKeys = map[string]bool{
+	model.ConfigKeyLogDatabase:    true,
+	model.ConfigKeyLogDBMigration: true,
+}
+
+func isProtectedConfigKey(key string) bool { return protectedConfigKeys[key] }
+
 // CreateSystemConfigRequest 创建系统配置请求
 type CreateSystemConfigRequest struct {
 	Key         string `json:"key" binding:"required,max=64"`
@@ -64,11 +75,21 @@ func CreateSystemConfig(c *gin.Context) {
 		return
 	}
 
+	// 与 PUT 路径一致：log_database / log_db_migration 仅允许内部（迁移任务/bootstrap）写入。
+	if isProtectedConfigKey(req.Key) {
+		response.AbortBadRequest(c, protectedConfigKeyMessage)
+		return
+	}
+
 	if err := createSystemConfig(c.Request.Context(), req); err != nil {
 		if err.Error() == ConfigKeyExists {
 			response.AbortBadRequest(c, ConfigKeyExists)
 			return
 		}
+		if err.Error() == protectedConfigKeyMessage {
+			response.AbortBadRequest(c, protectedConfigKeyMessage)
+			return
+		}
 		response.AbortInternal(c, err.Error())
 		return
 	}
@@ -155,6 +176,10 @@ func UpdateSystemConfig(c *gin.Context) {
 	}
 
 	key := c.Param("key")
+	if isProtectedConfigKey(key) {
+		response.AbortBadRequest(c, protectedConfigKeyMessage)
+		return
+	}
 	if err := updateSystemConfig(c.Request.Context(), key, req); err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
 			response.AbortNotFound(c, SystemConfigNotFound)

internal/apps/admin/system_config/routers_test.go

@@ -27,7 +27,7 @@ import (
 	"github.com/Rain-kl/Wavelet/internal/shared/response"
 )
 
-const expectedDefaultConfigsCount = 34
+const expectedDefaultConfigsCount = 37
 
 func setupTestRouter(authUser *model.User) *gin.Engine {
 	r := testhelper.NewTestGinEngine()
@@ -168,8 +168,8 @@ func TestListSystemConfigs(t *testing.T) {
 		var configs []model.SystemConfig
 		_ = json.Unmarshal(dataBytes, &configs)
 
-		if len(configs) != 5 {
-			t.Errorf("expected 5 business configs, got %d: %v", len(configs), configs)
+		if len(configs) != 8 {
+			t.Errorf("expected 8 business configs, got %d: %v", len(configs), configs)
 		}
 	})
 }