Langfuse 部署指南：Docker 与 Kubernetes Helm

本文档提供了使用 Docker 和 Kubernetes Helm 部署 Langfuse 的详细指南。Langfuse 是一个开源的 LLM 工程可观测性和评估平台，可帮助团队跟踪、监控和评估 LLM 应用程序。

目录

• 概述
• 前提条件
• Docker 部署
• 使用 Docker Compose
• 环境变量配置
• 数据持久化
• 安全配置
• Kubernetes Helm 部署
• Helm Chart 安装
• 配置参数
• 资源扩展
• 监控与日志
• 升级与维护
• 故障排除
• 最佳实践
• 参考资料

概述

Langfuse 是一个专为 LLM 应用设计的可观测性平台，提供了追踪、评估和监控 LLM 应用的能力。本指南将帮助您在生产环境中部署 Langfuse，包括：

• 使用 Docker 和 Docker Compose 进行单机部署
• 使用 Kubernetes Helm 进行集群部署
• 配置、扩展和维护部署

前提条件

Docker 部署前提条件

• Docker Engine 20.10.0+
• Docker Compose v2.0.0+
• 至少 2GB RAM 和 2 CPU 核心
• 至少 10GB 可用磁盘空间

Kubernetes 部署前提条件

• Kubernetes 集群 v1.19+
• Helm v3.0.0+
• kubectl 已配置访问您的集群
• 持久化存储类（StorageClass）
• Ingress 控制器（可选，用于外部访问）

Docker 部署

使用 Docker Compose

创建一个 docker-compose.yml 文件，包含 Langfuse 及其依赖组件：

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: langfuse
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  langfuse:
    image: langfuse/langfuse:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/langfuse
      - NEXTAUTH_SECRET=your-nextauth-secret
      - NEXTAUTH_URL=http://localhost:3000
      - SALT=your-salt
      - TELEMETRY_ENABLED=false
      # 添加其他环境变量
    ports:
      - "3000:3000"
    restart: unless-stopped

volumes:
  postgres_data:

启动服务：

docker-compose up -d

环境变量配置

Langfuse 需要配置以下关键环境变量：

环境变量	描述	示例值
DATABASE_URL	PostgreSQL 连接字符串	postgresql://user:password@host:5432/langfuse
NEXTAUTH_SECRET	用于加密会话的密钥	随机字符串
NEXTAUTH_URL	应用程序的公共 URL	https://langfuse.yourdomain.com
SALT	用于哈希的盐值	随机字符串
PORT	应用程序端口	3000
TELEMETRY_ENABLED	是否启用遥测	false

对于生产环境，建议使用环境变量文件（.env）并确保敏感信息的安全性。

数据持久化

确保为 PostgreSQL 配置持久化存储：

volumes:
  postgres_data:
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: '/path/on/host/postgres-data'

安全配置

为生产环境增强安全性：

1. 使用非默认端口
2. 配置 HTTPS（可使用 Nginx 或 Traefik 作为反向代理）
3. 设置强密码
4. 限制网络访问

示例 Nginx 配置：

