🪢 Langfuse 图解教程Langfuse Visual Guide 第二部分 · 前置基础Part 2 · Foundations 07 / 55
第二部分 · 前置基础Part 2 · Foundations

双存储架构The dual-store architecture

🧭 读前Before you start
先读 第2课 的宽事件理念,本课讲为什么要 Postgres + ClickHouse 双存储。
Read Lesson 2 on wide events; this lesson explains why there are two stores — Postgres + ClickHouse.

上一课,数据以「事件」的形式离开了你的应用。这一课讲它们最终落在哪。很多人以为一个数据库就够了,但 Langfuse 用了四种存储—— Postgres、ClickHouse、Redis、S3,各管一摊。这不是炫技,而是因为不同数据的访问模式天差地别:用错存储,热路径会被活活拖垮。 看懂这四者的分工,你就理解了 Langfuse 性能与可扩展性的地基。

🔌 生活类比
把这四种存储想成一家公司的四种「存放方式」:Postgres 是文件柜——放重要档案(谁是员工、项目配置),要求准、可改、查得快,但量不大; ClickHouse 是巨型货仓——堆放海量货物(每天上亿条事件),要的是按品类批量盘点的能力;Redis 是传送带 + 暂存台—— 货物先上传送带排队(队列),常用的小东西放手边随手取(缓存);S3 是外部仓储——存又大又不常翻的原件(事件底稿、上传的图片、导出的大文件)。 四者各有所长,硬塞进一个,必然顾此失彼。看懂这四种存储分别擅长什么、为什么这么分,是理解后面摄取与查询两条链路的前提。
两个容器,四种存储,各司其职 webUI · API worker后台处理 Postgres配置/元数据事务·强一致·量小 ClickHouse宽事件 trace/obs/score列存·海量·聚合快 Redis队列(BullMQ) + 缓存内存·极快·临时 S3 / blob事件底稿·媒体·导出对象存储·大·便宜 web 主要读 PG(配置)+CH(分析);worker 主要写 CH/S3、用 Redis 队列
四种存储的分工:Postgres=配置/元数据(事务、强一致、量小);ClickHouse=宽事件(列存、海量、聚合快);Redis=队列+缓存(内存、极快、临时);S3=事件底稿/媒体/导出(对象存储、大、便宜)。web 偏读、worker 偏写,但都按数据性质选对应的库。
四存储各就各位:按「性质」选库 纵轴:结构化行(上)↔ 批量对象(下) ← OLTP · 事务/控制面(小而一致) OLAP · 分析/数据面(海量) → Postgres · 控制面org/project/user · apiKey · promptdataset/eval 配置 · 定价 · 集成事务、强一致、量小、改得频 ClickHouse · 数据面traces / observations / scores 三宽表列存、海量、聚合飞快ReplacingMergeTree、按 project_id 排序 Redis · 队列 + 缓存摄取队列(BullMQ)· prompt 缓存内存、极快、临时削峰解耦:写路径塞进去就返回 S3 · 负载 + 媒体事件原文 <eventId>.json · 媒体 · 导出对象存储、便宜、能装大块「真账本」:任务丢了也能从这里重建
不是「主从」,是「分工」(依据 prisma/schema.prisma、CH 迁移、server/queues.ts、媒体服务):横轴是事务↔分析,纵轴是结构化行↔批量对象。Postgres 管「怎么配置」、ClickHouse 管「发生了什么」、Redis 削峰、S3 兜底原件——每条数据按它的性质落到对应象限。

为什么不能只用一个

核心原因一句话:事务型负载(OLTP)和分析型负载(OLAP)是两种相反的优化目标,没有哪个库能同时把两头都做到极致。

🗄️ Postgres 擅长(OLTP)

精确读写单条、强一致、外键关系、事务。适合小而重要、要立刻可用的配置类数据。不适合:海量行的聚合扫描。

📊 ClickHouse 擅长(OLAP)

对海量行的某几列做时间窗口扫描 + 聚合,列存 + 压缩。适合巨量、追加写、按维度统计的遥测数据。不适合:频繁改单条 + 强一致。

