Langfuse v3 Docker 部署

基于官方 Docker Compose 的一键部署方案，包含 Langfuse v3 全栈 6 个服务。

架构

复制代码

┌──────────────────────────────────────────────────┐
│                  Docker Compose                    │
│                                                    │
│  ┌──────────┐   ┌──────────┐   ┌────────────────┐│
│  │  nginx    │   │ Postgres │   │   ClickHouse   ││
│  │ (可选)    │   │ 用户/项目 │   │ Trace/Observa..││
│  └────┬─────┘   └──────────┘   └────────────────┘│
│       │                                            │
│  ┌────┴─────┐   ┌──────────┐   ┌────────────────┐│
│  │ Langfuse │   │  Redis   │   │     MinIO      ││
│  │ Web+Worker│   │ 队列/缓存│   │  S3 对象存储  ││
│  └──────────┘   └──────────┘   └────────────────┘│
└──────────────────────────────────────────────────┘

组件说明

服务	镜像	角色
langfuse-web	langfuse/langfuse:3	Web UI + API 服务
langfuse-worker	langfuse/langfuse-worker:3	异步事件处理（写 ClickHouse）
clickhouse	clickhouse/clickhouse-server	OLAP 数据库，存储 Trace 数据
minio	chainguard/minio	S3 兼容对象存储，存原始事件
redis	redis:7	消息队列 + API Key 缓存
postgres	postgres:17	事务数据库，存用户/项目元数据

前置条件

OS: Ubuntu 24.04 (其他 Linux 发行版也可用，脚本会自动适配)
SSH: 能够 SSH 到目标服务器
磁盘: 建议至少 20GB 可用空间（随 Trace 量增长）
端口 : 以下端口需未被占用
- 3000 --- Langfuse Web UI
- 9090 --- MinIO S3 API
- 5432 --- PostgreSQL (仅容器内监听 localhost)
- 8123 --- ClickHouse HTTP (仅 localhost)
- 6379 --- Redis (仅 localhost)

快速部署

1. 上传部署文件到服务器

bash 复制代码

# 从你的开发机上传到目标服务器
scp -r langfuse-docker-deploy root@<服务器IP>:~/

或者直接在服务器上克隆项目：

bash 复制代码

git clone <项目地址>
cd langx-example/langfuse-docker-deploy

2. 配置环境变量

bash 复制代码

cd langfuse-docker-deploy

# 编辑配置文件，填写所有 CHANGEME 标记
vim .env

# 至少需要修改：
#   NEXTAUTH_SECRET                          --- openssl rand -hex 32
#   SALT                                     --- openssl rand -hex 32
#   ENCRYPTION_KEY                           --- openssl rand -hex 32
#   DOCKER_HUB_USERNAME / _TOKEN             --- Docker Hub 认证
#   LANGFUSE_INIT_USER_EMAIL / _PASSWORD     --- 管理员账号
#   LANGFUSE_INIT_ORG_ID                     --- 必填，启用初始化流程
#   NEXTAUTH_URL                             --- 非 localhost 访问时改为外部 IP

3. 执行部署脚本

bash 复制代码

chmod +x deploy.sh
sudo ./deploy.sh

脚本会自动完成：

安装 Docker Engine + Compose 插件
配置 Docker 代理
登录 Docker Hub
启动全部 6 个服务

4. 验证部署

bash 复制代码

# 检查所有容器是否正常运行
docker compose ps

# 查看启动日志
docker compose logs -f

# 确认健康检查通过
docker compose ps --format "table {{.Name}}\t{{.Status}}"

5. 访问 Web UI

打开浏览器访问 http://<服务器IP>:3000，使用 .env 中配置的管理员邮箱和密码登录。

首次登录后，进入 Settings → API Keys 创建公钥/密钥对，用于 SDK 接入。

环境变量参考

