在 Helm chart 中配置环境变量

如何使用 commonEnv 和 extraEnv 在 Helm chart 中为各个 LangSmith 服务配置环境变量。

LangSmith Helm chart 提供两种向服务注入环境变量的方式：commonEnv 和 extraEnv。理解它们之间的区别有助于你正确配置部署并避免运行时错误。

commonEnv

commonEnv 是 values.yaml 中的顶层字段，应用于 除 playground 和 aceBackend 服务之外的所有 deployment 和 statefulset，这两个服务被沙箱化，不会接收 commonEnv 值。

当某个变量必须同时可供大多数服务使用时（例如自定义 CA 证书路径、代理设置或影响整个平台的功能标志），请使用 commonEnv。

commonEnv:
  - name: MY_ENV_VAR
    value: "my-value"

接收 commonEnv 的服务

以下服务会接收 commonEnv：

• backend
• platformBackend
• queue
• ingestQueue
• frontend
• hostBackend

不接收 commonEnv 的服务

以下服务被沙箱化，不会接收 commonEnv：

• playground
• aceBackend

要为这些服务设置环境变量，请直接使用它们的 extraEnv：

playground:
  deployment:
    extraEnv:
      - name: MY_ENV_VAR
        value: "my-value"

aceBackend:
  deployment:
    extraEnv:
      - name: MY_ENV_VAR
        value: "my-value"

extraEnv

extraEnv 是每服务字段，仅向特定服务添加环境变量。每个支持 extraEnv 的服务都在 <service>.deployment.extraEnv 下公开它。

当某个变量只适用于一个服务，或者你需要在 playground 或 aceBackend 上设置 commonEnv 无法覆盖的变量时，请使用 extraEnv。

backend:
  deployment:
    extraEnv:
      - name: MY_BACKEND_VAR
        value: "backend-value"

不要使用重复的变量名

Chart 使用 detectDuplicates 辅助函数来校验每个服务的环境变量名。如果同一个变量名在某个服务的合并变量列表中出现多次（包括从 commonEnv、extraEnv 和 chart 管理的变量中添加的变量），Helm 会在模板渲染期间失败，并显示类似以下内容的错误：

Duplicate keys detected: [MY_ENV_VAR]

要解决此问题，请从 commonEnv 或该服务的 extraEnv 中移除重复项，使每个变量名在每个服务中只出现一次。

WARNING

Chart 管理的变量（由 Helm chart 内部设置）也会计入重复检测。如果 chart 已经管理某个变量，请勿将该变量名添加到 commonEnv 或 extraEnv。请查看 chart values 文件，了解 chart 默认设置了哪些变量。

示例：在大多数服务上设置变量，但在某一个服务上覆盖它

要为大多数服务使用共同值，同时为特定服务覆盖该值，请在 commonEnv 中设置它，并将覆盖值添加到该服务的 extraEnv。由于 playground 和 aceBackend 不接收 commonEnv，你必须始终通过它们自己的 extraEnv 为这些服务设置变量。

# Apply to all services that receive commonEnv
commonEnv:
  - name: SSRF_ALLOW_K8S_INTERNAL
    value: "true"

# playground does not receive commonEnv — set it directly
playground:
  deployment:
    extraEnv:
      - name: SSRF_ALLOW_K8S_INTERNAL
        value: "true"
      - name: SSRF_ALLOW_PRIVATE_IPS_PLAYGROUND
        value: "true"

常用功能标志

减少批量运行持久化日志

默认情况下，LangSmith 会为通过基于 Go 的 ingest 队列持久化的每一批运行记录一条成功消息。在处理大量追踪的部署中，这可能会产生过多日志噪音。

FF_PERSIST_BATCHED_RUNS_SUCCESS_LOGGING 默认为 true，当 ingestQueue.enabled 为 true（默认值）时，会通过 commonEnv 注入到所有服务。要禁用这些成功日志消息，请在 commonEnv 中覆盖它：

commonEnv:
  - name: FF_PERSIST_BATCHED_RUNS_SUCCESS_LOGGING
    value: "false"

NOTE

将此标志设置为 false 只会抑制每批成功消息。错误仍会被记录。

相关页面

• 配置 LangSmith 以支持规模化
• Playground 环境设置
• LangSmith Helm chart values.yaml

---