如果硬把遥测塞进 Postgres,海量行 + 频繁聚合会让它不堪重负;反过来把配置塞进 ClickHouse,它的弱事务、最终一致又满足不了「创建即可用」。 所以 Langfuse 的选择不是「贪多」,而是让每种数据待在最适合它的库里——这正是第 2 课「按列式访问设计」「谨慎反范式化」等原则在存储层的总落点。

OLTP(Postgres):精确取单条 OLAP(ClickHouse):扫一片再聚合 WHERE id = 'x' → 命中这一行 读一条 · 毫秒 · 强一致 扫上亿行的某几列 · 按维度聚合 · 列存才扛得住
两种相反的访问模式:OLTP 靠索引精确命中一行(读配置、改设置);OLAP 要扫一大片行的某几列再聚合(按时间/模型统计成本)。行存数据库擅长前者,列存数据库擅长后者——这就是为什么配置归 Postgres、遥测归 ClickHouse。

四个存储各管什么

存储装什么仓库里的客户端
Postgresorg/project/user、API key、prompt、eval 配置、定价…(控制面)packages/shared/src/db.ts(Prisma)
ClickHousetraces / observations / scores 三张宽事件表(数据面).../server/clickhouse/client.ts
RedisBullMQ 队列(解耦摄取)+ 缓存(如 prompt、eval 配置).../server/redis/redis.ts
S3 / blob事件原始底稿(支撑合并/重放)、多模态媒体、批量导出.../server/s3/index.ts

注意一个细节:S3 不只是「存大文件」。摄取链路里,每个进来的事件先落 S3,worker 合并时再回 S3 取历史(第 5、15 课)——S3 在这里扮演的是 「事件日志 / 真相之源」的角色。ClickHouse 里的宽事件,本质上是 S3 事件底稿合并后的「物化视图」:万一 ClickHouse 数据需要重建, 理论上可以从 S3 的原始事件重放出来。这种「原始日志 + 派生表」的分工,正是第 2 课「不可变 / 追加式事件」原则的体现。

控制面Postgres
谁能用、配置成什么样:org/project/user、API key、prompt、eval 配置、定价。改动少而关键,要强一致。
数据面ClickHouse
实际的遥测洪流:trace/observation/score 三张宽事件表。海量、追加、按维度聚合。
传输Redis
把摄取异步化的队列,加上热点配置的缓存。内存级、临时、极快。
对象存储S3 / blob
事件真相之源、上传媒体、批量导出。又大又不常翻的东西放这里,便宜耐放。

这四层在运行时是协作的,不是各自孤立。回想第 5 课那条链路:摄取时,事件先进 Redis 队列、原件落 S3,worker 合并后写 ClickHouse; 而合并时要知道「这个 observation 关联哪版 prompt」「按什么模型定价」,又要回 Postgres 查配置。一次摄取,四种存储各出一份力。读取时也类似:UI 列表查 ClickHouse, 但「这个项目叫什么、谁有权限」来自 Postgres,热点配置走 Redis 缓存。所以理解 Langfuse,本质上就是理解数据如何在这四种存储之间流动—— 这也是为什么本指南的第二部分要专门用一课讲存储分工:它是后面所有链路课的共同底座。

🎯 设计取舍
四个存储 = 四份运维负担,为什么还要这么拆? 第 2 课有一条原则:「把成本与运维简单性当作架构约束」——多一个数据库就要多一份备份、监控、升级、容灾。 Langfuse 之所以仍坚持四存储,是因为每一个都在解决一个单一存储解决不了的硬问题:没有 ClickHouse,海量聚合查询会慢到不可用;没有 Redis 队列,摄取就无法异步抗洪峰; 没有 S3,大字段和媒体会把数据库撑爆、也无法重放。换句话说,这四个不是「想加就加」,而是各自挣到了自己的存在。这也是判断「该不该再加一个存储」的标准—— 它解决的问题,是否值得它带来的长期运维成本。

同一个 project:两侧各存一半

