LangSmith 使用 PostgreSQL 数据库作为事务性工作负载和操作数据（除了运行记录之外的几乎所有内容）的主要数据存储。默认情况下，LangSmith 自托管版将使用内部 PostgreSQL 数据库。但是，您可以配置 LangSmith 以使用外部 PostgreSQL 数据库。通过配置外部 PostgreSQL 数据库，您可以更轻松地管理数据库的备份、扩展和其他操作任务。

要求

• 一个已配置的 PostgreSQL 数据库，您的 LangSmith 实例需要能够通过网络访问它。我们建议使用托管的 PostgreSQL 服务，例如：
  • Amazon RDS
  • Google Cloud SQL
  • Azure Database for PostgreSQL
• 注意：我们仅官方支持 PostgreSQL 版本 >= 14。
• 我们支持密码和 IAM/工作负载身份 认证。
• 一个对 PostgreSQL 数据库具有管理员访问权限的用户。此用户将用于创建必要的表、索引和模式。
• 此用户还需要能够在数据库中创建扩展。我们使用/将尝试安装 btree_gin、btree_gist、pgcrypto、citext、ltree 和 pg_trgm 扩展。
• 如果使用非 public 的模式，请确保没有其他启用了这些扩展的模式，或者您必须将其包含在搜索路径中。
• 对 pgbouncer 和其他连接池的支持是基于社区的。社区成员报告称，pgbouncer 在 pool_mode = session 以及合适的 ignore_startup_parameters 设置下可以工作（截至撰写时，需要忽略 search_path 和 lock_timeout）。需要注意避免污染连接池；建议具备一定程度的 PostgreSQL 专业知识。LangChain Inc 目前没有将 pgbouncer 或 amazon rds proxy 或任何其他连接池的正式测试覆盖或商业支持纳入路线图计划，但欢迎社区通过 GitHub issues 讨论和协作支持。
• 默认情况下，我们建议使用 至少 2 个 vCPU 和 8GB 内存 的实例。但是，实际要求将取决于您的工作负载和用户数量。我们建议监控您的 PostgreSQL 实例并根据需要进行扩展。

连接字符串

您需要提供 PostgreSQL 数据库的连接字符串。此连接字符串应包含以下信息：

• 主机
• 端口
• 数据库
• 用户名
• 密码（如果有任何特殊字符，请确保进行 URL 编码）- 注意： 使用 IAM 身份验证时，连接字符串中不需要密码。更多信息见下文。
• URL 参数

其形式如下：

username:password@host:port/database?<url_params>

一个示例连接字符串可能如下所示：

myuser:mypassword@myhost:5432/mydatabase?sslmode=disable

如果没有 URL 参数，连接字符串将如下所示：

myuser:mypassword@myhost:5432/mydatabase

对于 IAM 身份验证，省略密码并使用身份名称作为用户名：

my-workload-identity@myhost:5432/mydatabase?sslmode=require

配置

准备好连接字符串后，您可以配置 LangSmith 实例以使用外部 PostgreSQL 数据库。您可以通过修改 LangSmith Helm Chart 安装的 values 文件或 Docker 安装的 .env 文件来实现。

Helm

postgres:
  external:
    enabled: true
    connectionUrl: "您的连接 URL"

Docker

# 在您的 .env 文件中
POSTGRES_DATABASE_URI="您的连接 URL"

配置完成后，您应该能够重新安装 LangSmith 实例。如果一切配置正确，您的 LangSmith 实例现在应该正在使用您的外部 PostgreSQL 数据库。

与 PostgreSQL 的 TLS

使用本节配置 PostgreSQL 连接的 TLS。有关挂载内部/公共 CA 以便 LangSmith 信任您的 PostgreSQL 服务器证书的信息，请参阅 配置自定义 TLS 证书。

服务器 TLS（单向）

要验证 PostgreSQL 服务器证书：

• 使用 config.customCa.secretName 和 config.customCa.secretKey 提供 CA 包。
• 在连接 URL 中使用 sslmode=require 或 sslmode=verify-full，以及 sslrootcert=system。

仅当您的 PostgreSQL 服务器使用内部或私有 CA 时才挂载自定义 CA。公开信任的 CA 不需要此配置。

Helm (服务器 TLS)

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 包的键
postgres:
  external:
    enabled: true
    connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system"
    customTls: true

Kubernetes Secret (CA 包)

apiVersion: v1
kind: Secret
metadata:
  name: langsmith-custom-ca
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <ROOT_OR_INTERMEDIATE_CA_CERT_CHAIN>
    -----END CERTIFICATE-----

带客户端认证的相互 TLS (mTLS)

