Langfuse 4.68.0 配置参数详解

目标：把 Langfuse v4.68.0 自托管部署涉及的约 200 个环境变量按功能域全量分类，讲清每个参数的作用域、默认值与改动影响，并对可观测的参数给出「修改 → 验证 → 还原」实测闭环。全部实测在 Ubuntu 22.04 + Docker Compose 部署的 Langfuse 4.68.0 实例上完成，官方变量清单以仓库 .env.prod.example（642 行）为准。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• 部署形态：Docker Compose 六服务全栈（部署过程见《Langfuse Docker Compose 部署指南》，compose 项目 langfuse-4.68.0-stack）
• Langfuse 版本：4.68.0（Web 与 Worker 同版本；curl http://localhost:8146/api/public/health 实测返回 {"status":"OK","version":"4.68.0"}）
• 依赖版本：PostgreSQL 17 / ClickHouse 25.12 / Redis 7 / MinIO（Chainguard 镜像）
• 参数清单依据：官方仓库 main 分支 .env.prod.example（2026-10-23 检索，642 行）+ 官方 docker-compose.yml 默认值
• 实例演示凭据：管理员 root@langfuse.local / q1w2e3r4，项目 API Key pk-lf-4ff4ca96909a5c6a1316:sk-lf-be93f07fe1be549f7b53693cee10e079

二、前置条件

1. 已按部署指南完成六服务栈启动且健康（/api/public/health 返回 OK）；
2. 能进入容器执行命令：docker compose exec langfuse-web sh；
3. 理解 v4 的配置模型：没有配置文件，全部配置经环境变量注入（12-factor 风格），改参数 = 改 compose 的 environment: 段并重建服务；
4. 明确「不可变参数」清单：SALT、ENCRYPTION_KEY 在产生数据后不可更换（SALT 参与 API Key 哈希、ENCRYPTION_KEY 加密敏感字段），更换即失效，只能清库重来。

三、参数查看与修改方式

3.1 查看容器内实际生效值

Langfuse 进程读的就是容器环境变量，直接在容器内导出即可核对：

cd /opt/langfuse
docker compose exec langfuse-web sh -c 'printenv | sort | grep -E "^(LANGFUSE|NEXTAUTH|DATABASE|CLICKHOUSE|REDIS|TELEMETRY|SALT|ENCRYPTION|PORT|NODE_ENV)"'

实测回显（与 compose 声明完全一致，输出节选）：

CLICKHOUSE_CLUSTER_ENABLED=false
CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000
DATABASE_URL=postgresql://postgres:q1w2e3r4@postgres:5432/postgres
ENCRYPTION_KEY=5f8a2c6e9b1d4f7a3c8e0b5d2a7f4c9e6b1d8a3f5c7e0b2d4a6f8c1e3b5d7a9f
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false
LANGFUSE_INIT_ORG_ID=demo-org
LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-4ff4ca96909a5c6a1316
NEXTAUTH_URL=http://localhost:8146
NODE_ENV=production
PORT=3000
REDIS_AUTH=q1w2e3r4redis
REDIS_HOST=redis
SALT=vGmKxPYsJnWqRtZuHfE3bL8cA5dO9iU2
TELEMETRY_ENABLED=false

3.2 修改参数的标准动作

改 compose 中对应服务的 environment: 值 → docker compose up -d <服务名> 重建 → 用 3.1 的 printenv 或日志回显验证 → 确认无误后保留（异常则还原重建）。3.9 节给出一个完整实测闭环。

3.3 三类参数的作用域差异

⚠️ 注意：官方 compose 用 YAML 锚点（&langfuse-worker-env / <<: *langfuse-worker-env）让 web 继承 worker 的全部变量再覆盖差异项；手工维护两份环境变量时极易漏改一处导致 web 与 worker 口令不一致（连接失败），建议保持锚点写法。

四、参数总览

按功能域分组（变量数按 .env.prod.example 实数统计，SSO 各 IdP 组按单组 5-8 个计）：

💡 说明：Cloud 专属变量（.env.prod.example 的「Langfuse Cloud Config」段）官方明确标注 "Not recommended for self-hosted deployments as these are NOT COVERED BY SEMANTIC VERSIONING"，自托管一律不设。EE 变量无许可时不生效但无害。

五、核心参数分类详解

5.1 数据库与迁移（PostgreSQL）

业务数据（用户/组织/项目/API Key/Prompt/数据集/审计日志）全部落 PostgreSQL。迁移由镜像内 entrypoint 自动执行（PostgreSQL 迁移 + ClickHouse 迁移两步）。

实测：首次启动 Web 日志显示 460 migrations found in prisma/migrations 并逐个 Applying migration ...；LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLED=true 后此步骤跳过（升级维护窗口手工控制时使用）。

