fix(config): set ClickHouse to disabled by default and update related documentation

.env.example

@@ -56,7 +56,7 @@ REDIS_MAINT_NOTIFICATIONS=false
 
 # ─── ClickHouse（必需）────────────────────────────────────────────────────────
 # CLICKHOUSE_HOST 设置后会自动启用；测试环境可显式 CLICKHOUSE_ENABLED=true 做 live 联调
-CLICKHOUSE_ENABLED=true
+CLICKHOUSE_ENABLED=false
 # compose 内：clickhouse:9000；本机连映射端口：127.0.0.1:9000
 CLICKHOUSE_HOST=clickhouse:9000
 CLICKHOUSE_USERNAME=default

config.example.yaml

@@ -99,10 +99,12 @@ otel:
   tracer_name: "github.com/Rain-kl/OpenFlare" # Global tracer instrumentation name
 
 
-# ─── ClickHouse (required) ──────────────────────────────────────────────────────
+# ─── ClickHouse (optional) ─────────────────────────────────────────────────────
 # Analytics / observability OLAP store. Telemetry writes are best-effort (async batch).
+# 默认关闭：缺失本配置块或 enabled: false 时不启用 ClickHouse，日志/指标由主库承担；
+# 设置 CLICKHOUSE_HOST 或 CLICKHOUSE_ENABLED=true 可经环境变量启用。
 clickhouse:
-  enabled: true
+  enabled: false
   hosts:
     - "127.0.0.1:9000"        # compose 内应用可用 clickhouse:9000（经 CLICKHOUSE_HOST）
   username: "default"

docs/changelog/index.md

@@ -26,6 +26,10 @@ sidebar: false
 
 - 日志存储解耦：新增日志存储抽象（`internal/repository/logstore`），ClickHouse 变为可选项，不启用时由 PostgreSQL/SQLite 承担全部日志功能；新增「切换日志数据库」任务支持 PostgreSQL/SQLite 与 ClickHouse 间数据迁移（迁移期间冻结日志写入，成功后自动切换主库并保留源数据）；日志保留时间改为按存储库在业务配置中设置（`log_retention_days_*`），过期清理并入系统垃圾清理每日任务。
 
+### 变更
+
+- ClickHouse 改为默认关闭：`clickhouse.enabled` 缺省或为 `false` 时不启用（此前会被强制置为 `true`），日志/指标由 PostgreSQL/SQLite 主库承担；显式 `true` 或设置 `CLICKHOUSE_HOST` / `CLICKHOUSE_ENABLED=true` 时启用。
+
 ### 修复
 
 - 「切换日志数据库」迁移任务修复冻结期目标库用户访问日志写入被误拦：`BuildForMigration` 未将跳过冻结标记传播到用户访问日志存储，导致迁移任务在清空目标库阶段以「log database is migrating」失败；现在目标库的清空与复制全程放行，任务可正常完成切换。

docs/reference/configuration.md

@@ -105,7 +105,7 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
 
 | 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
 | --- | --- | --- | --- |
-| `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | 是否启用 ClickHouse。**系统节点指标与访问日志在此进行海量写入** | `true` |
+| `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | 是否启用 ClickHouse。**系统节点指标与访问日志在此进行海量写入**。默认关闭：缺失本配置项或为 `false` 时不启用，日志/指标由主库承担；显式 `true` 或设置 `CLICKHOUSE_HOST` 时启用 | `false` |
 | `clickhouse.hosts` | `CLICKHOUSE_HOST` | ClickHouse 集群连接地址数组（环境变量仅设置单地址） | `["127.0.0.1:9000"]` |
 | `clickhouse.username` | `CLICKHOUSE_USERNAME` | ClickHouse 账号用户名 | `default` |
 | `clickhouse.password` | `CLICKHOUSE_PASSWORD` | ClickHouse 密码 | `replace-with-clickhouse-password` |

internal/infra/config/config.go

@@ -130,9 +130,8 @@ func applyClickHouseDefaults(c *configModel) {
 		}
 		// Keep Enabled=true from env and continue applying host/pool defaults.
 	}
-	if !c.ClickHouse.Enabled {
+	// 未显式启用（缺省或 enabled: false）时保持关闭，不再强制打开；
-		c.ClickHouse.Enabled = true
+	// 显式启用后补齐连接默认参数。
-	}
 	if c.ClickHouse.Database == "" {
 		c.ClickHouse.Database = "openflare"
 	}

internal/infra/config/config_test.go

@@ -12,3 +12,35 @@ func TestApplyEnvOverridesRedisMaintNotifications(t *testing.T) {
 		t.Fatal("REDIS_MAINT_NOTIFICATIONS=true was not applied")
 	}
 }
+
+// TestApplyClickHouseDefaultsRespectsDisabledConfig 回归：配置未显式启用（缺省或
+// enabled: false）时 ClickHouse 必须保持关闭，不得被 applyClickHouseDefaults 强制打开。
+// CLICKHOUSE_ENABLED=true 仅用于绕过测试分支（isTest 默认强制关闭），以便测真实默认逻辑。
+func TestApplyClickHouseDefaultsRespectsDisabledConfig(t *testing.T) {
+	t.Setenv("CLICKHOUSE_ENABLED", "true")
+
+	cfg := &configModel{ClickHouse: clickHouseConfig{Enabled: false}}
+	applyClickHouseDefaults(cfg)
+
+	if cfg.ClickHouse.Enabled {
+		t.Fatal("ClickHouse must stay disabled when config does not enable it")
+	}
+}
+
+// TestApplyClickHouseDefaultsEnablesWhenConfigured 显式 enabled: true 时保持启用并补齐默认连接参数。
+func TestApplyClickHouseDefaultsEnablesWhenConfigured(t *testing.T) {
+	t.Setenv("CLICKHOUSE_ENABLED", "true")
+
+	cfg := &configModel{ClickHouse: clickHouseConfig{Enabled: true}}
+	applyClickHouseDefaults(cfg)
+
+	if !cfg.ClickHouse.Enabled {
+		t.Fatal("ClickHouse must stay enabled when explicitly configured")
+	}
+	if cfg.ClickHouse.Database != "openflare" {
+		t.Fatalf("database default not applied: %q", cfg.ClickHouse.Database)
+	}
+	if len(cfg.ClickHouse.Hosts) != 1 || cfg.ClickHouse.Hosts[0] != "127.0.0.1:9000" {
+		t.Fatalf("hosts default not applied: %v", cfg.ClickHouse.Hosts)
+	}
+}