Langfuse Docker 部署完整教程

原创

IT蜗壳-Tango

发布于 2025-08-05 16:02:06

3990

Langfuse 是一个开源 LLM 工程平台，可帮助团队协作调试，分析和调试 LLM 应用程序。所有平台功能都是本地集成的，以加快开发工作流程。Langfuse 开放。它适用于任何模型，任何框架，允许复杂的嵌套，并具有开放的 API 来构建下游用例。LLM 应用程序使用越来越复杂的抽象，如链，工具代理和高级提示。Langfuse 中的嵌套跟踪有助于了解发生了什么并确定问题的根本原因。作为langsmith的平替方案还是很好用的。

📋 目录

系统要求
快速开始
服务配置详解
常见问题排错
端口冲突解决
服务优化配置
监控和维护
故障排除工具

🔧 系统要求

最低配置

操作系统: Windows 10/11, macOS, Linux
内存: 4GB RAM (推荐8GB+)
存储: 10GB 可用空间
Docker: Docker Desktop 4.0+ 或 Docker Engine 20.10+
Docker Compose: v2.0+

端口要求

默认使用的端口：

3000: Langfuse Web界面
3030: Langfuse Worker
5432: PostgreSQL数据库
6379: Redis缓存
8123: ClickHouse HTTP接口
9000: ClickHouse TCP接口
9001: MinIO API
9002: MinIO控制台

🚀 快速开始

1. 下载配置文件

# 创建项目目录
mkdir langfuse-docker
cd langfuse-docker

# 下载docker-compose.yml文件
curl -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml

2. 修改安全配置

编辑 docker-compose.yml 文件，修改以下标记为 # CHANGEME 的配置：

# 必须修改的安全配置
DATABASE_URL: postgresql://postgres:YOUR_PASSWORD@postgres:5432/postgres
SALT: "YOUR_RANDOM_SALT"
ENCRYPTION_KEY: "YOUR_64_CHAR_HEX_KEY"  # 使用: openssl rand -hex 32
NEXTAUTH_SECRET: YOUR_SECRET
CLICKHOUSE_PASSWORD: YOUR_CLICKHOUSE_PASSWORD
MINIO_ROOT_PASSWORD: YOUR_MINIO_PASSWORD
REDIS_AUTH: YOUR_REDIS_PASSWORD
POSTGRES_PASSWORD: YOUR_POSTGRES_PASSWORD

3. 启动服务

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

4. 访问服务

Langfuse Web: http://localhost:3000
MinIO控制台: http://localhost:9002

📊 服务配置详解

PostgreSQL 数据库

postgres:
  image: postgres:latest
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: postgres  # CHANGEME
    POSTGRES_DB: postgres
  ports:
    - "127.0.0.1:5432:5432"
  volumes:
    - langfuse_postgres_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres -p 5432"]
    interval: 3s
    timeout: 3s
    retries: 10

ClickHouse 分析数据库

clickhouse:
  image: clickhouse/clickhouse-server
  environment:
    CLICKHOUSE_DB: default
    CLICKHOUSE_USER: clickhouse
    CLICKHOUSE_PASSWORD: clickhouse  # CHANGEME
  ports:
    - "127.0.0.1:8123:8123"  # HTTP接口
    - "127.0.0.1:9000:9000"  # TCP接口
  healthcheck:
    test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
    interval: 5s
    timeout: 5s
    retries: 10

MinIO 对象存储

minio:
  image: minio/minio:latest
  command: -c 'mkdir -p /data/langfuse && minio server --address ":8080" --console-address ":9001" /data'
  environment:
    MINIO_ROOT_USER: minio
    MINIO_ROOT_PASSWORD: miniosecret  # CHANGEME
  ports:
    - "9001:8080"      # API端口
    - "127.0.0.1:9002:9001"  # 控制台端口
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:8080/minio/health/live"]
    interval: 10s
    timeout: 10s
    retries: 5
    start_period: 30s

🔍 常见问题排错

问题1: 端口被占用

错误信息:

Error response from daemon: driver failed programming external connectivity on endpoint: Bind for 127.0.0.1:5432 failed: port is already allocated

解决方案:

查看端口占用情况：

# Windows
netstat -ano | findstr :5432