把抽象落到真实表上:同一个 project,控制面在 Postgres 里是一个可改的行(配置、关系、强一致),数据面在 ClickHouse 里则化身为一张宽事件表(append、列存、后写覆盖)。两侧靠同一把 project_id 缝合——左边定义它,右边用它分区和排序。

Postgres · 控制面(OLTP) 行存 · 强一致 · 可改可删 · 精确单条 projects · organizations(配置/枢纽) api_keys · memberships(鉴权/权限) datasets · prompts(产品配置) dashboards · automations(控制面) ClickHouse · 数据面(OLAP) 列存 · append · 后写覆盖 · 海量扫描聚合 traces (一次调用的根) observations (每一步 LLM/工具) scores (评估/评分) ReplacingMergeTree · ORDER BY(project_id, date, id) 同一把 project_id 贯穿两侧:左边定义它,右边用它分区 + 排序
prisma/schema.prisma · clickhouse/migrations/unclustered/0001_traces.up.sql控制面 vs 数据面
// ── 控制面:Postgres 里 project 是一个「可改的行」(schema.prisma)──
model Project {
  id            String  @id @default(cuid())
  orgId         String  @map("org_id")
  name          String
  retentionDays Int?    @map("retention_days")   // 配置:强一致、随时可改
  apiKeys       ApiKey[]                          // 关系:OLTP 按主键精确取
}

-- ── 数据面:ClickHouse 里同一 project 的 trace 是「宽事件行」(0001_traces.up.sql)──
CREATE TABLE traces (
  `id` String,
  `timestamp` DateTime64(3),
  `project_id` String,                            -- 同一把 project_id
  ...
) ENGINE = ReplacingMergeTree(event_ts, is_deleted)
  PARTITION BY toYYYYMM(timestamp)               -- 按月裁剪
  ORDER BY (project_id, toDate(timestamp), id); -- project 内连续聚簇
🎯 本课要点
  • 四种存储各管一摊:Postgres(配置/元数据·OLTP)、ClickHouse(宽事件·OLAP)、Redis(队列+缓存)、S3(事件底稿+媒体+导出)。
  • 核心理由:OLTP 与 OLAP 是相反的优化目标,配置要精确单条+强一致,遥测要海量扫描+聚合,必须分库。
  • S3 是「真相之源」:事件先落 S3,ClickHouse 的宽事件是其合并后的派生表,可重放。
  • 控制面(Postgres)vs 数据面(ClickHouse)的划分,是第 3 课「领域形状 vs 物理存储」的宏观版。
  • 四存储不是堆技术,而是各自挣到了存在——这也是「该不该再加一个存储」的判断标准。

🧪 自测 · 想一想为什么这么设计

1. 为什么 Langfuse 把配置/元数据放 Postgres、把 trace/observation/score 放 ClickHouse,而不是统一用一个库?
  1. 因为 ClickHouse 不能存字符串
  2. 纯粹为了用更多技术
  3. 因为 Postgres 不支持索引
  4. 因为两者是相反的负载:配置是 OLTP(小、精确单条读写、强一致),遥测是 OLAP(海量、按时间窗口+维度聚合);没有哪个库能把两头都做到极致
看答案与解析 点击展开
答案:D。配置要精确读写单条且强一致(创建即可用),是行存 Postgres 的主场;遥测海量、写多于改、按维度聚合,是列存 ClickHouse 的主场。硬塞进一个必然顾此失彼。这是“按访问模式选存储”。
2. 在摄取链路里,S3 扮演的关键角色是什么?
  1. 事件的“真相之源/原始日志”:事件先落 S3,worker 合并时回 S3 取历史;ClickHouse 的宽事件相当于其合并后的派生表,理论上可从 S3 重放重建
  2. 只是存上传的图片,和摄取无关
  3. 存用户密码
  4. 代替 Redis 做队列
