bug: v4 self-host preview (`events_only`): Traces UI stuck on “Create API key” onboarding on a fresh deployment

快速结论：在使用 v4 自托管预览版并启用 events_only 模式的全新部署中，即使已经通过 OTLP 成功写入 traces 数据，Traces 页面仍会无限显示 “Create API key” / “Set up tracing” 引导界面。根本原因是引导检查硬编码查询了遗留的 traces 表，而该表在 events_only 模式下永远不会被填充。优先通过手动向 traces 表插入一条占位记录绕过，或等待修复 PR 合并。

问题场景

在运行 langfuse/langfuse:3 (版本 3.205.1) 镜像并遵循 v4 自托管预览指南（Issue #14157）的全新部署中触发。关键环境标志包括：

LANGFUSE_MIGRATION_V4_WRITE_MODE=events_only
LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true
LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct
CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION=true

ClickHouse Cloud 版本 26.2.1，且项目为全新创建，无任何 v3 历史数据迁移。

报错原文

-- Onboarding check queries the legacy `traces` table, which is never populated in `events_only` mode.
SELECT 1 FROM traces WHERE project_id = '<PROJECT_ID>' LIMIT 1   -- result_rows = 0

原因分析

Langfuse v4 自托管预览版的 events_only 模式下，所有追踪数据仅写入 events_full 和 events_core 表，遗留的 v3 traces 表从头到尾保持为空。

然而，Traces 页面加载时调用的引导检查函数 hasAnyTrace()（位于 packages/shared/src/server/repositories/traces.ts），仅查询遗留的 traces 表，并未检测 events 表。因此，即使数据已成功写入 ClickHouse 的 events 表，该检查仍返回 0 行，导致 UI 错误地认为项目从未收到过 trace，从而锁定在引导界面。

环境排查

确认镜像版本是否为 langfuse/langfuse:3 (特别关注 3.205.1)。
确认环境变量中 LANGFUSE_MIGRATION_V4_WRITE_MODE 是否为 events_only。
确认 ClickHouse 版本（本案例中为 Cloud 26.2.1）。
确认项目是否为全新创建，且无任何 v3 迁移数据（即 traces/observations/scores 表为空）。
通过 SQL 验证数据是否仅存在于 events_full 或 events_core 表中：SELECT count() FROM events_core WHERE project_id = '<PROJECT_ID>';。

解决步骤

临时绕过（可优先尝试）：直接向遗留 traces 表插入一条无效的占位记录。

执行插入命令示例（请替换占位符）：

INSERT INTO traces (id, project_id, timestamp, name) VALUES (gen_random_uuid(), '<PROJECT_ID>', now(), 'trace-onboarding-workaround');

验证插入是否成功：再次执行引导检查 SELECT 1 FROM traces WHERE project_id = '<PROJECT_ID>' LIMIT 1;，应返回 1 行。
刷新 Traces 页面：引导界面应消失并显示正常的 Traces 表格。
关注修复 PR：该问题已被确认为已知 bug，并有对应修复 PR（#13955）正在处理中。修复将添加一个 hasAnyEvent() 回退查询，按顺序检查 PostgreSQL 标志 → ClickHouse traces 表 → ClickHouse events 表。建议关注该 PR 的合并状态，一旦合并可回滚上述临时绕过并升级部署。

验证方法

执行临时绕过后，刷新项目下的 Traces 页面（/project/<PROJECT_ID>/traces），确认页面不再显示 “Create API key” 或 “Set up tracing” 引导界面，而是正常展示已通过 OTLP 写入的 trace 记录列表。此外，确认通过 OTLP 注入的 trace 仍能在 events_core 表中查询到，且引导检查不再返回空结果。