项目概述

Langfuse 项目采用 Monorepo（单体仓库）架构，使用 pnpm 作为包管理器进行多包管理。项目的核心依赖和配置信息集中在根目录的 package.json 中定义，通过 pnpm workspace 机制管理多个子项目。资料来源：package.json:1-50

技术栈概览

Langfuse 的技术栈涵盖前后端多个层面：

graph TD
    A[Langfuse Monorepo] --> B[web/ - 前端应用]
    A --> C[worker/ - 后端 Worker]
    A --> D[packages/shared/ - 共享包]
    B --> E[React Components]
    B --> F[Feature Modules]
    C --> G[Queue Processors]
    C --> H[Data Ingestion]
    D --> I[Shared Types]
    D --> J[Validation Schemas]

架构设计

Monorepo 结构

Langfuse 采用 pnpm workspace 实现的 Monorepo 架构，主要包含以下几个核心包：

• web: 前端 Next.js 应用，包含 UI 组件系统和业务功能模块
• worker: 后端 Worker 服务，处理数据摄取、队列管理和事件处理
• packages/shared: 前后端共享的类型定义、验证模式和业务接口

资料来源：package.json:20-40

前端架构分层

前端代码遵循清晰的分层设计原则：

graph TB
    subgraph web/src/components
        A[layouts/ - 页面布局组件]
        B[design-system/ - 基础设计系统]
        C[ui/ - 通用 UI 组件]
        D[table/ - 表格组件]
    end
    
    subgraph web/src/features
        E[entitlements/ - 权限系统]
        F[feature-flags/ - 功能开关]
        G[mcp/ - MCP 服务器]
        H[score-analytics/ - 分数分析]
        I[filters/ - 过滤器系统]
        J[comments/ - 评论功能]
    end
    
    A --> B
    B --> C
    D --> C
    E --> F

#### 布局系统 (layouts)

Page 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和适当的滚动行为。所有页面必须包装在 <Page> 组件内，不能直接使用 <main> 元素。

关键特性：

• 封装的粘性头部 - 防止布局不一致
• 滚动管理 - 支持 "content-scroll" 和 "page-scroll" 两种模式
• 标准化的内边距和布局
• 面包屑导航支持
• 自定义头部操作区域

资料来源：web/src/components/layouts/README.md:1-30

#### 设计系统 (design-system)

设计系统文件夹包含可复用的、原始的、展示性质的 UI 组件。设计原则如下：

组件规范：

• 一个组件一个文件
• 使用 CVA (Class Variance Authority) 管理变体
• 使用显式枚举定义尺寸和变体类型
• 布尔属性使用 is/should 前缀命名

资料来源：web/src/components/design-system/README.md:1-50

核心功能模块

权限系统 (entitlements)

Entitlements 系统用于控制功能的可用性，基于组织 (organization) 级别进行管理。

核心概念：

• Plan（套餐）: 功能层级的划分，如 oss、cloud:pro、self-hosted:enterprise
• Entitlement（权限）: 用户可用的功能特性，如 playground
• EntitlementLimit（权限限制）: 资源数量限制，如 annotation-queue-count

权限使用方式：

资料来源：web/src/features/entitlements/README.md:1-35

功能开关 (feature-flags)

Feature Flags 允许在运行时动态控制功能启用状态。

功能开关启用条件（满足任一即可）：

1. 用户在 user.feature_flags 中包含该标志
2. 环境变量 LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES 被设置
3. 用户具有管理员权限 (user.admin === true)

const isFeatureEnabled = useIsFeatureEnabled("feature-flag-name");

资料来源：web/src/features/feature-flags/README.md:1-15

MCP 服务器 (mcp)

Langfuse MCP 服务器提供了 6 个 Prompt 管理工具，采用无状态按请求架构：

架构特点：

• 每个 MCP 请求创建新的服务器实例
• 认证上下文通过闭包捕获
• 请求完成后服务器被丢弃
• 请求间无状态共享

graph LR
    A[MCP Client] -->|Request| B[New Server Instance]
    B --> C[Handler with Auth Closure]
    C --> D[Process Request]
    D --> E[Return Response]
    E --> F[Discard Server]

资料来源：web/src/features/mcp/README.md:1-80

分数分析 (score-analytics)

分数分析模块提供数据分析和可视化功能。

#### 关键组件

#### 数据转换管道

API Response → Extract Categories → Fill Distribution Bins → 
Generate Bin Labels → Transform Heatmap → Calculate Mode Metrics →
Fill Time Series Gaps → Namespace Categorical → Final Output

#### 统计分析工具

s statistics-utils.ts 提供了多种统计分析函数：

资料来源：web/src/features/score-analytics/README.md:1-60

分数接口系统 (scores/interfaces)

分数接口定义了完整的类型系统，支持多版本 API。

#### API 版本支持

#### 接口目录结构

interfaces/
├── api/
│   ├── v1/        # 遗留 API 类型
│   ├── v2/        # 当前 API 类型
│   └── shared.ts  # 共享模式
├── application/   # 应用层验证
├── ingestion/     # 摄取类型
└── ui/            # UI 专用类型

资料来源：packages/shared/src/features/scores/interfaces/README.md:1-40

过滤器系统 (filters)

过滤器系统提供灵活的查询条件编码和解码功能。

支持的过滤类型：

资料来源：web/src/features/filters/lib/filter-query-encoding.ts:1-50

表格 peek 功能 (table/peek)

PeekTable 系统允许在侧边栏中预览和查看表格数据，与主表格保持状态同步。

关键 Hook：

状态位置优先级：

1. Peek Context（peek 上下文）
2. URL & Session Storage（URL 和会话存储）

资料来源：web/src/components/table/peek/README.md:1-50

高级 JSON 查看器 (ui/AdvancedJsonViewer)

用于可视化大型 JSON 数据的组件，具备以下能力：

算法特点：

• 所有树操作使用显式基于栈的迭代而非递归
• 支持深度 1000+ 的树结构安全遍历
• 二进制搜索优化 getNodeByIndex 性能

资料来源：web/src/components/ui/AdvancedJsonViewer/README.md:1-80

评论提及功能 (comments/mentionParser)

支持用户提及功能的解析和处理。

提及格式：@DisplayName

核心函数：

资料来源：web/src/features/comments/lib/mentionParser.clienttest.ts:1-30

后端 Worker 系统

事件重放脚本 (replayIngestionEventsV2)

用于将历史事件重新摄取到系统的工具脚本。

主要功能：

• 从 S3 读取历史事件
• 通过 HTTP POST 发送到 Langfuse Host
• 支持检查点恢复
• 内置速率限制和重试机制

事件键格式：

状态码处理：

v1 vs v2 差异：

