3分钟上手Langfuse自托管：Docker Compose一键部署指南-优快云博客

3分钟上手Langfuse自托管：Docker Compose一键部署指南

【免费下载链接】langfuse Open source observability and analytics for LLM applications 项目地址: https://gitcode.com/GitHub_Trending/la/langfuse

还在为LLM应用的可观测性工具部署繁琐而烦恼？本文将带你通过Docker Compose在本地环境快速搭建Langfuse（Open source observability and analytics for LLM applications），全程仅需3个步骤，无需复杂配置即可拥有完整的LLM应用监控能力。

为什么选择Langfuse自托管？

Langfuse作为开源的LLM工程平台，提供了追踪（Tracing）、提示词管理（Prompt Management）、评估（Evaluations）等核心功能。自托管部署能满足数据隐私要求，同时支持完全定制化配置。根据官方架构设计，Docker Compose部署包含以下服务组件：

mermaid

准备工作

环境要求

Docker Engine ≥ 20.10
Docker Compose ≥ 2.20
至少4GB内存（推荐8GB）

必要工具安装

# Ubuntu/Debian示例
sudo apt update && sudo apt install -y docker.io docker-compose-plugin

部署步骤

1. 获取项目代码

git clone https://gitcode.com/GitHub_Trending/la/langfuse.git
cd langfuse

项目结构中与部署相关的核心文件：

docker-compose.yml：主部署配置
.env.example：环境变量模板（需复制为.env）
web/：前端应用代码
worker/：后端服务代码

2. 配置安全密钥

Docker Compose配置文件中标记为# CHANGEME的字段需要替换为安全随机值。使用以下命令生成必要的密钥：

# 生成ENCRYPTION_KEY (32字节十六进制)
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

# 生成NEXTAUTH_SECRET
echo "NEXTAUTH_SECRET=$(openssl rand -hex 32)" >> .env

# 设置强密码（示例，实际部署需自定义）
echo "POSTGRES_PASSWORD=$(openssl rand -base64 12)" >> .env
echo "REDIS_AUTH=$(openssl rand -base64 12)" >> .env
echo "MINIO_ROOT_PASSWORD=$(openssl rand -base64 12)" >> .env

关键配置项说明： | 配置项 | 用途 | 安全建议 | |--------|------|----------| | ENCRYPTION_KEY | 敏感数据加密 | 必须更换默认值，使用openssl rand -hex 32生成 | | NEXTAUTH_SECRET | 认证会话加密 | 必须更换，长度≥32字符 | | REDIS_AUTH | Redis访问密码 | 避免使用弱密码，至少12位字符 |

3. 启动服务

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

# 查看服务状态
docker compose ps

正常启动后将显示类似以下状态：

NAME                   IMAGE                        COMMAND                  SERVICE             CREATED             STATUS                    PORTS
langfuse-clickhouse    clickhouse/clickhouse-server "/entrypoint.sh"         clickhouse          50s ago             Up 49s (healthy)          127.0.0.1:8123->8123/tcp, 127.0.0.1:9000->9000/tcp
langfuse-langfuse-web  langfuse/langfuse:3          "/entrypoint.sh"         langfuse-web        50s ago             Up 49s                    0.0.0.0:3000->3000/tcp
langfuse-minio         minio/minio                  "sh -c 'mkdir -p /da…"   minio               50s ago             Up 49s (healthy)          0.0.0.0:9090->9000/tcp, 127.0.0.1:9091->9001/tcp
langfuse-postgres      postgres:17                  "docker-entrypoint.s…"   postgres            50s ago             Up 49s (healthy)          127.0.0.1:5432->5432/tcp
langfuse-redis         redis:7                      "docker-entrypoint.s…"   redis               50s ago             Up 49s (healthy)          127.0.0.1:6379->6379/tcp
langfuse-worker        langfuse/langfuse-worker:3   "docker-entrypoint.s…"   langfuse-worker     50s ago             Up 49s                    127.0.0.1:3030->3030/tcp

初始化配置

访问Web界面

打开浏览器访问 http://localhost:3000，首次登录需要创建管理员账户：

图片说明：Langfuse初始化登录界面，需创建管理员账户并设置组织信息

配置项目

创建组织（Organization）
创建项目（Project）
获取API密钥（在项目设置→API密钥）

API密钥将用于应用集成，格式如下：

Public Key: pk-lf-xxxxxxxxxxxx
Secret Key: sk-lf-xxxxxxxxxxxx

目录结构说明

部署相关核心目录：

docker-compose.yml：服务编排配置
docker-compose.dev.yml：开发环境配置
web/：前端应用代码
worker/：后端工作节点代码
packages/：共享依赖包

常见问题解决

服务启动失败

# 查看服务日志
docker compose logs -f langfuse-worker

# 检查关键服务健康状态
docker inspect -f '{{.State.Health.Status}}' langfuse-postgres

数据持久化

所有数据存储在Docker卷中，路径可通过以下命令查看：

docker volume inspect langfuse_postgres_data

备份策略

# PostgreSQL备份示例
docker exec langfuse-postgres pg_dump -U postgres > backup_$(date +%F).sql

扩展阅读

通过以上步骤，你已成功在本地环境部署了Langfuse。接下来可以参考快速入门指南集成LLM应用，开始追踪和分析你的AI服务性能。

【免费下载链接】langfuse Open source observability and analytics for LLM applications 项目地址: https://gitcode.com/GitHub_Trending/la/langfuse

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考