源码索引
这一页把书里出现的关键源码入口集中列出来。阅读时建议打开对应文件，对照章节中的运行链路看。
根配置
| 文件 | 读它是为了理解什么 |
|---|---|
package.json | 根脚本、Node 版本、pnpm 版本、Turbo 入口。 |
pnpm-workspace.yaml | 哪些目录被纳入 workspace。 |
turbo.json | build、dev、lint、typecheck、test 的任务关系和缓存策略。 |
docker-compose.yml | 本地完整自托管栈：web、worker、Postgres、ClickHouse、Redis、MinIO。 |
docker-compose.dev.yml | 本地开发依赖栈：通常只起数据设施，web/worker 从源码跑。 |
.agents/ARCHITECTURE_PRINCIPLES.md | 仓库内的架构原则和约束。 |
Web 层
| 文件或目录 | 读它是为了理解什么 |
|---|---|
web/src/pages | Next.js pages router 入口。 |
web/src/features | 主要业务功能的 UI 和局部服务端组织。 |
web/src/components/table/data-table.tsx | 通用表格抽象。 |
web/src/components/table/types.ts | 表格列、状态和行为类型。 |
web/src/features/tracing-tables/README.md | tracing tables 的组织原则。 |
web/src/features/search-bar/README.md | 搜索语法、FilterState 和跨视图扩展契约。 |
web/src/styles/globals.css | Tailwind token、颜色变量和基础样式。 |
web/src/server/api/root.ts | tRPC router 聚合入口。 |
web/src/server/api/trpc.ts | procedure、context、鉴权和项目权限约束。 |
web/src/pages/api/public/ingestion.ts | 普通 ingestion batch API：auth、rate limit、events_only 过滤和 processEventBatch 调用。 |
web/src/pages/api/public/events.ts | /events endpoint 如何包装成 legacy OBSERVATION_CREATE。 |
web/src/pages/api/public/otel/v1/traces/index.ts | OTel trace ingestion：raw body、gzip、JSON/Protobuf、SDK header 和 OTel queue 发布。 |
web/src/features/public-api/server/withMiddlewares.ts | Public API 的 method、CORS、错误处理包装。 |
web/src/features/public-api/server/createAuthedProjectAPIRoute.ts | API key、scope、rate limit 和 schema 校验入口。 |
web/src/features/public-api/README.md | 新增 Public API 的开发流程。 |
web/src/features/evals | evaluator 配置 UI、tRPC router、unstable public API、target/mapping 表单。 |
web/src/features/experiments | experiment 列表、comparison、metrics 和 run/item score 展示。 |
web/src/features/experiments/server/router.ts | Prompt Experiment 如何要求 prompt/dataset/model config，创建 DatasetRun 并投递 experiment create 队列。 |
web/src/features/datasets/server/publicDatasetService.ts | SDK/API 如何创建 DatasetRunItem，把外部 runtime 产生的 trace 连接到 dataset run。 |
web/src/features/datasets/server/dataset-router.ts | Remote Experiment webhook 的配置和触发入口。 |
web/src/features/score-analytics | score analytics 的 tRPC 查询、数据转换、图表和双 score 比较 UI。 |
Shared 契约层
| 文件或目录 | 读它是为了理解什么 |
|---|---|
packages/shared/src/domain/observations.ts | observation domain model。 |
packages/shared/src/domain/traces.ts | trace domain model。 |
packages/shared/src/domain/scores.ts | score domain model。 |
packages/shared/src/domain/score-configs.ts | score config 的数据类型、分类值和取值范围约束。 |
packages/shared/src/domain/dataset-run-items.ts | dataset run item 的运行结果连接模型。 |
packages/shared/src/server/llm/types.ts | ExperimentMetadataSchema：当前 Prompt Experiment 的 run metadata 契约。 |
packages/shared/src/features/evals/types.ts | evaluator target、变量映射和 legacy/new eval 语义。 |
packages/shared/src/features/evals/observationForEval.ts | observation/experiment evaluator 的执行输入快照格式。 |
packages/shared/src/server/queues.ts | 队列名、job 名、payload schema。 |
packages/shared/src/server/redis/** | BullMQ queue class、sharding、Redis 短期状态。 |
packages/shared/src/server/ingestion/processEventBatch.ts | ingestion 请求侧批量处理和入队。 |
packages/shared/src/server/ingestion/types.ts | ingestion event types、Zod schema、usage/cost/environment 规范化。 |
packages/shared/src/server/clickhouse/schemaUtils.ts | eventTypes 到 trace/observation/score/dataset_run_item 的实体映射。 |
packages/shared/src/server/otel/OtelIngestionProcessor.ts | OTel ResourceSpan 到 Langfuse ingestion events / v4 event inputs 的转换。 |
packages/shared/src/interfaces/filters.ts | FilterState、filter operator 和事件表筛选结构。 |
packages/shared/src/server/queries/clickhouse-sql/event-query-builder.ts | v4 events 查询构造器。 |
packages/shared/src/server/repositories/definitions.ts | ClickHouse record read/insert schema。 |
packages/shared/src/server/repositories/experiments.ts | experiment 查询、run/item 指标和 score 聚合。 |
packages/shared/src/server/repositories/scores.ts | trace/session/experiment/score analytics 使用的 score 查询入口。 |
packages/shared/prisma/schema.prisma | Postgres schema 源头。 |
packages/shared/clickhouse/migrations | ClickHouse schema 迁移。 |
packages/shared/clickhouse/scripts/dev-tables.sh | 本地 v4 events_full / events_core 表和 legacy backfill 示例。 |
Worker 层
| 文件或目录 | 读它是为了理解什么 |
|---|---|
worker/src/app.ts | worker 启动和队列注册。 |
worker/src/queues | 各队列 processor。 |
worker/src/queues/workerManager.ts | BullMQ Worker 注册、metrics、OpenTelemetry 和 failed/stalled hooks。 |
worker/src/queues/ingestionQueue.ts | ingestion job 消费流程。 |
worker/src/queues/otelIngestionQueue.ts | OTel ingestion job 消费、legacy/v4 direct write 决策和 observation eval 调度。 |
worker/src/queues/eventPropagationQueue.ts | v4 event propagation repeat job 的 worker processor。 |
worker/src/services/IngestionService/index.ts | 事件转换和写入准备。 |
worker/src/services/ClickhouseWriter/index.ts | ClickHouse 批量写入队列。 |
worker/src/features/eventPropagation/handleEventPropagationJob.ts | observations_batch_staging 按分区补写 events_full 的主逻辑。 |
worker/src/features/eventPropagation/handleExperimentBackfill.ts | 根据 dataset_run_items_rmt 回填 experiment 字段到 events_full。 |
worker/src/features/evaluation/evalService.ts | legacy trace/dataset evaluator 调度和 LLM-as-a-Judge 执行核心。 |
worker/src/features/evaluation/observationEval | observation/experiment evaluator 的新调度和执行路径。 |
worker/src/features/evaluation/evalScoreEvent.ts | evaluator 输出如何转换成标准 SCORE_CREATE 事件。 |
worker/src/features/evaluation/evalCompletion.ts | evaluator 完成后如何写 score、更新 JobExecution。 |
worker/src/features/experiments/experimentServiceClickhouse.ts | prompt experiment 如何创建 dataset run item、trace 和 observation。 |
部署与 K8s
| 文件或目录 | 读它是为了理解什么 |
|---|---|
web/Dockerfile | Langfuse Web 镜像构建、运行时文件和 entrypoint。 |
web/entrypoint.sh | Postgres/ClickHouse 自动迁移和 web 启动边界。 |
worker/Dockerfile | Langfuse Worker 镜像构建和运行入口。 |
worker/entrypoint.sh | Worker 容器如何拼接数据库环境并启动。 |
../langfuse-k8s/charts/langfuse/Chart.yaml | Helm chart dependency：Postgres、ClickHouse、Valkey、MinIO。 |
../langfuse-k8s/charts/langfuse/values.yaml | web/worker、数据库、Redis、S3、扩缩容和 secret 配置入口。 |
../langfuse-k8s/charts/langfuse/templates/web/deployment.yaml | Web Deployment 的 env、probe、Service 端口和副本配置。 |
../langfuse-k8s/charts/langfuse/templates/worker/deployment.yaml | Worker Deployment 的 env、probe、端口和副本配置。 |
../langfuse-k8s/charts/langfuse/templates/_helpers.tpl | Helm values 如何生成 DATABASE_*、CLICKHOUSE_*、REDIS_*、LANGFUSE_S3_*。 |
../langfuse-docs/content/self-hosting/deployment/kubernetes-helm.mdx | 官方 K8s Helm 部署教程。 |
../langfuse-docs/content/self-hosting/configuration/scaling.mdx | 官方 sizing、worker 扩缩容和高吞吐建议。 |
API Contract 和生成文件
| 文件或目录 | 读它是为了理解什么 |
|---|---|
fern/apis | Public API 定义源头。 |
generated | 生成后的 API client 或产物，只读。 |
web/src/features/public-api/types | Web 侧 Public API 类型桥接。 |
web/src/pages/api/public | Public API route 入口。 |
文档站点本身
| 文件或目录 | 读它是为了理解什么 |
|---|---|
.vitepress/config.mts | 本书站点的导航、sidebar、搜索和主题配置。 |
index.md | 站点首页。 |
part00-preface 到 part08-labs | 按参考教程结构拆分的正文和实验课。 |
part03-architecture/06-data-model-visuals.md | 数据结构图谱：实体关系、存储落点、observation tree、v4 抽象变化。 |
part03-architecture/08-entity-business-relations.md | 业务实体关系：Observation、Trace、Session、Dataset、Experiment、Score、Evaluator 的组合方式。 |
part03-architecture/07-deployment-k8s.md | 部署结构：Docker Compose 到 Kubernetes Helm 的对象映射和生产差距。 |
part09-subsystems | 子系统精读模板、Ingestion / Event Store 子系统、Experiment 子系统、Evaluation 子系统完整链路。 |
architecture/langfuse-current-architecture.drawio | 中文 draw.io 架构图 XML 源文件。 |
public/architecture/langfuse-current-architecture.drawio | 在线站点可直接访问的 draw.io XML。 |
architecture/skills-eval-system-architecture.drawio | Skills Eval 技术方案总览 draw.io XML 源文件。 |
public/architecture/skills-eval-system-architecture.drawio | 在线站点可直接访问的 Skills Eval draw.io XML。 |
langfuse-repo-guide.md | 早期单页长文版，可作为浓缩参考。 |