ESC
输入关键词搜索文章
目录

Langfuse Architecture

从自托管组件到仓库结构
Web + Worker + Postgres + ClickHouse + Redis + S3
2应用容器
4存储组件
1Monorepo
2026/06/03 10:29:05
AI/AI Infra·9 min read
LangfuseArchitectureClickHouseRedisS3PostgresWorker
第一章
运行时架构：两类应用容器，四类存储组件

Langfuse 自托管文档把系统拆成两类应用容器、四类存储组件和一个可选 LLM API/Gateway：Langfuse Web 提供 UI 和 API，Langfuse Worker 异步处理事件；Postgres 处理事务数据，ClickHouse 存储 traces、observations 和 scores，Redis/Valkey 用于队列与缓存，S3/Blob Store 保存原始事件、多模态输入和导出文件。#Langfuse Self Hosting, 2026

flowchart TD
    App[LLM 应用 / Agent / RAG] --> SDK[SDK / OpenTelemetry / Framework Integrations]
    SDK --> Web[Langfuse Web\nUI + API + Ingestion]
    Web --> Postgres[Postgres\n事务数据]
    Web --> Redis[Redis / Valkey\n队列与缓存]
    Web --> S3[S3 / Blob Store\n原始事件与大文件]
    Redis --> Worker[Langfuse Worker\n异步处理]
    S3 --> Worker
    Worker --> ClickHouse[ClickHouse\nTrace / Observation / Score]
    Web --> ClickHouse
    Web --> LLM[可选 LLM API / Gateway]
数据写入路径：为什么不是直接写数据库

Langfuse 自托管文档特别强调 queued trace ingestion：Web 容器接收 batch trace 后会先写入 S3，Redis 中保存队列引用，Worker 再从 S3 读取事件并写入 ClickHouse。这样做的目的，是在突发流量下保护数据库，降低 ingest API 超时风险，并让原始事件具备可恢复性。#Langfuse Self Hosting, 2026

架构重点：S3 不是边缘附件，而是 ingestion 可靠性的关键组件；Redis 不是只做缓存，还承担队列协调。
组件职责如果出问题会怎样
Web接收 API、鉴权、写入队列与对象存储请求入口不可用
S3 / Blob保存原始事件、多模态文件、导出事件恢复和大文件能力受影响
Redis队列、API key 缓存、prompt 缓存ingestion 延迟、鉴权与热 prompt 读取变慢
Worker异步消费、写 ClickHouse、后台任务trace 可接收但分析数据延迟出现
ClickHouseOLAP 查询和 trace/score 存储dashboard、trace 查询、score analytics 受影响
Postgres项目、用户、组织、配置等事务数据控制面和元数据不可用
仓库结构：pnpm + Turborepo Monorepo

langfuse/langfuse 根目录的 package.json 声明 Node 24、pnpm@11.1.3 和 Turborepo 脚本。仓库不是一个单体目录，而是由 web、worker、packages/shared、ee、fern、scripts 等组成。#Langfuse GitHub, 2026

路径作用阅读重点
webNext.js 应用、UI、API、trpc、集成入口用户操作和同步 API 如何进入系统
workerNode/TypeScript Worker队列消费、后台任务、事件回填
packages/shared共享领域模型与工具代码Web 与 Worker 共用的数据结构
docker-compose.yml本地自托管组合理解最小可运行生产切面
fernAPI 文档和规范API-first 生态接入
ee企业版扩展自托管许可证与企业能力边界
为什么 ClickHouse 是 Langfuse 的核心

Langfuse README 明确提到项目基于 ClickHouse；自托管文档说明 ClickHouse 存储 traces、observations 和 scores。原因很直接：这类数据既有高写入量，又要支持 dashboard、筛选、聚合和趋势分析。如果全部放在 Postgres 中，事务型数据库会承担大量 OLAP 压力。#Langfuse GitHub, 2026 #Langfuse Self Hosting, 2026

读架构时的主线

Langfuse 的控制面更像普通 SaaS：用户、项目、权限、prompt 元数据走 Postgres；数据面更像日志分析系统：trace、observation、score 进入 ClickHouse；可靠 ingestion 则依赖 Redis 队列和 S3 原始事件。

读仓库时按"控制面 / 数据面"拆开

阅读 langfuse/langfuse 时，不要把它当作一个普通 Web 项目从页面入口开始顺读。更有效的方式是先区分控制面和数据面：控制面管理组织、项目、用户、权限、API key、prompt 元数据；数据面处理 trace ingestion、异步队列、ClickHouse 写入、score 查询和 dashboard 聚合。

切面核心数据主要组件主要风险
控制面Org、Project、User、API Key、Prompt metadataWeb、Postgres权限、鉴权、配置一致性
数据面Trace、Observation、Score、Event payloadWeb、S3、Redis、Worker、ClickHouse吞吐、延迟、可恢复性、查询成本
体验面Dashboard、Trace detail、Playground、Annotation UIWeb、ClickHouse、Postgres查询性能、交互复杂度、信息密度
生产部署拓扑：单机、Kubernetes 与云资源

Langfuse 文档将低规模部署和生产级部署区分开：本地或 VM Docker Compose 适合测试和低规模场景，但缺少高可用、扩缩容和备份能力；生产和高可用部署推荐 Kubernetes Helm 或云上 Terraform。这个区分很重要，因为 Langfuse 不是单容器应用，而是包含数据库、队列、对象存储和异步 worker 的系统。#Langfuse Self Hosting, 2026

部署形态适合场景需要补齐的能力
Local Docker Compose试用、开发、功能验证无需 HA，但要更换示例密钥
VM Docker Compose小团队、低流量内部系统备份、监控、磁盘容量、升级流程
Kubernetes Helm生产、高可用、多团队共享HPA、资源限制、外部数据库、对象存储、密钥管理
Cloud Terraform标准化云上生产部署VPC、IAM、托管数据库、托管对象存储、日志监控
自托管部署的工程注意事项

官方 docker-compose 文件中多个密钥被标记为 CHANGEME，包括 Postgres、ClickHouse、Redis、MinIO、NextAuth、SALT 和 ENCRYPTION_KEY。生产部署还需要关注高可用、备份、网络暴露面、对象存储持久性，以及所有基础设施组件必须使用 UTC 时区。#Langfuse Docker Compose, 2026 #Langfuse Self Hosting, 2026

上一篇Prompt 与评测闭环 总览Langfuse 系列导读 下一篇实践与改进路线

参考来源

Categories:AI / AI Infra
Tags:Langfuse, Architecture, ClickHouse, Redis, S3, Postgres, Worker