以编程方式使用文档

本页描述如何为自托管 LangSmith 可观测性和评估规划、配置和操作灾难恢复 (DR)。它涵盖哪些数据必须保护、数据存储位置、如何备份，以及在区域或可用区故障后如何恢复平台。

您要恢复的内容

自托管 LangSmith 由四个状态存储支持的无状态服务组成。恢复规划几乎完全围绕状态存储进行。您可以通过重新应用 Helm chart 随时重新创建无状态服务。

层组件状态恢复操作
LangSmith 服务langsmith-frontend, langsmith-backend, langsmith-platform-backend, langsmith-queue, langsmith-ingest-queue, langsmith-playground, langsmith-ace-backend无状态重新安装 Helm chart
PostgreSQL运行数据：组织、工作区、用户、API 密钥、数据集、提示词、项目、部署元数据**持久**从备份或副本恢复
ClickHouse追踪和反馈（高容量分析数据）**持久**从备份或副本恢复
Blob storage (S3/GCS/Azure Blob)Run inputs, outputs, errors, manifests, extras, events, attachments (when enabled)**持久**从版本化存储桶或副本恢复
Redis (or Valkey)Ephemeral queue state, pub/sub, cache, run heartbeatsEphemeralReprovision; no restore required
Kubernetes 对象Helm values， Secrets, TLS material, IRSA / Workload Identity bindingsConfigurationRe-apply from source control or back up cluster state

规划您的 RPO 和 RTO

在设计 DR 架构之前，请定义两个目标：

  • 恢复点目标 (RPO)： 您的组织可以容忍的最大数据丢失量，以时间衡量。使用托管 Postgres PITR，RPO 通常少于 5 分钟。仅使用夜间快照，RPO 可达 24 小时。
  • 恢复时间目标 (RTO)： 故障后恢复服务的最长时间。热备份的跨区域副本可在几分钟内实现 RTO；从快照冷恢复可能需要数小时，特别是对于大型 ClickHouse 数据集。

以下部署模式假设三种目标配置文件之一：

配置文件典型 RPO典型 RTO方法
仅快照6 到 24 小时小时每个存储的每日托管备份。最低成本，最长恢复时间。
多可用区 HA秒分钟（可用区故障）Postgres 和 ClickHouse 在另一个可用区的同步备用，多可用区 Redis，区域冗余 blob 存储。标准生产姿态。
跨区域灾难恢复分钟到小时小时Postgres、ClickHouse 和 blob 存储的备份复制到第二个区域，可按需恢复。可选择 Postgres 跨区域副本以实现更严格的 Postgres RPO。成本最高，恢复速度比多可用区慢，但可防止区域级故障。

Postgres

LangSmith 使用 PostgreSQL 作为运营和事务数据的主要存储。 **与 Postgres 的所有通信都会对可重试错误使用重试机制**，因此故障转移期间的短暂中断通常不会作为用户可见的错误显示。长时间的故障将使 LangSmith API 不可用。

使用托管服务

我们强烈建议在生产环境中使用托管服务运行 Postgres。托管服务提供内置的自动备份、PITR 和 HA 故障转移。设置步骤请参阅 连接外部 Postgres.

AWS

运行 Amazon RDS for PostgreSQL or Aurora PostgreSQL ，并启用多可用区模式。

- **Backups:** 启用 自动备份 ，保留窗口应与您的合规姿态相匹配（通常为 7 到 35 天）。 - **PITR:** 自动备份包括保留窗口内的 PITR。 - **HA:** 多可用区部署在第二个可用区维护同步备用副本，并具有自动故障转移功能。 - **跨区域灾难恢复：** 对于 Aurora，配置 Aurora Global Database。对于 RDS，请使用 跨区域只读副本 或将自动快照复制到次区域。 - **Encryption:** 使用客户管理的 KMS key.

GCP

运行 Cloud SQL for PostgreSQL 并启用 高可用性 enabled.

