Langfuse 技术架构深度解析：从一个 Postgres 到 ClickHouse+Redis 的可观测性平台演进

> 来源: https://github.com/langfuse/langfuse

> 架构手册: https://langfuse.com/handbook/product-engineering/architecture

> v3 架构演进博客: https://langfuse.com/blog/2024-12-langfuse-v3-infrastructure-evolution

> 自托管文档: https://langfuse.com/self-hosting

> ClickHouse 合作博客: https://clickhouse.com/blog/langfuse-and-clickhouse-a-new-data-stack-for-modern-llm-applications

> 研究时间: 2026-03-17

📌 一句话总结

Langfuse 是目前最成熟的开源 LLM 可观测性平台（23K+ Stars，YC W23），从 2023 年的 Next.js + Postgres 单体架构，演进到 v3 的 ClickHouse + PostgreSQL + Redis + S3 四组件分布式架构。自托管 docker compose up 三分钟启动，生产部署支持 K8s Helm 和 AWS/Azure/GCP Terraform 模板。被 ClickHouse 收购后成为其 LLM 可观测性标杆。

🏗️ 架构全景

v1 → v3 演进

v1 (2023 YC W23)          v2 (2024 中期)              v3 (2024.12 发布)
┌──────────┐         ┌──────────────┐          ┌──────────────────────┐
│ Next.js  │         │ Next.js Web  │          │ Web (Next.js)        │
│    +     │   →     │    +         │    →     │ Worker (Express)     │
│ Postgres │         │ Redis Queue  │          │ PostgreSQL (OLTP)    │
└──────────┘         │ + Postgres   │          │ ClickHouse (OLAP)    │
                     └──────────────┘          │ Redis (Queue+Cache)  │
                                               │ S3/MinIO (Blob)      │
                                               └──────────────────────┘

v3 架构详解

┌─────────────────────────────────────────────────────────┐
│                        VPC                               │
│                                                          │
│  ┌─────────────┐     ┌──────────────┐                   │
│  │  Web Server  │────→│    Redis     │                   │
│  │  (Next.js)   │     │ (Queue+Cache)│                   │
│  │  UI + API    │     └──────┬───────┘                   │
│  └──────┬───────┘            │                           │
│         │              ┌─────▼──────┐                    │
│         │              │   Worker    │                    │
│         │              │  (Express)  │                    │
│         │              └──────┬──────┘                    │
│         │                     │                           │
│  ┌──────▼───────┐  ┌────────▼────────┐  ┌────────────┐ │
│  │  PostgreSQL   │  │   ClickHouse    │  │ S3 / MinIO │ │
│  │   (OLTP)      │  │    (OLAP)       │  │  (Blob)    │ │
│  │ 用户/组织/项目 │  │ Traces/Scores   │  │ 原始事件    │ │
│  │ API Key/Prompt │  │ 仪表盘/分析     │  │ 多模态附件  │ │
│  │ 数据集/评估    │  │                 │  │            │ │
│  └───────────────┘  └─────────────────┘  └────────────┘ │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  LLM API / Gateway (可选)                         │   │
│  │  用于 Playground、LLM-as-a-Judge 等功能           │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

四大存储组件职责

两个应用容器

🔧 关键技术设计

1. 排队摄入管线（解决高峰流量）

v1 的致命问题：高峰期摄入 API 延迟飙到 50 秒，因为每条事件同步写 Postgres。

v3 的解决方案：

SDK batch 发送
    ↓
Web API（轻量验证：认证 + 格式检查）
    ↓
事件写入 S3（持久化，确保不丢）
    ↓
S3 引用放入 Redis 队列（BullMQ）
    ↓
Worker 异步消费：token 化 → 成本计算 → 写入 ClickHouse

关键：Redis 队列里只传 S3 引用，不传实际数据。这样即使 ClickHouse 临时不可用，事件也不会丢失（全在 S3 里）。

2. ClickHouse ReplacingMergeTree（解决 OLAP 更新问题）

SDK 会对同一个 Trace ID 多次发送更新。在 Postgres 里 UPDATE 很快，但在 ClickHouse 里 UPDATE 极其昂贵。

解决方案：

• 把 UPDATE 转为 INSERT（新行）
• 使用 ReplacingMergeTree 引擎，后台自动去重
• 90% 的更新在 10 秒内到达 → 用 Redis 缓存当前状态，避免从 ClickHouse 读取不一致数据

新事件到达
    ↓
从 Redis 读取当前状态（10 秒内缓存）
    ↓
合并更新 → INSERT 新行到 ClickHouse
    ↓
ClickHouse 后台 merge 去重

3. Redis 三重角色

4. 可恢复性设计

所有摄入事件先写 S3，再处理。即使 ClickHouse 宕机，事件也安全保存在 S3 中，恢复后自动补处理。这个设计保证了零数据丢失。

📦 安装方法

方法一：Docker Compose（最简单，适合试用和小规模）

# 1. 克隆仓库
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# 2. 修改 docker-compose.yml 中的密钥（标记为 # CHANGEME 的行）

# 3. 启动
docker compose up

# 4. 等待 2-3 分钟，看到 "Ready" 后访问 http://localhost:3000

最低要求（VM 部署）：

• 4 核 CPU + 16 GB 内存（如 AWS t3.xlarge）
• 100 GB 磁盘
• 对外端口：3000（Web UI）、9090（MinIO）

方法二：Kubernetes Helm（生产推荐）

# 添加 Helm repo
helm repo add langfuse https://langfuse.github.io/langfuse-helm
helm repo update

