Langfuse2.60.3:独立数据库+docker部署及环境变量详细说明
一、什么是Langfuse
Langfuse 是一个 **开源 LLM 工程** 平台。它帮助团队协作 **开发、监控、评估** 以及 **调试** AI 应用。Langfuse 可在几分钟内 **自托管**，并且经过 **实战考验**。其核心组件包括Web界面、Worker进程、Postgres数据库、Clickhouse存储等。
## ✨ 核心特性
[LLM 应用可观察性]：为你的应用插入仪表代码，并开始将追踪数据传送到 Langfuse，从而追踪 LLM 调用及应用中其他相关逻辑（如检索、嵌入或代理操作）
[提示管理]：帮助你集中管理、版本控制并协作迭代提示。得益于服务器和客户端的高效缓存，你可以在不增加延迟的情况下反复迭代提示。
[评估]是 LLM 应用开发流程的关键组成部分，Langfuse 能够满足你的多样需求。它支持 LLM 作为"裁判"、用户反馈收集、手动标注以及通过 API/SDK 实现自定义评估流程。
[数据集]为评估你的 LLM 应用提供测试集和基准。它们支持持续改进、部署前测试、结构化实验、灵活评估，并能与 LangChain、LlamaIndex 等框架无缝整合。
[LLM 试玩平台]是用于测试和迭代提示及模型配置的工具，缩短反馈周期，加速开发。当你在追踪中发现异常结果时，可以直接跳转至试玩平台进行调整。
[综合 API]：Langfuse 常用于驱动定制化的 LLMOps 工作流程，同时利用 Langfuse 提供的构建模块和 API。我们提供 OpenAPI 规格、Postman 集合以及针对 Python 和 JS/TS 的类型化 SDK。
二、架构图
Langfuse仅依赖于开源组件，可以在本地、云基础设施或本地部署。
Langfuse由两个应用程序容器、存储组件和可选的LLM API/网关组成。
应用程序容器
Langfuse Web：服务于Langfuse UI和API的主要Web应用程序。
Langfuse Worker：异步处理事件的Worker。
存储组件：
Postgres：事务性工作负载的主数据库。
Clickhouse：高性能OLAP数据库，用于存储跟踪、观察和分数。
Redis/Valkey缓存：一种快速的内存数据结构存储。用于队列和缓存操作。
S3/Blob存储：对象存储，用于保存所有传入事件、多模式输入和大型导出。
LLM API/网关：某些功能依赖于外部LLM API或网关。
三、安装部署
3.1、拉取指定版本镜像
注：最新版本存在问题。
docker pull langfuse/langfuse:2.60.3
3.2、运行容器
docker run -d --name langfuse \
-e DATABASE_URL=postgresql://langfuse:Sinops1234~@192.168.1.201:5432/langfuse_db \
-e NEXTAUTH_URL=http://192.168.1.204:3001 \
-e NEXTAUTH_SECRET=mysecret \
-e SALT=mysalt \
-e CLICKHOUSE_MIGRATION_URL=clickhouse://192.168.1.204:9000 \
-e CLICKHOUSE_URL=http://192.168.1.204:8123 \
-e CLICKHOUSE_USER=default \
-e CLICKHOUSE_PASSWORD=sinops@2024 \
-e REDIS_HOST=192.168.1.204 \
-e REDIS_PORT=6379 \
-e REDIS_AUTH=Sinops1234~ \
-e LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://192.168.1.204:9000 \
-e LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=minioadmin \
-e LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=minioadmin \
-p 3001:3000 \
langfuse/langfuse:latest
3.3、postgresql的表
3.4、CLICKHOUSE的表
四、登录界面
http://192.168.1.204:3001/
四、环境参数说明
4.1、PostgreSQL 数据库配置（核心存储）
Langfuse 使用 PostgreSQL 存储结构化数据（如 trace、span、event 等）。
| 变量 | 是否必需 / 默认值 | 说明 |
| DATABASE_URL | ✅ 必需 | PostgreSQL 连接字符串，格式：postgresql://user:pass@host:port/dbname。<br>也可用 DATABASE_HOST, USERNAME, PASSWORD, NAME, ARGS 拆分配置。 |
| DIRECT_URL | 默认 = DATABASE_URL | 用于数据库迁移（migrations）的连接串。<br>建议在使用连接池（如 PgBouncer）时单独设置，避免迁移失败。 |
| SHADOW_DATABASE_URL | 可选 | 当主数据库用户无 CREATE DATABASE 权限时，需提供一个“影子数据库”用于 Prisma 迁移。<br>云数据库（如 AWS RDS）常需此配置。 |
4.2、ClickHouse 配置（高性能分析引擎）
ClickHouse 用于存储大量事件数据，支持快速查询与聚合分析。
| 变量 | 是否必需 / 默认值 | 说明 |
| CLICKHOUSE_MIGRATION_URL | ✅ 必需 | ClickHouse 迁移连接地址，使用 TCP 协议端口（9000 或 9440），格式：clickhouse://host:9000 |
| CLICKHOUSE_MIGRATION_SSL | false | 是否对迁移连接启用 SSL 加密 |
| CLICKHOUSE_URL | ✅ 必需 | ClickHouse HTTP 接口地址，用于应用访问，格式：http://host:8123 或 https://... |
| CLICKHOUSE_USER | ✅ 必需 | 用户名，需具备 SELECT, INSERT, ALTER, CREATE, DELETE 权限 |
| CLICKHOUSE_PASSWORD | ✅ 必需 | 对应用户的密码 |
| CLICKHOUSE_DB | default | 使用的数据库名 |
| CLICKHOUSE_CLUSTER_ENABLED | true | 是否启用集群模式（ON CLUSTER）。单节点部署请设为 false |
| LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED | false | 是否禁用启动时自动执行 ClickHouse 数据库迁移 |
4.3、Redis 缓存配置（提升性能）
Redis 用于缓存 API Key、Prompts 等高频访问数据，显著降低数据库压力。
| 变量 | 是否必需 / 默认值 | 说明 |
| REDIS_CONNECTION_STRING | ✅ 必需 | Redis 连接串，如 redis://:password@host:port<br>也可拆分为 REDIS_HOST, PORT, USERNAME, AUTH |
| REDIS_CLUSTER_ENABLED | false | 是否启用 Redis 集群模式 |
| REDIS_CLUSTER_NODES | 可选 | 当 REDIS_CLUSTER_ENABLED=true 时，列出所有节点 host:port，用逗号分隔，例如：redis1:6379,redis2:6379 |
| REDIS_AUTH | 可选 | Redis 认证密码（若未包含在连接串中） |
4.4、安全与认证配置（关键！）
这些变量直接影响系统安全性，请务必正确生成并保密。
| 变量 | 是否必需 / 默认值 | 说明 |
| NEXTAUTH_URL | ✅ 必需 | Langfuse 前端部署地址，如 https://your-langfuse.com 或 http://localhost:3000<br>用于 OAuth 登录回调和 Slack 链接生成 |
| NEXTAUTH_SECRET | ✅ 必需 | NextAuth 登录会话加密密钥<br>生成方式：openssl rand -base64 32（至少 256 bit 安全熵） |
| SALT | ✅ 必需 | 用于加盐哈希 API Key，防止彩虹表攻击<br>生成方式同上：openssl rand -base64 32 |
| ENCRYPTION_KEY | ✅ 必需 | 敏感数据加密密钥（如 secret prompts）<br>必须是 256 位十六进制字符串（64 字符）<br>生成命令：openssl rand -hex 32 |
4.5、对象存储（S3 兼容）配置
Langfuse 支持将事件、批处理导出、媒体文件上传到 S3 或兼容服务（如 MinIO、阿里云 OSS）。
1. 事件上传（Event Uploads）
| 变量 | 是否必需 / 默认值 | 说明 |
| LANGFUSE_S3_EVENT_UPLOAD_BUCKET | ✅ 必需 | 存储事件数据的桶名称 |
| LANGFUSE_S3_EVENT_UPLOAD_PREFIX | "" | 桶内子路径前缀，如 events/，必须以 / 结尾 |
| LANGFUSE_S3_EVENT_UPLOAD_REGION | 可选 | 桶所在区域（如 us-east-1） |
| LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT | 可选 | 自定义 S3 兼容端点（如 MinIO 地址） |
| LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID | 可选 | 访问密钥 ID（若需） |
| LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY | 可选 | 秘钥 |
| LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE | 可选 | 是否强制路径风格（MinIO 必须设为 true） |
2. 批量导出（Batch Exports）
| 变量 | 是否必需 / 默认值 | 说明 |
| LANGFUSE_S3_BATCH_EXPORT_ENABLED | false | 是否启用 S3 批量导出功能 |
| LANGFUSE_S3_BATCH_EXPORT_BUCKET | ✅ 必需（启用后） | 导出文件存储桶 |
| LANGFUSE_S3_BATCH_EXPORT_PREFIX | "" | 导出路径前缀 |
| LANGFUSE_S3_BATCH_EXPORT_REGION | 可选 | 区域 |
| LANGFUSE_S3_BATCH_EXPORT_ENDPOINT | 可选 | 自定义端点 |
| LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID | 可选 | 密钥 |
| LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY | 可选 | 秘钥 |
| LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE | 可选 | MinIO 需设为 true |
| LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT | 可选 | 外部可访问的预签名 URL 地址（如 CDN 或 VPC 内网地址） |
3. 媒体文件上传（Media Uploads）
| 变量 | 是否必需 / 默认值 | 说明 |
| LANGFUSE_S3_MEDIA_UPLOAD_BUCKET | ✅ 必需 | 存储音频、视频、图片等媒体文件的桶 |
| LANGFUSE_S3_MEDIA_UPLOAD_PREFIX | "" | 路径前缀 |
| LANGFUSE_S3_MEDIA_UPLOAD_REGION | 可选 | 区域 |
| LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT | 可选 | 端点 |
| LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID | 可选 | 密钥 |
| LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY | 可选 | 秘钥 |
| LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE | 可选 | MinIO 需设为 true |
| LANGFUSE_S3_MEDIA_MAX_CONTENT_LENGTH | 1_000_000_000 (~1GB) | 允许上传的最大文件大小（字节） |
| LANGFUSE_S3_MEDIA_DOWNLOAD_URL_EXPIRY_SECONDS | 3600 (1小时) | 预签名下载链接有效期 |
4. 并发控制
| 变量 | 默认值 | 说明 |
| LANGFUSE_S3_CONCURRENT_WRITES | 50 | 最大并发写入数（防止 socket 耗尽） |
| LANGFUSE_S3_CONCURRENT_READS | 50 | 最大并发读取数 |
4.6、服务运行与网络配置
| 变量 | 是否必需 / 默认值 | 说明 |
| PORT | 3000 (web), 3030 (worker) | 服务监听端口 |
| HOSTNAME | localhost | 容器内绑定地址。如部署在 Google Cloud Run 等平台，需设为 0.0.0.0 才能外部访问 |
4.7、缓存策略配置（性能调优）
| 变量 | 默认值 | 说明 |
| LANGFUSE_CACHE_API_KEY_ENABLED | true | 是否缓存 API Key（强烈建议开启） |
| LANGFUSE_CACHE_API_KEY_TTL_SECONDS | 300 (5分钟) | API Key 缓存过期时间 |
| LANGFUSE_CACHE_PROMPT_ENABLED | true | 是否缓存 Prompt 配置 |
| LANGFUSE_CACHE_PROMPT_TTL_SECONDS | 300 (5分钟) | Prompt 缓存过期时间 |
4.8、日志与可观测性
| 变量 | 默认值 | 说明 |
| LANGFUSE_LOG_LEVEL | info | 日志级别：trace, debug, info, warn, error, fatal |
| LANGFUSE_LOG_FORMAT | text | 输出格式：text（易读）或 json（适合日志系统采集） |
| LANGFUSE_LOG_PROPAGATED_HEADERS | 空 | 指定要通过 OpenTelemetry Baggage 传递的日志头字段，如 x-request-id,x-user-id，便于链路追踪 |
4.9、自动迁移控制
| 变量 | 默认值 | 说明 |
| LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLED | false | 是否禁用启动时自动数据库迁移<br>⚠️ 不推荐关闭，除非你手动执行迁移 |