Langfuse 自托管本地安装指南（Docker Compose）

为爱停留

572人浏览 · 2026-06-25 14:42:07

为爱停留 · 2026-06-25 14:42:07 发布

mystu 项目采用 自托管 Langfuse 接收 Agent 链路追踪数据（见 docs/langfuse-tracing-explained.md）。本文从零讲解：需要装什么、怎么装、装完如何拿到 API Key 并接到 mystu 的 .env。推荐路径是 Docker Compose，适合本地开发、内网测试与中小规模部署；生产高可用请另看 Langfuse Kubernetes / Terraform 部署。

1. 安装前你需要知道的事

1.1 自托管会拉起哪些组件

Langfuse 不是单个容器，而是一套可观测性栈。官方 docker-compose.yml 会同时启动：

组件	作用
langfuse-web	Web UI、Public API、SDK 上报入口
langfuse-worker	从队列/S3 异步写入 ClickHouse
PostgreSQL	用户、项目、API Key、配置等 OLTP 数据
ClickHouse	Trace / Observation 等分析型数据
Redis	队列、API Key 缓存、Prompt 缓存等
MinIO	S3 兼容对象存储，持久化原始 ingestion 事件

1.2 硬件与系统建议

场景	CPU	内存	磁盘	说明
本地试用	2 核+	8 GiB+	20 GiB+	能跑起来，trace 量大时 ClickHouse 会涨盘
团队内网	4 核+	16 GiB+	100 GiB+	官方 VM 推荐起点
时区	—	—	—	Postgres 与 ClickHouse 必须 UTC（`TZ=UTC`），否则查询可能为空

1.3 软件依赖

工具	版本建议	用途
Git	任意较新版本	克隆官方仓库
Docker Engine	24+	运行容器
Docker Compose V2	插件内置	`docker compose up`

Windows / macOS：安装 Docker Desktop，并启用 WSL2（Windows）。
Linux：安装 docker-ce + docker-compose-plugin（见下文 Ubuntu 示例）。

2. 整体安装工作流（一图看懂）

3. Windows 本地安装（逐步操作）

以下步骤在 Windows 10/11 上验证思路与官方文档一致；路径示例可按你的习惯调整。

3.1 安装 Docker Desktop

下载并安装 Docker Desktop for Windows。
安装时勾选 Use WSL 2 instead of Hyper-V（推荐）。
打开 Docker Desktop，等待左下角状态为 Engine running。
在 PowerShell 中验证：

docker --version
docker compose version
docker run hello-world

若 hello-world 成功，说明 Docker 引擎可用。

3.2 克隆 Langfuse 官方仓库

选一个不含中文路径的目录（避免 Docker 挂载异常），例如：

cd C:\dev
git clone https://github.com/langfuse/langfuse.git
cd langfuse

不要直接把 Langfuse 克隆进 mystu 仓库内——它是独立的基础设施栈，与业务代码分开维护更清晰。

3.3 修改密钥（必做，不要跳过）

官方 docker-compose.yml 里所有 # CHANGEME 标记的默认值仅适合本地试玩，正式使用前必须改成足够长的随机字符串。

必须修改的项（至少改这些）：

环境变量 / 配置	位置	生成方式示例
`POSTGRES_PASSWORD`	postgres 服务	随机 32+ 字符
`CLICKHOUSE_PASSWORD`	clickhouse / worker / web	随机强密码
`REDIS_AUTH`	redis command + worker env	随机强密码
`MINIO_ROOT_PASSWORD`	minio + S3 相关 SECRET	随机强密码
`SALT`	worker / web	随机字符串
`ENCRYPTION_KEY`	worker / web	`openssl rand -hex 32`（64 位十六进制）
`NEXTAUTH_SECRET`	langfuse-web	随机 32+ 字符

Windows 生成随机 hex（PowerShell）：

# 64 字符 hex，用作 ENCRYPTION_KEY
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

推荐做法：使用 .env 文件覆盖默认值

在 langfuse 仓库根目录创建 .env（不要提交 Git），例如：

# Langfuse docker compose 环境变量（示例，请自行替换为随机值）
POSTGRES_PASSWORD=your-strong-postgres-password
CLICKHOUSE_PASSWORD=your-strong-clickhouse-password
REDIS_AUTH=your-strong-redis-password
MINIO_ROOT_PASSWORD=your-strong-minio-password
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=your-strong-minio-password
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY=your-strong-minio-password
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY=your-strong-minio-password

SALT=your-random-salt-string
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
NEXTAUTH_SECRET=your-random-nextauth-secret

NEXTAUTH_URL=http://localhost:3000

docker compose 会自动读取同目录下的 .env 并替换 ${VAR:-default} 占位符。

可选：Headless 初始化（免手动注册）

若希望首次启动就创建管理员与项目，可在 .env 中追加（密钥也可预生成）：

