连接外部 Redis 或 Valkey 数据库

LangSmith 使用 Redis 来支持其队列/缓存操作。默认情况下，LangSmith 自托管版将使用内部的 Redis 实例。但是，您可以配置 LangSmith 使用外部 Redis 实例。通过配置外部 Redis 实例，您可以更轻松地管理备份、扩展以及 Redis 实例的其他运维任务。 Valkey 也被官方支持作为 Redis 的直接替代品。在本页任何提及 Redis 的地方，您都可以使用兼容的 Valkey 实例。支持的版本请参阅要求。

每个 LangSmith 安装必须使用其专用的 Redis 实例。Redis 不能跨不同的 LangSmith 安装共享（例如，在迁移过程中，现有集群和新集群之间不能共享）。跨安装共享会导致部署任务被路由到错误的集群。

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

关于云服务特定的 IAM/工作负载身份认证，请参阅 IAM 身份验证章节。

要求

一个您的 LangSmith 实例能够访问的已配置的 Redis 或 Valkey 实例。我们建议使用托管服务，例如：
- Amazon ElastiCache (Redis 或 Valkey)
- Google Cloud Memorystore (Redis 或 Valkey)
- Azure Cache for Redis
支持的版本： Redis >= 5 或 Valkey 8。在本指南中，Valkey 被视为 Redis 的直接替代品。
我们支持单机模式和 Redis 集群（包括 Valkey 集群）。请参阅相关章节获取部署说明。
我们支持无认证、密码认证和 IAM/工作负载身份认证。
默认情况下，我们建议使用至少具有 2 个 vCPU 和 8GB 内存的实例。但是，实际要求取决于您的跟踪工作负载。我们建议监控您的 Redis 实例并根据需要进行扩展。

单机 Redis

连接字符串

您需要为您的 Redis 实例组装连接字符串。此连接字符串应包含以下信息：

主机
数据库
端口
URL 参数

其形式如下：

"redis://host:port/db?<url_params>"

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

"redis://langsmith-redis:6379/0"

注意：如果您的单机 Redis 需要认证或 TLS，请在连接 URL 中直接包含这些信息：

当您的 Redis 服务器启用了 TLS 时，请使用 rediss://。
在连接字符串中提供密码。

例如：

rediss://langsmith-redis:6380/0?password=foo

对于 IAM 身份验证，请使用身份标识作为用户名（无需密码）：

rediss://<iam-identity>@host:6380

配置

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

Helm

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

您也可以将连接 URL 存储在现有的 Kubernetes Secret 中，并在 Helm values 中引用它。

redis:
  external:
    enabled: true
    # 包含连接 URL 的现有 Secret 名称
    existingSecretName: "my-redis-secret"
    # Secret 中存储连接 URL 的键（默认值如下所示）
    connectionUrlSecretKey: "connection_url"

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-secret
type: Opaque
stringData:
  # 完整的连接 URL，例如，使用带密码的 TLS
  connection_url: "rediss://langsmith-redis:6380/0?password=foo"

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

Redis 集群

从 LangSmith Helm 版本 0.12.25 开始，我们正式支持 Redis 集群。

主机名

使用 Redis 集群时，请提供节点主机名和端口列表。每个节点 URI 必须采用以下格式：

redis://hostname:port

例如：

redis://redis-node-0:6379
redis://redis-node-1:6379
redis://redis-node-2:6379

不要在这些 URI 中包含密码，也不要在此处使用 rediss。对于 Redis 集群：

请通过 redis.external.cluster.password 或通过使用 passwordSecretKey 的 Secret 单独提供密码。
Redis 集群默认启用 TLS (redis.external.cluster.tlsEnabled: true)。如果您的集群不使用 TLS，请设置 tlsEnabled: false。

配置

连接到外部 Redis 集群时，请在 redis.external.cluster 下配置 Helm 值。您可以：

在 values.yaml 中直接提供节点 URI 和（可选）密码。
或引用一个包含节点 URI 和密码的现有 Kubernetes Secret。

redis:
  external:
    enabled: true
    cluster:
      enabled: true
      # 集群节点 URI 列表。格式：redis://host:port
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      # 可选。如果您的集群需要认证，请设置密码或使用 Secret（推荐）。
      password: "您的_redis_密码"
      # 默认启用 TLS。如果您的集群不使用 TLS，请设置为 false。
      tlsEnabled: true

redis:
  external:
    enabled: true
    # 包含集群连接详情的现有 Secret 名称
    existingSecretName: "my-redis-cluster-secret"
    cluster:
      enabled: true
      # Secret 中的键。此处显示默认值；如果您的 Secret 使用不同的键，请覆盖。
      nodeUrisSecretKey: "redis_cluster_node_uris"
      passwordSecretKey: "redis_cluster_password"
      tlsEnabled: true

如果使用现有 Secret，它应包含：

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-cluster-secret
type: Opaque
stringData:
  # 节点 URI 的 JSON 数组（作为字符串）
  redis_cluster_node_uris: '["redis://redis-node-0:6379","redis://redis-node-1:6379","redis://redis-node-2:6379"]'
  # 如果您的集群需要密码，则为可选项
  redis_cluster_password: "您的_redis_密码"

