第 1 篇 · 1.1 为什么要这样读 Langfuse
学习目标
完成本节后，你将能够：
- 解释为什么 Langfuse 不是一个普通 Next.js 项目。
- 用“数据平台”视角理解
web、worker、shared的关系。 - 明白为什么本书反复强调契约和运行链路。
1.1.1 核心论点：Langfuse 是 LLM telemetry 数据平台
Langfuse 的产品入口是 Web UI，但工程形态是一个多入口、多存储、多队列的数据平台。它同时处理：
- 用户在 UI 中查询、筛选、标注和配置；
- SDK 和 Public API 上报 trace、observation、score、dataset；
- OTel 数据进入 ingestion 管道；
- worker 异步执行 eval、导出、删除、数据保留、webhook；
- ClickHouse 承担高吞吐分析查询；
- Postgres 承担组织、项目、权限、配置等事务型数据。
所以读它不能只看页面。更好的路线是先问：
这段代码属于同步请求、异步任务、共享契约，还是数据设施？
1.1.2 机场运行系统类比
| 机场系统 | Langfuse 模块 | 一句话职责 |
|---|---|---|
| 值机柜台 | web/ API 入口 | 接收请求、鉴权、校验、限流 |
| 调度中心 | packages/shared | 定义规则、模型、队列、查询契约 |
| 行李分拣 | worker/ | 异步处理重任务和可重试任务 |
| 航班历史库 | ClickHouse | 存宽事件和分析数据 |
| 会员系统 | PostgreSQL | 存组织、项目、权限、配置 |
| 临时传送带 | Redis/BullMQ | 队列、限流、缓存、锁 |
| 大件仓库 | S3/Blob | 原始事件、媒体、导出文件 |
关键直觉：前台入口不能自己发明规则，后台处理器不能猜 payload，所有稳定规则都应该沉到 shared。