170 lines
6.2 KiB
Markdown
170 lines
6.2 KiB
Markdown
# Langfuse
|
||
|
||
[English](./README.md) | [中文](./README.zh.md)
|
||
|
||
此服务部署 Langfuse，一个用于 LLM 应用可观测性、指标、评估和提示管理的开源平台。
|
||
|
||
## 服务
|
||
|
||
- **langfuse-worker**：处理 LLM 操作的后台工作者服务
|
||
- **langfuse-web**：Langfuse 主 Web 应用服务器
|
||
- **postgres**：PostgreSQL 数据库
|
||
- **clickhouse**：用于事件存储的 ClickHouse 分析数据库
|
||
- **minio**：兼容 S3 的对象存储，用于媒体和导出
|
||
- **redis**：用于缓存和作业队列的内存数据存储
|
||
|
||
## 快速开始
|
||
|
||
1. 将 `.env.example` 复制为 `.env`：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. 在 `.env` 中更新关键的密钥：
|
||
|
||
```bash
|
||
# 生成安全的密钥
|
||
NEXTAUTH_SECRET=$(openssl rand -base64 32)
|
||
ENCRYPTION_KEY=$(openssl rand -hex 32)
|
||
POSTGRES_PASSWORD=your-secure-password
|
||
CLICKHOUSE_PASSWORD=your-secure-password
|
||
MINIO_ROOT_PASSWORD=your-secure-password
|
||
REDIS_AUTH=your-secure-redis-password
|
||
```
|
||
|
||
3. 启动服务：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
4. 访问 `http://localhost:3000` 打开 Langfuse
|
||
|
||
## 核心环境变量
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| --------------------------------------- | ------------------------------------- | ----------------------- |
|
||
| `LANGFUSE_VERSION` | Langfuse 容器镜像版本 | `3.143.0` |
|
||
| `LANGFUSE_PORT` | Web 界面端口 | `3000` |
|
||
| `NEXTAUTH_URL` | Langfuse 实例的公开 URL | `http://localhost:3000` |
|
||
| `NEXTAUTH_SECRET` | NextAuth.js 密钥（生产环境必需） | `mysecret` |
|
||
| `ENCRYPTION_KEY` | 敏感数据加密密钥（64 个十六进制字符） | `0...0` |
|
||
| `SALT` | 密码哈希盐值 | `mysalt` |
|
||
| `TELEMETRY_ENABLED` | 启用匿名遥测 | `true` |
|
||
| `LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES` | 启用测试版功能 | `true` |
|
||
|
||
## 数据库配置
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| --------------------- | --------------- | ------------ |
|
||
| `POSTGRES_VERSION` | PostgreSQL 版本 | `17` |
|
||
| `POSTGRES_USER` | 数据库用户 | `postgres` |
|
||
| `POSTGRES_PASSWORD` | 数据库密码 | `postgres` |
|
||
| `POSTGRES_DB` | 数据库名称 | `postgres` |
|
||
| `CLICKHOUSE_USER` | ClickHouse 用户 | `clickhouse` |
|
||
| `CLICKHOUSE_PASSWORD` | ClickHouse 密码 | `clickhouse` |
|
||
|
||
## 存储和缓存配置
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| --------------------- | ------------------ | --------------- |
|
||
| `MINIO_ROOT_USER` | MinIO 管理员用户名 | `minio` |
|
||
| `MINIO_ROOT_PASSWORD` | MinIO 管理员密码 | `miniosecret` |
|
||
| `REDIS_AUTH` | Redis 密码 | `myredissecret` |
|
||
|
||
## S3/媒体配置
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| ----------------------------------- | ----------------- | ----------------------- |
|
||
| `LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT` | 媒体上传 S3 端点 | `http://localhost:9090` |
|
||
| `LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT` | 事件上传 S3 端点 | `http://minio:9000` |
|
||
| `LANGFUSE_S3_BATCH_EXPORT_ENABLED` | 启用批量导出到 S3 | `false` |
|
||
|
||
## 数据卷
|
||
|
||
- `langfuse_postgres_data`：PostgreSQL 数据持久化
|
||
- `langfuse_clickhouse_data`：ClickHouse 事件数据
|
||
- `langfuse_clickhouse_logs`：ClickHouse 日志
|
||
- `langfuse_minio_data`：MinIO 对象存储数据
|
||
|
||
## 资源限制
|
||
|
||
所有服务都有可配置的 CPU 和内存限制：
|
||
|
||
- **langfuse-worker**：2 个 CPU 核心，2GB RAM
|
||
- **langfuse-web**：2 个 CPU 核心，2GB RAM
|
||
- **clickhouse**：2 个 CPU 核心，4GB RAM
|
||
- **minio**：1 个 CPU 核心，1GB RAM
|
||
- **redis**：1 个 CPU 核心，512MB RAM
|
||
- **postgres**：2 个 CPU 核心，2GB RAM
|
||
|
||
通过修改 `.env` 中的 `*_CPU_LIMIT`、`*_MEMORY_LIMIT`、`*_CPU_RESERVATION` 和 `*_MEMORY_RESERVATION` 变量来调整限制。
|
||
|
||
## 网络访问
|
||
|
||
- **langfuse-web**（端口 3000）：对所有接口开放，用于外部访问
|
||
- **minio**（端口 9090）：对所有接口开放，用于媒体上传
|
||
- **所有其他服务**：绑定到 `127.0.0.1`（仅限本地）
|
||
|
||
在生产环境中，使用防火墙或反向代理限制外部访问。
|
||
|
||
## 生产部署
|
||
|
||
用于生产部署的建议：
|
||
|
||
1. **安全性**：
|
||
- 使用 `openssl rand -base64 32` 和 `openssl rand -hex 32` 生成强密钥
|
||
- 使用具有 SSL/TLS 的反向代理（nginx、Caddy）
|
||
- 更改所有默认密码
|
||
- 通过将 `NEXTAUTH_URL` 设置为您的域来启用 HTTPS
|
||
|
||
2. **数据持久化**：
|
||
- 对数据使用外部卷或云存储
|
||
- 配置定期 PostgreSQL 备份
|
||
- 监控 ClickHouse 磁盘使用情况
|
||
|
||
3. **性能**：
|
||
- 根据工作负载增加资源限制
|
||
- 大规模部署时考虑使用专用 ClickHouse 集群
|
||
- 如需要，配置 Redis 持久化
|
||
|
||
## 端口
|
||
|
||
- **3000**：Langfuse Web 界面（外部）
|
||
- **3030**：Langfuse 工作者 API（仅限本地）
|
||
- **5432**：PostgreSQL（仅限本地）
|
||
- **8123**：ClickHouse HTTP（仅限本地）
|
||
- **9000**：ClickHouse 原生协议（仅限本地）
|
||
- **9090**：MinIO S3 API（外部）
|
||
- **9091**：MinIO 控制台（仅限本地）
|
||
- **6379**：Redis（仅限本地）
|
||
|
||
## 健康检查
|
||
|
||
所有服务都包括健康检查，失败时会自动重新启动。
|
||
|
||
## 文档
|
||
|
||
- [Langfuse 文档](https://langfuse.com/docs)
|
||
- [Langfuse GitHub](https://github.com/langfuse/langfuse)
|
||
|
||
## 故障排除
|
||
|
||
### 服务无法启动
|
||
|
||
- 查看日志：`docker compose logs <service-name>`
|
||
- 确保设置了所有必需的环境变量
|
||
- 验证磁盘空间和系统资源是否充足
|
||
|
||
### 数据库连接错误
|
||
|
||
- 验证 `POSTGRES_PASSWORD` 在服务之间匹配
|
||
- 检查 PostgreSQL 服务是否健康：`docker compose ps`
|
||
- 确保端口未被占用
|
||
|
||
### MinIO 权限问题
|
||
|
||
- 清除 MinIO 数据并重新启动：`docker compose down -v`
|
||
- 在 `.env` 中重新生成 MinIO 凭证
|