Azure 托管 Redis

Azure 托管 Redis 支持两种集群策略，这会影响 LangSmith 如何连接它。请根据您实例的集群策略选择以下配置。

OSS 集群

LangSmith 使用 Redis 集群模式连接到 OSS 集群策略实例。从 LangSmith Helm Chart 版本 0.13.33 开始，ssl_check_hostname=false 被支持作为节点 URI 参数。在我们的测试中，OSS 集群策略需要禁用 SSL 主机名验证。Azure 的代理会将连接解析到证书 SAN 中不存在的内部节点 IP，导致主机名验证失败。

redis:
  external:
    enabled: true
    cluster:
      enabled: true
      nodeUris:
        - "redis://<node_url>:10000?ssl_check_hostname=false"
      tlsEnabled: true

企业集群

从 LangSmith Helm Chart 版本 0.13.33 开始，LangSmith 支持使用企业集群策略的 Azure 托管 Redis。此策略公开一个端点，内部处理分片。LangSmith 必须作为单机（单实例）客户端连接它，但它不支持集群不安全操作，如 MULTI/EXEC。设置 redis.external.clusterSafeMode: true 以禁用不安全的集群操作。

redis:
  external:
    enabled: true
    connectionUrl: "rediss://<azure-redis-host>:6380"
    # 企业集群必需：使用单实例客户端并禁用不安全的集群操作
    clusterSafeMode: true

有关企业集群的 Microsoft Entra（IAM）身份验证，请参阅 IAM 身份验证中的 Azure 选项卡，并在您的 Helm 值中包含 clusterSafeMode: true。

使用 TLS 的 Redis

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

服务器 TLS（单向）

要验证 Redis 服务器证书：

使用 config.customCa.secretName 和 config.customCa.secretKey 提供一个 CA 包。
对于单机 Redis，在连接 URL 中使用 rediss://。
对于 Redis 集群，redis.external.cluster.tlsEnabled 默认为 true。确保它未被设置为 false。

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

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 包的键
redis:
  external:
    enabled: true
    # 如果服务器需要密码，请使用 rediss:// 并包含密码
    connectionUrl: "rediss://host:6380/0?password=<PASSWORD>"

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 包的键
redis:
  external:
    enabled: true
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: "<PASSWORD>"

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 开始，我们支持 Redis 客户端的 mTLS。对于 mTLS 中的服务器端身份验证，请在以下客户端证书配置之外，使用服务器 TLS 步骤（自定义 CA）。如果您的 Redis 服务器需要客户端证书认证：

提供一个包含您的客户端证书和密钥的 Secret。
通过 redis.external.clientCert.secretName 引用它，并使用 certSecretKey 和 keySecretKey 指定键。
对于单机 Redis，在连接 URL 中继续使用 rediss://。
对于 Redis 集群，redis.external.cluster.tlsEnabled 默认为 true。确保它未被设置为 false。

redis:
  external:
    enabled: true
    clientCert:
      secretName: "redis-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"
    # 单机示例：
    # connectionUrl: "rediss://host:6380/0?password=<PASSWORD>"
    # 或者，对于集群：
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: "<PASSWORD>"

apiVersion: v1
kind: Secret
metadata:
  name: redis-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 开始，我们支持 Redis 的 IAM 身份验证。这允许您使用云提供商的工作负载身份而不是静态密码。

IAM 身份验证同时支持单机 Redis 和 Redis 集群配置。但是，并非所有云提供商都支持其所有 Redis 产品的 IAM 身份验证。请查阅您的云提供商文档，以验证您的特定 Redis 设置是否支持 IAM（例如，GCP 仅支持 Memorystore 集群的 IAM，不支持独立的 Memorystore）。

AWS
GCP
Azure

适用于 Redis 的 ElastiCache IAM 身份验证

适用于 Redis 的 ElastiCache 支持 IAM 身份验证，允许您使用 AWS IAM 凭据而非 Redis AUTH 密码进行身份验证。

前提条件

在您的 Kubernetes 集群中配置工作负载身份，使用 AWS IRSA 或 EKS Pod Identity。
在您的 ElastiCache 实例上启用 IAM 身份验证，并授予对您工作负载身份的访问权限。

配置

单机 Redis：

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

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
type: Opaque
stringData:
  # IAM 连接 URL - 身份标识作为用户名，无密码
  connection_url: "rediss://<iam-identity>@<elasticache-host>:6380"

Redis 集群：

redis:
  external:
    enabled: true
    existingSecretName: "redis-cluster-secret"
    iamAuthProvider: "aws"
    cluster:
      enabled: true
      nodeUrisSecretKey: "redis_cluster_node_uris"
      tlsEnabled: true

必需的注解

您必须将 AWS IRSA 所需的 ServiceAccount 注解应用于所有连接到 Redis 的 LangSmith 组件：部署： backend, queue, platformBackend, hostBackend, ingestQueue示例配置：

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

