Langfuse Self-Hosting — Production Docker Compose Stack

简介

这是 Langfuse v3 自托管的生产级 docker-compose 栈 —— Postgres、Clickhouse、Redis、MinIO、Worker、Web，一句 docker-compose up 起。含 SSO 配置片段（Google / Okta / GitHub OAuth）、S3 日志卸载、每日 Postgres 备份 cron、单日 100 万观测以上工作负载的扩容笔记。适合不能上云的敏感 prompt 数据团队 —— 医疗、金融、本地化合规环境。兼容任何 Docker 24+ 的 Linux 主机。装机时间：30 分钟从 0 到第一条 trace。

docker-compose.yml 核心

services:
  langfuse-web:
    image: langfuse/langfuse:3
    environment:
      DATABASE_URL: postgresql://lf:${POSTGRES_PASSWORD}@postgres:5432/langfuse
      CLICKHOUSE_URL: http://clickhouse:8123
      CLICKHOUSE_USER: lf
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      REDIS_URL: redis://redis:6379
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXTAUTH_URL: https://langfuse.example.com
      AUTH_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
      AUTH_GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse-events
      LANGFUSE_S3_EVENT_UPLOAD_REGION: us-east-1
    ports: ["3000:3000"]
    depends_on: [postgres, clickhouse, redis, minio]

  langfuse-worker:
    image: langfuse/langfuse-worker:3
    environment: # 同 web
      DATABASE_URL: postgresql://lf:${POSTGRES_PASSWORD}@postgres:5432/langfuse
      CLICKHOUSE_URL: http://clickhouse:8123
      REDIS_URL: redis://redis:6379

  postgres:
    image: postgres:16
    volumes: ["pgdata:/var/lib/postgresql/data"]
    environment:
      POSTGRES_USER: lf
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: langfuse

  clickhouse:
    image: clickhouse/clickhouse-server:24
    volumes: ["chdata:/var/lib/clickhouse"]
    environment:
      CLICKHOUSE_USER: lf
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}

  redis:
    image: redis:7-alpine

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    volumes: ["miniodata:/data"]

volumes: { pgdata: {}, chdata: {}, miniodata: {} }

每日 Postgres 备份

0 2 * * * docker exec postgres pg_dump -U lf langfuse | gzip > /backup/lf-$(date +\%F).sql.gz
0 3 * * * find /backup -name "lf-*.sql.gz" -mtime +30 -delete

扩容阈值

健康检查

curl -f https://langfuse.example.com/api/public/health  # web
docker exec clickhouse clickhouse-client -q "SELECT count() FROM traces"

FAQ

Q: Langfuse v3 和 v2 自托管者的区别？ A: v3 引入 Clickhouse 存 trace（v2 仅 Postgres）、MinIO/S3 存事件上传、worker 服务独立。仓库里有迁移指南。同样硬件 v3 能扛 10 倍观测量。

Q: 规模小要 MinIO 吗？ A: 单日 <10 万观测不要 —— Langfuse 回退到直写 DB。MinIO 是高量事件入库的队列。生产规模或要跟云端对齐就跑，开发环境可省。

Q: TLS 和反代怎么搞？ A: 前面架 Caddy 或 nginx。Caddy 自动签 Let's Encrypt：langfuse.example.com { reverse_proxy langfuse-web:3000 } 就完事。NEXTAUTH_URL 必须和公网 HTTPS URL 一致，否则 Google OAuth 跳转炸。