- **Backups:** 启用 自动备份 并启用 PITR。 - **HA:** 区域实例同步复制到第二个区域中的备用副本。 - **跨区域灾难恢复：** 配置 跨区域只读副本 ，并在区域故障时进行提升。 - **Encryption:** 使用 Cloud KMS 客户管理的加密密钥.

Azure

运行 Azure Database for PostgreSQL Flexible Server 并启用区域冗余高可用性。

- **Backups:** 启用 自动备份 并使用地理冗余备份存储。 - **HA:** 区域冗余高可用性在不同可用区维护同步备用副本。 - **跨区域灾难恢复：** 使用 只读副本 ，置于次区域中以便在区域故障时进行提升。

集群内 Postgres

如果您必须从捆绑的 chart 在集群内运行 Postgres，则需要负责备份底层 PersistentVolume。使用 CSI 驱动程序的快照类定期对 PVC 进行快照，并将快照复制到对象存储或不同的区域。 **此路径不推荐用于生产环境。**

ClickHouse

ClickHouse 存储大容量跟踪和反馈数据，通常是 LangSmith 部署中最大的数据存储。备份和复制需要规划成本和恢复时间影响。

托管 ClickHouse

实现有弹性的 ClickHouse 的最快路径是托管选项。请参阅 连接外部 ClickHouse.

  • - **LangSmith 托管 ClickHouse:** LangChain 运营 ClickHouse 集群，包括备份和复制。VPC 对等连接将其连接到您的 LangSmith 安装。
  • - **ClickHouse Cloud:** 提供内置备份、复制和高可用性。可在 AWS、GCP 和 Azure 市场上获取。

自管理复制集群

如果您因合规性或气隙原因自行管理 ClickHouse，请使用复制集群。单节点 ClickHouse 实例无法满足有意义的 RPO。

  • - 通过以下方式配置带复制功能的多节点 ClickHouse 集群 Keeper 或 ZooKeeper.
  • - 在 LangSmith chart 中设置 cluster 的值，以便迁移创建 Replicated 从一开始就使用表引擎。 **集群设置必须针对新的 schema 进行配置**，您稍后无法将独立实例转换为集群。
  • - 在可用区之间分布副本。
  • - 将 BACKUP TABLE or BACKUP DATABASE 到与 RPO 相匹配的对象存储频率。社区 clickhouse-backup 工具也是定期增量备份的流行选项，支持内置的 S3、GCS 和 Azure Blob。
  • - For cross-region DR, copy the backup bucket to a secondary region. Cross-region ClickHouse replication is not generally supported in self-managed deployments and is not offered by ClickHouse Cloud either, so plan for a backup/restore failover model rather than a hot replica.

有关示例复制配置，请参阅 复制的 ClickHouse 示例 在 Helm repo 中。

Blob 存储

如果您已启用 Blob 存储 （推荐用于生产），您的运行输入、输出、错误、清单、附加信息、事件和附件存储在 S3、GCS 或 Azure Blob Storage 中。云 blob 服务在设计上具有持久性，但您仍应配置防止意外删除和区域中断的保护。

AWS

- 启用 S3 版本控制 以防止意外删除和覆盖。 - 为高安全性存储桶启用 MFA 删除 。 - 对于跨区域灾难恢复，请配置 跨区域复制 (CRR) 到灾难恢复区域的存储桶。 - 使用 S3 对象锁定 用于一次写入多次读取（WORM）保留。 - 使用以下方式加密 SSE-KMS。LangSmith 支持传递特定的 KMS 密钥 ARN，请参阅 KMS 加密头支持.

GCP

- 启用 对象版本控制 在存储桶上。 - 使用 双区域或多区域存储桶 以实现地理冗余。 - 对于跨区域灾难恢复，请使用 存储传输服务 or 对象生命周期管理 以及复制策略。 - 使用以下方式加密 客户管理的加密密钥（CMEK）.