资料来源：worker/src/scripts/replayIngestionEventsV2/README.md:1-120

队列填充脚本 (refillQueueEvent)

用于从本地机器回填队列事件的实用工具脚本。

使用流程：

1. 创建 ./worker/events.jsonl 文件
2. 配置 .env 环境变量
3. 确保 Redis 连接可达
4. 执行 pnpm run --filter=worker refill-queue-event

环境变量要求：

REDIS_CONNECTION_STRING=redis://:[email protected]:6379
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_USER=clickhouse
CLICKHOUSE_PASSWORD=clickhouse

资料来源：worker/src/scripts/refillQueueEvent/README.md:1-50

依赖管理

pnpm Overrides

项目使用 pnpm overrides 强制管理依赖版本：

资料来源：package.json:55-75

总结

Langfuse 是一个功能完备的 LLM 可观测性平台，其架构设计体现了以下特点：

1. Monorepo 组织：通过 pnpm workspace 高效管理多个相关包
2. 清晰的分层：前端组件与业务逻辑分离，设计系统独立维护
3. 多版本 API 支持：v1/v2 API 并存，保证向后兼容
4. 灵活的扩展机制：Feature Flags 和 Entitlements 支持动态功能控制
5. 完善的工具链：事件重放、队列填充等运维工具完备

该平台适用于需要追踪 AI 应用行为、评估模型性能、管理 Prompt 版本的开发团队。

概述

Langfuse 是一个开源的 LLMOps 平台，采用 Monorepo（单体仓库）架构进行项目管理。整个仓库包含多个子项目，通过 pnpm workspace 进行统一管理和协调。资料来源：package.json

该架构的核心设计目标是：

• 代码共享：在多个包之间共享类型定义、工具函数和业务逻辑
• 统一版本管理：所有子项目保持一致的依赖版本
• 简化开发流程：一次安装即可配置好所有开发环境

Langfuse 的主要子系统包括：

资料来源：package.json

概述

Langfuse 是一个开源的 LLM 工程平台，采用分布式微服务架构设计。系统由多个核心组件构成，包括 Web 前端服务、Worker 后台处理服务、数据存储层和缓存层。这种架构设计实现了前端展示与后端处理的分离，保证了系统的高可用性和可扩展性。

Langfuse 的技术栈涵盖了现代 Web 开发的多个层面：使用 Next.js 构建前端应用、使用 BullMQ 与 Redis 实现异步任务队列、使用 PostgreSQL 存储核心业务数据、使用 ClickHouse 处理分析查询、使用 S3 兼容存储管理事件文件。

核心架构组件

整体架构图

graph TB
    subgraph Client["客户端层"]
        Web[Web 前端<br/>Next.js]
    end

    subgraph API["API 层"]
        TRPC[tRPC API]
    end

    subgraph Worker["Worker 层"]
        Queue[BullMQ 队列]
        Worker[Worker 进程]
    end

    subgraph Storage["存储层"]
        Redis[(Redis<br/>队列/缓存)]
        Postgres[(PostgreSQL<br/>核心数据)]
        ClickHouse[(ClickHouse<br/>分析数据)]
        S3[(S3 存储<br/>事件文件)]
    end

    Web --> TRPC
    TRPC --> Postgres
    TRPC --> Redis
    TRPC --> ClickHouse
    TRPC --> S3
    Queue --> Redis
    Worker --> Queue
    Worker --> Postgres
    Worker --> ClickHouse
    Worker --> Redis
    Worker --> S3

技术栈概览

Web 前端服务

Next.js 应用架构

Web 前端基于 Next.js 框架构建，采用 App Router 架构进行路由管理。前端服务负责用户交互界面、数据展示和 API 调用。

Web 前端的源码位于 web/ 目录，其核心配置文件包括 Next.js 配置和应用程序入口点。

graph LR
    subgraph Web["Web 服务"]
        Next[Next.js App]
        Config[next.config.mjs]
        Components[React 组件]
        Features[Feature 模块]
    end

    subgraph API["后端通信"]
        TRPC[tRPC Client]
        HTTP[REST API]
    end

    Next --> Components
    Next --> Features
    Components --> TRPC
    Features --> TRPC
    TRPC --> HTTP

前端采用模块化设计，将功能划分为独立的 Feature 目录，例如：

• features/prompts - 提示词管理
• features/score-analytics - 评分分析
• features/filters - 过滤功能
• features/mcp - MCP 服务器集成
• features/comments - 评论功能
• features/entitlements - 权限控制

Worker 后台服务

Worker 应用架构

Worker 服务是 Langfuse 的后台任务处理核心，负责处理异步任务，包括数据摄入、队列管理和事件处理。

Worker 的主入口文件位于 worker/src/app.ts，该文件初始化 Worker 应用并注册各种处理器。

graph TB
    subgraph WorkerApp["Worker 应用"]
        Init[应用初始化]
        QueueProcessors[队列处理器]
        Schedulers[定时任务]
    end

    subgraph Queues["队列系统"]
        IngestionQueue[摄入队列]
        OtelQueue[OTEL 队列]
        SecondaryQueue[二级处理队列]
    end

    Init --> QueueProcessors
    QueueProcessors --> IngestionQueue
    QueueProcessors --> OtelQueue
    QueueProcessors --> SecondaryQueue

队列系统

Langfuse 使用 BullMQ 实现任务队列，支持多种队列类型：

Worker 数据处理流程

graph TD
    A[接收 HTTP 请求] --> B[验证请求参数]
    B --> C{请求类型}
    C -->|admin API| D[写入队列]
    C -->|普通请求| E[直接处理]
    D --> F[Worker 获取任务]
    F --> G[读取 S3 文件]
    G --> H[解析事件数据]
    H --> I[数据转换]
    I --> J[写入 PostgreSQL]
    J --> K[写入 ClickHouse]
    K --> L[任务完成]
    E --> L

Worker 服务实现了无状态架构设计：每个 MCP 请求创建新的服务器实例，认证上下文通过闭包捕获，请求完成后服务器被丢弃，任务处理器之间无共享状态。

数据存储层

PostgreSQL 数据库

PostgreSQL 作为 Langfuse 的主数据库，存储所有核心业务数据，包括用户信息、项目配置、提示词版本、追踪记录等。

数据库连接通过 packages/shared/src/db.ts 中的 Prisma Client 实现，该模块提供统一的数据库访问接口。

graph TB
    subgraph Postgres[(PostgreSQL)]
        Users[用户表]
        Projects[项目表]
        Prompts[提示词表]
        Traces[追踪表]
        Scores[评分表]
    end

    subgraph Tables["核心数据表"]
        Organizations[组织表]
        Members[成员表]
        Datasets[数据集表]
    end

ClickHouse 分析数据库

