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

​
要求

  • 一个已部署的 PostgreSQL 数据库，您的 LangSmith 实例需要能够通过网络访问它。我们建议使用托管的 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 文件来实现。 
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 参考。
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.