# Linux/macOS
lsof -i :5432

修改端口映射：

ports:
  - "127.0.0.1:5433:5432"  # 将5432改为5433

更新相关环境变量：

DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres

问题2: 服务启动失败

错误信息:

langfuse-web-1 | error: failed to open database: dial tcp connect: connection refused

排错步骤:

检查依赖服务状态：

docker-compose ps

查看服务日志：

docker-compose logs postgres
docker-compose logs clickhouse
docker-compose logs redis

检查健康检查：

docker-compose exec postgres pg_isready -U postgres
docker-compose exec clickhouse wget -q --spider http://localhost:8123/ping

问题3: MinIO服务失败

错误信息:

minio-1 | Unable to start the server: listen tcp :8080: bind: address already in use

解决方案:

修改MinIO端口配置：

minio:
  ports:
    - "9001:8080"      # API端口
    - "127.0.0.1:9002:9001"  # 控制台端口
  command: -c 'mkdir -p /data/langfuse && minio server --address ":8080" --console-address ":9001" /data'

更新S3端点配置：

LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://minio:8080
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: http://localhost:9001

问题4: 浏览器无法访问

症状: Docker服务正常，但浏览器无法访问 http://localhost:3000

排错步骤:

测试服务连通性：

curl -I http://localhost:3000
curl -I http://127.0.0.1:3000

检查端口监听：

# Windows
netstat -an | findstr :3000

# Linux/macOS
netstat -tlnp | grep :3000

浏览器解决方案：
- 清除浏览器缓存 (Ctrl + Shift + Delete)
- 使用无痕模式访问
- 尝试 http://127.0.0.1:3000 替代 http://localhost:3000
- 强制刷新页面 (Ctrl + F5)

问题5: 数据库迁移失败

错误信息:

langfuse-web-1 | Prisma migrate failed

解决方案:

手动运行迁移：

docker-compose exec langfuse-web npx prisma migrate deploy

重置数据库（谨慎使用）：

docker-compose down -v
docker-compose up -d

🔧 端口冲突解决

常见端口冲突及解决方案

服务	默认端口	替代端口	配置修改
PostgreSQL	5432	5433	`127.0.0.1:5433:5432`
Redis	6379	6380	`127.0.0.1:6380:6379`
ClickHouse HTTP	8123	8124	`127.0.0.1:8124:8123`
ClickHouse TCP	9000	9003	`127.0.0.1:9003:9000`
MinIO API	9001	9004	`9004:8080`
MinIO Console	9002	9005	`127.0.0.1:9005:9001`

端口冲突检测脚本

#!/bin/bash
# 检测端口占用情况
ports=(3000 3030 5432 6379 8123 9000 9001 9002)

echo "检测端口占用情况..."
for port in "${ports[@]}"; do
    if netstat -tlnp 2>/dev/null | grep -q ":$port "; then
        echo "❌ 端口 $port 已被占用"
    else
        echo "✅ 端口 $port 可用"
    fi
done

⚡ 服务优化配置

1. 性能优化

# PostgreSQL优化
postgres:
  environment:
    POSTGRES_SHARED_PRELOAD_LIBRARIES: pg_stat_statements
    POSTGRES_MAX_CONNECTIONS: 200
    POSTGRES_SHARED_BUFFERS: 256MB
    POSTGRES_EFFECTIVE_CACHE_SIZE: 1GB

# ClickHouse优化
clickhouse:
  environment:
    CLICKHOUSE_MAX_MEMORY_USAGE: 2000000000
    CLICKHOUSE_MAX_THREADS: 4

2. 资源限制

services:
  langfuse-web:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '0.5'
        reservations:
          memory: 512M
          cpus: '0.25'

3. 健康检查优化

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

📊 监控和维护

1. 服务状态监控

# 查看所有服务状态
docker-compose ps

# 查看资源使用情况
docker stats

# 查看服务日志
docker-compose logs -f --tail=100

2. 数据备份

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

# 恢复数据
docker-compose exec -T postgres psql -U postgres postgres < backup.sql

# MinIO数据备份
docker-compose exec minio mc mirror /data /backup

3. 清理和维护

# 清理未使用的镜像
docker image prune -f

