Langfuse部署与使用

1. 环境准备

## 1. 修改静态ip
[root@spark001 ~]# vi /etc/sysconfig/network-scripts/ifcfg-ens33 

## 2. 修改机器名
[root@spark001 ~]# hostnamectl set-hostname langfuse

## 3. 查看docker dcoker-compose版本
[root@langfuse ~]# docker compose version
Docker Compose version v2.27.1
[root@langfuse ~]# docker --version
Docker version 26.1.4, build 5650f9b

2. 下载配置

## 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.1 docker-compose.yml

# ============================= 核心说明 =============================
# 1. 已关联 .env 文件，所有安全配置（密码/密钥）从 .env 读取，避免明文暴露
# 2. 建议限制主机入站流量：仅开放 langfuse-web（3000 端口）和 minio（9090 端口）
# 3. 其他组件（如 PostgreSQL、Redis）仅绑定 localhost（127.0.0.1），不允许外部直接访问
# ====================================================================

version: '3.8'  # 补充规范的 Compose 版本（原文件隐含，显式声明更兼容）
services:

  # -------------------------- Langfuse 核心服务 --------------------------
  # 1. 工作节点：处理任务队列、数据 ingestion 等后台逻辑
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:3  # 固定版本镜像
    restart: always  # 容器退出后自动重启
    depends_on: &langfuse-depends-on  # 依赖服务（复用锚点，供其他服务引用）
      postgres:
        condition: service_healthy  # 等待 PostgreSQL 健康检查通过
      minio:
        condition: service_healthy  # 等待 MinIO 健康检查通过
      redis:
        condition: service_healthy  # 等待 Redis 健康检查通过
      clickhouse:
        condition: service_healthy  # 等待 ClickHouse 健康检查通过
    ports:
      - 127.0.0.1:3030:3030  # 仅本地访问的工作节点端口
    environment: &langfuse-worker-env  # 环境变量（复用锚点，供 web 服务引用）
      # 基础配置（NEXTAUTH_URL 保留默认本地地址，如需外部访问可在 .env 中定义）
      NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
      TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}  # 是否开启遥测（默认开启）
      LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-true}  # 实验性功能（默认开启）
      
      # -------------------------- 安全配置：从 .env 读取 --------------------------
      # 数据库配置（DATABASE_URL/SALT/ENCRYPTION_KEY 已在 .env 定义）
      DATABASE_URL: ${DATABASE_URL}
      SALT: ${SALT}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
      
      # ClickHouse 配置（用户名默认保留，密码从 .env 读取）
      CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
      CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
      
      # MinIO/S3 配置（访问密钥默认保留，密钥与 MINIO_ROOT_PASSWORD 一致，从 .env 读取）
      LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
      # 事件上传配置
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
      LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: ${LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID:-minio}
      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}  # 与 MinIO 密码一致
      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: ${LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT:-http://minio:9000}
      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: ${LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE:-true}
      LANGFUSE_S3_EVENT_UPLOAD_PREFIX: ${LANGFUSE_S3_EVENT_UPLOAD_PREFIX:-events/}
      # 媒体上传配置
      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: ${LANGFUSE_S3_MEDIA_UPLOAD_BUCKET:-langfuse}
      LANGFUSE_S3_MEDIA_UPLOAD_REGION: ${LANGFUSE_S3_MEDIA_UPLOAD_REGION:-auto}
      LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: ${LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID:-minio}
      LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}  # 与 MinIO 密码一致
      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT:-http://localhost:9090}
      LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: ${LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE:-true}
      LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: ${LANGFUSE_S3_MEDIA_UPLOAD_PREFIX:-media/}
      # 批量导出配置
      LANGFUSE_S3_BATCH_EXPORT_ENABLED: ${LANGFUSE_S3_BATCH_EXPORT_ENABLED:-false}
      LANGFUSE_S3_BATCH_EXPORT_BUCKET: ${LANGFUSE_S3_BATCH_EXPORT_BUCKET:-langfuse}
      LANGFUSE_S3_BATCH_EXPORT_PREFIX: ${LANGFUSE_S3_BATCH_EXPORT_PREFIX:-exports/}
      LANGFUSE_S3_BATCH_EXPORT_REGION: ${LANGFUSE_S3_BATCH_EXPORT_REGION:-auto}
      LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: ${LANGFUSE_S3_BATCH_EXPORT_ENDPOINT:-http://minio:9000}
      LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT: ${LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT:-http://localhost:9090}
      LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: ${LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID:-minio}
      LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}  # 与 MinIO 密码一致
      LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: ${LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE:-true}
      
      # Redis 配置（地址/端口默认保留，密码从 .env 读取）
      REDIS_HOST: ${REDIS_HOST:-redis}
      REDIS_PORT: ${REDIS_PORT:-6379}
      REDIS_AUTH: ${REDIS_AUTH}
      REDIS_TLS_ENABLED: ${REDIS_TLS_ENABLED:-false}
      REDIS_TLS_CA: ${REDIS_TLS_CA:-/certs/ca.crt}
      REDIS_TLS_CERT: ${REDIS_TLS_CERT:-/certs/redis.crt}
      REDIS_TLS_KEY: ${REDIS_TLS_KEY:-/certs/redis.key}
      
      # 邮件配置（可选，如需邮件通知可在 .env 中定义）
      EMAIL_FROM_ADDRESS: ${EMAIL_FROM_ADDRESS:-}
      SMTP_CONNECTION_URL: ${SMTP_CONNECTION_URL:-}

  # 2. Web 节点：Langfuse 前端界面与 API 服务
  langfuse-web:
    image: docker.io/langfuse/langfuse:3  # 固定版本镜像
    restart: always  # 容器退出后自动重启
    depends_on: *langfuse-depends-on  # 复用依赖服务配置（同 worker）
    ports:
      - 3000:3000  # 对外暴露的 Web 端口（需开放主机防火墙）
    environment:
      <<: *langfuse-worker-env  # 复用 worker 的环境变量
      # -------------------------- Web 额外配置：从 .env 读取 --------------------------
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}  # NextAuth 密钥已在 .env 定义
      # 初始化组织/项目/用户（可选，如需预设可在 .env 中定义，当前保留空值）
      LANGFUSE_INIT_ORG_ID: ${LANGFUSE_INIT_ORG_ID:-}
      LANGFUSE_INIT_ORG_NAME: ${LANGFUSE_INIT_ORG_NAME:-}
      LANGFUSE_INIT_PROJECT_ID: ${LANGFUSE_INIT_PROJECT_ID:-}
      LANGFUSE_INIT_PROJECT_NAME: ${LANGFUSE_INIT_PROJECT_NAME:-}
      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-}
      LANGFUSE_INIT_PROJECT_SECRET_KEY: ${LANGFUSE_INIT_PROJECT_SECRET_KEY:-}
      LANGFUSE_INIT_USER_EMAIL: ${LANGFUSE_INIT_USER_EMAIL:-}
      LANGFUSE_INIT_USER_NAME: ${LANGFUSE_INIT_USER_NAME:-}
      LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_INIT_USER_PASSWORD:-}


  # -------------------------- 依赖服务：数据存储/缓存 --------------------------
  # 1. ClickHouse：时序数据存储（Langfuse 核心数据）
  clickhouse:
    image: docker.io/clickhouse/clickhouse-server  # 官方 ClickHouse 镜像
    restart: always
    user: "101:101"  # 匹配容器内默认用户组（避免权限问题）
    environment:
      CLICKHOUSE_DB: default  # 默认数据库名
      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}  # 与 worker 配置一致
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}  # 从 .env 读取密码
    volumes:
      - langfuse_clickhouse_data:/var/lib/clickhouse  # 数据持久化卷
      - langfuse_clickhouse_logs:/var/log/clickhouse-server  # 日志持久化卷
    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
      start_period: 1s

  # 2. MinIO：对象存储（存储事件、媒体文件）
  minio:
    image: docker.io/minio/minio  # 官方 MinIO 镜像
    restart: always
    entrypoint: sh  # 自定义启动脚本（先创建存储桶）
    command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
    environment:
      # MinIO 管理员配置：从 .env 读取（用户名默认保留，密码统一为 123456）
      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-minio}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    ports:
      - 9090:9000  # 对象存储服务端口（对外暴露，需开放防火墙）
      - 127.0.0.1:9091:9001  # Web 控制台端口（仅本地访问）
    volumes:
      - langfuse_minio_data:/data  # 数据持久化卷
    healthcheck:  # 健康检查
      test: ["CMD", "mc", "ready", "local"]
      interval: 1s
      timeout: 5s
      retries: 5
      start_period: 1s

  # 3. Redis：缓存/任务队列
  redis:
    image: docker.io/redis:7  # 官方 Redis 7 镜像
    restart: always
    command: >  # 启动命令（密码从 .env 读取）
      --requirepass ${REDIS_AUTH}
    ports:
      - 127.0.0.1:6379:6379  # 仅本地访问
    healthcheck:  # 健康检查
      test: ["CMD", "redis-cli", "-a", "${REDIS_AUTH}", "ping"]  # 带密码检查
      interval: 3s
      timeout: 10s
      retries: 10

  # 4. PostgreSQL：关系型数据库（存储用户、组织、项目等元数据）
  postgres:
    image: docker.io/postgres:${POSTGRES_VERSION:-17}  # 官方 PostgreSQL 镜像（默认17版本）
    restart: always
    environment:
      # PostgreSQL 配置：从 .env 读取（用户名/数据库名默认保留，密码统一为 123456）
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB:-postgres}
      TZ: UTC  # 时区（固定UTC，避免时间偏差）
      PGTZ: UTC  # PostgreSQL 时区
    ports:
      - 127.0.0.1:5432:5432  # 仅本地访问
    volumes:
      - langfuse_postgres_data:/var/lib/postgresql/data  # 数据持久化卷
    healthcheck:  # 健康检查
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]  # 匹配用户名
      interval: 3s
      timeout: 3s
      retries: 10


