连接到一个外部 PostgreSQL 数据库

LangSmith 用一个 PostgreSQL 数据库作为事务性工作负载和运营数据（除了运行之外的几乎一切）的主数据存储。默认情况下，LangSmith Self-Hosted 会用一个内部的 PostgreSQL 数据库。不过，你可以配置 LangSmith 使用一个外部 PostgreSQL 数据库。通过配置一个外部 PostgreSQL 数据库，你能更轻松地管理数据库的备份、扩容和其他运营任务。

TIP

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

• Amazon RDS（AWS）
• Google Cloud SQL（GCP）
• Azure Database for PostgreSQL（Azure）

关于云专属的 IAM/Workload Identity 身份验证，参阅 IAM 身份验证一节。

要求

• 一个已预配的 PostgreSQL 数据库，你的 LangSmith 实例将能网络访问到它。我们推荐使用像以下这样的托管 PostgreSQL 服务：

  • Amazon RDS
  • Google Cloud SQL
  • Azure Database for PostgreSQL

• 注意：我们只正式支持 PostgreSQL 14 或更高版本。

• 我们支持密码和 IAM/Workload Identity 身份验证。

• 一个对 PostgreSQL 数据库有 admin 访问权限的用户。这个用户将用于创建必要的表、索引和 schema。

• 这个用户还需要有在数据库中创建扩展的能力。我们使用/将尝试安装 btree_gin、btree_gist、pgcrypto、citext、ltree 和 pg_trgm 扩展。

• 如果使用 public 以外的 schema，请确保你没有任何其他启用了这些扩展的 schema，否则你必须把它们包含在你的搜索路径中。

• 对 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 文件来做到这一点。

postgres:
  external:
    enabled: true
    connectionUrl: "Your connection 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。

WARNING

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

Helm (server TLS)

config:
  customCa:
    secretName: "langsmith-custom-ca"  # Secret containing your CA bundle
    secretKey: "ca.crt"    # Key in the Secret with the CA bundle
postgres:
  external:
    enabled: true
    connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system"
    customTls: true

Kubernetes Secret (CA bundle)

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 (client Auth)

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 (client cert/key)

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 身份验证。这让你能使用云提供商的工作负载身份而非静态密码。

WARNING

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

Amazon RDS IAM 身份验证

Amazon RDS 支持 IAM 数据库身份验证，它让你能用 AWS IAM 凭据而非数据库密码来对你的 PostgreSQL 实例进行身份验证。

前置条件

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

配置

WARNING

如果在 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 connection URL - note no password, username is the IAM identity name
  connection_url: "<iam-identity-name>@<rds-host>:5432/<database>?sslmode=require"

WARNING

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

必需的注解

你必须把 AWS IRSA 所要求的 ServiceAccount 注解，应用到所有连接 PostgreSQL 的 LangSmith 组件：

Deployments： backend、queue、platformBackend、hostBackend、ingestQueue

Jobs： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

NOTE

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

backend 服务的示例配置：

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 参考。

---