# 清理未使用的卷
docker volume prune -f

# 重启所有服务
docker-compose restart

# 更新镜像
docker-compose pull
docker-compose up -d

🛠️ 故障排除工具

1. 诊断脚本

#!/bin/bash
# Langfuse诊断脚本

echo "=== Langfuse 服务诊断 ==="

echo "1. 检查Docker服务状态..."
docker-compose ps

echo "2. 检查端口监听..."
netstat -tlnp | grep -E ":(3000|5432|6379|8123|9000|9001|9002)"

echo "3. 检查服务连通性..."
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 && echo " - Langfuse Web: OK" || echo " - Langfuse Web: FAIL"
curl -s -o /dev/null -w "%{http_code}" http://localhost:9002 && echo " - MinIO Console: OK" || echo " - MinIO Console: FAIL"

echo "4. 检查容器资源使用..."
docker stats --no-stream --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"

echo "5. 检查最近的错误日志..."
docker-compose logs --tail=20 | grep -i error

2. 常用命令集合

# 快速重启有问题的服务
docker-compose restart langfuse-web

# 查看特定服务的详细日志
docker-compose logs -f langfuse-web

# 进入容器调试
docker-compose exec langfuse-web bash

# 检查网络连接
docker-compose exec langfuse-web ping postgres
docker-compose exec langfuse-web ping clickhouse

# 测试数据库连接
docker-compose exec postgres psql -U postgres -c "SELECT version();"
docker-compose exec clickhouse clickhouse-client --query "SELECT version()"

3. 环境变量检查

# 检查关键环境变量
docker-compose exec langfuse-web env | grep -E "(DATABASE_URL|CLICKHOUSE|REDIS|MINIO)"

📝 最佳实践

1. 安全配置

修改所有默认密码
使用强随机密钥
限制服务只绑定到localhost（除了Web服务）
定期更新镜像版本

2. 生产环境建议

使用外部数据库服务
配置SSL/TLS证书
设置反向代理（Nginx/Traefik）
配置日志轮转
设置监控告警

3. 开发环境优化

使用Docker卷进行数据持久化
配置开发环境专用的环境变量
使用docker-compose override文件

🆘 紧急故障处理

服务完全无法启动

停止所有服务：docker-compose down
清理卷数据：docker-compose down -v（注意：会丢失数据）
重新拉取镜像：docker-compose pull
重新启动：docker-compose up -d

数据损坏恢复

停止服务：docker-compose stop
从备份恢复数据
重新启动服务：docker-compose start

内存不足

检查资源使用：docker stats
重启占用内存过多的服务
考虑增加系统内存或优化配置

📞 获取帮助

如果遇到本教程未涵盖的问题：

查看官方文档：https://langfuse.com/docs
检查GitHub Issues：https://github.com/langfuse/langfuse/issues
社区讨论：https://discord.gg/7NXusRtqYU

最后更新: 2025年8月5日

版本: v1.0

适用于: Langfuse v3.x + Docker Compose v2.x

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

agent

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

agent

#Langfuse

登录后参与评论

0 条评论

热度

Langfuse Docker 部署完整教程

Langfuse Docker 部署完整教程

📋 目录

🔧 系统要求

最低配置

端口要求

🚀 快速开始

1. 下载配置文件

2. 修改安全配置

3. 启动服务

4. 访问服务

📊 服务配置详解

PostgreSQL 数据库

ClickHouse 分析数据库

MinIO 对象存储

🔍 常见问题排错

问题1: 端口被占用

问题2: 服务启动失败

问题3: MinIO服务失败

问题4: 浏览器无法访问

问题5: 数据库迁移失败

🔧 端口冲突解决

常见端口冲突及解决方案

端口冲突检测脚本

⚡ 服务优化配置

1. 性能优化

2. 资源限制

3. 健康检查优化

📊 监控和维护

1. 服务状态监控

2. 数据备份

3. 清理和维护

🛠️ 故障排除工具

1. 诊断脚本

2. 常用命令集合

3. 环境变量检查

📝 最佳实践

1. 安全配置

2. 生产环境建议

3. 开发环境优化

🆘 紧急故障处理

服务完全无法启动

数据损坏恢复

内存不足

📞 获取帮助

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