Skip to main content
LangSmith 使用 PostgreSQL 数据库作为事务性工作负载和操作数据（几乎所有非运行数据）的主要数据存储。默认情况下，LangSmith 自托管版本将使用内部 PostgreSQL 数据库。但是，您可以配置 LangSmith 以使用外部 PostgreSQL 数据库。通过配置外部 PostgreSQL 数据库，您可以更轻松地管理数据库的备份、扩展和其他运维任务。
如果您使用的是托管 PostgreSQL 服务，我们推荐：有关云特定的 IAM/工作负载身份验证，请参阅 IAM 身份验证部分。

​
要求

  • 一个您的 LangSmith 实例可以网络访问的已配置 PostgreSQL 数据库。我们建议使用托管 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 文件来完成此操作。 
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 不需要此配置。
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。
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 模式所需的权限和特权。

​
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 参考。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。