Langfuse 自托管部署

约 720 字大约 2 分钟

LangfuseDocker自托管

2026-09-01

为什么自托管

Langfuse 提供两种形态：官方云（Langfuse Cloud）和自托管。自托管的核心价值：

数据可控：trace 里往往包含敏感的用户输入输出，数据不离开自己的服务器
成本可控：有规模的团队长期算下来比按量付费便宜
灵活：可自定义存储、接入内网、二次开发

代价是：需要自己维护基础设施（数据库、存储、升级）。

架构组件

自托管一份完整的 Langfuse 由这些组件构成，官方用 Docker Compose 编排：

组件	作用
Web App（Next.js）	前端 UI + 后端 API
Worker	异步处理上报的 trace 数据
PostgreSQL	元数据（项目、API key、prompt 版本、用户等）
ClickHouse	分析型存储，存海量 trace 与聚合查询
Redis	队列与缓存、限流
S3 / MinIO	对象存储，存原始大对象（输入输出、附件）

从 v3 起 ClickHouse 是必选组件（旧版可只用 Postgres）。

快速部署

# 1. 克隆仓库并进入自托管目录
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# 2. 启动（内部已包含所有依赖组件）
docker compose up -d

# 3. 访问
# http://localhost:3000

首次进入后按提示创建管理员账号。官方推荐用仓库自带的 docker-compose.yml 作为起点，再按需调整。

关键环境变量

自托管必须配置几个核心变量，否则服务无法启动或数据不安全：

变量	说明
`DATABASE_URL`	Postgres 连接串
`CLICKHOUSE_URL`	ClickHouse 连接串
`SALT`	用于哈希的盐值，生成后不要再改
`ENCRYPTION_KEY`	加密 API key 等敏感字段的密钥
`NEXTAUTH_SECRET`	登录会话签名密钥

生成随机值：

openssl rand -base64 32

SALT / ENCRYPTION_KEY / NEXTAUTH_SECRET 一经生成必须持久保存并保持不变，否则已有数据（尤其是加密的 API key）将无法解密。

接入自托管实例

部署完成后，在 UI 的「Project Settings」里拿到 Public Key / Secret Key，应用侧配置指向自己的地址：

import os
from langfuse import Langfuse

langfuse = Langfuse(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
    host="http://localhost:3000",   # 指向自托管实例
)

生产注意事项

反代 + HTTPS：把 Web 服务用 Nginx / Caddy 反代，挂上 HTTPS
持久化：Postgres、ClickHouse、MinIO 的数据卷务必挂载到宿主机，避免容器重建丢数据
备份：至少备份 Postgres 和加密密钥（ENCRYPTION_KEY、SALT）
资源：ClickHouse 和 Worker 在 trace 量大时是主要瓶颈，注意 CPU / 内存预留
升级：关注官方 changelog，跨大版本升级前留意数据库迁移说明

小结

自托管适合对数据主权敏感、或规模较大的团队。Docker Compose 已把复杂度封装得比较友好，真正的长期成本在于维护数据安全（密钥）、备份和升级，并非初次拉起的那一下。

Claude Code

OpenAI

Qwen Code

LangGraph

Langfuse