bug: ClickHouse cluster name hardcoded as `default` breaks clustered migrations on non-default clusters

快速结论：这个报错通常出现在自托管 Langfuse 使用非默认名称的 ClickHouse 集群（如腾讯云 virtual-cluster）并执行集群模式数据库迁移时，迁移 SQL 里写死的 ON CLUSTER default 与实际集群名不匹配。优先检查你的 ClickHouse 集群名是否为非 default，以及迁移 SQL 文件是否仍硬编码 default。

适用环境：Issue 中已确认的环境为自托管 Langfuse v3.124.1，涉及 packages/shared/clickhouse/scripts/up.sh 迁移脚本与 packages/shared/clickhouse/migrations/clustered 下的集群迁移 SQL；未提供操作系统、Python、CUDA、显卡等环境信息，无需补写。

最快修复方案：暂无确认的一步修复方案。Issue 中给出的可行处理方式是：在执行迁移前，手动把集群迁移 SQL 文件中所有 ON CLUSTER default 替换为你的实际集群名，然后再运行迁移。

注意事项：手动替换只影响你当前修改的 SQL 文件，后续升级 Langfuse 时这些文件可能被覆盖，需要重新处理；CLICKHOUSE_CLUSTER_NAME 只会被注入到 DATABASE_URL，并不会自动改写 SQL 文件中的集群名。基于 sed 预处理、迁移工具模板化等做法在 Issue 中属于建议方向，并非已验证方案，可优先尝试但需自行验证。

问题场景

用户在自托管环境中运行 Langfuse，使用 ClickHouse 集群模式数据库迁移。ClickHouse 集群名称不是 default（例如腾讯云的 virtual-cluster），配置了集群相关环境变量后执行 bash packages/shared/clickhouse/scripts/up.sh，迁移过程报未知集群错误。

报错原文

DB::Exception: Unknown cluster 'default' specified in ON CLUSTER. (UNKNOWN_CLUSTER)

原因分析

最可能的原因是：packages/shared/clickhouse/migrations/clustered 目录下的集群迁移 SQL 文件里硬编码了 ON CLUSTER default。迁移运行脚本 packages/shared/clickhouse/scripts/up.sh 虽然支持 CLICKHOUSE_CLUSTER_NAME 环境变量，并会把它注入到 DATABASE_URL（x-cluster-name），但这个变量不会改写 SQL 语句本身，因此 SQL 中写死的 default 与实际集群名不一致，触发 UNKNOWN_CLUSTER。

环境排查

确认 Langfuse 版本：Issue 中为 v3.124.1，其他版本行为可能不同。
确认 ClickHouse 实际集群名，是否为非 default（例如腾讯云 virtual-cluster）。
确认环境变量：CLICKHOUSE_CLUSTER_ENABLED=true、CLICKHOUSE_CLUSTER_NAME=<你的集群名>，以及 CLICKHOUSE_MIGRATION_URL、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD、CLICKHOUSE_DB、CLICKHOUSE_MIGRATION_SSL 等标准 ClickHouse 环境变量。
检查 packages/shared/clickhouse/migrations/clustered 下的 .up.sql 文件是否仍包含 ON CLUSTER default。

解决步骤

先备份 packages/shared/clickhouse/migrations/clustered 目录，避免修改出错后无法回退。
打开该目录下的集群迁移 SQL 文件，查找所有 ON CLUSTER default。
将每一处 ON CLUSTER default 替换为你的实际集群名，例如 ON CLUSTER virtual-cluster（请按你的真实集群名填写）。
确认 ClickHouse 相关环境变量已按你的集群配置正确设置。
重新运行 bash packages/shared/clickhouse/scripts/up.sh 执行迁移。
如果你希望自动化，Issue 中建议的方向是在迁移前用脚本（例如 sed）把 ON CLUSTER default 替换为 ON CLUSTER $CLICKHOUSE_CLUSTER_NAME，或改用支持模板化的迁移工具，或在迁移运行脚本中加入预处理步骤。这些属于建议方案，需要你自行实现和验证。

验证方法

重新执行迁移后，如果不再出现 DB::Exception: Unknown cluster 'default' specified in ON CLUSTER. (UNKNOWN_CLUSTER)，并且迁移正常完成，说明集群名已与实际环境匹配。也可在 ClickHouse 中确认迁移后的表结构是否已在目标集群上正确建立。