LANGFUSE_INIT_ORG_NAME=mystu-dev
LANGFUSE_INIT_PROJECT_NAME=mystu-agent
LANGFUSE_INIT_USER_EMAIL=admin@example.com
LANGFUSE_INIT_USER_NAME=Admin
LANGFUSE_INIT_USER_PASSWORD=ChangeMeOnFirstLogin!
# 可选：固定 project API keys（否则启动后在 UI 创建）
# LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-...
# LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-lf-...

详见 Headless Initialization。

3.4 启动 Langfuse

在 langfuse 目录执行：

# 前台启动（首次建议，方便看日志）
docker compose up

# 或后台启动
docker compose up -d

首次启动大约需要 2–5 分钟，需等待依赖健康检查通过：

如何判断成功：

docker compose ps
docker compose logs langfuse-web --tail 50

当 langfuse-web 日志中出现 Ready（或类似就绪提示），即可访问 UI。

3.5 打开 Web UI 并完成初始化

浏览器访问：http://localhost:3000
若未使用 Headless 初始化：点击 Sign up 注册第一个账号（首个用户通常为管理员）。
登录后创建 Organization → Project（若向导未自动创建）。
进入 Project → Settings → API Keys：
- 创建一对 Public Key（pk-lf-...）和 Secret Key（sk-lf-...）
- Secret Key 只显示一次，请立即保存到密码管理器。

3.6 验证 Langfuse 自身是否正常

UI 健康：

能打开 Dashboard，无 502/500。

容器健康：

docker compose ps
# 期望 langfuse-web、langfuse-worker、postgres、clickhouse、redis、minio 均为 running / healthy

可选：Public API 探测

Langfuse 提供健康检查端点（版本可能略有差异，以官方文档为准）：

curl http://localhost:3000/api/public/health

返回 200 即表示 Web 进程可用。

4. Linux / macOS 本地安装

与 Windows 逻辑相同，仅 Docker 安装方式不同。

4.1 macOS

安装 Docker Desktop for Mac。
分配足够资源：Settings → Resources，建议 Memory ≥ 8 GiB。
后续步骤同 §3.2–3.6。

4.2 Ubuntu 服务器 / WSL2 内 Linux

安装 Docker（官方源）：

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world

克隆并启动：

git clone https://github.com/langfuse/langfuse.git
cd langfuse
# 编辑 .env 修改 CHANGEME 密钥（同 §3.3）
docker compose up -d
docker compose logs -f langfuse-web

远程 VM 访问 UI 时，在安全组/防火墙中仅开放 3000（及按需 9090），不要把 Postgres/Redis/ClickHouse 暴露到公网。

5. 与 mystu 项目对接

Langfuse 装好后，还需让 mystu Agent 把 trace 发到你的实例。

5.1 mystu 侧环境变量

在 mystu 项目根目录 .env 中增加（与 AGENTS.md 一致）：

# Langfuse 自托管 tracing
LANGFUSE_ENABLED=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
LANGFUSE_HOST=http://localhost:3000
LANGFUSE_SAMPLE_RATE=1.0

变量	说明
`LANGFUSE_ENABLED`	必须显式 `true` 才启用
`LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY`	来自 Langfuse Project → API Keys
`LANGFUSE_HOST`	自托管 Web 地址；mystu 与 Langfuse 同机时用 `http://localhost:3000`
`LANGFUSE_SAMPLE_RATE`	`1.0` 全量；生产可改 `0.1` 等

mystu 运行在 Docker 容器内、Langfuse 在宿主机时，不能用 localhost，应改为 http://host.docker.internal:3000（Docker Desktop）或宿主机局域网 IP。

5.2 网络连通性检查

mystu（Python 进程）必须能访问 Langfuse Ingest API：

# 在 mystu 同一环境执行
curl http://localhost:3000/api/public/health

若 mystu 在 WSL、Langfuse 在 Windows Docker Desktop，一般 localhost:3000 可通；若不通，改用 Docker 网桥 IP 或 host.docker.internal。

5.3 端到端验证工作流

操作步骤：

启动 Langfuse：docker compose up -d（在 langfuse 目录）。
启动 mystu：python main.py（在 mystu 根目录，且 .env 已配置 LLM + MySQL + Redis + Langfuse）。
浏览器登录 mystu，发送一条会触发模型回复的消息。
打开 Langfuse UI → Tracing → 按时间或 Session 查看是否出现新 Trace。
Session ID 应与 mystu 的 thread_id 一致（见 docs/langfuse-tracing-explained.md）。

若无 Trace：

确认 LANGFUSE_ENABLED=true 且密钥正确。
查看 mystu 日志是否有 Langfuse callback 注入失败 / flush 失败 的 warning。
查看 docker compose logs langfuse-web langfuse-worker。

6. 端口与防火墙一览

官方 compose 默认端口（便于排查冲突）：

