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/openflare/tasks/database_cleanup.go

@@ -1,245 +0,0 @@
-// Copyright 2026 Arctel.net
-// SPDX-License-Identifier: Apache-2.0
-
-package tasks
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/Rain-kl/Wavelet/internal/model"
-	"github.com/Rain-kl/Wavelet/internal/repository"
-	analyticsrepo "github.com/Rain-kl/Wavelet/internal/repository/analytics"
-)
-
-const (
-	// DatabaseCleanupTargetAccessLogs is the API cleanup target for access logs.
-	DatabaseCleanupTargetAccessLogs = "node_access_logs"
-	// DatabaseCleanupTargetMetricSnapshots is the API cleanup target for metric snapshots.
-	DatabaseCleanupTargetMetricSnapshots = "node_metric_snapshots"
-	// DatabaseCleanupTargetEdgeHealth is the API cleanup target for OpenResty edge health (connections).
-	DatabaseCleanupTargetEdgeHealth = "node_edge_health"
-	// DatabaseCleanupTargetObsFrps is the API cleanup target for FRPS observations.
-	DatabaseCleanupTargetObsFrps = "node_obs_frps"
-	// DatabaseCleanupTargetObsFrpc is the API cleanup target for FRPC observations.
-	DatabaseCleanupTargetObsFrpc = "node_obs_frpc"
-)
-
-var databaseCleanupTargets = map[string]string{
-	DatabaseCleanupTargetAccessLogs:      "访问日志",
-	DatabaseCleanupTargetMetricSnapshots: "性能快照",
-	DatabaseCleanupTargetEdgeHealth:      "OpenResty 健康(连接)",
-	DatabaseCleanupTargetObsFrps:         "FRPS 观测",
-	DatabaseCleanupTargetObsFrpc:         "FRPC 观测",
-}
-
-// databaseCleanupTableTTLDays maps API targets to ClickHouse DDL TTL days.
-var databaseCleanupTableTTLDays = map[string]int{
-	DatabaseCleanupTargetAccessLogs:      analyticsrepo.TableTTLDaysNodeAccessLogs,
-	DatabaseCleanupTargetMetricSnapshots: analyticsrepo.TableTTLDaysNodeMetricSnapshots,
-	DatabaseCleanupTargetEdgeHealth:      analyticsrepo.TableTTLDaysNodeObs,
-	DatabaseCleanupTargetObsFrps:         analyticsrepo.TableTTLDaysNodeObs,
-	DatabaseCleanupTargetObsFrpc:         analyticsrepo.TableTTLDaysNodeObs,
-}
-
-// DatabaseCleanupInput describes a manual observability cleanup request.
-type DatabaseCleanupInput struct {
-	Target        string `json:"target"`
-	RetentionDays *int   `json:"retention_days"`
-}
-
-// DatabaseCleanupResult summarizes a manual observability cleanup run.
-//
-// Semantics:
-//   - delete_all / cleanup_mode=truncate: DeletedCount is hard-deleted rows (TRUNCATE).
-//   - retention path / cleanup_mode=ttl_materialize: DeletedCount is always 0;
-//     EligibleCount estimates rows past the table DDL TTL (not an arbitrary younger cutoff).
-type DatabaseCleanupResult struct {
-	Target        string     `json:"target"`
-	TargetLabel   string     `json:"target_label"`
-	DeletedCount  int64      `json:"deleted_count"`
-	EligibleCount int64      `json:"eligible_count,omitempty"`
-	CleanupMode   string     `json:"cleanup_mode,omitempty"`
-	TableTTLDays  int        `json:"table_ttl_days,omitempty"`
-	DeleteAll     bool       `json:"delete_all"`
-	RetentionDays *int       `json:"retention_days,omitempty"`
-	Cutoff        *time.Time `json:"cutoff,omitempty"`
-}
-
-// DatabaseAutoCleanupSummary summarizes a scheduled auto-cleanup run.
-type DatabaseAutoCleanupSummary struct {
-	RetentionDays int                     `json:"retention_days"`
-	ExecutedAt    time.Time               `json:"executed_at"`
-	Results       []DatabaseCleanupResult `json:"results"`
-}
-
-// TableTTLDaysForCleanupTarget returns the DDL TTL days for a cleanup target.
-func TableTTLDaysForCleanupTarget(target string) (int, bool) {
-	days, ok := databaseCleanupTableTTLDays[strings.TrimSpace(target)]
-	return days, ok
-}
-
-// CleanupDatabaseObservability deletes observability rows for the given target.
-//
-// When RetentionDays is nil, rows are hard-deleted via TRUNCATE.
-// When RetentionDays is set, ClickHouse only force-materializes the table TTL policy:
-// retention_days shorter than the table TTL is rejected (do not fake success).
-func CleanupDatabaseObservability(ctx context.Context, input DatabaseCleanupInput) (*DatabaseCleanupResult, error) {
-	target := strings.TrimSpace(input.Target)
-	targetLabel, ok := databaseCleanupTargets[target]
-	if !ok {
-		return nil, errors.New("unsupported cleanup target")
-	}
-	if input.RetentionDays != nil && *input.RetentionDays <= 0 {
-		return nil, errors.New("retention_days 必须为大于 0 的整数")
-	}
-
-	tableTTLDays := databaseCleanupTableTTLDays[target]
-	result := &DatabaseCleanupResult{
-		Target:       target,
-		TargetLabel:  targetLabel,
-		DeleteAll:    input.RetentionDays == nil,
-		TableTTLDays: tableTTLDays,
-	}
-
-	if input.RetentionDays == nil {
-		deleted, mode, err := deleteAllObservabilityRows(ctx, target)
-		if err != nil {
-			return nil, err
-		}
-		result.DeletedCount = deleted
-		result.EligibleCount = deleted
-		result.CleanupMode = mode
-		return result, nil
-	}
-
-	retentionDays := *input.RetentionDays
-	if retentionDays < tableTTLDays {
-		return nil, fmt.Errorf(
-			"retention_days 不能小于表 TTL（%d 天）；ClickHouse 仅支持按表 TTL 物化过期，更短保留请使用清空全部或调整 DDL",
-			tableTTLDays,
-		)
-	}
-
-	// MATERIALIZE TTL only enforces DDL policy; cutoff reported is the table TTL boundary.
-	tableCutoff := time.Now().UTC().Add(-time.Duration(tableTTLDays) * 24 * time.Hour)
-	eligible, mode, err := materializeObservabilityTableTTL(ctx, target)
-	if err != nil {
-		return nil, err
-	}
-	result.DeletedCount = 0
-	result.EligibleCount = eligible
-	result.CleanupMode = mode
-	result.RetentionDays = &retentionDays
-	result.Cutoff = &tableCutoff
-	return result, nil
-}
-
-// RunDatabaseAutoCleanupOnce runs retention-based cleanup for all observability targets.
-//
-// Configured retention shorter than a target's table TTL is clamped up to the table TTL
-// so the scheduled job can force-materialize each table policy without failing.
-func RunDatabaseAutoCleanupOnce(ctx context.Context, now time.Time) (*DatabaseAutoCleanupSummary, error) {
-	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyDatabaseAutoCleanupEnabled)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read database_auto_cleanup_enabled: %w", err)
-	}
-	if !enabled {
-		return nil, nil
-	}
-
-	retentionDays, err := repository.GetIntByKey(ctx, model.ConfigKeyDatabaseAutoCleanupRetentionDays)
-	if err != nil || retentionDays <= 0 {
-		// Use default value 30 if config read fails or value is invalid
-		retentionDays = 30
-	}
-
-	results := make([]DatabaseCleanupResult, 0, len(databaseCleanupTargets))
-	for _, target := range []string{
-		DatabaseCleanupTargetAccessLogs,
-		DatabaseCleanupTargetMetricSnapshots,
-		DatabaseCleanupTargetEdgeHealth,
-		DatabaseCleanupTargetObsFrps,
-		DatabaseCleanupTargetObsFrpc,
-	} {
-		effectiveDays := retentionDays
-		if ttl, ok := databaseCleanupTableTTLDays[target]; ok && effectiveDays < ttl {
-			effectiveDays = ttl
-		}
-		result, err := CleanupDatabaseObservability(ctx, DatabaseCleanupInput{
-			Target:        target,
-			RetentionDays: &effectiveDays,
-		})
-		if err != nil {
-			return nil, err
-		}
-		results = append(results, *result)
-	}
-
-	return &DatabaseAutoCleanupSummary{
-		RetentionDays: retentionDays,
-		ExecutedAt:    now.UTC(),
-		Results:       results,
-	}, nil
-}
-
-func deleteAllObservabilityRows(ctx context.Context, target string) (int64, string, error) {
-	var (
-		deleted int64
-		err     error
-	)
-	switch target {
-	case DatabaseCleanupTargetAccessLogs:
-		deleted, err = repository.DeleteAllOpenFlareAccessLogs(ctx)
-	case DatabaseCleanupTargetMetricSnapshots:
-		deleted, err = repository.DeleteAllOpenFlareMetricSnapshots(ctx)
-	case DatabaseCleanupTargetEdgeHealth:
-		deleted, err = repository.DeleteAllOpenFlareEdgeHealth(ctx)
-	case DatabaseCleanupTargetObsFrps:
-		deleted, err = repository.DeleteAllOpenFlareNodeObservationFrps(ctx)
-	case DatabaseCleanupTargetObsFrpc:
-		deleted, err = repository.DeleteAllOpenFlareNodeObservationFrpc(ctx)
-	default:
-		return 0, "", errors.New("unsupported cleanup target")
-	}
-	if err != nil {
-		return 0, "", err
-	}
-	return deleted, analyticsrepo.CleanupModeTruncate, nil
-}
-
-// materializeObservabilityTableTTL triggers table-TTL materialize (or memory-store delete-before
-// with the table TTL cutoff for tests) and returns the eligible/estimate row count.
-func materializeObservabilityTableTTL(ctx context.Context, target string) (int64, string, error) {
-	ttlDays, ok := databaseCleanupTableTTLDays[target]
-	if !ok {
-		return 0, "", errors.New("unsupported cleanup target")
-	}
-	cutoff := time.Now().UTC().Add(-time.Duration(ttlDays) * 24 * time.Hour)
-
-	var (
-		eligible int64
-		err      error
-	)
-	switch target {
-	case DatabaseCleanupTargetAccessLogs:
-		eligible, err = repository.DeleteOpenFlareAccessLogsBefore(ctx, cutoff)
-	case DatabaseCleanupTargetMetricSnapshots:
-		eligible, err = repository.DeleteOpenFlareMetricSnapshotsBefore(ctx, cutoff)
-	case DatabaseCleanupTargetEdgeHealth:
-		eligible, err = repository.DeleteOpenFlareEdgeHealthBefore(ctx, cutoff)
-	case DatabaseCleanupTargetObsFrps:
-		eligible, err = repository.DeleteOpenFlareNodeObservationFrpsBefore(ctx, cutoff)
-	case DatabaseCleanupTargetObsFrpc:
-		eligible, err = repository.DeleteOpenFlareNodeObservationFrpcBefore(ctx, cutoff)
-	default:
-		return 0, "", errors.New("unsupported cleanup target")
-	}
-	if err != nil {
-		return 0, "", err
-	}
-	return eligible, analyticsrepo.CleanupModeTTLMaterialize, nil
-}