⚠️ 注意：DATABASE_URL 口令含 @ : / % # ? 等字符必须百分号编码（p@ss → p%40ss），否则 Prisma 报 P1013；官方 entrypoint 内置了检测器，失败时会输出 HINT 提示。

5.2 认证与会话（NextAuth / SALT / ENCRYPTION_KEY / SSO）

SSO 组（每组独立命名空间，自托管常用 Keycloak/自定义 OIDC）：AUTH_GOOGLE_、AUTH_GITHUB_（含 GITHUB_ENTERPRISE_）、AUTH_GITLAB_、AUTH_AZURE_AD_、AUTH_OKTA_、AUTH_AUTH0_、AUTH_COGNITO_、AUTH_KEYCLOAK_、AUTH_WORKOS_、AUTH_JUMPCLOUD_、AUTH_CUSTOM_（通用 OIDC：AUTH_CUSTOM_ISSUER/CLIENT_ID/CLIENT_SECRET/SCOPE 等）。每组公共开关：_ALLOW_ACCOUNT_LINKING（账号关联）、_CLIENT_AUTH_METHOD（默认 client_secret_basic）、_CHECKS（ID/访问令牌校验项）。

实测：本实例用口令登录 root@langfuse.local，POST /api/auth/callback/credentials 返回 302、会话接口返回用户与组织（部署指南 4.5 节实录）。将 AUTH_DISABLE_SIGNUP=true 写入 web 环境后重建，注册页即关闭（组合拳：先引导初始化管理员 → 再关闭注册，是私有化标准姿势）。

5.3 ClickHouse

追踪宽表（v4 的 events_full/events_core/analytics_* 等 18 张表）落 ClickHouse。

实测佐证：启动日志会解析 ClickHouse 版本并输出兼容性开关，25.12.11.4 实测应用了 disable-lazy-materialization-for-patch-parts（绕过 ClickHouse #102904）：

