主题
自托管 LangSmith 的灾备恢复
本页描述如何为自托管 LangSmith 可观测性与评估规划、配置并运维灾备恢复（DR）。它涵盖哪些数据必须被保护、它们位于何处、如何备份，以及在区域或可用区故障后如何恢复平台。
NOTE
共同责任。 对于自托管部署，你负责每个组件的备份、复制、恢复测试和恢复流程，包括 LangSmith pod 和所有后端数据存储。LangChain 只负责 LangSmith 软件本身。对等的 SaaS 责任参见共同责任模型。
TIP
有关本页所假定的架构原语（无状态服务、队列心跳、恰好一次语义）的详情，参阅可扩展性与弹性。
你在恢复什么
自托管 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 存储（S3/GCS/Azure Blob） | 运行输入、输出、错误、清单、额外项、事件、附件（启用时） | 持久 | 从版本化存储桶或副本恢复 |
| Redis（或 Valkey） | 临时队列状态、pub/sub、缓存、运行心跳 | 临时 | 重新预配；无需恢复 |
| Kubernetes 对象 | Helm values、Secret、TLS 材料、IRSA / Workload Identity 绑定 | 配置 | 从源码控制重新应用，或备份集群状态 |
WARNING
所有持久数据存储必须一起受保护。Postgres、ClickHouse 和 blob 存储是持有持久数据的三个存储；Redis 是临时的，不需要备份。只恢复 Postgres 而不恢复 ClickHouse 和 blob 存储（或反之）会产生一个不一致的安装。Postgres 到 ClickHouse 中运行、到 blob 存储中对象的引用，会在分歧点处断裂。始终做协调一致的备份，或使用在各存储间彼此接近的时间点恢复（PITR）目标。
规划你的 RPO 和 RTO
在设计你的 DR 架构之前，定义两个目标：
- 恢复点目标（RPO）： 你的组织能承受的最大数据丢失量，以时间衡量。用托管 Postgres PITR，RPO 通常少于 5 分钟。仅用每晚快照，RPO 可达 24 小时。
- 恢复时间目标（RTO）： 故障后你恢复服务所能花的最大时间。一个热的跨区域副本能在几分钟内达成 RTO；从快照冷恢复可能耗时数小时，对大型 ClickHouse 数据集尤其如此。
以下部署模式假定三种目标配置之一：
| 配置 | 典型 RPO | 典型 RTO | 方法 |
|---|---|---|---|
| 仅快照 | 6 到 24 小时 | 数小时 | 每个存储的每日托管备份。成本最低，恢复最久。 |
| 多可用区 HA | 秒 | 分钟（可用区故障） | Postgres 和 ClickHouse 在另一可用区的同步备库，多可用区 Redis，可用区冗余 blob 存储。标准生产姿态。 |
| 跨区域 DR | 分钟到小时 | 数小时 | Postgres、ClickHouse 和 blob 存储的备份被复制到一个第二区域，按需恢复。可选一个 Postgres 跨区域副本以获得更紧的 Postgres RPO。成本最高，恢复比多可用区慢，但能防区域性中断。 |
Postgres
LangSmith 用 PostgreSQL 作为运维和事务数据的主存储。与 Postgres 的所有通信都对可重试错误使用重试，因此故障转移期间的短暂中断通常不会以用户可见的错误浮现。一次长时间中断会使 LangSmith API 不可用。
使用托管服务
我们强烈建议在生产中把 Postgres 运行在托管服务上。托管服务提供内置的自动备份、PITR 和 HA 故障转移。有关设置，参阅连接外部 Postgres。
以多可用区模式运行 Amazon RDS for PostgreSQL 或 Aurora PostgreSQL。
- 备份： 启用与你的合规姿态相匹配保留窗口的自动备份（7 到 35 天很典型）。
- PITR： 自动备份在保留窗口内包含 PITR。
- HA： 多可用区部署在第二个可用区维持一个同步备库，带自动故障转移。
- 跨区域 DR： 对于 Aurora，配置一个 Aurora Global Database。对于 RDS，使用跨区域只读副本或把自动快照复制到一个次级区域。
- 加密： 用一个客户管理的 KMS 密钥启用存储加密。
集群内 Postgres
如果你必须从随附的 chart 在集群内运行 Postgres，你负责备份底层 PersistentVolume。用你的 CSI 驱动的快照类，按定期节奏对 PVC 打快照，并把快照复制到对象存储或另一个区域。此路径不建议用于生产。
ClickHouse
ClickHouse 持有高容量的追踪和反馈数据，通常是 LangSmith 部署中最大的数据存储。备份和复制需要就成本和恢复时间影响做规划。
托管 ClickHouse
通往有韧性 ClickHouse 最快的路径是一个托管选项。参见连接外部 ClickHouse。
- LangSmith Managed ClickHouse： LangChain 运维该 ClickHouse 集群，包括备份和复制。VPC 对等连接把它连到你的 LangSmith 安装。
- ClickHouse Cloud： 提供内置备份、复制和 HA。可在 AWS、GCP 和 Azure 市场上获得。
自管理复制集群
如果你出于合规或气隙原因自管理 ClickHouse，使用一个复制集群。单节点 ClickHouse 实例无法满足有意义的 RPO。
- 通过 Keeper 或 ZooKeeper 配置一个带复制的多节点 ClickHouse 集群。
- 在 LangSmith chart 中设置
cluster值，使迁移从一开始就创建Replicated表引擎。集群化设置必须针对一个全新 schema 配置，你无法稍后将一个独立实例转换为集群化。 - 把副本分散到各可用区。
- 按与你 RPO 相匹配的频率，把
BACKUP TABLE或BACKUP DATABASE调度到对象存储。社区clickhouse-backup工具也是带内置 S3、GCS 和 Azure Blob 支持的定期增量备份的流行选择。 - 对于跨区域 DR，把备份存储桶复制到一个次级区域。跨区域 ClickHouse 复制在自管理部署中通常不受支持，ClickHouse Cloud 也不提供，因此按备份/恢复故障转移模型规划，而非热副本。
有关一个示例复制配置，参阅 Helm 仓库中的复制 ClickHouse 示例。
WARNING
在相同数据量下，恢复 ClickHouse 可能比恢复 Postgres 耗时明显更长，因为追踪表很大。在设定你的 RTO 时把这一点考虑在内。在 DR 演练期间就一个有代表性的数据集验证恢复时间。
Blob 存储
如果你启用了 blob 存储（生产推荐），你的运行输入、输出、错误、清单、额外项、事件和附件位于 S3、GCS 或 Azure Blob Storage。云 blob 服务在设计上就是持久的，但你仍应配置以防误删和区域中断。
- 启用 S3 Versioning 以防误删和覆盖。
- 对高安全存储桶启用 MFA Delete。
- 对于跨区域 DR，配置跨区域复制（CRR）到你的 DR 区域中的一个存储桶。
- 用 S3 Object Lock 做写一次读多次（WORM）保留。
- 用 SSE-KMS 加密。LangSmith 支持传入一个特定的 KMS 密钥 ARN，参见 KMS 加密标头支持。
WARNING
在你的 DR 存储桶中保留 TTL 生命周期规则。 如果你把数据复制到一个 DR 存储桶，也为 ttl_s/、ttl_l/ 和任何自定义 ttl_XXd/ 前缀复制生命周期规则。DR 存储桶中缺失的规则会导致数据在故障转移后被无限期保留。参见 TTL 配置。
Redis
Redis 存储临时元数据、队列状态和跨实例 pub/sub。Redis 中不存持久数据，因此你不需要备份它。 与 Redis 的通信对可重试错误会重试。恢复设计是让 Redis 在活动区域内高度可用，并在 DR 区域从头重新预配它。
- 为你的云使用托管服务：Amazon ElastiCache、Google Cloud Memorystore 或 Azure Cache for Redis。
- 启用多可用区故障转移。
- 对于跨区域 DR，在故障转移期间在 DR 区域预配一个全新的 Redis 实例；不要在新集群中复用活动区域的 Redis URI。
WARNING
每个 LangSmith 安装必须使用它自己专属的 Redis 实例。不要在两个安装之间共享一个 Redis 实例，包括任何可能同时活动的主实例和 DR 副本。共享 Redis 会导致部署任务被路由到错误的集群。参见连接外部 Redis。
Kubernetes 配置与机密
Helm chart values、Kubernetes Secret 和身份绑定与你的数据备份同样重要。一次完整的恢复两者都需要。
- Helm values： 把
values.yaml存进源码控制。按环境分别跟踪覆盖。 - 镜像版本： 固定 LangSmith chart 版本和镜像标签，使一次恢复安装相同的软件版本。参见自托管升级和依赖版本。
- 机密： LangSmith 从 Kubernetes
Secret读取数据库、blob 和许可凭据。把这些镜像到你 DR 集群的机密管理器（AWS Secrets Manager、GCP Secret Manager 或 Azure Key Vault）。参见使用现有密钥。 - TLS 材料： 如果你在 LangSmith ingress 处终止 TLS，备份证书和密钥，或在 DR 区域从你的私有 CA 重新签发。参见自定义 TLS 证书。
- IRSA / Workload Identity 绑定： 在 DR 区域重建 IAM 角色和服务账户绑定；服务账户 ARN 和注解是区域作用域的。
- 许可密钥： 把 LangSmith 许可密钥与其他恢复机密放在一起保管。
参考部署模式
单区域带多可用区 HA（推荐基线）
这是最低的生产姿态，能防可用区故障。它不能防区域性中断。
- 跨至少两个可用区的 Kubernetes 节点池。
- Postgres 以多可用区 HA 模式（RDS Multi-AZ、Cloud SQL HA，或 Flexible Server 可用区冗余）。
- ClickHouse 作为托管服务，或一个跨可用区分散的 3 节点复制集群。
- Redis 启用多可用区故障转移。
- Blob 存储启用版本管理，冗余层级至少为可用区冗余。
- 每个数据存储的每日快照，至少保留 7 天。
跨区域主动/被动 DR
这能防区域性中断。它明显更贵，但对于一级部署是正确的模式。
- DR 区域中一个第二 Kubernetes 集群，装了 LangSmith Helm chart 但缩到低副本数（温）或零（冷）。
- Postgres 跨区域副本（RDS 或 Aurora 跨区域副本、Cloud SQL 跨区域副本、Azure Flexible Server 跨区域副本）。故障转移时提升。
- ClickHouse Cloud 或 LangSmith Managed ClickHouse 带一个区域故障转移计划，或 ClickHouse 备份被复制到 DR 区域，并在故障转移时恢复进一个全新的自管理集群。跨区域 ClickHouse 复制通常不受支持（ClickHouse Cloud 也不提供），因此按备份/恢复而非热 DR 副本规划。
- Blob 存储复制到一个带版本管理和匹配生命周期规则的 DR 存储桶。
- Redis 在故障转移期间在 DR 区域全新预配。
- DNS 由 Route 53、Cloud DNS 或 Azure DNS 管理，带健康检查和故障转移策略，指向每个区域的 LangSmith 前端 ingress。
NOTE
LangSmith 是一个单写平台。一个跨区域部署应当是主动/被动，而非主动/主动。对同一逻辑安装并发地向两个区域写入不受支持，会产生数据不一致。
恢复流程
可用区故障后恢复
在单区域多可用区部署中，可用区故障由你的云提供商自动处理：
- 托管 Postgres 故障转移到另一可用区的备库。LangSmith pod 通过集群端点在重试后重连。
- 托管 Redis 类似地故障转移。LangSmith 自动重试重连。
- Kubernetes 在剩余可用区的健康节点上重新调度 LangSmith pod。验证节点池和 Horizontal Pod Autoscaler 上限允许这一余量。
- 通过从 SDK 提交一条测试追踪并确认它出现在 UI 中来验证摄取。
区域故障后恢复
这是跨区域故障转移手册。请调整以适配你的具体基础设施。
Declare failover
确认主区域不可用。向干系人通报你正在故障转移，以及预期的 RTO 是什么。
Promote data stores
在 DR 区域把 Postgres 跨区域副本提升为主。对于 ClickHouse Cloud 或 LangSmith Managed 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
如果以温/冷运行，把 LangSmith 部署扩到其生产副本数。从源码控制应用任何待处理的 Helm value 更新。
Run smoke tests
提交一条测试追踪，验证它落入 ClickHouse 并且（若启用了 blob 存储）落入 DR 存储桶。打开 UI，确认追踪、数据集和项目能加载。验证身份认证。参见诊断。
Cut DNS over
更新 DNS 以把流量路由到 DR ingress。向干系人通报切换。
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
如果你丢失了 blob 数据（罕见），从 S3/GCS/Azure 恢复版本化对象，或从一个复制的 DR 存储桶复制。
Resume ingestion
把 langsmith-queue 和 langsmith-ingest-queue 扩回生产副本数。提交一条冒烟测试追踪并验证它落入。
WARNING
务必把 Postgres、ClickHouse 和 blob 存储恢复到尽可能接近的协调时点。把 Postgres 恢复到比 ClickHouse 更新的点，可能产生悬空的项目引用和 UI 中缺失的追踪。
测试你的 DR 计划
一次备份的好坏只取决于最近一次成功的恢复。安排以下演习：
- 每季度： 把 Postgres 和 ClickHouse 快照恢复到一非生产环境，并运行诊断工具和一次冒烟追踪测试。衡量实际恢复时间并确认它在 RTO 之内。
- 每年两次： 对一个预发布安装做一次完整的跨区域故障转移演习。提升副本、重新指向 blob 存储、扩 DR 集群、运行冒烟测试，然后回滚。
- 每次 chart 升级时： 验证升级路径不会使你的 DR 计划失效（例如，只应用到主实例的 schema 迁移需要复制到 DR 副本）。参见自托管升级。
相关页面
- 可扩展性与弹性
- 共同责任模型
- 连接外部 Postgres
- 连接外部 ClickHouse
- 连接外部 Redis
- 启用 blob 存储
- 自托管升级
- 使用现有密钥
- 自托管的诊断
- AWS 自托管参考架构
- GCP 自托管参考架构
- Azure 自托管参考架构