internal/apps/openflare/tasks/database_cleanup_test.go

@@ -1,208 +0,0 @@
-// Copyright 2026 Arctel.net
-// SPDX-License-Identifier: Apache-2.0
-
-package tasks
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
-	"github.com/Rain-kl/Wavelet/internal/model"
-	"github.com/Rain-kl/Wavelet/internal/repository"
-	analyticsrepo "github.com/Rain-kl/Wavelet/internal/repository/analytics"
-	"github.com/glebarez/sqlite"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-	"gorm.io/gorm"
-)
-
-func setupDatabaseCleanupTestDB(t *testing.T) context.Context {
-	t.Helper()
-
-	sqliteDB, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
-		DisableForeignKeyConstraintWhenMigrating: true,
-	})
-	require.NoError(t, err)
-	require.NoError(t, sqliteDB.AutoMigrate(&model.SystemConfig{}))
-	db.SetDB(sqliteDB)
-	resetAccessLogStore := repository.SetAccessLogStoreForTest(repository.NewMemoryAccessLogStore())
-	resetObservabilityStore := repository.SetObservabilityStoreForTest(repository.NewMemoryObservabilityStore())
-	t.Cleanup(func() {
-		resetObservabilityStore()
-		resetAccessLogStore()
-		db.SetDB(nil)
-	})
-	return context.Background()
-}
-
-func TestCleanupDatabaseObservabilityRejectsRetentionShorterThanTableTTL(t *testing.T) {
-	ctx := setupDatabaseCleanupTestDB(t)
-
-	retentionDays := 7 // metric snapshots DDL TTL is 30 days
-	result, err := CleanupDatabaseObservability(ctx, DatabaseCleanupInput{
-		Target:        DatabaseCleanupTargetMetricSnapshots,
-		RetentionDays: &retentionDays,
-	})
-	require.Error(t, err)
-	assert.Nil(t, result)
-	assert.Contains(t, err.Error(), "不能小于表 TTL")
-	assert.Contains(t, err.Error(), "30")
-}
-
-func TestCleanupDatabaseObservabilityRejectsAccessLogRetentionShorterThanTableTTL(t *testing.T) {
-	ctx := setupDatabaseCleanupTestDB(t)
-
-	retentionDays := 30 // access logs DDL TTL is 90 days
-	result, err := CleanupDatabaseObservability(ctx, DatabaseCleanupInput{
-		Target:        DatabaseCleanupTargetAccessLogs,
-		RetentionDays: &retentionDays,
-	})
-	require.Error(t, err)
-	assert.Nil(t, result)
-	assert.Contains(t, err.Error(), "90")
-}
-
-func TestCleanupDatabaseObservabilityMaterializeDoesNotClaimHardDelete(t *testing.T) {
-	ctx := setupDatabaseCleanupTestDB(t)
-	now := time.Now().UTC()
-
-	// One row past metric table TTL (30d), one still inside the window.
-	require.NoError(t, repository.InsertOpenFlareMetricSnapshot(ctx, &model.OpenFlareMetricSnapshot{
-		NodeID:          "node-a",
-		CapturedAt:      now.Add(-40 * 24 * time.Hour),
-		CPUUsagePercent: 10,
-	}))
-	require.NoError(t, repository.InsertOpenFlareMetricSnapshot(ctx, &model.OpenFlareMetricSnapshot{
-		NodeID:          "node-a",
-		CapturedAt:      now.Add(-12 * time.Hour),
-		CPUUsagePercent: 20,
-	}))
-
-	retentionDays := analyticsrepo.TableTTLDaysNodeMetricSnapshots
-	result, err := CleanupDatabaseObservability(ctx, DatabaseCleanupInput{
-		Target:        DatabaseCleanupTargetMetricSnapshots,
-		RetentionDays: &retentionDays,
-	})
-	require.NoError(t, err)
-	assert.False(t, result.DeleteAll)
-	assert.Equal(t, analyticsrepo.CleanupModeTTLMaterialize, result.CleanupMode)
-	assert.Equal(t, analyticsrepo.TableTTLDaysNodeMetricSnapshots, result.TableTTLDays)
-	// MATERIALIZE is not a counted hard delete.
-	assert.Equal(t, int64(0), result.DeletedCount)
-	assert.Equal(t, int64(1), result.EligibleCount)
-	require.NotNil(t, result.Cutoff)
-	assert.True(t, result.Cutoff.Before(now.Add(-29*24*time.Hour)))
-
-	// Memory store applies the table-TTL cutoff for tests; only the recent row remains.
-	rows, err := repository.ListOpenFlareMetricSnapshotsSince(ctx, "", time.Time{}, 0)
-	require.NoError(t, err)
-	require.Len(t, rows, 1)
-	assert.Equal(t, float64(20), rows[0].CPUUsagePercent)
-}
-
-func TestCleanupDatabaseObservabilityDeletesAllRowsWhenRetentionMissing(t *testing.T) {
-	ctx := setupDatabaseCleanupTestDB(t)
-	now := time.Now().UTC()
-
-	require.NoError(t, repository.InsertOpenFlareAccessLogsBatch(ctx, []*model.OpenFlareAccessLog{
-		{
-			NodeID:     "node-a",
-			LoggedAt:   now.Add(-3 * time.Hour),
-			RemoteAddr: "203.0.113.1",
-			Host:       "example.com",
-			Path:       "/one",
-			StatusCode: 200,
-		},
-		{
-			NodeID:     "node-a",
-			LoggedAt:   now.Add(-2 * time.Hour),
-			RemoteAddr: "203.0.113.2",
-			Host:       "example.com",
-			Path:       "/two",
-			StatusCode: 502,
-		},
-	}))
-
-	result, err := CleanupDatabaseObservability(ctx, DatabaseCleanupInput{
-		Target: DatabaseCleanupTargetAccessLogs,
-	})
-	require.NoError(t, err)
-	assert.True(t, result.DeleteAll)
-	assert.Equal(t, analyticsrepo.CleanupModeTruncate, result.CleanupMode)
-	assert.Equal(t, int64(2), result.DeletedCount)
-	assert.Equal(t, int64(2), result.EligibleCount)
-
-	rows, err := repository.ListOpenFlareAccessLogs(ctx, model.OpenFlareAccessLogQuery{Page: 0, PageSize: 10})
-	require.NoError(t, err)
-	assert.Empty(t, rows)
-}
-
-func TestRunDatabaseAutoCleanupOnceClampsRetentionToTableTTL(t *testing.T) {
-	ctx := setupDatabaseCleanupTestDB(t)
-	now := time.Now().UTC()
-
-	// Access logs TTL=90d, metrics TTL=30d. Config retention=1 must clamp, not reject.
-	require.NoError(t, repository.InsertOpenFlareAccessLogsBatch(ctx, []*model.OpenFlareAccessLog{{
-		NodeID:     "node-a",
-		LoggedAt:   now.Add(-100 * 24 * time.Hour),
-		RemoteAddr: "203.0.113.10",
-		Host:       "example.com",
-		Path:       "/access",
-		StatusCode: 200,
-	}}))
-	require.NoError(t, repository.InsertOpenFlareMetricSnapshot(ctx, &model.OpenFlareMetricSnapshot{
-		NodeID:          "node-a",
-		CapturedAt:      now.Add(-40 * 24 * time.Hour),
-		CPUUsagePercent: 10,
-	}))
-	require.NoError(t, repository.InsertOpenFlareEdgeHealth(ctx, &model.OpenFlareEdgeHealth{
-		NodeID:      "node-a",
-		CapturedAt:  now.Add(-40 * 24 * time.Hour),
-		Status:      "healthy",
-		Connections: 2,
-	}))
-
-	require.NoError(t, repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyDatabaseAutoCleanupEnabled, "true"))
-	require.NoError(t, repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyDatabaseAutoCleanupRetentionDays, "1"))
-
-	summary, err := RunDatabaseAutoCleanupOnce(ctx, now)
-	require.NoError(t, err)
-	require.NotNil(t, summary)
-	require.Len(t, summary.Results, 5)
-	assert.Equal(t, 1, summary.RetentionDays)
-
-	for _, result := range summary.Results {
-		assert.Equal(t, analyticsrepo.CleanupModeTTLMaterialize, result.CleanupMode)
-		assert.Equal(t, int64(0), result.DeletedCount, "target %s must not claim hard delete", result.Target)
-		assert.GreaterOrEqual(t, result.TableTTLDays, 30)
-		require.NotNil(t, result.RetentionDays)
-		assert.GreaterOrEqual(t, *result.RetentionDays, result.TableTTLDays)
-	}
-
-	accessLogs, err := repository.ListOpenFlareAccessLogs(ctx, model.OpenFlareAccessLogQuery{Page: 0, PageSize: 10})
-	require.NoError(t, err)
-	assert.Empty(t, accessLogs)
-
-	metricSnapshots, err := repository.ListOpenFlareMetricSnapshotsSince(ctx, "", time.Time{}, 0)
-	require.NoError(t, err)
-	assert.Empty(t, metricSnapshots)
-
-	edgeHealth, err := repository.ListOpenFlareEdgeHealth(ctx, "", time.Time{}, 0)
-	require.NoError(t, err)
-	assert.Empty(t, edgeHealth)
-}
-
-func TestTableTTLDaysForCleanupTarget(t *testing.T) {
-	days, ok := TableTTLDaysForCleanupTarget(DatabaseCleanupTargetAccessLogs)
-	require.True(t, ok)
-	assert.Equal(t, 90, days)
-
-	days, ok = TableTTLDaysForCleanupTarget(DatabaseCleanupTargetMetricSnapshots)
-	require.True(t, ok)
-	assert.Equal(t, 30, days)
-
-	_, ok = TableTTLDaysForCleanupTarget("unknown")
-	assert.False(t, ok)
-}