自 LangSmith helm chart 版本 0.12.29 起，我们支持 PostgreSQL 客户端的 mTLS。对于 mTLS 中的服务器端认证，除了以下客户端证书配置外，还需使用 服务器 TLS 步骤（自定义 CA）。

如果您的 PostgreSQL 服务器要求客户端证书认证：

• 提供一个包含您的客户端证书和密钥的 Secret。
• 通过 postgres.external.clientCert.secretName 引用它，并使用 certSecretKey 和 keySecretKey 指定密钥。
• 在连接 URL 中使用 sslmode=verify-full 和 sslrootcert=system。

Helm (客户端认证)

postgres:
  external:
    enabled: true
    connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system"
    customTls: true
    clientCert:
      secretName: "postgres-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"

Kubernetes Secret (客户端证书/密钥)

apiVersion: v1
kind: Secret
metadata:
  name: postgres-mtls-secret
type: Opaque
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    <CLIENT_CERT>
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    <CLIENT_KEY>
    -----END PRIVATE KEY-----

证书卷的 Pod 安全上下文

为 mTLS 挂载的证书卷受文件访问限制保护。为确保所有 LangSmith pod 都能读取证书文件，您必须在 pod 安全上下文中设置 fsGroup: 1000。

您可以通过以下两种方式之一进行配置：

选项 1：使用 commonPodSecurityContext

在顶层设置 fsGroup 以应用于所有 pod：

commonPodSecurityContext:
  fsGroup: 1000

选项 2：添加到各个 pod 的安全上下文

如果需要更细粒度的控制，请将 fsGroup 单独添加到每个 pod 的安全上下文中。有关完整参考，请参阅 mTLS 配置示例。

IAM 身份验证

自 LangSmith helm chart 版本 0.12.34 起，我们支持 PostgreSQL 的 IAM 身份验证。这允许您使用云提供商的工作负载身份而不是静态密码。

支持的提供商

提供商	数据库服务	文档
AWS	RDS PostgreSQL	IAM 数据库身份验证
GCP	Cloud SQL	IAM 身份验证
Azure	Azure Database for PostgreSQL	Microsoft Entra 身份验证

先决条件

IAM 身份验证仅处理连接身份验证。您可能仍然需要在数据库中运行 SQL 命令来创建 IAM 用户/角色，并授予其访问 LangSmith 模式所需的权限和特权。

1. 在您的 Kubernetes 集群中 配置工作负载身份。请参阅您的云提供商的文档：
   • AWS IRSA 或 EKS Pod Identity
   • GCP Workload Identity
   • Azure Workload Identity
2. 在您的 PostgreSQL 实例上 启用 IAM 身份验证 并授予您的工作负载身份访问权限。请参考上面链接的云提供商文档。
3. 根据您的云提供商的要求，使用工作负载身份绑定 注解您的 Kubernetes ServiceAccounts 和 Deployments/Jobs。

配置

如果在 LangSmith 已经运行了初始迁移后切换到新的 IAM 用户，您可能需要将现有表的所有权转移给新的 IAM 用户。否则，由于对先前用户拥有的表权限不足，迁移可能会失败。

要启用 IAM 身份验证，请设置 iamAuthProvider 字段并使用兼容 IAM 的连接字符串（无密码）：

Helm

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "azure"  # 或 "gcp" 或 "aws"

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
type: Opaque
stringData:
  # IAM 连接 URL - 注意没有密码，用户名是身份名称
  connection_url: "<identity-name>@<host>:5432/<database>?sslmode=require"

IAM 身份验证需要 TLS。您必须在连接字符串中包含 sslmode=require。

必需的注解

您必须将云提供商工作负载身份所需的所有 ServiceAccount 注解和 pod 标签应用到所有连接到 PostgreSQL 的 LangSmith 组件。这包括：

Deployments: backend, queue, platformBackend, hostBackend

Jobs: migrations, authBootstrap, feedbackConfigMigration, feedbackDataMigration, e2eTest

上面列出的所有作业（除了 e2eTest）都使用 backend 服务账户。对于这些作业，如果您的云提供商要求，您只需要配置 pod 标签（例如，Azure 要求在 pod 上设置 azure.workload.identity/use: "true"）。e2eTest 作业使用其自己的服务账户，需要单独的注解配置。

后端服务的示例（对上面列出的其他服务重复此操作）：

AWS

backend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"
...

GCP

backend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"
...

Azure

backend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"
  migrations:
    labels:
      azure.workload.identity/use: "true"
...

有关可配置服务及其注解/标签选项的完整列表，请参阅 Helm values 参考。