Langfuse 自托管

日期: 2026-07-09 阶段: Phase 1 - 产品定义×评测×可观测底座 标签: #langfuse #self-hosting #clickhouse #data-residency

核心问题

Day 24 把全链路 span 树和 trace↔eval 关联设计完了，但前端可视化只是教学/演示形态；要让这套 telemetry 落到一个真能查、能存、能算 $/案件的后端，需要选型。Langfuse 是开源自托管 LLM 可观测的首选，且 2026-01-16 被 ClickHouse 收购（$15B 估值），承诺保持核心 MIT 开源——这对金融场景关键，因为 AML 案件 trace 含 PII，数据驻留（data residency）不可妥协，SaaS 把数据送出自有边界在合规上往往不可接受。

今天回答三问：(A) 入 ClickHouse 后的存储架构——为什么 trace 用列存而非 Postgres；(B) 自托管 vs SaaS 的数据驻留权衡（金融 PII 场景）；(C) OTLP 接入与 trace↔eval 互查怎么落到 Langfuse。

关键内容

A. 为什么 trace 用列存（ClickHouse）而非行存（Postgres）

Langfuse v2 用 Postgres 做全部存储，v3 把核心数据层切到 ClickHouse——Postgres 成了瓶颈（Langfuse 官方）。原因是 trace 工作负载的两个特征：高吞吐写入（每秒数百事件）+ 快速分析读（聚合查询），这恰是 OLAP 列存的主场、行存 OLTP 的死穴。

trace 查询长什么样？「过去 7 天，gpt-4o 在 structuring 案件上的 P95 延迟和总 token 成本」——这是对少数几列（model、latency、tokens、case_type）的全表聚合，不是按主键取单行。行存（Postgres）把一行所有字段连续存，做这种「只读 4 列、扫百万行」的聚合时要把每行全部字段都读进内存再丢弃无关列，I/O 浪费巨大；列存（ClickHouse）把每列连续存，只读需要的列，且同列数据类型一致、压缩率极高。

收购的战略逻辑也在这：ClickHouse 核心是高性能分析引擎，Langfuse 的 trace/eval/成本追踪正好「直接补足」其分析强项（ClickHouse 博客 2026-01）。所以这不是「换个数据库」，是 trace 数据形态（高吞吐、分析型）与列存引擎的本质匹配。

反直觉洞察（trace 不是日志，是分析负载）：直觉把 trace 当「日志」，以为塞进任何能存文本的库就行。错。trace 的价值在聚合分析——按模型/案件类型/时间窗算成本、延迟分布、错误率、recall 趋势。这是 OLAP 查询，不是日志检索。用行存数据库存 trace，在 demo 量级没事，一上规模（每秒数百事件、要做趋势聚合）立刻撞墙——这正是 Langfuse v2→v3 切 ClickHouse 的实战教训。本项目即便量小，选型时也要按「这是分析负载」来定后端。

B. 自托管 vs SaaS：金融 PII 场景的数据驻留权衡

Langfuse 既有托管 Cloud（SaaS）也支持完全自托管（开源核心，可跑在用户自有基础设施内，完整数据驻留）。对 AML Copilot，自托管是合规驱动的强约束而非偏好：

AML 案件 trace（哪怕只采元数据）会沉淀客户/交易对手/账号关联——这些是受监管 PII。SaaS 模式下数据要出自有网络边界、落到第三方控制的存储，触发三类问题：数据驻留（数据必须留在特定司法辖区）、数据主权（监管对受控数据的处置权）、第三方处理协议（DPA/审计）。金融机构对此通常零容忍。

权衡的本质：用「多担运维」换「数据不出门」。对消费级产品，SaaS 的零运维通常更优；对金融受监管数据，数据驻留的合规价值压倒运维成本——这正是 Langfuse 被金融团队选为自托管首选的原因。收购后 Langfuse 明确「路线图不变，继续承诺开源与自托管」（Langfuse/ClickHouse 2026-01），消除了「被收购后闭源」的选型风险。