internal/apps/openflare/tasks/log_db_switch.go

@@ -0,0 +1,401 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package tasks
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"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"
+	"github.com/Rain-kl/Wavelet/internal/infra/task"
+	"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/pkg/logger"
+)
+
+const copyBatchSize = 1000
+
+// 迁移目标库名常量（normalizeTarget 归一化后的取值）。
+const (
+	targetPostgres   = "postgres"
+	targetSQLite     = "sqlite"
+	targetClickHouse = "clickhouse"
+)
+
+type logDBSwitchPayload struct {
+	Target string `json:"target"`
+}
+
+// LogDBSwitchHandler 切换日志数据库任务处理器。
+type LogDBSwitchHandler struct{}
+
+// ValidatePayload 校验并规范化参数。
+func (h *LogDBSwitchHandler) ValidatePayload(payload []byte) ([]byte, error) {
+	var p logDBSwitchPayload
+	if err := json.Unmarshal(payload, &p); err != nil {
+		return nil, fmt.Errorf("参数解析失败: %w", err)
+	}
+	p.Target = normalizeTarget(p.Target)
+	if !validTarget(p.Target) {
+		return nil, fmt.Errorf("目标日志库不合法: %s", p.Target)
+	}
+	out, err := json.Marshal(p)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func normalizeTarget(v string) string {
+	switch v {
+	case targetPostgres, "postgresql":
+		return targetPostgres
+	case targetSQLite, "sqlite3":
+		return targetSQLite
+	case targetClickHouse, "ch":
+		return targetClickHouse
+	}
+	return v
+}
+
+func validTarget(v string) bool {
+	return v == targetPostgres || v == targetSQLite || v == targetClickHouse
+}
+
+// Execute 执行迁移。
+func (h *LogDBSwitchHandler) Execute(ctx context.Context, payload []byte) (*task.TaskResult, error) {
+	var p logDBSwitchPayload
+	if err := json.Unmarshal(payload, &p); err != nil {
+		return nil, fmt.Errorf("参数解析失败: %w", err)
+	}
+	p.Target = normalizeTarget(p.Target)
+	if err := validateSwitch(ctx, p.Target); err != nil {
+		return nil, err
+	}
+
+	source, err := currentLogDatabase(ctx)
+	if err != nil {
+		task.AppendLog(ctx, "读取日志主库失败: %v", err)
+		return nil, err
+	}
+	task.AppendLog(ctx, "开始切换日志数据库：%s -> %s", source, p.Target)
+
+	// 冻结前先排空在途批次（chwriter + 用户访问日志 writer），避免迁移期间积压丢失；
+	// 只等 flush 完成，不停止 writer（置位后由 ensureWritable 拒绝新写入）。
+	if err := drainLogWriters(ctx); err != nil {
+		return nil, fmt.Errorf("排空日志写入队列失败: %w", err)
+	}
+
+	if err := setMigrationFlag(ctx, "migrating"); err != nil {
+		return nil, err
+	}
+	// 失败也清除（SaveOrUpdateSystemConfig 会失效 RAM 缓存并广播），保持源库可写。
+	defer func() {
+		if err := setMigrationFlag(ctx, ""); err != nil {
+			logger.ErrorF(ctx, "清除日志迁移冻结标记失败: %v", err)
+		}
+	}()
+
+	src, err := logstore.Active(ctx)
+	if err != nil {
+		return nil, err
+	}
+	dst, err := buildTargetStore(ctx, p.Target)
+	if err != nil {
+		return nil, err
+	}
+
+	// 清空目标库日志表（幂等重试前提）。
+	if err := clearTargetLogTables(ctx, dst); err != nil {
+		return nil, err
+	}
+
+	// PG 目标：按源库时间范围预建分区，避免历史数据复制报 "no partition of relation found"。
+	if err := ensureTargetPartitions(ctx, src, dst, p.Target); err != nil {
+		return nil, err
+	}
+
+	// 逐表复制（6 张日志表）。
+	if err := copyAccessLogs(ctx, src, dst); err != nil {
+		return nil, err
+	}
+	if err := copyUserAccessLogs(ctx, src, dst); err != nil {
+		return nil, err
+	}
+	if err := copyObservability(ctx, src, dst); err != nil {
+		return nil, err
+	}
+
+	// 翻转主库标记。
+	if err := flipLogDatabase(ctx, p.Target); err != nil {
+		return nil, err
+	}
+	task.AppendLog(ctx, "日志数据库已切换为 %s，写入恢复", p.Target)
+	return &task.TaskResult{Message: fmt.Sprintf("日志数据库已从 %s 切换为 %s", source, p.Target)}, nil
+}
+
+func validateSwitch(ctx context.Context, target string) error {
+	source, err := currentLogDatabase(ctx)
+	if err != nil {
+		return err
+	}
+	if source == target {
+		return errors.New("目标日志库与当前日志库相同，无需迁移")
+	}
+	switch target {
+	case "clickhouse":
+		if !config.Config.ClickHouse.Enabled {
+			return errors.New("ClickHouse 未启用，无法迁移到 ClickHouse")
+		}
+	case "postgres":
+		if !config.Config.Database.Enabled {
+			return errors.New("PostgreSQL 未启用（当前主库为 SQLite），无法迁移到 PostgreSQL")
+		}
+	case "sqlite":
+		if config.Config.Database.Enabled {
+			return errors.New("当前主库为 PostgreSQL，日志库不能设置为 SQLite")
+		}
+	}
+	return nil
+}
+
+func currentLogDatabase(ctx context.Context) (string, error) {
+	cfg, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyLogDatabase)
+	if err != nil {
+		return "", fmt.Errorf("读取日志主库失败: %w", err)
+	}
+	if cfg.Value == "" {
+		return "", errors.New("日志主库配置为空")
+	}
+	return cfg.Value, nil
+}
+
+// drainLogWriters 等待 chwriter（节点访问日志 + 可观测 4 表）与 risk_control
+// （用户访问日志）的在途批次全部落库。见设计 §7.2：先排空再冻结。
+func drainLogWriters(ctx context.Context) error {
+	if err := chwriter.Drain(ctx); err != nil {
+		return err
+	}
+	return risk_control.DrainLogWriter(ctx)
+}
+
+// setMigrationFlag 写入迁移冻结标记。用 SaveOrUpdateSystemConfig：行缺失时 upsert，
+// 并失效 RAM 缓存 + 广播其他节点，保证 logstore.Migrating/resolveDatabase 立即生效。
+func setMigrationFlag(ctx context.Context, v string) error {
+	return repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyLogDBMigration, v)
+}
+
+// flipLogDatabase 翻转日志主库。同上用 SaveOrUpdateSystemConfig，确保各进程缓存失效后指向新库。
+func flipLogDatabase(ctx context.Context, target string) error {
+	return repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyLogDatabase, target)
+}
+
+// buildTargetStore 构造目标库 Store（不经过 Active 缓存，直接 Build）。
+// 迁移期间冻结标记已置位，目标库的清空/复制写入必须放行，故使用 BuildForMigration。
+func buildTargetStore(ctx context.Context, database string) (*logstore.Store, error) {
+	return logstore.BuildForMigration(ctx, database)
+}
+
+func clearTargetLogTables(ctx context.Context, dst *logstore.Store) error {
+	// 依次清空 6 张表：AccessLogs.DeleteAll、UserAccessLogs.DeleteAll、Observability.DeleteAll*
+	// （SQLite/PG 用 DeleteAll；CH 用 TRUNCATE 语义）。
+	if _, err := dst.AccessLogs.DeleteAll(ctx); err != nil {
+		return fmt.Errorf("清空目标访问日志失败: %w", err)
+	}
+	if _, err := dst.UserAccessLogs.DeleteAll(ctx); err != nil {
+		return fmt.Errorf("清空目标用户访问日志失败: %w", err)
+	}
+	for _, fn := range []func(context.Context) (int64, error){
+		dst.Observability.DeleteAllMetricSnapshots,
+		dst.Observability.DeleteAllEdgeHealth,
+		dst.Observability.DeleteAllNodeObservationFrps,
+		dst.Observability.DeleteAllNodeObservationFrpc,
+	} {
+		if _, err := fn(ctx); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ensureTargetPartitions 目标为 PG 时，按源库时间范围（两表合并）预建分区，
+// 否则复制历史数据会报 "no partition of relation found"；目标非 PG 为 no-op。
+func ensureTargetPartitions(ctx context.Context, src, dst *logstore.Store, target string) error {
+	if target != targetPostgres {
+		return nil
+	}
+	from, to, err := migrationRange(ctx, src)
+	if err != nil {
+		return err
+	}
+	if from.IsZero() || to.IsZero() {
+		task.AppendLog(ctx, "源库无日志数据，跳过分区预建")
+		return nil
+	}
+	if err := dst.AccessLogs.EnsurePartitions(ctx, from, to.AddDate(0, 1, 0)); err != nil {
+		return fmt.Errorf("预建目标 PG 分区失败: %w", err)
+	}
+	task.AppendLog(ctx, "已为目标 PG 预建分区 %s ~ %s", from.Format("2006-01"), to.Format("2006-01"))
+	return nil
+}
+
+// migrationRange 合并源库节点访问日志（logged_at）与用户访问日志（created_at）
+// 的最小/最大时间；任一表为空时忽略该表。
+func migrationRange(ctx context.Context, src *logstore.Store) (time.Time, time.Time, error) {
+	fromAccess, toAccess, err := src.AccessLogs.MigrationRange(ctx)
+	if err != nil {
+		return time.Time{}, time.Time{}, fmt.Errorf("读取源访问日志时间范围失败: %w", err)
+	}
+	fromUser, toUser, err := src.UserAccessLogs.MigrationRange(ctx)
+	if err != nil {
+		return time.Time{}, time.Time{}, fmt.Errorf("读取源用户访问日志时间范围失败: %w", err)
+	}
+	return minTime(fromAccess, fromUser), maxTime(toAccess, toUser), nil
+}
+
+func minTime(a, b time.Time) time.Time {
+	switch {
+	case a.IsZero():
+		return b
+	case b.IsZero():
+		return a
+	case a.Before(b):
+		return a
+	default:
+		return b
+	}
+}
+
+func maxTime(a, b time.Time) time.Time {
+	switch {
+	case a.IsZero():
+		return b
+	case b.IsZero():
+		return a
+	case a.After(b):
+		return a
+	default:
+		return b
+	}
+}
+
+// copyAccessLogs 从 src 复制节点访问日志到 dst。
+func copyAccessLogs(ctx context.Context, src, dst *logstore.Store) error {
+	// 注意：迁移期间 src 已冻结，但复制读取不受冻结影响；每批按 id 升序扫描。
+	var lastID uint64
+	for {
+		rows, err := listNodeAccessLogsByID(ctx, src, lastID, copyBatchSize)
+		if err != nil {
+			return err
+		}
+		if len(rows) == 0 {
+			break
+		}
+		if err := dst.AccessLogs.BatchInsertNodeAccessLogs(ctx, rows); err != nil {
+			return fmt.Errorf("写入目标访问日志失败(批 %d): %w", lastID, err)
+		}
+		task.AppendLog(ctx, "已复制访问日志 %d 条（截至 id=%d）", len(rows), rows[len(rows)-1].ID)
+		lastID = rows[len(rows)-1].ID
+		if len(rows) < copyBatchSize {
+			break
+		}
+	}
+	return nil
+}
+
+func listNodeAccessLogsByID(ctx context.Context, src *logstore.Store, afterID uint64, limit int) ([]analyticsmodel.NodeAccessLog, error) {
+	return src.AccessLogs.ListForMigration(ctx, afterID, limit)
+}
+
+// copyUserAccessLogs 从 src 复制用户访问日志到 dst（按 id 升序分批）。
+func copyUserAccessLogs(ctx context.Context, src, dst *logstore.Store) error {
+	var lastID uint64
+	for {
+		rows, err := src.UserAccessLogs.ListForMigration(ctx, lastID, copyBatchSize)
+		if err != nil {
+			return err
+		}
+		if len(rows) == 0 {
+			return nil
+		}
+		if err := dst.UserAccessLogs.BatchInsert(ctx, rows); err != nil {
+			return fmt.Errorf("写入目标用户访问日志失败(批 %d): %w", lastID, err)
+		}
+		lastID = rows[len(rows)-1].ID
+		task.AppendLog(ctx, "已复制用户访问日志 %d 条（截至 id=%d）", len(rows), lastID)
+		if len(rows) < copyBatchSize {
+			return nil
+		}
+	}
+}
+
+// copyObservability 复制 4 张可观测表，每张表按 id 升序分批复制，
+// 以每批最后一条 id 作为下一批游标（不使用 len 近似）。
+func copyObservability(ctx context.Context, src, dst *logstore.Store) error {
+	if err := copyObsTable(ctx, "metric_snapshots",
+		src.Observability.ListMetricSnapshotsForMigration,
+		dst.Observability.BatchInsertNodeMetricSnapshots,
+		lastMetricSnapshotID); err != nil {
+		return err
+	}
+	if err := copyObsTable(ctx, "edge_health",
+		src.Observability.ListEdgeHealthForMigration,
+		dst.Observability.BatchInsertNodeEdgeHealth,
+		lastEdgeHealthID); err != nil {
+		return err
+	}
+	if err := copyObsTable(ctx, "obs_frps",
+		src.Observability.ListNodeObsFrpsForMigration,
+		dst.Observability.BatchInsertNodeObsFrps,
+		lastObsFrpsID); err != nil {
+		return err
+	}
+	if err := copyObsTable(ctx, "obs_frpc",
+		src.Observability.ListNodeObsFrpcForMigration,
+		dst.Observability.BatchInsertNodeObsFrpc,
+		lastObsFrpcID); err != nil {
+		return err
+	}
+	return nil
+}
+
+// copyObsTable 按 id 升序分批复制单张可观测表；idOf 返回批内最后一条 id。
+func copyObsTable[T any](ctx context.Context, name string,
+	list func(context.Context, uint64, int) ([]T, error),
+	insert func(context.Context, []T) error,
+	idOf func([]T) uint64,
+) error {
+	var lastID uint64
+	for {
+		rows, err := list(ctx, lastID, copyBatchSize)
+		if err != nil {
+			return fmt.Errorf("复制 %s 失败: %w", name, err)
+		}
+		if len(rows) == 0 {
+			return nil
+		}
+		if err := insert(ctx, rows); err != nil {
+			return fmt.Errorf("复制 %s 失败: %w", name, err)
+		}
+		lastID = idOf(rows)
+		task.AppendLog(ctx, "已复制 %s %d 条（截至 id=%d）", name, len(rows), lastID)
+		if len(rows) < copyBatchSize {
+			return nil
+		}
+	}
+}
+
+func lastMetricSnapshotID(rows []analyticsmodel.NodeMetricSnapshot) uint64 {
+	return rows[len(rows)-1].ID
+}
+func lastEdgeHealthID(rows []analyticsmodel.NodeEdgeHealth) uint64 { return rows[len(rows)-1].ID }
+func lastObsFrpsID(rows []analyticsmodel.NodeObsFrps) uint64       { return rows[len(rows)-1].ID }
+func lastObsFrpcID(rows []analyticsmodel.NodeObsFrpc) uint64       { return rows[len(rows)-1].ID }

internal/apps/openflare/tasks/log_db_switch_test.go

@@ -0,0 +1,358 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package tasks
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"github.com/Rain-kl/Wavelet/internal/infra/config"
+	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
+	"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"
+)
+
+var logDBSwitchDBSeq int64
+
+// newLogDBSwitchDB 构造内存 sqlite 库（含日志 5 表 + 系统配置表）。
+func newLogDBSwitchDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:log-db-switch-%d?mode=memory&cache=shared", atomic.AddInt64(&logDBSwitchDBSeq, 1))
+	gdb, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+	require.NoError(t, err)
+	require.NoError(t, gdb.AutoMigrate(
+		&model.SystemConfig{},
+		&analyticsmodel.NodeAccessLog{},
+		&analyticsmodel.NodeMetricSnapshot{},
+		&analyticsmodel.NodeEdgeHealth{},
+		&analyticsmodel.NodeObsFrps{},
+		&analyticsmodel.NodeObsFrpc{},
+		&analyticsmodel.UserAccessLog{},
+	))
+	return gdb
+}
+
+// TestCopyAccessLogsPreservesIDs sqlite→sqlite 模拟：源 store 3 条，目标空库，
+// copyAccessLogs 后 ID 保留、数量一致。
+func TestCopyAccessLogsPreservesIDs(t *testing.T) {
+	oldDB, oldCH := config.Config.Database.Enabled, config.Config.ClickHouse.Enabled
+	config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = false, false
+	t.Cleanup(func() {
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = oldDB, oldCH
+	})
+	logstore.ResetForTest()
+	defer logstore.ResetForTest()
+
+	ctx := context.Background()
+	srcDB := newLogDBSwitchDB(t)
+	dstDB := newLogDBSwitchDB(t)
+
+	db.SetDB(srcDB)
+	src, err := logstore.Active(ctx) // 无 reader 时按 seed 规则解析为 sqlite
+	require.NoError(t, err)
+	db.SetDB(dstDB)
+	dst, err := logstore.BuildForMigration(ctx, "sqlite")
+	require.NoError(t, err)
+	t.Cleanup(func() { db.SetDB(nil) })
+
+	now := time.Now().UTC()
+	rows := []analyticsmodel.NodeAccessLog{
+		{ID: 101, NodeID: "n1", LoggedAt: now, RemoteAddr: "1.1.1.1", Host: "a.example.com", Path: "/"},
+		{ID: 202, NodeID: "n2", LoggedAt: now, RemoteAddr: "2.2.2.2", Host: "b.example.com", Path: "/x"},
+		{ID: 303, NodeID: "n1", LoggedAt: now, RemoteAddr: "3.3.3.3", Host: "c.example.com", Path: "/y"},
+	}
+	require.NoError(t, src.AccessLogs.BatchInsertNodeAccessLogs(ctx, rows))
+
+	require.NoError(t, copyAccessLogs(ctx, src, dst))
+
+	var got []analyticsmodel.NodeAccessLog
+	require.NoError(t, dstDB.Order("id ASC").Find(&got).Error)
+	require.Len(t, got, 3)
+	for i, wantID := range []uint64{101, 202, 303} {
+		assert.Equal(t, wantID, got[i].ID, "row %d id preserved", i)
+	}
+	assert.Equal(t, "n1", got[0].NodeID)
+	assert.Equal(t, "n2", got[1].NodeID)
+	assert.Equal(t, "n1", got[2].NodeID)
+	assert.Equal(t, "1.1.1.1", got[0].RemoteAddr)
+
+	// 源库保持不变。
+	var srcCount int64
+	require.NoError(t, srcDB.Model(&analyticsmodel.NodeAccessLog{}).Count(&srcCount).Error)
+	assert.Equal(t, int64(3), srcCount)
+}
+
+// TestCopyUserAccessLogsPreservesIDs sqlite→sqlite 模拟：源库用户访问日志按 id 升序
+// 复制到目标库，ID 保留、数量一致，且源库保持不变。
+func TestCopyUserAccessLogsPreservesIDs(t *testing.T) {
+	oldDB, oldCH := config.Config.Database.Enabled, config.Config.ClickHouse.Enabled
+	config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = false, false
+	t.Cleanup(func() {
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = oldDB, oldCH
+	})
+	logstore.ResetForTest()
+	defer logstore.ResetForTest()
+
+	ctx := context.Background()
+	srcDB := newLogDBSwitchDB(t)
+	dstDB := newLogDBSwitchDB(t)
+
+	db.SetDB(srcDB)
+	src, err := logstore.Active(ctx)
+	require.NoError(t, err)
+	db.SetDB(dstDB)
+	dst, err := logstore.BuildForMigration(ctx, "sqlite")
+	require.NoError(t, err)
+	t.Cleanup(func() { db.SetDB(nil) })
+
+	now := time.Now().UTC()
+	rows := []analyticsmodel.UserAccessLog{
+		{ID: 11, UserID: 1, Path: "/a", CreatedAt: now},
+		{ID: 22, UserID: 2, Path: "/b", CreatedAt: now.Add(time.Second)},
+		{ID: 33, UserID: 1, Path: "/c", CreatedAt: now.Add(2 * time.Second)},
+	}
+	require.NoError(t, src.UserAccessLogs.BatchInsert(ctx, rows))
+
+	require.NoError(t, copyUserAccessLogs(ctx, src, dst))
+
+	var got []analyticsmodel.UserAccessLog
+	require.NoError(t, dstDB.Order("id ASC").Find(&got).Error)
+	require.Len(t, got, 3)
+	for i, wantID := range []uint64{11, 22, 33} {
+		assert.Equal(t, wantID, got[i].ID, "row %d id preserved", i)
+	}
+
+	var srcCount int64
+	require.NoError(t, srcDB.Model(&analyticsmodel.UserAccessLog{}).Count(&srcCount).Error)
+	assert.Equal(t, int64(3), srcCount)
+}
+
+// TestClearTargetLogTablesClearsUserAccessLogs 验证清空目标包含用户访问日志表
+// （6 张日志表之一），迁移「覆盖目标库已有日志」幂等前提成立。
+func TestClearTargetLogTablesClearsUserAccessLogs(t *testing.T) {
+	oldDB, oldCH := config.Config.Database.Enabled, config.Config.ClickHouse.Enabled
+	config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = false, false
+	t.Cleanup(func() {
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = oldDB, oldCH
+	})
+	logstore.ResetForTest()
+	defer logstore.ResetForTest()
+
+	ctx := context.Background()
+	dstDB := newLogDBSwitchDB(t)
+	db.SetDB(dstDB)
+	t.Cleanup(func() { db.SetDB(nil) })
+	dst, err := logstore.BuildForMigration(ctx, "sqlite")
+	require.NoError(t, err)
+
+	now := time.Now().UTC()
+	require.NoError(t, dst.UserAccessLogs.BatchInsert(ctx, []analyticsmodel.UserAccessLog{
+		{ID: 1, UserID: 1, Path: "/a", CreatedAt: now},
+		{ID: 2, UserID: 2, Path: "/b", CreatedAt: now},
+	}))
+
+	require.NoError(t, clearTargetLogTables(ctx, dst))
+
+	var count int64
+	require.NoError(t, dstDB.Model(&analyticsmodel.UserAccessLog{}).Count(&count).Error)
+	assert.Zero(t, count, "用户访问日志应被清空")
+}
+
+// TestValidateSwitch 各非法组合报错。
+func TestValidateSwitch(t *testing.T) {
+	oldDB, oldCH := config.Config.Database.Enabled, config.Config.ClickHouse.Enabled
+	t.Cleanup(func() {
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = oldDB, oldCH
+	})
+
+	gdb := newLogDBSwitchDB(t)
+	db.SetDB(gdb)
+	t.Cleanup(func() { db.SetDB(nil) })
+	ctx := context.Background()
+	setLogDB := func(v string) {
+		require.NoError(t, repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyLogDatabase, v))
+	}
+
+	t.Run("same target rejected", func(t *testing.T) {
+		setLogDB("sqlite")
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = false, false
+		err := validateSwitch(ctx, "sqlite")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "相同")
+	})
+	t.Run("clickhouse disabled rejected", func(t *testing.T) {
+		setLogDB("sqlite")
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = false, false
+		err := validateSwitch(ctx, "clickhouse")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "ClickHouse 未启用")
+	})
+	t.Run("postgres requires main db enabled", func(t *testing.T) {
+		setLogDB("sqlite")
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = false, false
+		err := validateSwitch(ctx, "postgres")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "PostgreSQL 未启用")
+	})
+	t.Run("sqlite rejected when main db is postgres", func(t *testing.T) {
+		setLogDB("postgres")
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = true, false
+		err := validateSwitch(ctx, "sqlite")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "SQLite")
+	})
+	t.Run("valid postgres migration", func(t *testing.T) {
+		setLogDB("sqlite")
+		config.Config.Database.Enabled, config.Config.ClickHouse.Enabled = true, false
+		require.NoError(t, validateSwitch(ctx, "postgres"))
+	})
+}
+
+// TestLogDBSwitchValidatePayload 参数归一化与非法值拒绝。
+func TestLogDBSwitchValidatePayload(t *testing.T) {
+	h := &LogDBSwitchHandler{}
+	cases := []struct {
+		name string
+		in   string
+		want string
+		ok   bool
+	}{
+		{name: "postgresql normalized", in: `{"target":"postgresql"}`, want: "postgres", ok: true},
+		{name: "sqlite3 normalized", in: `{"target":"sqlite3"}`, want: "sqlite", ok: true},
+		{name: "ch normalized", in: `{"target":"ch"}`, want: "clickhouse", ok: true},
+		{name: "postgres passthrough", in: `{"target":"postgres"}`, want: "postgres", ok: true},
+		{name: "invalid target", in: `{"target":"mysql"}`, ok: false},
+		{name: "malformed json", in: `not-json`, ok: false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			out, err := h.ValidatePayload([]byte(c.in))
+			if !c.ok {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			var p logDBSwitchPayload
+			require.NoError(t, json.Unmarshal(out, &p))
+			assert.Equal(t, c.want, p.Target)
+		})
+	}
+}
+
+// TestExecuteFailureClearsMigrationFlag 迁移失败后 log_db_migration 冻结标记被清除。
+// 在 FRESH DB（不预置 log_db_migration 行）上验证：setMigrationFlag 必须 upsert 建行，
+// 且失败后经缓存路径（GetSystemConfigByKey）可观察为空。
+func TestExecuteFailureClearsMigrationFlag(t *testing.T) {
+	oldDB := config.Config.Database.Enabled
+	config.Config.Database.Enabled = true
+	t.Cleanup(func() { config.Config.Database.Enabled = oldDB })
+
+	logstore.ResetForTest()
+	defer logstore.ResetForTest()
+
+	gdb := newLogDBSwitchDB(t)
+	db.SetDB(gdb)
+	t.Cleanup(func() { db.SetDB(nil) })
+	ctx := context.Background()
+
+	// FRESH DB：log_db_migration 行不存在（不预置），log_database 预置为 sqlite。
+	require.NoError(t, repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyLogDatabase, "sqlite"))
+	_, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyLogDBMigration)
+	require.ErrorIs(t, err, gorm.ErrRecordNotFound)
+
+	// configReader 对 log_database 报错，使 logstore.Active 在冻结标记置位后失败。
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == model.ConfigKeyLogDatabase {
+			return "", errors.New("reader error")
+		}
+		return "", nil
+	})
+
+	_, err = (&LogDBSwitchHandler{}).Execute(ctx, []byte(`{"target":"postgres"}`))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "reader error")
+
+	// 冻结标记必须被 upsert 持久化（行存在）并经缓存路径可观察为空，源库恢复可写。
+	cfg, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyLogDBMigration)
+	require.NoError(t, err, "setMigrationFlag 应 upsert 创建 log_db_migration 行")
+	assert.Empty(t, cfg.Value, "失败后冻结标记必须清除，源库保持可写")
+	assert.False(t, logstore.Migrating(ctx))
+}
+
+// TestSetMigrationFlagObservableThroughCache 在 FRESH DB 上验证 setMigrationFlag 写入
+// 经缓存路径（logstore.Migrating → repository 读取）实时反映：置位 true、清除 false。
+func TestSetMigrationFlagObservableThroughCache(t *testing.T) {
+	logstore.ResetForTest()
+	defer logstore.ResetForTest()
+
+	gdb := newLogDBSwitchDB(t)
+	db.SetDB(gdb)
+	t.Cleanup(func() { db.SetDB(nil) })
+	ctx := context.Background()
+
+	// 按 bootstrap 同款注入 repository 读取，走 RAM 缓存路径。
+	logstore.SetConfigReader(func(ctx context.Context, key string) (string, error) {
+		cfg, err := repository.GetSystemConfigByKey(ctx, key)
+		if err != nil {
+			return "", err
+		}
+		return cfg.Value, nil
+	})
+
+	// FRESH DB：行缺失 → fail-open false。
+	assert.False(t, logstore.Migrating(ctx))
+
+	require.NoError(t, setMigrationFlag(ctx, "migrating"))
+	assert.True(t, logstore.Migrating(ctx), "置位后缓存路径必须立即观察到 migrating")
+
+	require.NoError(t, setMigrationFlag(ctx, ""))
+	assert.False(t, logstore.Migrating(ctx), "清除后缓存路径必须立即观察到非 migrating")
+}
+
+// TestFlipLogDatabaseRefreshesCachedConfig 验证翻转日志主库后缓存路径立即反映新库
+// （logstore.ActiveDatabase / GetSystemConfigByKey），防止各进程继续写旧库（split-brain）。
+func TestFlipLogDatabaseRefreshesCachedConfig(t *testing.T) {
+	logstore.ResetForTest()
+	defer logstore.ResetForTest()
+
+	gdb := newLogDBSwitchDB(t)
+	db.SetDB(gdb)
+	t.Cleanup(func() { db.SetDB(nil) })
+	ctx := context.Background()
+
+	logstore.SetConfigReader(func(ctx context.Context, key string) (string, error) {
+		cfg, err := repository.GetSystemConfigByKey(ctx, key)
+		if err != nil {
+			return "", err
+		}
+		return cfg.Value, nil
+	})
+
+	require.NoError(t, repository.SaveOrUpdateSystemConfig(ctx, model.ConfigKeyLogDatabase, "sqlite"))
+	active, err := logstore.ActiveDatabase(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "sqlite", active) // 预热缓存
+
+	require.NoError(t, flipLogDatabase(ctx, "postgres"))
+
+	active, err = logstore.ActiveDatabase(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "postgres", active, "翻转后缓存路径必须立即反映新库")
+	cfg, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyLogDatabase)
+	require.NoError(t, err)
+	assert.Equal(t, "postgres", cfg.Value)
+}