ClickHouse 是 Langfuse 的分析查询引擎，专门用于处理大规模追踪数据的 OLAP 查询。分析功能包括评分趋势分析、热力图生成、时间序列聚合等。

ClickHouse 客户端配置位于 packages/shared/src/server/clickhouse/client.ts，该模块初始化 ClickHouse 连接并提供查询接口。

Redis 缓存与队列

Redis 在 Langfuse 架构中承担多重职责：作为任务队列的后端存储、实现 API 限流、提供数据缓存加速查询。

Redis 客户端配置位于 packages/shared/src/server/redis/redis.ts，该模块封装了 Redis 连接管理和常用操作。

graph LR
    subgraph Redis[(Redis)]
        Queues[BullMQ 队列]
        Cache[数据缓存]
        RateLimit[限流控制]
        Locks[分布式锁]
    end

    subgraph CacheKeys["缓存键结构"]
        PromptCache[prompt:{projectId}:{name}:{version}]
        SessionCache[session:{sessionId}]
    end

    Redis --> Queues
    Redis --> Cache
    Redis --> RateLimit
    Redis --> Locks

S3 对象存储

S3 存储用于保存原始事件文件，包括追踪事件、OTEL 数据和大型 JSON 对象。Worker 服务从 S3 读取事件文件进行处理，处理后的结构化数据存入 PostgreSQL 和 ClickHouse。

事件文件存储路径遵循特定格式：{projectId}/{type}/{eventBodyId}/{eventId}.json，便于快速定位和检索。

服务间通信

tRPC API 调用

Web 前端与后端服务通过 tRPC 进行类型安全的 API 通信。tRPC 提供了端到端的类型推断，减少了前后端接口不匹配的问题。

API 路由定义采用模块化结构，每个 Feature 拥有独立的 Router 文件，例如：

• scoreAnalyticsRouter - 评分分析 API
• promptRouter - 提示词管理 API
• traceRouter - 追踪数据 API

缓存策略

Langfuse 实现了多级缓存策略以提升系统性能：

1. Redis 缓存层：提示词内容缓存，避免重复查询数据库
2. TTK 重置机制：缓存条目被访问时自动重置 TTL
3. 写时失效：数据更新时清除相关缓存条目

缓存键结构示例：prompt:<project-id>:<prompt-name>:<version-or-label>

graph TD
    A[读取请求] --> B{检查 Redis 锁}
    B -->|有锁| C[等待或降级]
    B -->|无锁| D{检查缓存}
    D -->|命中| E[返回缓存数据]
    D -->|未命中| F[查询 PostgreSQL]
    F --> G[写入 Redis]
    G --> H[返回数据]
    E --> I[重置 TTL]

权限与认证

组织级权限模型

Langfuse 采用组织级权限管理模型，权限通过 Plan 和 Entitlement 两层机制控制。

Plan 信息通过以下方式获取：

• Cloud 版本：通过 NextAuth JWT 获取
• Self-hosted：通过环境变量或许可证密钥获取

权限检查流程

graph TB
    A[请求进入] --> B{获取 Organization}
    B --> C{检查 JWT 中的 Plan}
    C -->|Cloud| D[使用 cloudConfig]
    C -->|Self-hosted| E[检查许可证]
    D --> F[加载 Entitlements]
    E --> F
    F --> G{验证功能权限}
    G -->|通过| H[处理请求]
    G -->|拒绝| I[返回 403]

部署架构

服务组件关系

graph TB
    subgraph Deployment["部署拓扑"]
        Web[Web 服务<br/>Next.js]
        API[API 服务]
        Worker1[Worker 实例 1]
        Worker2[Worker 实例 2]
        WorkerN[Worker 实例 N]
    end

    subgraph Shared["共享服务"]
        Redis[(Redis Cluster)]
        Postgres[(PostgreSQL)]
        ClickHouse[(ClickHouse)]
        S3[(S3 兼容存储)]
    end

    Web --> API
    API --> Redis
    API --> Postgres
    API --> ClickHouse
    API --> S3
    Worker1 --> Redis
    Worker2 --> Redis
    WorkerN --> Redis
    Worker1 --> Postgres
    Worker2 --> Postgres
    WorkerN --> Postgres
    Worker1 --> ClickHouse
    Worker2 --> ClickHouse
    Worker1 --> S3
    Worker2 --> S3

环境配置

主要环境变量配置项：

源码文件引用

本文档基于以下核心源码文件编写：

• packages/shared/src/server/redis/redis.ts - Redis 客户端封装
• packages/shared/src/server/clickhouse/client.ts - ClickHouse 连接配置
• packages/shared/src/db.ts - Prisma 数据库客户端
• worker/src/app.ts - Worker 应用入口
• web/next.config.mjs - Next.js 应用配置

概述

Langfuse 采用多数据库架构，针对不同的数据访问模式选择最适合的存储方案。系统主要使用三种数据存储技术：PostgreSQL 作为主关系型数据库，ClickHouse 用于事件分析和时序数据，Redis 用于缓存和消息队列。这种混合架构平衡了事务一致性、查询性能和实时处理能力。

资料来源：packages/shared/prisma/schema.prisma

架构概览

graph TB
    subgraph 客户端层
        A[Langfuse SDK] --> B[Ingestion API]
        C[Web UI] --> D[Management API]
    end
    
    subgraph 数据处理层
        B --> E[BullMQ Queue]
        E --> F[Worker Process]
    end
    
    subgraph 存储层
        F --> G[(PostgreSQL)]
        F --> H[(ClickHouse)]
        F --> I[(Redis)]
        D --> G
        D --> H
    end
    
    subgraph 查询层
        G --> J[Repository Pattern]
        H --> K[ClickHouse Queries]
        I --> L[Cache Layer]
    end

Langfuse 的数据流向遵循以下原则：所有写入操作通过消息队列异步处理，确保高并发场景下的稳定性；读取操作根据数据类型选择最优存储引擎。Observation 和 Trace 等核心实体同时存在于 PostgreSQL 和 ClickHouse 中，前者保证关系完整性，后者支持复杂分析查询。

资料来源：packages/shared/src/server/repositories

PostgreSQL 核心表设计

实体关系模型

PostgreSQL 使用 Prisma ORM 进行模式管理，所有表设计遵循标准关系型数据库规范。核心实体包括组织、项目、用户、追踪、观察、提示词和数据集。