看答案与解析 点击展开
答案:A。S3 不只是大文件仓。事件先落 S3 作为不可变原始日志,worker 据此合并出 ClickHouse 宽事件(派生/物化)。这正是第 2 课“不可变/追加式事件”的体现,也让数据可重放重建。
3. Langfuse 用四种存储,但第 2 课又说“把运维简单性当约束”。怎么调和?判断“该不该再加一个存储”的标准是什么?
  1. 由前端框架决定
  2. 永远只能用一个数据库
  3. 每个存储都必须挣到自己的存在——它解决的硬问题是否值得它带来的长期运维成本(备份/监控/升级/容灾)
  4. 存储越多越好,多多益善
看答案与解析 点击展开
答案:C。四存储不是“想加就加”:ClickHouse 解决海量聚合、Redis 解决异步抗洪峰、S3 解决大字段+重放,各自解决单库做不到的硬问题,所以挣到了存在。这也正是判断要不要再加存储的标准。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 想象你在设计一个新的日志/监控系统,预算有限。你会从一个 Postgres 起步,还是一开始就上 ClickHouse?在什么规模/查询模式下,引入列存才真正“挣到存在”?

Last lesson, data left your app as "events". This lesson is about where it lands. Many assume one database suffices, but Langfuse uses four stores — Postgres, ClickHouse, Redis, S3 — each for its own job. Not showing off: different data has wildly different access patterns, and the wrong store will crush the hot path. Understand the division of labor and you understand the foundation of Langfuse's performance and scalability.

🔌 Analogy
Picture the four stores as a company's four "ways to keep things": Postgres is the filing cabinet — important records (who's an employee, project config), needing to be accurate, editable, quick to look up but not huge; ClickHouse is the giant warehouse — mountains of goods (hundreds of millions of events a day), needing bulk stock-taking by category; Redis is the conveyor belt + staging table — goods queue on the belt (queues), and frequently-used small items stay at hand (cache); S3 is off-site storage — big, rarely-flipped originals (event manuscripts, uploaded images, large exports). Each excels at its own; cram them into one and you lose.
Two containers, four stores, each its own job webUI · API workerbackground Postgresconfig/metadatatxn·consistent·small ClickHousewide eventscolumnar·huge·fast agg Redisqueue(BullMQ)+cachein-memory·fast·temp S3 / blobevent log·media·exportobject store·big·cheap web mostly reads PG(config)+CH(analytics); worker mostly writes CH/S3, uses the Redis queue
The four stores' division of labor: Postgres=config/metadata (txn, consistent, small); ClickHouse=wide events (columnar, huge, fast aggregation); Redis=queue+cache (in-memory, fast, temporary); S3=event manuscript/media/exports (object store, big, cheap). web leans read, worker leans write, but both pick the store that fits the data.
Four stores, each in its place: pick by nature y-axis: structured rows (top) ↔ bulk objects (bottom) ← OLTP · transactional/control (small, consistent) OLAP · analytical/data (huge) → Postgres · control planeorg/project/user · apiKey · promptdataset/eval config · pricing · integrationstransactional, consistent, small, edited often ClickHouse · data planetraces / observations / scores wide tablescolumnar, huge, fast aggregationReplacingMergeTree, sorted by project_id Redis · queue + cacheingestion queue (BullMQ) · prompt cachein-memory, very fast, ephemeralabsorb spikes: write path pushes and returns S3 · payloads + mediaevent source <eventId>.json · media · exportsobject store, cheap, holds big blobsthe source of truth: rebuild if a job is lost
Not "primary/replica", but division of labor (per prisma/schema.prisma, CH migrations, server/queues.ts, the media service): the x-axis is transactional↔analytical, the y-axis structured rows↔bulk objects. Postgres governs "how it's configured", ClickHouse "what happened", Redis absorbs spikes, S3 backstops the originals — each datum lands in the quadrant that fits its nature.

Why not just one

The core reason in one line: transactional (OLTP) and analytical (OLAP) workloads are opposite optimization targets, and no single store nails both extremes.

🗄️ Postgres is good at (OLTP)

precise single-row read/write, strong consistency, foreign keys, transactions. Fits small, important, must-be-instant config data. Bad at: aggregating scans over huge rows.

📊 ClickHouse is good at (OLAP)

time-window scans + aggregation over a few columns of huge rows, columnar + compressed. Fits massive, append-write, dimensional telemetry. Bad at: frequent single-row edits + strong consistency.