Azure

- 选择 冗余层级 以匹配您的灾难恢复目标。使用 **RA-GRS** or **RA-GZRS** 在主区域中断期间实现跨区域读取访问。 - 启用 软删除和 Blob 版本控制. - 使用以下方式加密 Key Vault 中的客户管理密钥.

Redis

Redis stores ephemeral metadata, queue state, and cross-instance pub/sub. **Redis 中不存储持久数据，因此您无需对其进行备份。** 与 Redis 的通信会对可重试错误进行重试。恢复设计是使 Redis 在活动区域中保持高可用性，并在灾难恢复区域中从头重新配置。

  • - 使用您云平台的托管服务： Amazon ElastiCache, Google Cloud Memorystore, or Azure Cache for Redis.
  • - 启用多可用区故障转移。
  • - 对于跨区域灾难恢复，请在故障转移期间在灾难恢复区域中配置新的 Redis 实例；请勿 **不要** 在新群集中重复使用活动区域的 Redis URI。

Kubernetes 配置和密钥

Helm 图表值、Kubernetes Secret以及身份绑定与您的数据备份同样重要。完整的恢复需要两者。

  • Helm 值： 存储 values.yaml 在源代码管理中。单独跟踪每个环境的覆盖值。
  • 镜像版本： 固定 LangSmith chart 版本和镜像标签，以便恢复时安装相同的软件版本。参见 自托管升级 和 依赖版本.
  • Secrets: LangSmith 从 Kubernetes Secret读取数据库、blob 和许可凭证。将这些镜像到您的 DR 集群的密钥管理器（AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault）。参见 使用现有密钥.
  • TLS 材料： 如果您在 LangSmith 入口处终止 TLS，请备份证书和密钥，或在 DR 区域从您的私有 CA 重新颁发。参见 自定义 TLS 证书.
  • IRSA / Workload Identity bindings: 在 DR 区域重新创建 IAM 角色和服务账户绑定；服务账户 ARN 和注解是区域范围的。
  • 许可证密钥： 将 LangSmith 许可证密钥与其他恢复密钥一起保存。

参考部署模式

单区域多可用区 HA（推荐的基线）

这是最低生产姿态，可防止可用区故障。它不能防止区域中断。

  • - 跨至少两个可用区的 Kubernetes 节点池。
  • - 多可用区 HA 模式的 Postgres（RDS Multi-AZ、Cloud SQL HA 或 Flexible Server 区域冗余）。
  • - ClickHouse 作为托管服务，或跨 AZ 分布的 3 节点复制集群。
  • - 启用多可用区故障转移的 Redis。
  • - 启用版本控制且冗余层级至少为区域冗余的 Blob 存储。
  • - 每个数据存储的每日快照，保留至少 7 天。

Cross-region active/passive DR

这可以防止区域中断。它成本更高，但对于一级部署是正确的模式。

  • - DR 区域中的第二个 Kubernetes 集群，安装了 LangSmith Helm chart，但缩减到低副本数（热备）或零副本（冷备）。
  • - Postgres 跨区域副本（RDS 或 Aurora 跨区域副本、Cloud SQL 跨区域副本、Azure Flexible Server 跨区域副本）。故障转移时提升。
  • - ClickHouse Cloud 或 LangSmith 托管的 ClickHouse，配合区域故障转移计划， **or** ClickHouse backups copied to the DR region and restored into a fresh self-managed cluster on failover. Cross-region ClickHouse replication is not generally supported (ClickHouse Cloud does not offer it either), so plan for backup/restore rather than a hot DR replica.
  • - Blob 存储复制到带有版本控制和完善生命周期规则的 DR 存储桶。
  • - 在故障转移期间在 DR 区域新配置 Redis。
  • - DNS 由以下服务管理 Route 53, Cloud DNS, or Azure DNS 进行健康检查和故障转移策略，指向每个区域的 LangSmith 前端入口。