适用于 Redis 的 Memorystore IAM 身份验证

适用于 Redis 的 Memorystore 支持 集群实例（而非独立的 Memorystore）的 IAM 身份验证。这允许您使用 GCP 服务帐户进行身份验证。

IAM 身份验证仅适用于 Memorystore 集群，不适用于独立的 Memorystore 实例。

前提条件

在您的 Kubernetes 集群中配置工作负载身份，使用 GCP Workload Identity。
在您的 Memorystore 集群上启用 IAM 身份验证，并授予对您工作负载身份的访问权限。

配置

带 IAM 的 Memorystore 集群：

redis:
  external:
    enabled: true
    existingSecretName: "redis-cluster-secret"
    iamAuthProvider: "gcp"
    cluster:
      enabled: true
      nodeUrisSecretKey: "redis_cluster_node_uris"
      tlsEnabled: true

apiVersion: v1
kind: Secret
metadata:
  name: redis-cluster-secret
type: Opaque
stringData:
  redis_cluster_node_uris: '["redis://node-0:6379","redis://node-1:6379","redis://node-2:6379"]'

必需的注解

您必须将 GCP Workload Identity 所需的 ServiceAccount 注解应用于所有连接到 Redis 的 LangSmith 组件：部署： backend, queue, platformBackend, hostBackend, ingestQueue示例配置：

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

使用 Microsoft Entra 身份验证的 Azure Cache for Redis

Azure Cache for Redis 支持 Microsoft Entra 身份验证，允许您使用 Azure 托管标识进行身份验证。

前提条件

在您的 Kubernetes 集群中配置工作负载身份，使用 Azure Workload Identity。
在您的 Azure Cache for Redis 上启用 Microsoft Entra 身份验证，并授予对您工作负载身份的访问权限。

配置

单机 Redis：

redis:
  external:
    enabled: true
    existingSecretName: "redis-secret"
    iamAuthProvider: "azure"
    # 如果使用企业集群策略，请包含此项。详情请参阅 Azure 托管 Redis 章节。
    # clusterSafeMode: true

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
type: Opaque
stringData:
  # IAM 连接 URL - 托管标识作为用户名，无密码
  connection_url: "rediss://<managed-identity>@<azure-redis-host>:6380"

Redis 集群：

redis:
  external:
    enabled: true
    existingSecretName: "redis-cluster-secret"
    iamAuthProvider: "azure"
    cluster:
      enabled: true
      nodeUrisSecretKey: "redis_cluster_node_uris"
      tlsEnabled: true

必需的注解和标签

您必须将 Azure Workload Identity 所需的 ServiceAccount 注解和 Pod 标签应用于所有连接到 Redis 的 LangSmith 组件：部署： backend, queue, platformBackend, hostBackend, ingestQueue示例配置：

backend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    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 参考。

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

Edit this page on GitHub or file an issue.

Get started by cloud provider

Deploy with Terraform

Setup guides

Configuration

Connect external services

Platform auth & access control

Self-hosted observability

Hybrid

Scripts

Reference

连接外部 Redis 或 Valkey 数据库

要求

单机 Redis

连接字符串

配置

Redis 集群

主机名

配置

Azure 托管 Redis

OSS 集群

企业集群

使用 TLS 的 Redis

服务器 TLS（单向）

带客户端认证的双向 TLS (mTLS)

证书卷的 Pod 安全上下文

IAM 身份验证

适用于 Redis 的 ElastiCache IAM 身份验证

前提条件

配置

必需的注解

适用于 Redis 的 Memorystore IAM 身份验证

前提条件

配置

必需的注解

使用 Microsoft Entra 身份验证的 Azure Cache for Redis

前提条件

配置

必需的注解和标签

​要求

​单机 Redis

​连接字符串

​配置

​Redis 集群

​主机名

​配置

​Azure 托管 Redis

​OSS 集群

​企业集群

​使用 TLS 的 Redis

​服务器 TLS（单向）

​带客户端认证的双向 TLS (mTLS)

​证书卷的 Pod 安全上下文

​IAM 身份验证

​适用于 Redis 的 ElastiCache IAM 身份验证

​前提条件

​配置

​必需的注解

​适用于 Redis 的 Memorystore IAM 身份验证

​前提条件

​配置

​必需的注解

​使用 Microsoft Entra 身份验证的 Azure Cache for Redis

​前提条件

​配置

​必需的注解和标签

要求

单机 Redis

连接字符串

配置

Redis 集群

主机名

配置

Azure 托管 Redis

OSS 集群

企业集群

使用 TLS 的 Redis

服务器 TLS（单向）

带客户端认证的双向 TLS (mTLS)

证书卷的 Pod 安全上下文

IAM 身份验证

适用于 Redis 的 ElastiCache IAM 身份验证

前提条件

配置

必需的注解

适用于 Redis 的 Memorystore IAM 身份验证

前提条件

配置

必需的注解

使用 Microsoft Entra 身份验证的 Azure Cache for Redis

前提条件

配置

必需的注解和标签