Cram telemetry into Postgres and huge rows + frequent aggregation overwhelm it; cram config into ClickHouse and its weak transactions, eventual consistency fail "instantly usable". So Langfuse isn't being greedy — it's letting each kind of data live in the store that fits it best, the storage-layer landing point of Lesson 2's "design around columnar access" and "denormalize carefully".

OLTP (Postgres): fetch one row OLAP (ClickHouse): scan a slice + aggregate WHERE id = 'x' → hits this row one row · ms · strongly consistent scan a few columns of millions of rows · aggregate · needs columnar
Two opposite access patterns: OLTP uses an index to hit exactly one row (read config, change settings); OLAP must scan a few columns of a big slice of rows and aggregate (cost by time/model). Row stores excel at the former, columnar at the latter — which is why config goes to Postgres and telemetry to ClickHouse.

What each store holds

StoreHoldsClient in the repo
Postgresorg/project/user, API keys, prompts, eval config, pricing… (control plane)packages/shared/src/db.ts (Prisma)
ClickHousetraces / observations / scores — three wide-event tables (data plane).../server/clickhouse/client.ts
RedisBullMQ queues (decouple ingestion) + cache (e.g. prompts, eval config).../server/redis/redis.ts
S3 / blobraw event manuscript (for merge/replay), multimodal media, bulk exports.../server/s3/index.ts

One detail: S3 isn't just "big-file storage". In the ingestion path, each incoming event lands in S3 first, and the worker re-reads S3 when merging (L05, L15) — here S3 plays the "event log / source of truth" role. The wide events in ClickHouse are essentially a "materialized view" of the merged S3 manuscripts: if ClickHouse data ever needs rebuilding, it can in principle be replayed from the raw S3 events. This "raw log + derived table" split is Lesson 2's "immutable / append-oriented events" in action.

control planePostgres
who can use it, configured how: org/project/user, API keys, prompts, eval config, pricing. Few but critical changes, needs strong consistency.
data planeClickHouse
the actual telemetry flood: traces/observations/scores wide-event tables. Huge, append, dimensional aggregation.
transportRedis
the queue that makes ingestion async, plus a cache for hot config. In-memory, temporary, very fast.
object storeS3 / blob
the event source of truth, uploaded media, bulk exports. Big, rarely-flipped things live here — cheap and durable.

These four layers collaborate at runtime, not in isolation. Recall Lesson 5's path: on ingestion, events first enter the Redis queue and originals land in S3; after merging the worker writes ClickHouse; and to merge it must know "which prompt version this observation links to" and "what model pricing applies", so it reads config back from Postgres. One ingestion, four stores each pulling their weight. Reads are similar: the UI list queries ClickHouse, but "what's this project called, who has access" comes from Postgres, and hot config goes through the Redis cache. So understanding Langfuse is essentially understanding how data flows among these four stores — which is why Part 2 spends a whole lesson on the storage division of labor: it's the shared foundation of every later path lesson.

🎯 Design trade-off
Four stores = four operational burdens, so why split this much? Lesson 2 has a principle: "treat cost and operational simplicity as constraints" — each extra database means more backups, monitoring, upgrades, DR. Langfuse still keeps four because each solves a hard problem a single store can't: without ClickHouse, huge aggregation queries are unusably slow; without the Redis queue, ingestion can't go async to absorb spikes; without S3, big fields and media bloat the database and you can't replay. In other words, these four aren't "add because we can" — each earned its existence. That's also the test for "should we add another store": does the problem it solves justify its long-term operational cost?

One project: each side stores half

Grounding the abstraction in real tables: the same project lives in Postgres as an editable row (config, relations, strong consistency) and in ClickHouse as a wide-event table (append, columnar, later-write-wins). The two halves are stitched by the same project_id — the left side defines it, the right side partitions and sorts by it.