恢复程序

可用区故障后恢复

在单区域多可用区部署中，区域故障由您的云提供商自动处理：

  1. 托管 Postgres 故障转移到另一可用区中的备用实例。LangSmith Pod 通过重试后的集群端点重新连接。
  2. 托管版 Redis 的故障转移方式类似。LangSmith 会自动重试重新连接。
  3. Kubernetes 会在剩余可用区中的健康节点上重新调度 LangSmith Pod。请验证节点池和水平 Pod 自动扩缩容限制是否留有足够的余量。
  4. 通过从 SDK 提交测试追踪来验证数据摄入，并确认追踪数据在 UI 中显示。

区域故障后恢复

这是跨区域故障转移操作手册。请根据您的具体基础设施进行调整。

Declare failover

确认主区域不可用。向利益相关者通报故障转移情况及预期的 RTO。

Promote data stores

将 Postgres 跨区域副本提升为 DR 区域的主节点。对于 ClickHouse Cloud 或 LangSmith 托管版 ClickHouse，请按照文档启动区域故障转移。对于自托管 ClickHouse，请将最新备份恢复到 DR 集群（这通常是耗时最长的步骤）。

Repoint blob storage

更新 LangSmith Helm config.blobStorage.bucketName 和 apiURL 指向 DR 存储桶。确认存储桶具有相同的 TTL 生命周期规则。参见 Blob 存储配置.

Provision Redis

在 DR 区域中创建一个新的托管 Redis 实例。更新 LangSmith Helm redis.external values 以指向新实例。 **不要从主 Redis 导入数据**；请配置为空实例。

Scale the DR cluster

If running warm/cold, scale the LangSmith deployments to their production replica counts. Apply any pending Helm value updates from source control.

Run smoke tests

提交测试追踪，验证数据是否写入 ClickHouse（以及如果启用了 blob 存储）是否写入 DR 存储桶。打开 UI 确认追踪、数据集和项目是否正常加载。验证身份验证。参见 诊断.

Cut DNS over

更新 DNS 以将流量路由到 DR 入口。向利益相关者通报切换情况。

Plan failback

主区域恢复健康后，请规划受控的回切操作。这通常会安排在维护窗口期间进行，涉及将主区域重建为新的 DR 副本，然后再进行交换。

从快照恢复

如果您完全丢失了主数据存储，需要从快照恢复：

Stop ingestion

将 langsmith-queue 和 langsmith-ingest-queue 缩容至零，以便在恢复期间不会写入新追踪。

Restore Postgres

将 Postgres 备份恢复到新实例，或执行 PITR 恢复到事件前的最新时间戳。更新 LangSmith Helm postgres.external 连接详情以指向恢复后的实例。

Restore ClickHouse

恢复与 Postgres 恢复点时间最接近的最近一次 ClickHouse 备份。恢复时间取决于数据大小。

Restore blob storage

If you lost blob data (rare), restore versioned objects from S3/GCS/Azure or copy from a replicated DR bucket.

Resume ingestion

将 langsmith-queue 和 langsmith-ingest-queue 扩容回生产副本数量。提交冒烟测试追踪并验证数据是否写入。

测试您的 DR 计划

备份的有效性取决于上次成功恢复的情况。请安排以下演练：

  • Quarterly: 将 Postgres 和 ClickHouse 快照恢复到非生产环境，并运行 诊断工具 以及冒烟追踪测试。测量实际恢复时间并确认其在 RTO 范围内。
  • 每半年： 针对 staging 环境执行完整的跨区域故障转移演练。提升副本、重新指向 blob 存储、扩缩 DR 集群、运行冒烟测试，然后回滚。
  • 每次图表升级时： 验证升级路径不会使您的灾难恢复计划失效（例如，仅应用于主数据库的架构迁移需要复制到灾难恢复副本）。请参阅 自托管升级.

相关页面