反直觉洞察（开源 ≠ 免运维，自托管的隐性成本在组件协同）：「开源免费自托管」听起来省钱，但 Langfuse v3 自托管不是单容器——是 Web + Worker + Postgres + ClickHouse + Redis + S3 共六个组件（C 节）。真实成本不在软件许可（MIT 免费），在让这六件套稳定协同：ClickHouse 调优、Redis 队列监控、S3 生命周期、版本同步升级。把这笔账算清楚再选自托管，否则「省了 SaaS 费、赔进去更多工程时间」。本项目作品集阶段用 docker compose 单机起最小拓扑，不假装跑生产级 K8s 集群。

C. OTLP 接入与 trace↔eval 互查落到 Langfuse

Langfuse v3 自托管拓扑（官方架构文档）：

                    ┌─────────────────────────────────────────┐
   OTel SDK         │            Langfuse 自托管边界            │
  (本项目埋点)      │                                          │
      │ OTLP        │  ┌──────────────┐    ┌───────────────┐  │
      └────────────►│  │ Langfuse Web │───►│  S3 / Blob    │  │ ← 事件先落 S3(持久化)
  /api/public/otel  │  │  (UI + API)  │    │  (原始事件)   │  │
                    │  └──────┬───────┘    └───────┬───────┘  │
                    │         │ 引用入队            │ 读取     │
                    │         ▼                     ▼          │
                    │  ┌──────────────┐    ┌───────────────┐  │
                    │  │ Redis/Valkey │    │ Langfuse Worker│ │ ← 异步消费
                    │  │ (队列+缓存)  │◄───┤  (摄取处理)    │ │
                    │  └──────────────┘    └───────┬───────┘  │
                    │  ┌──────────────┐            │ 写入      │
                    │  │  Postgres    │            ▼          │
                    │  │ (用户/项目/  │    ┌───────────────┐  │
                    │  │  API key)    │    │  ClickHouse   │  │ ← traces/observations
                    │  └──────────────┘    │ (列存,分析)   │  │   /scores 列存
                    │                      └───────────────┘  │
                    └─────────────────────────────────────────┘

摄取数据流（官方）有个关键的「先落盘再异步」设计：批量 trace 到 Web → 立即写 S3（持久化）→ 仅把引用入 Redis 队列 → Worker 从 S3 读取 → 摄取进 ClickHouse。为什么先 S3 再队列？这样数据库瞬时不可用或流量尖峰时事件不丢——S3 已持久化，Worker 慢慢消费即可，避免「写入直冲数据库导致超时/丢事件」。

OTLP 接入：本项目 Day 24 产出的 span（经 Day 23 attributeMap 翻译成 semconv 属性）直接 POST 到 Langfuse 的 /api/public/otel 端点即可摄取，无需改埋点代码——这正是 Day 22-23 坚持用 semconv 标准属性的回报。注意纯 OTLP 摄取的每个 observation 写为一行不可变记录（LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS=true 可优化），与 Langfuse 原生 SDK 的可变事件模型不同。

trace↔eval 互查落地：Day 24 的 eval.execution_id 作为 span 属性进 ClickHouse 后，可在 Langfuse 里按该 ID 关联——eval 报告（src/aml/evalBaseline.ts 产出）记录 execution_id，Langfuse trace 也带同一 ID，于是「某案 recall=0 → 查该 execution_id 的 trace → 看 retrieve span」的互查（Day 24 B 节）在真实后端成立。

设计要点/决策表

对本项目的落地