Postgres · control plane (OLTP) row store · strong consistency · editable projects · organizations (config/hub) api_keys · memberships (auth/perms) datasets · prompts (product config) dashboards · automations (control) ClickHouse · data plane (OLAP) columnar · append · later-wins · scan+aggregate traces (root of one call) observations (each LLM/tool step) scores (evals/grades) ReplacingMergeTree · ORDER BY(project_id, date, id) the same project_id runs through both: the left defines it, the right partitions + sorts by it
prisma/schema.prisma · clickhouse/migrations/unclustered/0001_traces.up.sqlcontrol plane vs data plane
// ── Control plane: in Postgres a project is an "editable row" (schema.prisma) ──
model Project {
  id            String  @id @default(cuid())
  orgId         String  @map("org_id")
  name          String
  retentionDays Int?    @map("retention_days")   // config: strongly consistent, editable anytime
  apiKeys       ApiKey[]                          // relation: OLTP fetches by key
}

-- ── Data plane: in ClickHouse the same project's trace is a "wide-event row" (0001_traces.up.sql) ──
CREATE TABLE traces (
  `id` String,
  `timestamp` DateTime64(3),
  `project_id` String,                            -- the same project_id
  ...
) ENGINE = ReplacingMergeTree(event_ts, is_deleted)
  PARTITION BY toYYYYMM(timestamp)               -- prune by month
  ORDER BY (project_id, toDate(timestamp), id); -- clustered within a project
🎯 Key points
  • Four stores, each its own job: Postgres (config/metadata·OLTP), ClickHouse (wide events·OLAP), Redis (queue+cache), S3 (event manuscript+media+exports).
  • Core reason: OLTP and OLAP are opposite targets — config needs precise single-row + strong consistency, telemetry needs massive scan + aggregation, so split stores.
  • S3 is the "source of truth": events land in S3 first; ClickHouse wide events are the merged derived table, replayable.
  • Control plane (Postgres) vs data plane (ClickHouse) is the macro version of Lesson 3's "domain shape vs physical storage".
  • Four stores aren't tech-stacking — each earned its existence, which is also the test for "should we add another store".

🧪 Self-test - think about the design

1. Why does Langfuse put config/metadata in Postgres and trace/observation/score in ClickHouse, rather than one database for all?
  1. Because ClickHouse can't store strings
  2. Purely to use more tech
  3. Because Postgres has no indexes
  4. Because they're opposite workloads: config is OLTP (small, precise single-row, strongly consistent), telemetry is OLAP (massive, time-window + dimensional aggregation); no single store nails both extremes
Show answer & explanation click to expand
Answer: D. Config needs precise single-row read/write and strong consistency (instantly usable) — row-store Postgres's turf; telemetry is massive, write-mostly, dimensionally aggregated — columnar ClickHouse's turf. Forcing one store loses both ways. This is 'choose storage by access pattern'.
2. What key role does S3 play in the ingestion path?
  1. The events' 'source of truth / raw log': events land in S3 first, the worker re-reads S3 to merge; ClickHouse wide events are the merged derived table, in principle replayable from S3
  2. Just stores uploaded images, unrelated to ingestion
  3. Stores user passwords
  4. Replaces Redis as the queue
Show answer & explanation click to expand
Answer: A. S3 isn't just a big-file store. Events land in S3 as an immutable raw log, from which the worker merges ClickHouse wide events (derived/materialized). This is L02's 'immutable/append-oriented events', and makes data replayable.
3. Langfuse uses four stores, yet L02 says 'treat operational simplicity as a constraint'. How to reconcile? What's the test for 'should we add another store'?
  1. The frontend framework decides
  2. You may only ever use one database
  3. Each store must earn its existence — does the hard problem it solves justify its long-term ops cost (backup/monitoring/upgrade/DR)
  4. More stores are always better
Show answer & explanation click to expand
Answer: C. The four aren't 'add because we can': ClickHouse solves huge aggregation, Redis solves async spike absorption, S3 solves big fields + replay — each solving what one store can't, thus earning its place. That's exactly the test for adding another store.
💭 Open questions (no single right answer - just think or try)
  • Imagine designing a new logging/monitoring system on a tight budget. Would you start with one Postgres, or bring in ClickHouse from day one? At what scale/query pattern does a columnar store truly 'earn its existence'?