erDiagram
    Organization ||--o{ Project : contains
    Project ||--o{ ApiKey : has
    Project ||--o{ Trace : contains
    Project ||--o{ Dataset : contains
    Project ||--o{ Prompt : contains
    Trace ||--o{ Observation : contains
    Trace ||--o{ Score : has
    Observation ||--o{ Score : has
    Dataset ||--o{ DatasetItem : contains
    Dataset ||--o{ DatasetRun : has
    User ||--o{ Membership : belongs_to
    Organization ||--o{ Membership : has

主要数据表

资料来源：packages/shared/prisma/schema.prisma

Trace 表结构

Trace 表是 Langfuse 数据模型的核心，用于记录完整的 LLM 调用会话：

model Trace {
  id            String       @id @default(cuid())
  name          String?
  userId        String?
  projectId     String
  metadata      Json?
  release       String?
  version       String?
  createdAt     DateTime     @default(now())
  updatedAt     DateTime     @updatedAt
  
  observations  Observation[]
  scores        Score[]
  sessions      Session[]
}

关键字段说明：

• id: 全局唯一标识符，使用 CUID 算法生成
• name: 可选的追踪名称，便于识别
• userId: 终端用户标识，用于多用户场景
• metadata: 灵活 JSON 字段存储附加信息
• release: 发布版本标签
• version: 追踪数据版本

资料来源：packages/shared/prisma/schema.prisma

Observation 表结构

Observation 表存储追踪内的具体调用单元，支持多种事件类型：

model Observation {
  id            String       @id @default(cuid())
  traceId       String
  type          ObservationType
  name          String?
  startTime     DateTime
  endTime       DateTime?
  metadata      Json?
  
  // 嵌套调用
  parentObservationId String?
  parentObservation   Observation? @relation(...)
  childObservations   Observation[]
  
  // 嵌入内容
  input      String?
  output     String?
  usage      Json?
  parameters Json?
  
  // 成本追踪
  promptTokens        Int?
  completionTokens    Int?
  totalTokens         Int?
  unitDollarPrice     Float?
  totalDollarPrice   Float?
  
  scores      Score[]
}

ObservationType 枚举定义事件类型：

• CHAT Spike: 聊天消息
• COMPLETION: 文本补全
• CHUNK: 流式数据块
• GENERATION: 生成事件
• EVENT: 通用事件
• SPAN: 跨度（包含子事件）

资料来源：packages/shared/prisma/schema.prisma

Score 评分设计

评分系统支持多维度评估，采用灵活的 JSON 结构：

model Score {
  id            String       @id @default(cuid())
  name          String
  value         Float
  dataType      ScoreDataType
  
  // 评分来源
  source        ScoreSource
  
  // 关联对象
  traceId       String?
  observationId String?
  
  // 评分者信息
  authorId      String?
  comment       String?
  
  createdAt     DateTime     @default(now())
}

评分数据类型：

• NUMERIC: 数值型评分
• CATEGORICAL: 分类型评分
• BOOLEAN: 布尔型评分

评分来源包括 API、INGESTION、EVALUATION、USER、BENCHMARK 等。

资料来源：packages/shared/prisma/schema.prisma 资料来源：packages/shared/src/features/scores/interfaces/README.md

ClickHouse 事件存储

事件存储架构

ClickHouse 作为列式存储数据库，专门用于高吞吐量的事件数据和分析查询。所有通过 Ingestion API 摄入的事件都会写入 ClickHouse，形成持久化的事件流。

graph LR
    A[SDK Events] --> B[Ingestion API]
    B --> C[Event Validation]
    C --> D[Queue Event]
    D --> E[Worker Processing]
    E --> F[(ClickHouse)]
    E --> G[(PostgreSQL)]
    
    F --> H[Analytics Queries]
    G --> I[Relational Queries]

事件数据按时间分区存储，支持高效的时间范围查询。数据采用分层设计：原始事件存储在 ClickHouse，经过处理的关系数据同步到 PostgreSQL。

资料来源：packages/shared/clickhouse/migrations/clustered 资料来源：worker/src/scripts/refillQueueEvent/README.md

ClickHouse 表结构

ClickHouse 采用物化视图和合并树引擎优化查询性能：

CREATE TABLE events (
    id UUID,
    project_id String,
    trace_id String,
    type String,
    body String,
    event_timestamp DateTime,
    created_at DateTime
) ENGINE = MergeTree()
ORDER BY (project_id, event_timestamp, id)
PARTITION BY toYYYYMM(event_timestamp);

关键设计决策：

• 使用 project_id 作为排序键首位，支持项目级高效过滤
• 按月份分区，便于历史数据管理
• 事件体存储为字符串，支持灵活的反序列化

资料来源：packages/shared/clickhouse/migrations/clustered

OTEL 事件格式

OpenTelemetry 兼容事件使用特定路径格式存储：

otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json

这种层次化路径设计允许 S3 兼容存储和 ClickHouse 联合查询，实现边缘缓存和计算分离。

资料来源：worker/src/scripts/replayIngestionEventsV2/README.md

Redis 缓存与队列

队列架构

Langfuse 使用 BullMQ（基于 Redis）实现异步任务处理：

graph TB
    subgraph 队列系统
        A[OtelIngestionQueue] --> B[Ingestion Worker]
        C[IngestionSecondaryQueue] --> D[Secondary Worker]
        E[PromptCacheQueue] --> F[Cache Worker]
    end
    
    subgraph 数据流
        B --> G[(ClickHouse)]
        D --> H[(PostgreSQL)]
        F --> I[(Cache)]
    end

主要队列类型：

资料来源：worker/src/scripts/refillQueueEvent/README.md

缓存策略

提示词模板使用 Redis 缓存加速访问：

interface PromptCacheEntry {
  promptId: string;
  content: string;
  version: number;
  expiresAt: number;
}

缓存失效采用主动更新模式：当提示词更新时，通过队列触发缓存刷新，确保多实例部署的一致性。

资料来源：web/src/features/mcp/README.md

数据流与同步

事件摄取流程

sequenceDiagram
    participant SDK
    participant API as Ingestion API
    participant Queue as BullMQ
    participant Worker
    participant CH as ClickHouse
    participant PG as PostgreSQL

    SDK->>API: POST /ingestion
    API->>API: Validate & Transform
    API->>Queue: Enqueue Event
    API-->>SDK: 200 OK
    
    Queue->>Worker: Dequeue Job
    Worker->>CH: Insert Event
    Worker->>PG: Upsert Entity
    Worker->>Worker: Index & Compute

事件摄取遵循写入放大模式：单次 API 调用触发多次数据写入，通过队列解耦确保响应延迟最小化。

资料来源：packages/shared/src/server/repositories

批量处理与检查点

摄取脚本支持断点续传机制：

interface BatchProgress {
  totalRows: number;
  processedRows: number;
  queuedCount: number;
  skippedCount: number;
  errorCount: number;
}

检查点文件保存当前处理位置，失败后可从上次成功位置恢复，保证大规模数据导入的可靠性。

资料来源：worker/src/scripts/replayIngestionEventsV2/README.md

查询优化

索引策略

PostgreSQL 表设计包含多层索引优化：

-- 复合索引支持项目级快速查询
CREATE INDEX idx_traces_project_created 
ON traces(project_id, created_at DESC);

-- 文本搜索索引
CREATE INDEX idx_traces_name_gin 
ON traces USING gin(name gin_trgm_ops);

-- 关系索引维护查询性能
CREATE INDEX idx_observations_trace 
ON observations(trace_id, start_time DESC);

ClickHouse 查询模式

分析查询使用物化视图聚合：

CREATE MATERIALIZED VIEW score_stats_mv
ENGINE = SummingMergeTree()
ORDER BY (project_id, score_name, period)
AS SELECT
    project_id,
    score_name,
    toDate(timestamp) as period,
    count() as count,
    avg(value) as avg_value,
    quantile(0.5)(value) as p50
FROM raw_events
WHERE type = 'score'
GROUP BY project_id, score_name, period;

资料来源：packages/shared/src/tableDefinitions

安全与隔离

组织级数据隔离

所有查询必须通过项目作用域验证：

interface AuthCheck {
  validKey: boolean;
  scope: {
    projectId: string;
    accessLevel: "project" | "org";
  };
}

API 密钥与项目绑定，跨项目访问通过组织成员关系控制。

资料来源：worker/src/scripts/replayIngestionEventsV2/README.md

敏感数据处理

用户上传的 metadata 字段支持服务端过滤：

interface FilterConfig {
  fieldPath: string;
  action: "REDACT" | "REMOVE" | "ALLOW";
}

配置化的数据过滤规则确保敏感信息不会出现在日志或分析结果中。

总结

Langfuse 的数据库设计体现了现代 SaaS 应用的多存储策略：

• PostgreSQL 提供强一致性的关系数据存储
• ClickHouse 处理高吞吐量分析工作负载
• Redis 实现异步处理和高速缓存

三层架构通过事件驱动模式松耦合，支持水平扩展同时保持数据完整性。Repository 模式封装数据访问逻辑，隐藏底层存储细节，便于未来架构演进。

资料来源：packages/shared/src/server/repositories 资料来源：packages/shared/prisma/schema.prisma

概述

追踪系统（Tracing System）是 Langfuse 的核心功能模块，负责收集、存储和展示 LLM 应用执行过程中的完整调用链路。该系统基于 OpenTelemetry 标准构建，支持多种观察类型，能够帮助开发者监控、分析和优化 AI 应用的行为。

追踪系统的主要职责包括：

• 链路追踪：记录完整的请求调用链路，包括输入、输出和中间过程
• 观察类型支持：支持 SPAN（跨度）、GENERATION（生成）、EVENT（事件）等多种观察类型
• 层级结构：通过父子关系构建树形结构，展现调用嵌套关系
• 元数据管理：附加和解析丰富的上下文元数据
• 评分集成：与评分系统集成，支持评估执行效果的追踪

资料来源：packages/shared/src/domain/traces.ts

核心概念

提示词实体

Langfuse 中的提示词是一个包含名称、版本、内容和元数据的实体。每个提示词具有以下核心属性：

资料来源：packages/shared/src/domain/prompts.ts

提示词类型

Langfuse 支持两种提示词类型：

文本提示词（Text Prompt）

• 用于简单的文本补全任务
• prompt 字段存储纯文本内容

聊天提示词（Chat Prompt）

• 用于 OpenAI 风格的聊天接口
• prompt 字段存储消息数组，每条消息包含 role 和 content

资料来源：web/src/features/mcp/README.md

系统架构

整体架构

graph TD
    subgraph 客户端层
        MCP[ MCP Server ]
        API[ REST API ]
        WebUI[ Web 前端 ]
    end
    
    subgraph 服务层
        PromptService[ PromptService ]
        PromptCache[ Redis Cache ]
        PromptDB[( PostgreSQL )]
    end
    
    MCP -->|getPrompt/createPrompt| PromptService
    API -->|CRUD 操作| PromptService
    WebUI -->|管理界面| PromptService
    
    PromptService -->|缓存读写| PromptCache
    PromptService -->|持久化| PromptDB

数据存储

Langfuse 使用 PostgreSQL 作为提示词的持久化存储，并通过 Redis 实现缓存层以提升读取性能。

graph LR
    A[读请求] --> B{检查 Redis}
    B -->|缓存命中| C[返回缓存数据]
    B -->|缓存未命中| D[查询 PostgreSQL]
    D --> E[写入 Redis]
    E --> C

资料来源：web/src/features/prompts/README.md

缓存策略

缓存结构

提示词的缓存使用 Redis 管理，缓存键格式如下：

prompt:<project-id>:<prompt-name>:<prompt-version ?? label>

这意味着：

• 同一提示词名称可能对应多个缓存键
• 具有多个标签的提示词会在缓存中多次出现

缓存操作流程

sequenceDiagram
    participant Client as 客户端
    participant Cache as Redis Cache
    participant Lock as Redis Lock
    participant DB as PostgreSQL

    Client->>Cache: 读取提示词
    Cache->>Cache: 检查缓存键
    alt 缓存命中
        Cache-->>Client: 返回缓存数据
        Cache->>Cache: 重置 TTL
    else 缓存未命中 或 锁存在
        Cache-->>DB: 查询数据库
        DB-->>Cache: 返回提示词数据
        Cache-->>Client: 返回数据并缓存
    end

    Note over Lock,DB: 更新提示词时
    Lock->>Lock: 获取分布式锁
    Lock->>Cache: 清除所有相关缓存键
    Lock->>DB: 执行数据库更新
    Lock->>Lock: 释放锁

关键设计原则

1. 从不更新缓存：当提示词更新时，系统会删除所有相关的缓存条目，而不是修改它们
2. 分布式锁保护：使用 Redis 锁确保并发更新的安全性
3. 操作顺序：先获取锁 → 失效缓存 → 执行数据库操作 → 释放锁

资料来源：web/src/features/prompts/README.md

MCP 集成

Langfuse 提供了 MCP（Model Context Protocol）服务器集成，允许外部工具和客户端程序访问提示词管理功能。

MCP 工具列表

提示词解析模式

MCP 服务提供两种提示词获取模式：

完全解析模式（getPrompt）

• 用于获取可直接发送给 LLM 的最终提示词
• 递归解析所有依赖标签
• 返回包含完整内容的提示词

原始模式（getPromptUnresolved）

• 用于分析提示词组合结构
• 保留 @@@langfusePrompt:name=xxx|label=yyy@@@ 依赖标签
• 有助于调试和理解提示词依赖关系

资料来源：web/src/features/mcp/README.md

提示词组合

依赖标签语法

Langfuse 支持提示词组合功能，允许一个提示词引用其他提示词。依赖标签语法如下：

@@@langfusePrompt:name=<prompt-name>|label=<label-name>@@@

组合示例

输入: "You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@"
输出: "You are helpful. Always be kind and respectful."

使用场景

• 提示词堆叠：将基础规则与具体任务提示词组合
• 依赖链分析：使用 getPromptUnresolved 调试依赖关系
• 构建工具：开发管理提示词组合的自动化工具

graph TD
    A[主提示词] -->|依赖| B[基础规则提示词]
    A -->|依赖| C[角色定义提示词]
    B -->|依赖| D[通用指令提示词]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#f3e5f5

API 接口

创建提示词

文本提示词

createTextPrompt(params: {
  projectId: string;
  promptName: string;
  prompt: string;
  config?: PromptConfig;
  labels?: string[];
})

聊天提示词

createChatPrompt(params: {
  projectId: string;
  promptName: string;
  messages: ChatMessage[];
  config?: PromptConfig;
  labels?: string[];
})

查询提示词

listPrompts(params: {
  projectId: string;
  name?: string;      // 可选：按名称过滤
  label?: string;     // 可选：按标签过滤
  tag?: string;       // 可选：按标签过滤
  updatedAtStart?: Date;
  updatedAtEnd?: Date;
  page?: number;
  limit?: number;
})

版本控制与标签

版本管理

每个提示词版本具有自动递增的版本号。创建新版本时：

1. 版本号自动加一
2. 可选择性地添加标签（如 production、dev）
3. 版本记录创建时间戳

标签系统

标签用于标识提示词的用途或环境：

标签更新操作

updatePromptLabels 工具允许：

• 添加新标签到现有版本
• 将标签从一个版本移动到另一个版本
• 删除不需要的标签

数据库模型

提示词表结构定义：

interface PromptTable {
  id: string;              // UUID 主键
  project_id: string;      // 项目 ID
  name: string;           // 提示词名称
  version: number;         // 版本号
  type: "text" | "chat";   // 提示词类型
  prompt: string;          // 提示词内容
  config: object;          // 配置（JSON）
  labels: string[];        // 标签数组
  created_at: Date;        // 创建时间
  updated_at: Date;        // 更新时间
}

资料来源：packages/shared/src/tableDefinitions/promptsTable.ts

审计日志

所有写入操作（创建、更新标签）会自动创建审计日志条目，包含：

• 操作前状态快照
• 操作后状态快照
• 操作时间戳
• 操作者信息

安全与权限

访问控制

MCP 集成使用 BasicAuth 认证：

# 生成 Basic Auth Token
echo -n "pk-lf-your-public-key:sk-lf-your-secret-key" | base64

权限级别

工具注解

MCP 工具包含安全提示注解：

• readOnly: true：安全操作，无需确认（如 getPrompt、listPrompts）
• destructive: true：修改数据的操作（如 createTextPrompt、createChatPrompt）

客户端程序可以根据这些注解自动批准只读操作，或在执行破坏性操作时要求用户确认。

最佳实践

命名规范

• 使用描述性名称：customer-support-greeting 而非 prompt-1
• 统一命名风格：建议使用 kebab-case 或 camelCase
• 包含版本或环境信息：prompt-name:production

标签使用策略

1. 生产环境使用 production 标签
2. 开发和测试使用 dev 或 staging 标签
3. 避免在标签中包含敏感信息
4. 定期清理不再使用的标签

缓存优化

1. 避免频繁更新提示词，以减少缓存失效开销
2. 使用标签而非版本号来引用提示词（标签更稳定）
3. 监控缓存命中率，及时调整缓存策略

总结

Langfuse 的提示词管理系统提供了企业级的提示词管理能力，包括：

• 版本控制：自动版本管理和标签系统
• 组合能力：支持提示词依赖和复用
• 高性能：Redis 缓存和锁机制确保并发安全
• 标准化接口：REST API 和 MCP 集成支持多种客户端
• 审计追踪：完整的操作日志记录

概述

Langfuse 的评估系统（Evaluation System）是用于衡量和分析 LLM 应用输出的核心模块。该系统提供了一套完整的评分（Score）管理机制，包括评分的定义、存储、分析和可视化功能。评估系统帮助开发者量化 LLM 生成内容的质量，支持自定义评分规则，并通过统计分析提供对模型性能的洞察。

Langfuse 采用双轨 API 设计，支持 v1（遗留版本，仅支持 trace 级别评分）和 v2（当前版本，支持 trace、session 和数据集运行级别的评分）。资料来源：packages/shared/src/features/scores/interfaces/README.md

概述

数据集管理（Datasets）是 Langfuse 平台的核心功能之一，用于管理和组织用于评估和测试 LLM 应用的数据集合。数据集由多个数据项组成，每个数据项包含输入、期望输出以及其他元数据，支持在实验和评估流程中被引用和执行。

数据集管理功能覆盖了从数据项的创建、编辑，到运行时与 trace 的关联，再到实验执行和结果评估的完整生命周期。

核心数据模型

DatasetItem（数据集项）

DatasetItem 是数据集的基本组成单元，代表数据集中的单个测试样本。

资料来源：packages/shared/src/domain/dataset-items.ts

DatasetRunItem（数据集运行项）

DatasetRunItem 记录数据集在特定实验运行中的执行结果，将数据集项与实际执行产生的 trace 关联起来。

资料来源：packages/shared/src/domain/dataset-run-items.ts

架构设计

系统架构图

graph TD
    subgraph 前端层["前端层 (web/src/features/datasets)"]
        UI[数据集管理界面]
        Hooks[React Hooks]
    end

    subgraph 服务层["服务层 (packages/shared)"]
        DS[DatasetService]
        DRS[DatasetRunService]
    end

    subgraph 数据层["数据层"]
        PG[(PostgreSQL)]
        CH[(ClickHouse)]
    end

    subgraph 实验执行层["实验执行层 (worker/src/features/experiments)"]
        Executor[实验执行器]
        Evaluator[评估器]
    end

    UI --> Hooks
    Hooks --> DS
    DS --> DRS
    DRS --> PG
    DRS --> CH
    Executor --> DRS
    Executor --> Evaluator
    Evaluator --> CH

服务层职责

DatasetService 负责数据集的核心业务逻辑：

• 创建和管理数据集
• 数据集项的 CRUD 操作
• 数据集与项目（Project）的关联管理

DatasetRunService 负责实验运行的生命周期：

• 管理实验运行的创建和状态
• 关联数据集项与执行 trace
• 记录执行结果和评估数据

实验与评估

实验系统概述

Langfuse 的实验系统（Experiments）与数据集管理紧密集成，支持以下核心功能：

1. 数据集选择：从现有数据集中选择运行的数据项
2. 变量注入：将数据集项的输入注入到 prompt 模板中
3. 批量执行：对数据集中的所有项执行推理
4. 结果收集：收集执行产生的 trace 和 observation
5. 评估计算：基于预设的评分标准计算评估分数

资料来源：worker/src/features/experiments

实验运行流程

graph LR
    A[启动实验] --> B[加载数据集项]
    B --> C{遍历数据项}
    C -->|存在未处理项| D[注入变量到 Prompt]
    D --> E[执行 LLM 调用]
    E --> F[创建 Trace]
    F --> G[记录 DatasetRunItem]
    G --> H{评估分数}
    H --> I[计算评分]
    I --> C
    C -->|处理完成| J[生成实验报告]

评估数据存储

评估相关的分数数据存储在 ClickHouse 中，支持高效的查询和分析：

• 实验运行的分数数据通过 SeederOrchestrator 批量插入
• 支持环境（environment）过滤：production、development、staging
• 支持按数据集和实验运行进行聚合查询

资料来源：packages/shared/scripts/seeder/utils/README.md

API 接口

评分接口版本

Langfuse 为评分（Scores）功能提供了 v1 和 v2 两个 API 版本：

资料来源：packages/shared/src/features/scores/interfaces/README.md

核心 API 端点

前端组件

前端数据集管理功能位于 web/src/features/datasets 目录，提供以下核心功能：

• 数据集列表展示和搜索
• 数据集项的添加、编辑、删除
• 实验运行的历史记录查看
• 实验结果的可视化展示

数据集列表页面

数据集列表页面提供以下功能：

• 按名称、环境过滤数据集
• 查看数据集项数量
• 快速操作入口（运行实验、导出数据）

数据集详情页面

数据集详情页面展示：

• 数据集基本信息（名称、描述、创建时间）
• 数据集项列表（支持分页）
• 实验运行历史
• 评估分数统计

数据流转

graph TD
    subgraph 数据录入
        UserInput[用户录入]
        Import[批量导入]
    end

    subgraph 数据存储
        PG[(PostgreSQL<br/>数据集元数据)]
        CH[(ClickHouse<br/>运行时数据)]
    end

    subgraph 评估执行
        Experiment[实验]
        LLM[LLM 调用]
    end

    subgraph 结果分析
        ScoreUI[分数展示]
        TraceView[Trace 详情]
    end

    UserInput --> PG
    Import --> PG
    Experiment --> LLM
    LLM --> PG
    LLM --> CH
    Experiment --> CH
    CH --> ScoreUI
    PG --> TraceView

环境与隔离

多环境支持

数据集支持环境隔离，确保不同环境（生产、开发、测试）的数据相互独立：

• production：生产环境数据
• development：开发环境数据
• staging：预发布环境数据

数据隔离策略

资料来源：packages/shared/scripts/seeder/utils/README.md

最佳实践

数据集组织

1. 按用途分类：将用于不同目的的数据集分开管理
2. 版本控制：对重要数据集进行版本标记
3. 元数据丰富：为数据项添加充分的元数据，便于筛选和分析

实验设计

1. 小规模测试：先在小数据集上验证实验逻辑
2. 变量控制：确保对比实验仅改变目标变量
3. 结果复现：记录实验参数，便于复现结果

评估配置

1. 选择合适的评分标准：根据业务需求选择或自定义评分函数
2. 设置合理的阈值：避免过于宽松或严格的评估标准
3. 定期校准：随着 LLM 版本更新，重新校准评估标准

相关模块

概述

Langfuse 的队列系统是基于 Redis 和 BullMQ 构建的消息队列基础设施，负责处理异步任务、事件摄取、评估执行和批量操作。该系统采用生产者和消费者模式，通过队列解耦服务间的通信，提高系统的可扩展性和可靠性。

队列系统在 Langfuse 架构中扮演核心角色，主要承担以下职责：

• 事件摄取：处理来自 SDK 和 OTEL 协议的事件数据
• 评估执行：管理评估任务的异步执行
• 批量操作：处理需要批量处理的后台任务
• 事件重放：支持从 S3 重新导入历史事件

架构设计

Langfuse 采用多队列架构，不同类型的任务使用独立的队列，每个队列由专门的消费者处理器处理。

graph TD
    subgraph "生产者"
        SDK[Langfuse SDK]
        OTEL[OTEL Protocol]
        API[API Server]
    end

    subgraph "队列层"
        IQ[IngestionQueue<br/>摄取队列]
        OIQ[OtelIngestionQueue<br/>OTEL摄取队列]
        ISQ[IngestionSecondaryQueue<br/>摄取次级队列]
        EEQ[EvalExecutionQueue<br/>评估执行队列]
        BAQ[BatchActionQueue<br/>批量操作队列]
    end

    subgraph "消费者"
        Worker[Worker Service]
    end

    SDK --> IQ
    OTEL --> OIQ
    API --> EEQ
    API --> BAQ
    
    IQ --> Worker
    OIQ --> Worker
    ISQ --> Worker
    EEQ --> Worker
    BAQ --> Worker

    Worker --> Redis[(Redis)]

队列类型

摄取队列 (IngestionQueue)

摄取队列是 Langfuse 最核心的队列，负责处理来自客户端 SDK 的事件数据。事件类型包括 traces、generations、scores、evals 等。

事件格式示例：

{
  "projectId": "project-123",
  "orgId": "org-456",
  "eventType": "trace-create",
  "body": { /* 事件数据 */ }
}

资料来源：packages/shared/src/server/redis/ingestionQueue.ts

OTEL 摄取队列 (OtelIngestionQueue)

专门处理 OpenTelemetry 协议格式的事件，采用特定的文件存储路径格式。

S3 文件路径格式：

otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json

资料来源：worker/src/scripts/replayIngestionEventsV2/README.md

摄取次级队列 (IngestionSecondaryQueue)

作为摄取队列的补充队列，用于处理需要二次处理的事件或分流部分摄取负载。

评估执行队列 (EvalExecutionQueue)

负责调度和管理评估任务的执行。当用户触发评估操作时，评估任务被加入此队列，由专门的评估工作器异步处理。

资料来源：packages/shared/src/server/redis/evalExecutionQueue.ts

批量操作队列 (BatchActionQueue)

处理需要批量执行的系统操作，如批量更新、批量删除等后台任务。

资料来源：packages/shared/src/server/redis/batchActionQueue.ts

队列配置

Langfuse 在中央配置文件 queues.ts 中定义所有队列的默认配置和行为。

// packages/shared/src/server/queues.ts 中的典型配置结构
interface QueueConfig {
  name: string;
  concurrency: number;
  maxRetries: number;
  backoff: {
    type: 'exponential' | 'fixed';
    delay: number;
  };
  removeOnComplete: boolean | number;
  removeOnFail: boolean | number;
}

资料来源：packages/shared/src/server/queues.ts

消费者与工作器

Worker 服务架构

Worker 服务运行在独立的进程中，通过 Redis 连接队列并消费消息。每个队列类型对应专门的处理逻辑。

graph LR
    subgraph "Worker 进程"
        subgraph "处理器"
            IQH[IngestionHandler]
            OIQH[OtelHandler]
            EEQH[EvalHandler]
            BAH[BatchHandler]
        end
        
        subgraph "队列连接"
            R[Redis BullMQ]
        end
    end

    IQH --> R
    OIQH --> R
    EEQH --> R
    BAH --> R

处理器职责

资料来源：worker/src/queues

事件重放系统

Langfuse 提供了事件重放脚本，允许从 S3 重新导入历史事件到队列系统。

replayIngestionEventsV2

最新版本的事件重放工具，提供完整的事件重放功能。

主要特性：

• 支持从 S3 读取历史事件
• 支持增量重放和断点续传
• 内置速率限制和重试机制
• 支持批量并发请求

命令行参数：

环境变量：

进度追踪与错误处理：

• 进度日志：每批次处理后记录进度（如 [1200/45000] 2.7% — 498 queued, 2 skipped）
• 检查点：每批成功处理后写入检查点文件到CSV同目录，使用 --resume 可从断点继续
• 速率限制：尊重本地 --rate-limit 配置，对429响应使用指数退避
• 重试机制：临时错误（429、5xx）最多重试3次，永久错误（其他4xx）记录并跳过
• 错误日志：失败记录追加到输入文件同目录的 errors.csv

资料来源：worker/src/scripts/replayIngestionEventsV2/README.md

v1 与 v2 版本对比

事件转换

重放脚本支持两种 S3 key 格式的转换：

标准格式

路径：{projectId}/{type}/{eventBodyId}/{eventId}.json

转换结果：

{
  "authCheck": {
    "validKey": true,
    "scope": { "projectId": "<projectId>" }
  },
  "data": {
    "eventBodyId": "<eventBodyId>",
    "fileKey": "<eventId>",
    "type": "<type>-create"
  }
}

投递到 IngestionSecondaryQueue。

OTEL 格式

路径：otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json

转换结果：

{
  "authCheck": {
    "validKey": true,
    "scope": { "projectId": "<projectId>", "accessLevel": "project" }
  },
  "data": {
    "fileKey": "otel/<projectId>/<yyyy>/<mm>/<dd>/<hh>/<mm>/<eventId>.json"
  }
}

投递到 OtelIngestionQueue。

管理员 API 端点

POST /api/admin/ingestion-replay

接受批量 S3 key 并将其排队等待重新处理。

认证方式：Authorization: Bearer {ADMIN_API_KEY} 头，由 AdminApiAuthService 验证。

请求格式：

{
  "keys": [
    "projectId/trace/eventBodyId/eventId.json",
    "otel/projectId/2025/07/09/14/30/some-uuid.json"
  ]
}

响应格式：

{
  "queued": 498,
  "skipped": 2,
  "errors": []
}

状态码说明：

性能优化

队列系统采用多种策略确保高性能：

并发处理

• 不同队列可独立配置并发数
• Worker 支持水平扩展，多实例并行消费
• 基于 Redis 的队列提供低延迟的消息传递

重试机制

graph TD
    A[消息处理失败] --> B{错误类型}
    B -->|临时错误 429/5xx| C[指数退避重试]
    B -->|永久错误 4xx| D[记录并跳过]
    C --> E[重试次数 < 3?]
    E -->|是| A
    E -->|否| D

资源管理

• 完成或失败的消息自动清理（可配置保留策略）
• 死信队列处理长时间失败的消息
• 内存敏感操作使用流式处理

监控与调试

本地调试工具

事件重放脚本提供进度追踪功能：

# 运行脚本会输出类似：
[1200/45000] 2.7% — 498 queued, 2 skipped

检查点文件

脚本在每次批量处理成功后保存检查点：

./worker/events.csv
./worker/events.csv.checkpoint  # 存储当前行偏移量

错误日志

处理失败的事件记录到 errors.csv：

s3_key,error_message,timestamp
projectId/trace/xxx.json,Rate limited,2025-07-09T10:30:00Z

最佳实践

生产环境部署

1. 队列隔离：不同环境的队列使用不同的 Redis 实例或键前缀
2. 监控告警：配置队列深度、处理延迟、失败率的监控
3. 优雅关闭：Worker 支持优雅关闭，确保处理中的任务完成

故障恢复

1. 启用检查点：长时间运行的批量任务使用断点续传
2. 死信处理：定期检查死信队列，分析失败原因
3. 数据校验：重放前验证事件格式，避免格式错误导致处理失败

容量规划

• 根据峰值吞吐量配置 Worker 并发数
• 监控队列积压情况，动态扩展 Worker
• 评估 Redis 内存使用，预留足够空间

相关文档

• Worker 服务文档
• 事件摄取系统
• 评估执行系统
• ClickHouse 存储

概述

Langfuse 的 API 系统是一个多层架构，支持数据摄取、公共 API 接口、客户端 SDK 以及服务端内部调用。该系统采用 Fern 进行 API 定义和类型生成，实现了服务端和客户端的双向代码生成，确保 API 的一致性和类型安全。

API 系统主要包含以下几个核心组成部分：

• 摄取 API (Ingestion API)：接收来自 SDK 和集成工具的事件数据
• 公共 API (Public API)：面向外部开发者的高层 REST 接口
• 客户端 SDK API：Python 和 JavaScript/TypeScript SDK 使用的接口
• 服务端定义 API：内部服务端使用的 API 定义

资料来源：web/src/features/public-api/README.md

Pitfall Log / 踩坑日志

项目：langfuse/langfuse

摘要：发现 17 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: Using client with context manager breaks the scoring。

1. 安装坑 · 来源证据：bug: Using client with context manager breaks the scoring

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：bug: unnamed trace name in Langfuse UI

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：v3.169.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：v3.172.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

8. 安装坑 · 来源证据：v3.173.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

9. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass.

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing

11. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：v3.168.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.168.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_202b4e8c2c1f4b3790315098d1530297 | https://github.com/langfuse/langfuse/releases/tag/v3.168.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：v3.170.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.170.0
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9ed6f994e1424878aa4559a73d72fc52 | https://github.com/langfuse/langfuse/releases/tag/v3.170.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：v3.174.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.174.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f9cb7b7232ff4cce96f0c020fe48c7f4 | https://github.com/langfuse/langfuse/releases/tag/v3.174.0 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

16. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | issue_or_pr_quality=unknown

17. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | release_recency=unknown