变量	默认值	说明
`NEXTAUTH_SECRET`	---	必填。NextAuth 密钥 (`openssl rand -hex 32`)
`SALT`	---	必填。加密盐值 (`openssl rand -hex 32`)
`ENCRYPTION_KEY`	---	必填。加密密钥 (`openssl rand -hex 32`)
`DOCKER_HUB_USERNAME`	---	Docker Hub 用户名（防限速）
`DOCKER_HUB_TOKEN`	---	Docker Hub 访问令牌
`HTTP_PROXY`	`http://192.168.56.1:10811`	HTTP 代理地址
`HTTPS_PROXY`	同 HTTP_PROXY	HTTPS 代理地址
`NO_PROXY`	`localhost,192.168.56.0/24`	不走代理的地址
`LANGFUSE_INIT_USER_EMAIL`	---	首次启动自动创建的管理员邮箱
`LANGFUSE_INIT_USER_NAME`	`Admin`	管理员名称
`LANGFUSE_INIT_USER_PASSWORD`	---	管理员密码
`LANGFUSE_INIT_ORG_NAME`	`MyOrg`	初始组织名称
`LANGFUSE_INIT_PROJECT_NAME`	`MyProject`	初始项目名称
`LANGFUSE_INIT_ORG_ID`	---	必填。组织标识，无此值 init 脚本被跳过
`NEXTAUTH_URL`	`http://localhost:3000`	回调 URL。通过外部 IP 访问时需改为 `http://<服务器IP>:3000`
`POSTGRES_USER`	`postgres`	PG 用户
`POSTGRES_PASSWORD`	`postgres`	PG 密码
`CLICKHOUSE_USER`	`clickhouse`	ClickHouse 用户
`CLICKHOUSE_PASSWORD`	`clickhouse`	ClickHouse 密码
`REDIS_AUTH`	`myredissecret`	Redis 密码
`MINIO_ROOT_USER`	`minio`	MinIO 管理员用户
`MINIO_ROOT_PASSWORD`	`miniosecret`	MinIO 管理员密码

运维操作

查看日志

bash 复制代码

# 所有服务
docker compose logs -f

# 单个服务
docker compose logs -f langfuse-web
docker compose logs -f clickhouse

重启服务

bash 复制代码

# 重启单个
docker compose restart langfuse-web

# 重启全部
docker compose restart

停止服务

bash 复制代码

docker compose down
# 保留数据卷，再次 up -d 即可恢复

数据备份

bash 复制代码

# PostgreSQL
docker compose exec postgres pg_dump -U postgres > backup.sql

# 数据卷位置
docker volume inspect langfuse-docker-deploy_langfuse_postgres_data

版本升级

bash 复制代码

# 1. 拉取新镜像
docker compose pull

# 2. 重启服务
docker compose up -d

# 3. 检查迁移日志
docker compose logs langfuse-web | grep migration

常见问题

ClickHouse OOM

ClickHouse 默认会尽量使用空闲内存。本部署已限制 2G 上限。如果仍有 OOM：

yaml 复制代码

# 在 docker-compose.yml 中调小限制
clickhouse:
  deploy:
    resources:
      limits:
        memory: 1g

Docker Hub 拉取限速

匿名用户每 6 小时限制 100 次拉取。配置 .env 中的 DOCKER_HUB_USERNAME 和 DOCKER_HUB_TOKEN 即可解除。

代理不可用

如果部署环境不需要代理，在 .env 中注释或删掉 HTTP_PROXY/HTTPS_PROXY 行，脚本会自动跳过代理配置。

如果代理不稳定导致大镜像拉取中断（报错 EOF），可改用 registry mirror：

bash 复制代码

# 创建 /etc/docker/daemon.json
cat > /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}
EOF
systemctl restart docker

然后重跑 deploy.sh 即可。

修改账号/密码后无法登录

Langfuse 的 init 脚本只在首次启动时 创建管理员。后续修改 .env 中的 LANGFUSE_INIT_* 后，需要清空数据卷重新初始化：

bash 复制代码

docker compose down -v
docker compose up -d

-v 会删除所有数据卷（PG、Redis、ClickHouse、MinIO），仅适用于新部署或测试环境。

从外部 IP 访问时登录跳转到 localhost

如果通过服务器 IP 访问 Web UI 但登录后跳转到 http://localhost:3000，说明 NEXTAUTH_URL 未配置为外部地址：

env 复制代码

# .env 中改为实际访问地址
NEXTAUTH_URL=http://<服务器IP>:3000

修改后重启容器使配置生效：

bash 复制代码

docker compose down && docker compose up -d

服务启动失败

bash 复制代码

# 查看详细错误
docker compose logs --tail=50 langfuse-web
docker compose logs --tail=50 langfuse-worker

常见原因：

端口冲突：检查 docker compose ps 中是否有端口绑定失败
密钥未配置：确认 NEXTAUTH_SECRET、SALT、ENCRYPTION_KEY 已填写