连接外部 PostgreSQL 数据库

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

如果您使用托管的 PostgreSQL 服务，我们推荐：

• Amazon RDS (AWS)
• Google Cloud SQL (GCP)
• Azure Database for PostgreSQL (Azure)

关于云服务商特定的 IAM/工作负载身份认证，请参阅 IAM 认证部分。

要求

• 一个已部署的 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 参数

其格式如下：

用户名:密码@主机:端口/数据库?<url参数>

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

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"

配置完成后，您应该能够重新安装 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

双向 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"

证书卷的 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 认证。这允许您使用云服务商的工作负载身份代替静态密码。

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

AWS

Amazon RDS IAM 认证

Amazon RDS 支持 IAM 数据库认证，允许您使用 AWS IAM 凭证而不是数据库密码来验证 PostgreSQL 实例。

先决条件

1. 使用 AWS IRSA 或 EKS Pod Identity 在您的 Kubernetes 集群中配置工作负载身份
2. 在您的 RDS PostgreSQL 实例上启用 IAM 认证并向您的工作负载身份授予访问权限

配置

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

将 iamAuthProvider 设置为 "aws" 并提供 IAM 兼容的连接字符串（无密码）：

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "aws"

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

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

必需的注解

您必须将 AWS IRSA 所需的 ServiceAccount 注解应用到所有连接到 PostgreSQL 的 LangSmith 组件：

部署： backend、queue、platformBackend、hostBackend、ingestQueue

作业： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

上面列出的所有作业（除了 e2eTest）都使用 backend 服务账户。e2eTest 作业使用自己的服务账户，需要单独的注解配置。

后端服务的示例配置：

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

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

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

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

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

有关可配置服务的完整列表，请参阅 Helm values 参考。

GCP

Cloud SQL IAM 认证

Cloud SQL 支持 IAM 认证，允许您使用 GCP 服务账户而不是数据库密码进行认证。

先决条件

1. 使用 GCP Workload Identity 在您的 Kubernetes 集群中配置工作负载身份
2. 在您的 Cloud SQL 实例上启用 IAM 认证并向您的工作负载身份授予访问权限

配置

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

将 iamAuthProvider 设置为 "gcp" 并提供 IAM 兼容的连接字符串（无密码）：

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "gcp"

apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
type: Opaque
stringData:
  # IAM 连接 URL - 注意没有密码，用户名是服务账户邮箱
  connection_url: "<service-account>@<project>.iam@<cloud-sql-host>:5432/<database>?sslmode=require"

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

必需的注解

您必须将 GCP Workload Identity 所需的 ServiceAccount 注解应用到所有连接到 PostgreSQL 的 LangSmith 组件：

部署： backend、queue、platformBackend、hostBackend、ingestQueue

作业： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

上面列出的所有作业（除了 e2eTest）都使用 backend 服务账户。e2eTest 作业使用自己的服务账户，需要单独的注解配置。

后端服务的示例配置：

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

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

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

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

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

有关可配置服务的完整列表，请参阅 Helm values 参考。

Azure

Azure Database for PostgreSQL 与 Microsoft Entra 认证

Azure Database for PostgreSQL 支持 Microsoft Entra 认证，允许您使用 Azure 托管标识而不是数据库密码进行认证。

先决条件

1. 使用 Azure Workload Identity 在您的 Kubernetes 集群中配置工作负载身份
2. 在您的 Azure Database for PostgreSQL 实例上启用 Microsoft Entra 认证并向您的工作负载身份授予访问权限

配置

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

将 iamAuthProvider 设置为 "azure" 并提供 IAM 兼容的连接字符串（无密码）：

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "azure"

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

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

必需的注解和标签

您必须将 Azure Workload Identity 所需的 ServiceAccount 注解和 pod 标签应用到所有连接到 PostgreSQL 的 LangSmith 组件：

部署： backend、queue、platformBackend、hostBackend、ingestQueue

作业： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

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

后端服务的示例配置：

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"

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

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

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

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

有关可配置服务的完整列表，请参阅 Helm values 参考。

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.