Langfuse：开源 LLM 工程平台（Tracing/评估/Prompt 管理）｜部署与使用全指南
适用版本说明：本文基于 langfuse/langfuse 官方仓库 main 分支的官方
docker-compose.yml（Langfuse Server v4 镜像docker.langfuse.com/langfuse/langfuse:4与langfuse-worker:4）撰写，撰写日期 2026 年 10 月；自托管 v3+ 起架构为 web/worker/Postgres/Redis/ClickHouse/MinIO 六服务组合，本文环境变量均取自官方 compose 文件，与你的版本可能略有差异时以官方 self-hosting 文档为准。仓库 star 数超 1.6 万，2026 年 1 月起成为 ClickHouse 的一部分，迭代非常活跃。
Langfuse 是一个开源的 LLM 工程平台，帮助团队协作地开发、监控、评估与调试 AI 应用：把每一次 LLM 调用、检索、工具执行都记录为可检索的 Trace，集中版本化管理 Prompt，并支持 LLM-as-a-judge、人工标注、数据集评测等多种评估方式。它既可以一键接入 Langfuse Cloud，也可以用官方 docker compose 在自己的服务器上完整自托管——本文聚焦后者，从环境变量到 SDK 接入、Trace 实操到故障排查给出全流程。
一、项目介绍与适用场景
Langfuse 的核心定位是 LLM 应用可观测性（LLM Observability）+ LLM Ops 工具链。它不属于模型服务层，而是架在你的应用与 LLM API 之间，采集运行时数据：
应用通过 SDK/OpenAI drop-in 埋点，把 trace 发送到 Langfuse Server；
Server 由 web（API+UI）与 worker（异步摄入、评估任务）组成，数据落在 Postgres（元数据）、ClickHouse（trace 分析）与对象存储 MinIO/S3（大 payload）。
适用人群与场景：
不适合的场景：
需要 LLM 网关做路由/限流/计费的主体功能（Langfuse 是观测平台，不是网关；可与 LiteLLM 等互补）。
极小团队追求"零运维"——直接用 Langfuse Cloud 免费层更省事。
期望开箱即用的对话聊天界面（它不是 chat UI）。
二、核心功能逐条拆解
LLM 应用可观测（Tracing）：应用埋点后摄入 trace，追踪 LLM 调用、检索、embedding、agent 行动，按 session/user 组织排查复杂日志。官方示例 trace 见下图。
Prompt Management：集中管理、版本化 prompt，服务端与客户端强缓存，迭代 prompt 不增加应用延迟；支持 label（如
production）切换。Evaluations（评估）：LLM-as-a-judge、代码评估器、用户反馈收集、人工标注（Queues）、通过 API/SDK 自定义评估流水线。
Datasets（数据集）：构建测试集与基准，配合实验（experiments）做持续改进与上线前回归，可无缝对接 LangChain/LlamaIndex。
LLM Playground：在 UI 中直接改 prompt/模型配置即时重跑，trace 里的坏结果可一键跳到 Playground 迭代。
公开 API：完整的 REST API + OpenAPI spec + Postman collection，可用 API 驱动自定义 LLMOps 流程。
Python/JS-TS SDK：官方 SDK（
langfusePyPI/npm 包），Python 提供@observe()装饰器零侵入追踪。OpenAI drop-in 集成：
from langfuse.openai import openai一行替换，自动记录所有模型参数与用量。框架自动埋点：LangChain（callback）、LlamaIndex、Haystack、LiteLLM、Vercel AI SDK、Mastra 等一键回调接入。
UI 应用生态：Dify、OpenWebUI、Flowise、LobeChat 等主流自托管 LLM 应用均可对接 Langfuse。
11. AI 功能（新）：内置 in-app agent 与 LLM 评估所需的 LANGFUSE_AI_* 系列配置，可接 OpenAI/Azure/Bedrock/Vertex 等。 12. 多租户：organization → project 两级结构，每 project 独立 API key，支持 RBAC 与 SSO（EE 组件）。
三、全套官方链接
四、硬件与环境前置要求
五、多平台部署步骤
官方提供四种自托管方式：本地 docker compose、VM docker compose、Kubernetes (Helm，生产首选)、以及 AWS/Azure/GCP 的 Terraform 模板。Windows/macOS 官方未提供非 Docker 的原生安装方式（Langfuse Server 是 Node.js 应用但官方仅以容器分发，Docker Desktop 即可覆盖），下面按官方 compose 为准展开。
5.1 本地部署（官方推荐入门，5 分钟）
# 获取最新仓库
git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# 直接启动（第一次会拉取 6 个镜像并执行数据库迁移）
docker compose up
看到 langfuse-web 启动后，浏览器访问 http://localhost:3000 注册账号即可。
5.2 Linux VM 生产部署
git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# 生成密钥（官方 compose 注释要求 CHANGEME 的项）
echo "SALT=$(openssl rand -base64 32)" # 用于 API key 哈希，之后不可更改
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" # 32 字节 hex
echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)"
# 编辑 docker-compose.yml，把所有 # CHANGEME 的默认值替换为自己的密钥：
# DATABASE_URL、SALT、ENCRYPTION_KEY、NEXTAUTH_SECRET、
# CLICKHOUSE_PASSWORD、REDIS_AUTH、MINIO_ROOT_PASSWORD 及各 LANGFUSE_S3_*_SECRET_ACCESS_KEY
# 后台启动
docker compose up -d
# 查看迁移与服务状态
docker compose ps
docker compose logs -f langfuse-web
官方 compose 的安全默认：仅 langfuse-web（3000）与 minio（9090）对宿主开放，Postgres/Redis/ClickHouse/worker 端口都绑定在 127.0.0.1。
5.3 macOS / Windows
安装 Docker Desktop 后执行与 5.1/5.2 相同的命令即可；docker compose v2 语法一致。Windows 注意在 WSL2 后端运行，项目目录放在 WSL 文件系统内性能更好。
5.4 Kubernetes（生产首选）
官方维护 Helm chart，用法以官方文档为准：
helm repo add langfuse https://langfuse.github.io/langfuse-kube
helm repo update
helm install langfuse langfuse/langfuse \
--set postgresql.enabled=true \
--set clickhouse.enabled=true \
--set additionalEnv.NEXTAUTH_SECRET=$(openssl rand -base64 32) \
--set additionalEnv.SALT=$(openssl rand -base64 32)
具体 values 参数较多，务必对照官方 Helm 文档 https://langfuse.com/self-hosting/kubernetes-helm。
六、配置文件全部参数解释
以下参数来自官方 docker-compose.yml（以官方文件为准），全部为环境变量注入。
6.1 核心必配
6.2 对象存储（MinIO/S3）
6.3 初始化（首次启动自动建组织/项目/用户）
6.4 其他
6.5 带注释的完整 .env 示例
# ---- 核心（全部 CHANGEME）----
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/postgres
NEXTAUTH_URL=http://localhost:3000 # 生产改为 https://langfuse.example.com
NEXTAUTH_SECRET=<openssl rand -base64 32 的输出>
SALT=<openssl rand -base64 32 的输出> # 之后不可改
ENCRYPTION_KEY=<openssl rand -hex 32 的输出>
# ---- ClickHouse ----
CLICKHOUSE_USER=clickhouse
CLICKHOUSE_PASSWORD=<自定义强密码>
CLICKHOUSE_CLUSTER_ENABLED=false
# ---- Redis ----
REDIS_AUTH=<自定义强密码>
# ---- MinIO ----
MINIO_ROOT_USER=minio
MINIO_ROOT_PASSWORD=<自定义强密码>
# ---- 初始化（仅首次启动生效）----
LANGFUSE_INIT_ORG_NAME=my-org
LANGFUSE_INIT_PROJECT_NAME=prod
LANGFUSE_INIT_USER_EMAIL=admin@example.com
LANGFUSE_INIT_USER_NAME=Admin
LANGFUSE_INIT_USER_PASSWORD=<强密码>
# ---- 遥测 ----
TELEMETRY_ENABLED=false
七、启动、后台常驻、开机自启、改端口
前台启动（调试用）：
docker compose up # Ctrl+C 停止
后台常驻（生产标准姿势）：
docker compose up -d
docker compose ps # 六个服务均应 Up (healthy)
docker compose logs -f langfuse-web langfuse-worker
官方 compose 已为每个服务写好 restart: always，即 Docker 守护进程启动时自动拉起——只要宿主机开机自启 Docker 服务，Langfuse 就开机自启：
sudo systemctl enable docker
服务组成与端口一览：
改端口： 编辑 docker-compose.yml 的 ports 段，例如 web 改为 8080：
langfuse-web:
ports:
- "8080:3000"
同时把 NEXTAUTH_URL 改成 http://<主机>:8080（否则登录回调 404），再 docker compose up -d 重建。
反向代理（Nginx + HTTPS）示例：
server {
listen 443 ssl;
server_name langfuse.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
反代后如需真实客户端 IP，设置 LANGFUSE_TRUSTED_PROXY_COUNT=1。
Windows 常驻： Docker Desktop 设为开机自启，compose 内 restart: always 即可；官方未提供 Windows 原生服务方式。
八、功能实操教程
8.1 初始化组织、项目与 API Key
方式 A：UI 手动 —— 访问 http://localhost:3000 → 注册 → 新建 Organization → 新建 Project → 进入 Project Settings → API Keys → Create new API keys，得到 pk-lf-... 与 sk-lf-...。
方式 B：环境变量自动初始化 —— 首次 docker compose up 前在 compose/.env 里设置 6.3 节的 LANGFUSE_INIT_*，启动后即有现成账号与 key，直接登录使用。
8.2 Python @observe() 接入
pip install langfuse openai
from langfuse import observe
from langfuse.openai import openai # OpenAI drop-in：自动上报
@observe()
def story():
return openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "What is Langfuse?"}],
).choices[0].message.content
@observe()
def main():
return story()
main() # 自动生成 main -> story -> LLM 调用的嵌套 trace
自托管时环境变量指向自己的实例：
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_HOST="http://localhost:3000" # 自托管地址；Cloud 为 https://cloud.langfuse.com
8.3 JS/TS SDK 接入
npm install langfuse
import { Langfuse } from "langfuse";
const langfuse = new Langfuse({
publicKey: "pk-lf-...",
secretKey: "sk-lf-...",
baseUrl: "http://localhost:3000", // 自托管必填
});
const trace = langfuse.trace({ name: "chat", userId: "u123" });
const span = trace.span({ name: "retrieval" });
span.end(); // 结束观测
trace.update({ output: "done" });
await langfuse.flushAsync(); // 进程退出前确保上报
8.4 OpenAI drop-in（最小改造接入）
只需把 import openai 换成 from langfuse.openai import openai，所有 chat.completions.create 的模型参数、prompt、补全、用量都会自动进 Langfuse，无需任何其他代码。
8.5 Trace 查看与 Score 实操
打开 UI → 侧边栏 Traces，可按 name/user/session/时间过滤；点进单条 trace 看嵌套 observations 树、耗时、token 与费用。
打分：
from langfuse import Langfuse
lf = Langfuse()
trace = lf.trace(id="db22d0a442216b485abd83cc9df6d9ee")
trace.score(name="user-feedback", value=0.8, comment="回答准确")
lf.flush()
UI 中 Trace 详情页 → Scores 即可看到该评分。
8.6 Prompt 管理
from langfuse import Langfuse
lf = Langfuse()
# 创建（UI 中也可操作）：Prompt 带版本与 label
lf.create_prompt(name="support-bot", prompt="你是客服助手...{{question}}",
labels=["production"])
# 应用中拉取（带缓存）
prompt = lf.get_prompt("support-bot", label="production")
compiled = prompt.compile(question="怎么退货？")
UI 路径：Prompts → 新建/查看版本 → label 管理（如把 v3 标记为 production）。
8.7 数据集评估（Datasets + Experiments）
UI：Datasets → New dataset → 添加 items（input / expected output）。
用 Python 跑实验：
dataset = lf.get_dataset("qa-regression")
for item in dataset.items:
output = my_llm_app(item.input) # 你的应用
item.link(lf.trace(name="experiment-run"), input=item.input, output=output)
UI 的 Dataset Runs 页对比每次实验的平均分、耗时与费用。
8.8 公开 API 调用示例
# 列出 traces（Basic Auth：publicKey:secretKey）
curl -u "pk-lf-...:sk-lf-..." \
"http://localhost:3000/api/public/traces?limit=10"
# 创建 score
curl -u "pk-lf-...:sk-lf-..." -X POST \
http://localhost:3000/api/public/scores \
-H "Content-Type: application/json" \
-d '{"traceId":"<trace-id>","name":"feedback","value":1}'
完整 endpoint 列表见官方 API 文档（含 OpenAPI spec 与 Postman collection）。
九、全套报错故障排查
十、升级、回滚与卸载
版本查看：
docker compose images
docker compose ps
# 官方建议订阅 self-hosting update list 获取版本公告：https://langfuse.com/self-hosting#subscribe
升级（Docker Compose）：
git pull # 拉取最新 compose 文件
# 修改镜像 tag（如 :4 → 新版本）后：
docker compose pull
docker compose up -d # web/worker 启动时自动执行数据库迁移
升级（Helm/K8s）：
helm repo update
helm upgrade langfuse langfuse/langfuse -f values.yaml
回滚到指定版本： 把 compose 中的镜像 tag 改回旧版本（如 docker.langfuse.com/langfuse/langfuse:3）再 docker compose up -d。注意：如果新版本已执行迁移，降级可能不被官方支持，回滚前务必恢复升级前的数据卷备份——生产升级前先备份：
docker compose down
docker run --rm -v langfuse_langfuse_postgres_data:/data -v $(pwd):/bk \
alpine tar czf /bk/pg-backup.tar.gz /data
# clickhouse、minio、redis 数据卷同理
完整卸载清理清单：
# 1. 停止并删除容器与网络
docker compose down
# 2. 删除全部数据卷（不可逆！含所有 trace 数据）
docker compose down -v
# 3. 删除镜像
docker rmi docker.langfuse.com/langfuse/langfuse:4 \
docker.langfuse.com/langfuse/langfuse-worker:4 \
docker.io/clickhouse/clickhouse-server:25.12 docker.io/redis:7 \
docker.io/postgres:17 cgr.dev/chainguard/minio
# 4. 删除代码目录
rm -rf langfuse/
# 5. 清理反代配置与 DNS（如有）
十一、商用许可与合规风险提示
License 结构：仓库主体为 MIT（包括 web、worker 核心代码），但
ee/目录下的企业版组件（SSO、RBAC、高级 admin 功能等）使用单独的 EE 许可，不可自由商用。详见 https://langfuse.com/docs/open-source 与 LICENSE 文件。MIT 义务：保留版权声明即可，可闭源商用、可修改再分发；但官方商标 "Langfuse" 受保护，二次分发产品请改名，不得暗示官方出品。
EE 组件：若使用 SSO/SAML、SCIM、LDAP 等 EE 特性，需要购买商业许可（或使用 Langfuse Cloud）。
无 API 费用：自托管版本不限 trace 量、不收费；Langfuse Cloud 有免费层与按量计费，额度以官方 pricing 页为准。
数据隐私与出网：
自托管时 trace 数据全部存本机（Postgres/ClickHouse/MinIO），但默认
TELEMETRY_ENABLED=true会向官方 PostHog 上报匿名使用统计（不含 trace 内容），敏感环境设为false。LLM-as-a-judge、in-app agent 等 AI 功能会把被评估内容发给
LANGFUSE_AI_*配置的模型服务商，注意数据流向。客户端 SDK 会把 prompt/输入输出发送到你的 Langfuse Server，生产环境务必用 HTTPS，
pk/sk妥善保管（sk只放服务端）。生产风险：trace 含用户原始输入，注意按 GDPR/个保法处理留存策略；ClickHouse/Postgres 需自行做备份与容量规划；官方 compose 是单机方案，规模化要转 Helm 部署。
附录：命令速查
# 部署
git clone --depth=1 https://github.com/langfuse/langfuse.git && cd langfuse
docker compose up -d # 后台启动
docker compose logs -f langfuse-web # 跟日志
docker compose ps # 健康状态
# 密钥生成
openssl rand -base64 32 # NEXTAUTH_SECRET / SALT
openssl rand -hex 32 # ENCRYPTION_KEY
# 运维
docker compose down # 停止（保留数据）
docker compose down -v # 停止并删数据卷
docker compose pull && docker compose up -d # 升级
# SDK
pip install langfuse openai # Python
npm install langfuse # JS/TS
export LANGFUSE_HOST=http://localhost:3000
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
# API
curl -u "pk-lf-...:sk-lf-..." "http://localhost:3000/api/public/traces?limit=10"