• 选型定稿：Langfuse 自托管作为 P1 可观测后端目标（计划态），理由 = 数据驻留（B 节）+ 列存分析能力（A 节）+ 收购后开源承诺。作品集文档写明「选型已定、最小拓扑用 docker compose、生产级 K8s 为后续」，不夸大为已上生产。
• 埋点零改对接：Day 24 的 span 经 Day 23 attributeMap.ts 翻译为 semconv 属性后，POST 到 /api/public/otel——这条链路依赖 Day 22-23 已铺好的标准属性，是「先定边界、后补后端」设计的兑现。
• execution_id 贯穿到 ClickHouse：src/aml/evalBaseline.ts 的 BaselineEval 每案携带 execution_id，与 Langfuse trace 同键关联，落地 Day 24 B 节 trace↔eval 双向互查在真实后端的形态。
• $/案件 成本聚合：用 ClickHouse 对 gen_ai.usage.* × 模型单价做列存聚合（A 节列存正是为这类查询设计），对接 Day 22 成本指标——用 response.model（非 request.model）算计费，遵守 Day 22 口径陷阱。
• PII 边界纪律：生产对 AML prompt 一律不开内容捕获（Day 22 B 节 CAPTURE_MESSAGE_CONTENT=false），即便自托管也最小化 PII 落 ClickHouse；仅元数据进后端，内容不进。
• 诚实标注：当前 output:export 静态站无后端，Langfuse 是 P1 后段的计划态后端；前端可视化（Day 24，对标 dsdb-lab）是当前已实现形态。二者分清，不混淆。

参考资料

1. Langfuse — Self-host Langfuse（六组件拓扑：Web/Worker/Postgres/ClickHouse/Redis/S3、先 S3 后队列摄取流、完整数据驻留、docker compose vs K8s）官方架构文档 (2026)
2. ClickHouse Blog — ClickHouse welcomes Langfuse: The future of open-source LLM observability（收购、保持开源、trace/eval 补足分析强项）(2026-01-16)
3. Langfuse Blog — Langfuse joins ClickHouse（路线图不变、继续承诺开源与自托管）(2026-01-16)
4. Langfuse — Self-hosting scaling / OTLP 摄取（/api/public/otel 端点、LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS、OTel 单行不可变记录）(2026)
5. ClickHouse Blog — Langfuse and ClickHouse: A new data stack for modern LLM applications（v3 切 ClickHouse 的动因：Postgres 在高吞吐摄取+快速分析读下成瓶颈）(2024-2026)
6. Orrick / SiliconANGLE — Langfuse acquired by ClickHouse（$400M Series D、$15B 估值、收购确认）(2026-01-16)

SOTA 检查 (2026-06-11)

• Langfuse 仍是开源自托管 LLM 可观测首选，且选型风险刚被消除：2026-01-16 被 ClickHouse 收购后官方明示保持 MIT 核心开源、路线图不变——这把「被收购后闭源/弃维」的最大选型风险排除，使自托管选型在 2026-06 比收购前更稳。
• v3 ClickHouse 架构是当前 SOTA 数据栈：trace 存储用列存 OLAP 已是行业共识（Arize Phoenix、Datadog LLM Obs 后端同走分析型存储）；Langfuse v3 的 Web/Worker/CH/Redis/S3 分层是生产级参考架构。
• 是否仍是 SOTA：✅ 「自托管 Langfuse + ClickHouse 列存 + OTLP 接入」是 2026 金融/受监管场景 LLM 可观测的事实最佳实践；与 Day 24 的 OTel semconv 埋点天然衔接（OTLP 端点）。
• 数据驻留判断仍成立：金融 PII 的数据驻留/主权要求是结构性的、不随版本变；自托管而非 SaaS 的结论对 AML 场景长期有效。
• 过时认知警示：引用 Langfuse v2（纯 Postgres）的自托管教程已过时——v2 在高吞吐下撞瓶颈，v3 才是当前架构；选型/部署须按 v3 六组件来，勿照 v2 单库教程。
• 待跟踪：收购后 Langfuse 与 ClickHouse Cloud 的集成是否推出更省运维的「半托管」选项（可能影响自托管 vs 托管的权衡）；v3 后续版本号与 OTLP 摄取参数变更。
• WebSearch 验证关键词: "Langfuse self-hosting v3 ClickHouse 2026", "Langfuse ClickHouse acquisition open source"