Resolved ClickHouse compatibility from version {"clickhouseVersion":"25.12.11.4",...,"computedCompatibilityFlags":[{"id":"disable-lazy-materialization-for-patch-parts",...,"matchesVersionBand":true,"applied":true},...

5.4 Redis 与缓存

实测：Redis 口令不一致时 Worker 连不上队列（日志报 Redis 认证错误），改齐 REDIS_AUTH 与 --requirepass 后恢复；--maxmemory-policy noeviction 为官方指定（队列数据不可淘汰）。

5.5 对象存储（S3 / MinIO）

三组用途独立配置：事件原始落盘（EVENT_UPLOAD）、媒体（MEDIA_UPLOAD）、批量导出（BATCH_EXPORT）。自托管最小栈用同一个 MinIO 桶 langfuse。

实测佐证：摄取一条 OTLP trace 后，MinIO /data/langfuse 出现 events/otel/demo-project/2026/10/22/21/<uuid>.json（部署指南 4.6 节实录），对象键即由 LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/ + OTLP 路径规则拼出。

5.6 摄取与队列（Ingestion / OTEL / Worker 队列开关）

💡 技术拓展：Worker 的队列开关决定了自托管 Langfuse 的水平扩容模型——默认单 Worker 消费全部队列；大流量时按「摄取 / 评估 / 事件传播 / 数据保留」拆多组 Worker 实例，每组只开对应 QUEUE_CONSUMER_*_IS_ENABLED，其余设 false，与 Kafka 消费者组、BullMQ 队列隔离是同一种「按队列分治」思路。本栈为单 Worker 全队列默认形态。

5.7 Web 展示与代理

5.8 引导初始化（LANGFUSE_INIT_*，实测警告）

排障实录：只设 USER_EMAIL/PASSWORD 不设 ORG_ID 时，初始化整体被忽略，启动日志输出：

2026-10-22T21:17:16.537Z warn         [Langfuse Init] LANGFUSE_INIT_ORG_ID is not set but other LANGFUSE_INIT_* variables are configured. The following variables will be ignored: LANGFUSE_INIT_ORG_NAME, LANGFUSE_INIT_PROJECT_NAME, LANGFUSE_INIT_USER_EMAIL, LANGFUSE_INIT_USER_NAME, LANGFUSE_INIT_USER_PASSWORD. Set LANGFUSE_INIT_ORG_ID to enable initialization.

补齐 LANGFUSE_INIT_ORG_ID + LANGFUSE_INIT_PROJECT_ID 后重建即生效（部署指南 4.3 节有完整定位过程）。INIT 只在空库首启时执行一次，之后改这些变量不再触发；生产口令务必换掉演示值。

5.9 日志与遥测（实测闭环）

「修改 → 验证 → 还原」实测闭环（worker 容器）：

第一步，临时把 worker 的日志调到 debug + json：

# docker-compose.yml 的 langfuse-worker environment 段临时追加两行
      LANGFUSE_LOG_LEVEL: debug
      LANGFUSE_LOG_FORMAT: json

docker compose up -d langfuse-worker
docker compose logs --tail 3 langfuse-worker

实测回显（已切 JSON 格式且出现 DEBUG 级别，节选）：

{"langfuse.clickhouse.route":"langfuse.queue.event_propagation",...,"level":"debug","message":"[EXPERIMENT BACKFILL] Using existing cutoff timestamp: 2026-10-22T21:27:30.041Z","severity":"DEBUG","timestamp":"2026-10-22T21:29:00.058Z",...}
{"langfuse.clickhouse.route":"langfuse.periodic_runner.trace_delete_batch_action_runner",...,"level":"debug","message":"[TraceDeleteBatchActionRunner] Acquired lock with TTL 1800s",...}

第二步，还原（删掉两行再 docker compose up -d langfuse-worker），实测回显回到默认 text/info：

2026-10-22T21:29:32.652Z info      Listening: http://f4505ee3ab31:3030
2026-10-22T21:29:32.682Z info      [Background Migration] No background migrations to run

结论：LANGFUSE_LOG_LEVEL 与 LANGFUSE_LOG_FORMAT 即改即生效（重建容器后），无需迁移，可安全用于排障。

5.10 角色与组织默认值

用途：统一身份源的团队把新用户自动落入只读角色，避免注册即 OWNER。

5.11 邮件（SMTP）

不配则注册/邀请无邮件能力（只显示链接或不支持远程邀请），私有化内网常见做法是配合 AUTH_DISABLE_SIGNUP 使用。

5.12 AI 功能与 Assistant（v4 新增）

实测佐证：启动日志中 MCP 功能逐个注册（节选）：

MCP feature registered: prompts {"featureName":"prompts","toolCount":6,...}
MCP feature registered: observations {"featureName":"observations","toolCount":5,...}
MCP feature registered: datasets {"featureName":"datasets","toolCount":13,...}
MCP feature registered: evals {"featureName":"evals","toolCount":14,...}

5.13 API 行为控制

排障实录（对应部署指南 Q3）：向 /api/public/ingestion 发 trace-create 事件实测返回 400：

{"successes":[],"errors":[{"id":"demo-trace-0001","status":400,"message":"Event type not accepted","error":"Event type \"trace-create\" is not accepted by /api/public/ingestion when LANGFUSE_MIGRATION_V4_WRITE_MODE is events_only. This endpoint only accepts score events. Upgrade to the latest Langfuse SDKs, which send traces via OpenTelemetry, or send traces directly to POST /api/public/otel/v1/traces. Scores can still be sent via POST /api/public/scores...

结论：v4 的 trace/observation 摄取入口是 POST /api/public/otel/v1/traces（OTLP），ingestion 端点只留 score；自写脚本或旧 SDK 迁移时按报错提示改端点即可。

5.14 出网管控与 SSRF 防护（v4）

v4 把「服务器代表用户发起的出网请求」按用途分组管控，未设白名单时默认只屏蔽私网段，设了白名单则强制匹配：

内网接自建 LLM 网关（如 vLLM 192.168.x.x）必须配置 LANGFUSE_LLM_CONNECTION_WHITELISTED_IP_SEGMENTS 豁免私网段，否则测试连接会被拒。

5.15 企业版（EE）与 Cloud 专属变量

EE 组（无许可时设置无效）：LANGFUSE_UI_LOGO_LIGHT_MODE_HREF/DARK_MODE_HREF（白标 logo）、LANGFUSE_UI_DOCUMENTATION_HREF/SUPPORT_HREF/FEEDBACK_HREF、LANGFUSE_UI_DEFAULT_MODEL_ADAPTER、LANGFUSE_UI_VISIBLE_PRODUCT_MODULES/HIDDEN_PRODUCT_MODULES、LANGFUSE_ALLOWED_ORGANIZATION_CREATORS（组织创建白名单）、LANGFUSE_REQUIRE_FIPS（FIPS 模式，EE 许可 + OpenSSL FIPS provider 双重前置，entrypoint 启动前强校验）。

Cloud 专属（自托管禁用，官方注明不受语义化版本约束）：NEXT_PUBLIC_LANGFUSE_CLOUD_REGION、NEXTAUTH_COOKIE_DOMAIN、STRIPE_、免费额度相关 QUEUE_CONSUMER_FREE_TIER_、ClickHouse Billing（CHB）整组等。

六、生产配置模板

适用场景：8GB+ 内存服务器、PostgreSQL/ClickHouse/Redis/MinIO 已就绪或复用已有实例、走 Nginx 反代 TLS、团队 ≤50 人。以下为 compose 环境段的生产模板（口令类自行替换为随机值）：

    environment: &langfuse-worker-env
      # —— 核心三件（不可变，先定后建库）——
      SALT: ${SALT:?请先 openssl rand -base64 32 生成}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY:?请先 openssl rand -hex 32 生成}
      DATABASE_URL: postgresql://langfuse:<强口令>@postgres:5432/langfuse?connection_limit=20&pool_timeout=10
      # —— 认证 ——
      NEXTAUTH_URL: https://langfuse.example.com
      NEXTAUTH_SECRET: <openssl rand -base64 32>
      AUTH_DISABLE_SIGNUP: "true"          # 引导管理员建好后关闭自助注册
      LANGFUSE_TRUSTED_PROXY_COUNT: "1"    # 前置 1 层 Nginx 反代时审计日志记录真实 IP
      LANGFUSE_CSP_ENFORCE_HTTPS: "true"
      # —— 追踪与队列 ——
      CLICKHOUSE_URL: http://clickhouse:8123
      CLICKHOUSE_MIGRATION_URL: clickhouse://clickhouse:9000
      CLICKHOUSE_USER: langfuse
      CLICKHOUSE_PASSWORD: <强口令>
      REDIS_HOST: redis
      REDIS_AUTH: <强口令>
      # —— 对象存储（外部 MinIO/云 S3 均可）——
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://minio:9000
      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: langfuse
      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: <强口令>
      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_EVENT_KEY_MAX_SEGMENT_BYTES: "255"   # MinIO on ext4 建议值（web/worker 一致）
      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: https://langfuse.example.com/s3
      LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT: http://minio:9000
      # —— 运维 ——
      TELEMETRY_ENABLED: "false"
      LANGFUSE_LOG_LEVEL: info
      LANGFUSE_LOG_FORMAT: json             # 便于日志采集系统解析
      LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT: "150000"
      LANGFUSE_API_TRACES_REJECT_NO_DATE_RANGE: "true"   # 保护大表

关键取舍说明：AUTH_DISABLE_SIGNUP 与 LANGFUSE_DEFAULT_ORG_* 二选一（前者封闭注册、后者开放但收口角色）；日志切 json 以便接入 Loki/ELK；LANGFUSE_API_TRACES_REJECT_NO_DATE_RANGE=true 防止未带时间范围的查询拖垮 ClickHouse；DATABASE_URL 带 connection_limit=20 控制 Prisma 连接数，多 Worker 副本时按副本数摊。

七、常见问题

Q1：改了 SALT/ENCRYPTION_KEY 后所有 API Key 失效、SDK 全部 401？

预期行为：SALT 参与 API Key 哈希、ENCRYPTION_KEY 解密敏感字段，二者建库后不可变。处理：改回原值重启；确需轮换只能新建实例迁移数据（导出 traces 重新摄取 + 手工迁移业务配置）。

Q2：web 与 worker 连不上 PostgreSQL/Redis/ClickHouse？

两类根因：口令不一致（compose 锚点被拆散后两服务口令改了一处漏一处）或凭据含未转义特殊字符（P1013）。排查顺序：容器内 printenv 核对两服务同组变量 → 官方 entrypoint 的 HINT 输出 → 各依赖容器日志的认证失败记录。

Q3：设置的 LANGFUSE_INIT_ 没生效？*

缺 LANGFUSE_INIT_ORG_ID/LANGFUSE_INIT_PROJECT_ID（见 5.8 排障实录），或库已初始化过（INIT 只跑一次）。

Q4：哪些变量是「构建期」的，预构建镜像改了没用？

NEXT_PUBLIC_* 系列（NEXT_PUBLIC_BASE_PATH、NEXT_PUBLIC_ASSET_PREFIX、NEXT_PUBLIC_TURNSTILE_SITE_KEY 等）在构建时打进前端产物，预构建镜像不支持运行时改；需要这些能力的要按官方 Dockerfile 自行 build。

Q5：如何确认某个变量真的被进程读到了？

三步：容器内 printenv <变量名> 确认注入 → 找对应可观测面（日志格式、健康端点、报错信息、UI 行为）验证 → 还原重建。空值陷阱：compose 里 VAR: 与 VAR: null 会注入空串而非「未设置」，个别「空串=禁用」语义的变量（如 LANGFUSE_AI_PROVIDER）要注意用注释掉整行的方式表达「不设置」。

八、参考链接

1. 官方环境变量参考（.env.prod.example，main 分支，2026-10-23 检索）：https://raw.githubusercontent.com/langfuse/langfuse/main/.env.prod.example
2. 官方部署文档（环境变量章节）：https://langfuse.com/docs/deployment/self-hosting
3. 官方 docker-compose.yml：https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml
4. 本专栏系列：《Langfuse Docker Compose 部署指南》（部署与排障实录）、《Langfuse 介绍与选型指南》（架构与选型）、《Langfuse 4.68.0 常用 CLI 命令与工具详解》（运维命令）