服务	宿主机端口	绑定	是否需对外
langfuse-web	3000	0.0.0.0	是（UI + API）
MinIO S3 API	9090	0.0.0.0	视多模态上传需求
MinIO Console	9091	127.0.0.1	否
PostgreSQL	5432	127.0.0.1	否
ClickHouse HTTP	8123	127.0.0.1	否
ClickHouse Native	9000	127.0.0.1	否
Redis	6379	127.0.0.1	否
langfuse-worker	3030	127.0.0.1	否

若本机 3000 已被占用（例如其他前端项目），可在 docker-compose.yml 中把 3000:3000 改为 3001:3000，并同步修改 NEXTAUTH_URL 与 mystu 的 LANGFUSE_HOST。

7. 日常运维命令

7.1 启动 / 停止 / 重启

cd C:\dev\langfuse

# 后台启动
docker compose up -d

# 停止（保留数据卷）
docker compose down

# 停止并删除所有数据（⚠️ 清空 trace，慎用）
docker compose down -v

# 拉取新镜像并重启（升级）
docker compose pull
docker compose up -d

7.2 查看日志

docker compose logs -f langfuse-web
docker compose logs -f langfuse-worker
docker compose logs -f clickhouse

7.3 磁盘占用

Trace 与原始事件会持续增长，主要占用：

Docker volume langfuse_clickhouse_data
Docker volume langfuse_minio_data
Docker volume langfuse_postgres_data

docker system df -v

磁盘不足时优先清理旧 trace（Langfuse UI / 保留策略）或扩容 volume。

8. 常见问题排查

8.1 长时间无法 Ready

可能原因	处理
内存不足	Docker Desktop 调高 Memory；关闭其它占内存容器
端口冲突	`netstat -ano \| findstr :3000`，改 compose 端口
ClickHouse 启动慢	`docker compose logs clickhouse`，等待 healthcheck 通过
密码含特殊字符未转义	`.env` 中用引号包裹或换简单强密码测试

8.2 UI 能开，但 mystu 无 Trace

检查项	处理
`LANGFUSE_ENABLED` 未设 true	改 `.env` 并重启 mystu
Host 地址错误	容器内勿用错 `localhost`
Secret Key 错误	在 UI 重新创建 Key
采样率为 0	`LANGFUSE_SAMPLE_RATE=1.0`
防火墙拦截	放行 mystu → Langfuse 3000

8.3 查询结果为空 / 时间不对

官方要求 Postgres 与 ClickHouse 时区为 UTC。官方 compose 已为 Postgres 设置 TZ=UTC / PGTZ=UTC；若你自建库，需手动保证 UTC。

8.4 多模态 Trace 上传失败

Docker Compose 默认 MinIO 的 media upload 外部 endpoint 为 http://localhost:9090。SDK 从浏览器或外部进程直传时，需保证该地址可达，或按 Blob Storage 配置指南调整。
mystu 当前以 文本 LLM + 工具 span 为主，一般不受影响。

8.5 Windows 路径 / 权限问题

仓库路径避免中文与空格。
Docker Desktop 确保 WSL2 集成已启用。
公司环境若禁止 Docker，只能改用 Linux VM 或 Langfuse Cloud。

9. 安全与合规建议（自托管必读）

mystu 当前 tracing 策略为全量记录用户消息与工具参数（见需求文档）。自托管时请注意：

项	建议
密钥	所有 `# CHANGEME` 必须替换；`.env` 不提交 Git
网络	仅内网访问 3000；公网暴露务必加 HTTPS + 认证
RBAC	Langfuse 项目级权限；生产限制 UI 访问人员
Retention	在 Langfuse 或库层面规划 trace 保留周期
备份	Docker Compose 无内置 HA/备份；重要环境请备份 volume 或上 K8s

10. 与 Docker Compose 之外的部署方式

方式	适用	文档
Docker Compose	本地 / 单机 VM	本文
Kubernetes (Helm)	生产 HA	Langfuse K8s
AWS / Azure / GCP Terraform	云上单区域生产	Langfuse 官网 Self-hosting
Langfuse Cloud	免运维	cloud.langfuse.com

mystu 的 SDK 配置方式相同，仅 LANGFUSE_HOST 改为你的生产域名，例如 https://langfuse.internal.example.com。

11. 安装完成检查清单

复制以下清单逐项打勾：

Docker / Docker Compose 可用（docker compose version）
已克隆 github.com/langfuse/langfuse
已修改所有 CHANGEME 密钥（或 .env 覆盖）
docker compose up -d 后 langfuse-web 日志 Ready
浏览器可打开 http://localhost:3000 并登录
已创建 Project 并取得 pk-lf / sk-lf
mystu .env 已配置 LANGFUSE_* 且 LANGFUSE_ENABLED=true
mystu 发一条 chat 后 Langfuse UI 可见 Trace
Session 与 mystu thread_id 可对应（可选：走一遍 HITL resume）

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责