Langfuse环境变量配置：多环境部署指南

最新推荐文章于 2025-08-28 19:51:15 发布
原创 最新推荐文章于 2025-08-28 19:51:15 发布 · 764 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

Langfuse环境变量配置：多环境部署指南

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

概述

Langfuse是一个开源的LLM工程平台，为AI应用提供观测性、分析和调试功能。在多环境部署中，环境变量配置是确保系统正常运行的关键。本文将深入探讨Langfuse的环境变量体系，提供从开发到生产环境的完整配置指南。

环境变量分类体系

Langfuse的环境变量可以分为以下几个主要类别：

1. 核心配置变量

变量名描述默认值必需
DATABASE_URLPostgreSQL数据库连接URL-✅
NEXTAUTH_SECRETNextAuth.js加密密钥-✅
SALTAPI密钥哈希盐值-✅
ENCRYPTION_KEY数据加密密钥(256位)-✅
NEXTAUTH_URLNextAuth.js回调URLhttp://localhost:3000✅

2. 数据库配置

mermaid

3. 存储配置（S3/MinIO）

mermaid

多环境配置策略

开发环境配置 (.env.dev)

# 数据库配置
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
CLICKHOUSE_URL="http://localhost:8123"
CLICKHOUSE_USER="clickhouse"
CLICKHOUSE_PASSWORD="clickhouse"

# 认证配置
NEXTAUTH_SECRET="development_secret"
SALT="dev_salt"
ENCRYPTION_KEY="0000000000000000000000000000000000000000000000000000000000000000"

# S3/MinIO配置（本地开发）
LANGFUSE_S3_EVENT_UPLOAD_BUCKET="langfuse"
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID="minio"
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY="miniosecret"
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT="http://localhost:9090"
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE="true"

# 实验性功能
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES="true"

测试环境配置 (.env.test)

# 覆盖开发环境配置
NODE_ENV="test"
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES="false"

# 测试专用数据库
DATABASE_URL="postgresql://postgres:postgres@test-db:5432/test_db"

# 禁用不必要的服务
LANGFUSE_S3_BATCH_EXPORT_ENABLED="false"

生产环境配置 (.env.prod)

# 安全配置
NEXTAUTH_SECRET="$(openssl rand -base64 32)"
SALT="$(openssl rand -base64 16)"
ENCRYPTION_KEY="$(openssl rand -hex 32)"

# 生产数据库
DATABASE_URL="postgresql://user:password@production-db:5432/production_db"
CLICKHOUSE_URL="http://clickhouse-prod:8123"
CLICKHOUSE_USER="prod_user"
CLICKHOUSE_PASSWORD="strong_password"

# 生产S3配置
LANGFUSE_S3_EVENT_UPLOAD_BUCKET="prod-langfuse-events"
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID="AKIA..."
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY="secret_key"
LANGFUSE_S3_EVENT_UPLOAD_REGION="us-east-1"
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT="https://s3.amazonaws.com"

# 安全增强
LANGFUSE_CSP_ENFORCE_HTTPS="true"
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES="false"

# 性能优化
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_BATCH_SIZE="10000"
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS="1000"

环境变量管理最佳实践

1. 密钥管理策略

mermaid

2. 多环境变量覆盖机制

Langfuse支持环境变量覆盖机制：

# .env (基础配置)
DATABASE_URL="postgresql://user:pass@localhost:5432/app"
NODE_ENV="development"

# .env.production (生产覆盖)
DATABASE_URL="postgresql://prod-user:prod-pass@prod-db:5432/prod-app"
NODE_ENV="production"
LANGFUSE_CSP_ENFORCE_HTTPS="true"

3. Docker环境变量注入

在Docker部署中，环境变量通过docker-compose.yml注入：

services:
  langfuse-web:
    image: langfuse/langfuse:3
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/postgres
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - SALT=${SALT}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
    env_file:
      - .env.production

关键环境变量详解

数据库相关变量

变量名描述示例值
DATABASE_URLPostgreSQL连接字符串postgresql://user:pass@host:5432/db
CLICKHOUSE_URLClickHouse HTTP接口http://localhost:8123
CLICKHOUSE_USERClickHouse用户名clickhouse
CLICKHOUSE_PASSWORDClickHouse密码password
REDIS_HOSTRedis主机地址localhost
REDIS_PORTRedis端口6379
REDIS_AUTHRedis认证密码redis_password