server {
    listen 443 ssl;
    server_name langfuse.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Kubernetes Helm 部署

Helm Chart 安装

1. 添加 Langfuse Helm 仓库：

helm repo add langfuse https://langfuse.github.io/helm-charts
helm repo update

1. 创建 values.yaml 文件：

# values.yaml
global:
  environment: production

langfuse:
  replicaCount: 2
  image:
    repository: langfuse/langfuse
    tag: latest
    pullPolicy: Always

  env:
    - name: DATABASE_URL
      valueFrom:
        secretKeyRef:
          name: langfuse-secrets
          key: database-url
    - name: NEXTAUTH_SECRET
      valueFrom:
        secretKeyRef:
          name: langfuse-secrets
          key: nextauth-secret
    - name: NEXTAUTH_URL
      value: "https://langfuse.yourdomain.com"
    - name: SALT
      valueFrom:
        secretKeyRef:
          name: langfuse-secrets
          key: salt
    - name: TELEMETRY_ENABLED
      value: "false"

  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi

  service:
    type: ClusterIP
    port: 3000

  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: nginx
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
      - host: langfuse.yourdomain.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: langfuse-tls
        hosts:
          - langfuse.yourdomain.com

postgresql:
  enabled: true
  auth:
    username: postgres
    password: postgres
    database: langfuse
  primary:
    persistence:
      enabled: true
      size: 10Gi
  metrics:
    enabled: true

1. 创建 Kubernetes Secret：

kubectl create namespace langfuse

kubectl create secret generic langfuse-secrets \
  --namespace langfuse \
  --from-literal=database-url="postgresql://postgres:postgres@langfuse-postgresql:5432/langfuse" \
  --from-literal=nextauth-secret="your-nextauth-secret" \
  --from-literal=salt="your-salt"

1. 安装 Helm Chart：

helm install langfuse langfuse/langfuse \
  --namespace langfuse \
  --values values.yaml \
  --create-namespace

配置参数

Helm Chart 支持多种配置参数，以下是一些重要参数：

参数	描述	默认值
langfuse.replicaCount	Langfuse 副本数	1
langfuse.image.tag	镜像标签	latest
langfuse.resources	资源请求和限制	{}
langfuse.ingress.enabled	是否启用 Ingress	false
postgresql.enabled	是否部署 PostgreSQL	true
postgresql.auth.password	PostgreSQL 密码	random
postgresql.primary.persistence.size	PostgreSQL 存储大小	8Gi

资源扩展

根据负载调整资源配置：

langfuse:
  replicaCount: 3
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

  resources:
    requests:
      cpu: 1000m
      memory: 1Gi
    limits:
      cpu: 2000m
      memory: 2Gi

监控与日志

集成 Prometheus 和 Grafana 进行监控：

prometheus:
  enabled: true
  serviceMonitor:
    enabled: true

grafana:
  enabled: true
  dashboards:
    default:
      langfuse-dashboard:
        json: |
          {
            "annotations": {...},
            "editable": true,
            "panels": [...],
            "title": "Langfuse Dashboard",
            ...
          }

升级与维护

Docker 升级

1. 拉取最新镜像：

docker-compose pull

1. 重启服务：

docker-compose down
docker-compose up -d

Kubernetes 升级

1. 更新 Helm 仓库：

helm repo update

1. 升级部署：

helm upgrade langfuse langfuse/langfuse \
  --namespace langfuse \
  --values values.yaml

备份与恢复

定期备份 PostgreSQL 数据库：

# Docker 环境
docker exec -t langfuse_postgres_1 pg_dump -U postgres langfuse > langfuse_backup_$(date +%Y%m%d).sql

# Kubernetes 环境
kubectl exec -it -n langfuse langfuse-postgresql-0 -- pg_dump -U postgres langfuse > langfuse_backup_$(date +%Y%m%d).sql

故障排除

常见问题

1. 连接数据库失败
2. 检查 DATABASE_URL 环境变量
3. 确认 PostgreSQL 服务正在运行

4. 验证网络连接和防火墙设置

5. 应用程序启动失败

6. 检查日志：docker-compose logs langfuse 或 kubectl logs -n langfuse deployment/langfuse
7. 验证所有必需的环境变量

8. 检查资源限制

9. 性能问题

10. 增加资源分配
11. 检查数据库索引和查询性能
12. 考虑启用缓存

日志收集

在 Kubernetes 中设置 EFK (Elasticsearch, Fluentd, Kibana) 或 PLG (Prometheus, Loki, Grafana) 堆栈：

fluentd:
  enabled: true
  elasticsearch:
    host: elasticsearch-master
    port: 9200

elasticsearch:
  enabled: true
  replicas: 3
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi

kibana:
  enabled: true
  resources:
    requests:
      cpu: 500m
      memory: 1Gi

最佳实践

1. 高可用性配置
2. 使用多个副本
3. 配置 Pod 反亲和性

4. 跨多个可用区部署

5. 安全最佳实践

6. 定期更新密码和密钥
7. 实施网络策略限制访问
8. 使用 HTTPS 加密所有流量

9. 定期更新容器镜像

10. 性能优化

11. 为 PostgreSQL 配置适当的资源
12. 使用 PgBouncer 进行连接池管理

13. 考虑使用 Redis 进行缓存

14. 备份策略

15. 实施自动定时备份
16. 测试恢复过程
17. 存储备份在外部存储

参考资料

• Langfuse 官方文档
• Docker 文档
• Kubernetes 文档
• Helm 文档
• PostgreSQL 文档