# -------------------------- 持久化卷配置 --------------------------
# 所有卷均使用本地驱动，数据存储在主机 /var/lib/docker/volumes/ 目录下
volumes:
  langfuse_postgres_data:
    driver: local
  langfuse_clickhouse_data:
    driver: local
  langfuse_clickhouse_logs:
    driver: local
  langfuse_minio_data:
    driver: local

2.2 .env

# .env 文件（仅本地可见，避免提交到代码库）
DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@postgres:5432/postgres
SALT=f8e7d6c5b4a39281706f5e4d3c2b1a00
ENCRYPTION_KEY=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2
NEXTAUTH_SECRET=9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d
CLICKHOUSE_PASSWORD=123456
MINIO_ROOT_PASSWORD=123456
REDIS_AUTH=123456
POSTGRES_PASSWORD=123456

2.3 启动

docker compose up -d

3. 访问服务

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

4. 使用

langfuse_handler = CallbackHandler(
            public_key=public_key,
)

llm = ChatOpenAI(
    model="deepseek-chat",
    temperature=0.7,
    base_url="https://api.deepseek.com",
    api_key=os.getenv("DEEPSEEK_API_KEY"),  # 使用环境变量
    streaming=False,  # 禁用流式传输以获取完整响应
    callbacks=[langfuse_handler]  # 添加Langfuse回调
)