认证和安全变量

变量名描述生成命令
NEXTAUTH_SECRETNextAuth会话加密openssl rand -base64 32
SALTAPI密钥哈希盐openssl rand -base64 16
ENCRYPTION_KEY数据加密密钥openssl rand -hex 32

S3存储配置变量

# 事件存储配置
LANGFUSE_S3_EVENT_UPLOAD_BUCKET="your-bucket"
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID="AKIA..."
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY="secret"
LANGFUSE_S3_EVENT_UPLOAD_REGION="us-east-1"
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT="https://s3.amazonaws.com"

# 媒体上传配置  
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET="media-bucket"
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX="media/"

# 批量导出配置
LANGFUSE_S3_BATCH_EXPORT_ENABLED="true"
LANGFUSE_S3_BATCH_EXPORT_BUCKET="exports-bucket"

环境特定配置示例

开发环境完整配置

# .env.dev
NODE_ENV=development

# 数据库
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
CLICKHOUSE_URL="http://localhost:8123"
CLICKHOUSE_USER="clickhouse"
CLICKHOUSE_PASSWORD="clickhouse"

# 认证
NEXTAUTH_SECRET="dev_secret_123"
SALT="dev_salt_456"
ENCRYPTION_KEY="0000000000000000000000000000000000000000000000000000000000000000"

# S3/MinIO
LANGFUSE_S3_EVENT_UPLOAD_BUCKET="langfuse"
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID="minio"
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY="miniosecret"
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT="http://localhost:9090"

# 功能开关
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES="true"
TELEMETRY_ENABLED="false"

生产环境安全配置

# .env.prod
NODE_ENV=production

# 安全密钥（通过密钥管理器注入）
NEXTAUTH_SECRET="{{ .Secrets.nextauth_secret }}"
SALT="{{ .Secrets.salt }}"
ENCRYPTION_KEY="{{ .Secrets.encryption_key }}"

# 数据库连接
DATABASE_URL="{{ .Secrets.database_url }}"
CLICKHOUSE_URL="{{ .Secrets.clickhouse_url }}"
CLICKHOUSE_USER="{{ .Secrets.clickhouse_user }}"
CLICKHOUSE_PASSWORD="{{ .Secrets.clickhouse_password }}"

# S3配置
LANGFUSE_S3_EVENT_UPLOAD_BUCKET="{{ .Secrets.s3_bucket }}"
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID="{{ .Secrets.s3_access_key }}"
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY="{{ .Secrets.s3_secret_key }}"
LANGFUSE_S3_EVENT_UPLOAD_REGION="us-east-1"

# 安全增强
LANGFUSE_CSP_ENFORCE_HTTPS="true"
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES="false"

# 性能配置
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_BATCH_SIZE="20000"
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS="500"

故障排除和调试

常见问题解决方案

  1. 数据库连接失败

    # 检查数据库变量
echo $DATABASE_URL
# 测试连接
psql $DATABASE_URL -c "SELECT 1"

  2. S3存储配置错误

    # 验证S3配置
aws s3 ls s3://$LANGFUSE_S3_EVENT_UPLOAD_BUCKET/ \
  --endpoint-url $LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT \
  --profile langfuse

  3. 认证密钥问题

    # 重新生成密钥
openssl rand -base64 32  # NEXTAUTH_SECRET
openssl rand -base64 16  # SALT  
openssl rand -hex 32     # ENCRYPTION_KEY

环境变量验证脚本

#!/bin/bash
# env-validator.sh

validate_env() {
    local required_vars=("DATABASE_URL" "NEXTAUTH_SECRET" "SALT" "ENCRYPTION_KEY")
    
    for var in "${required_vars[@]}"; do
        if [ -z "${!var}" ]; then
            echo "错误: 环境变量 $var 未设置"
            exit 1
        fi
    done
    
    echo "环境变量验证通过"
}

validate_env

总结

Langfuse的环境变量配置体系提供了灵活的多环境部署支持。通过合理的环境变量管理，可以实现：

  • 🔒 安全性: 密钥分离和加密存储
  • 🚀 性能: 环境特定的性能调优
  • 🔧 可维护性: 清晰的配置结构和文档
  • 📊 可观测性: 完整的配置追踪和审计

遵循本文的指南，您可以轻松地在开发、测试和生产环境中部署和管理Langfuse实例，确保LLM应用的稳定运行和高效观测。

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

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

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值