# 安装
helm install langfuse langfuse/langfuse \
  --namespace langfuse \
  --create-namespace \
  -f values.yaml

支持：

• 水平扩展（Web/Worker 独立伸缩）
• 高可用
• 自动备份
• 滚动升级 + 后台迁移（升级不停服）

方法三：Terraform 模板

一键部署完整基础设施：ECS/EKS + Aurora PostgreSQL + ElastiCache Redis + ClickHouse + S3。

方法四：Langfuse Cloud（零运维）

直接注册 https://cloud.langfuse.com，免费 Hobby 套餐即可开始。

💰 定价

超出套餐：$8 / 100K units（所有付费方案）

> "Unit" = 1 个 Trace、Observation 或 Score

自托管 vs Cloud 成本对比

假设月处理 100 万 units：

• Cloud Pro: $199 + $72 超出 = $271/月
• 自托管（t3.xlarge）: ~$150/月（EC2 + RDS + ElastiCache + S3）

自托管在大规模时更便宜，但需要运维投入。小规模直接用 Cloud 更省事。

🔌 集成生态

SDK & 框架

OpenClaw 集成

Langfuse 官方有 OpenClaw 集成文档。最简单的接入方式：

1. OpenRouter Broadcast：零代码修改，在 OpenRouter 配置里加一个 Langfuse callback URL

2. LiteLLM Proxy：如果用 LiteLLM 做模型路由，自带 Langfuse 集成

🤔 深度分析

为什么选 ClickHouse 而不是其他 OLAP？

Langfuse 选 ClickHouse 的决定性因素：开源许可 + 可自托管 + 列式分析性能。后来被 ClickHouse 收购更证明了这个选择。

架构的三个聪明之处

1. S3 First：所有事件先落 S3，再异步处理。这意味着即使整个处理管线宕机，数据也不会丢。这是大规模可观测性系统的标准做法（Datadog、Honeycomb 也这么干）。

2. Redis 而非 Kafka：对于需要自托管的开源项目，Redis 的运维成本远低于 Kafka。BullMQ 提供了足够的队列能力。代价是不如 Kafka 能处理极端吞吐，但对绝大多数用户够了。

3. 双数据库分离：Postgres 管事务（写多读少、强一致）、ClickHouse 管分析（写多读多、最终一致）。两者各司其职，互不干扰。

潜在问题

• ⚠️ 自托管复杂度上升：v1 只需 Postgres，v3 需要 4 个存储组件。虽然 docker-compose 封装了，但生产环境运维复杂度显著增加。
• ⚠️ ClickHouse 更新延迟：ReplacingMergeTree 的去重是后台异步的，短时间内可能读到重复数据。
• ⚠️ License Key 功能分层：部分功能（SSO、Organization Creators、UI 定制、Instance Management API）需要企业许可证。

💡 与我们的关联

1. 我们的 OpenClaw 可以直接接入

之前研究过，最简路径是 OpenRouter Broadcast——零代码改动，在 OpenRouter 后台加个 Langfuse callback 就行。所有 Agent 的 LLM 调用自动出现在 Langfuse 仪表盘。

2. 我们的服务器能跑

我们的 VPS 是 1vCPU/2GB（偏小），但 docker-compose 最低推荐 4 核 16GB。两个方案：

• 用 Cloud 免费版：50K units/月，30 天保留，够我们试用
• 在 ub2 上自托管：i9-13900K + 63GB RAM，完全够跑生产级 Langfuse

3. 反馈闭环

之前研究 auxten（ClickMem 作者）提到的 "Agent 查 Langfuse → 找 bad case → 自动优化" 模式。有了 Langfuse 的 Trace 数据，我们可以：

• 找出 Agent 失败率最高的任务类型
• 分析 token 消耗模式
• 评估不同模型的成本效益
• 发现 Prompt 需要改进的地方

❓ 常见问题

Q1: Langfuse 的 "Unit" 是什么？

Langfuse 的计费单位 unit = 1 个可计费事件，包括三种：

实际消耗举例：

• 简单聊天机器人（1 次 LLM 调用）：2 units/请求（1 trace + 1 observation）
• 多步骤 Agent（web_search + web_fetch + write + deploy）：10-20 units/请求（1 trace + 多个 observation）
• 加上 LLM-as-a-Judge 自动评分：每个评分再 +1 unit

所以 Hobby 的 50K units/月：

• 简单应用 ≈ 25,000 次请求
• 多步骤 Agent ≈ 3,000-5,000 次请求

Q2: 有更简单运维的开源替代品吗？

有。主流开源 LLM 可观测性平台运维复杂度对比：

最简单的替代品：Phoenix（Arize）

# 安装（一行命令）
pip install arize-phoenix

# 启动（一行命令）
phoenix serve

# 打开 http://localhost:6006

Phoenix 的优势：

• 只依赖 PostgreSQL（甚至可以用 SQLite 试用）
• 没有 ClickHouse、没有 Redis、没有 S3
• 原生支持 OpenTelemetry 标准
• Apache 2.0 开源
• 支持 OpenAI / LangChain / LlamaIndex / LiteLLM 集成
• 内置 LLM 评估（hallucination、QA、toxicity）

Phoenix 的代价：

• ⚠️ 不适合极高吞吐（没有异步队列 + ClickHouse OLAP）
• ⚠️ 没有内置 Prompt 管理
• ⚠️ 没有团队协作功能

建议：个人/小团队先用 Phoenix（pip install 秒装），量大了再迁移到 Langfuse。

📊 评分

报告由深度研究助手自动生成 | 2026-03-17

来源: https://github.com/langfuse/langfuse