---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, self-hosted, kubernetes, security]
topic: LangSmith 自托管架构、Kubernetes 安装与安全基线
sources:
  - "https://docs.langchain.com/langsmith/aws-self-hosted"
  - "https://docs.langchain.com/langsmith/azure-self-hosted"
  - "https://docs.langchain.com/langsmith/deploy-self-hosted-full-platform"
  - "https://docs.langchain.com/langsmith/gcp-self-hosted"
  - "https://docs.langchain.com/langsmith/kubernetes"
  - "https://docs.langchain.com/langsmith/self-host-basic-auth"
  - "https://docs.langchain.com/langsmith/self-host-custom-tls-certificates"
  - "https://docs.langchain.com/langsmith/self-host-dependency-versions"
  - "https://docs.langchain.com/langsmith/self-host-environment-variables"
  - "https://docs.langchain.com/langsmith/self-host-fips"
  - "https://docs.langchain.com/langsmith/self-host-ingress"
  - "https://docs.langchain.com/langsmith/self-host-mirroring-images"
  - "https://docs.langchain.com/langsmith/self-host-sso"
  - "https://docs.langchain.com/langsmith/self-host-using-an-existing-secret"
  - "https://docs.langchain.com/langsmith/self-hosted-mission-control"
last_verified: 2026-08-11
---

# 自托管架构、Kubernetes 与安全安装

## 基础平台组成

Self-hosted 基础 Helm 安装包含 Frontend/Nginx、Backend、Platform Backend、Queue/Ingest Queue、Playground、ACE，以及 PostgreSQL、Redis/Valkey、ClickHouse；Blob Storage 可选但生产强烈推荐。Frontend 是主要用户入口，内部服务不应直接暴露公网。

生产优先使用云托管外部数据库和对象存储，Helm 内置 datastore 更适合试用或小规模验证。最低依赖基线：PostgreSQL 14、Redis 5 或 Valkey 8；ClickHouse 版本应匹配 Helm chart，降级不受支持。

## AWS、Azure、GCP 参考映射

| 能力 | AWS | Azure | GCP |
| --- | --- | --- | --- |
| Kubernetes | EKS | AKS | GKE |
| PostgreSQL | RDS/Aurora | Flexible Server | Cloud SQL |
| Redis | ElastiCache | Azure Managed Redis | Memorystore |
| Blob | S3 | Azure Blob | GCS |
| Secret/身份 | Secrets/SSM + IRSA | Key Vault + Workload Identity | Secret Manager + Workload Identity |
| 入口 | ALB/Envoy | AGIC/Istio/Envoy | Envoy/GCLB |

三云都应跨可用区部署节点与托管数据库、私网访问存储、用工作负载身份取代长期云密钥，并把平台指标送入各云监控或 OTel/Prometheus。

## Helm 安装顺序

1. 获取 Enterprise license，准备符合版本要求的集群、DNS、TLS 与存储。
2. 先安装基础 LangSmith，验证 UI/API、Trace ingestion、数据库迁移和用户登录。
3. 再按需启用 Deployment、Fleet、Insights、Chat、Sandboxes、Engine；不要一次开启所有 add-on 后再定位故障。
4. Queue/Deployment 自动扩容安装 KEDA；验证 CRD 与 Metrics API 后再启用 HPA/KEDA。
5. 记录实际 Helm chart、`appVersion`、镜像 digest、values 与数据库 schema 版本。

附加能力会增加 Host Backend、Listener、Operator、Tool/Trigger servers、Sandbox/Engine 组件和额外密钥。Engine 依赖 Sandboxes，且 Self-hosted Engine 仍需访问 LangSmith Intelligence；“自托管”不自动等于“完全无出站”。

## 环境变量注入

- `commonEnv` 进入绝大多数 Deployment/StatefulSet，但不会进入隔离的 `playground` 与 `aceBackend`。
- 服务专属 `extraEnv` 用于精确注入；同一服务不得同时出现重复变量名，否则结果可能不确定。
- 模型 provider 凭据需单独给 Playground，优先 Secret/Workload Identity。
- Feature flag 需记录 chart/app 最低版本，不能只复制新文档到旧 chart。

## Ingress 与 TLS

默认 Frontend LoadBalancer 可能获得公网 IP。生产改为 ClusterIP，并使用 Ingress、Gateway API 或 Istio；统一定义 hostname、basePath、IngressClass 与 TLS termination。

内部 CA 应以 Kubernetes Secret 挂载到系统 trust store；PostgreSQL 使用 `sslmode=verify-full`，Redis 使用 `rediss://`。Playground mTLS 的 client cert/key 与全局 CA 是两套配置。证书轮换必须验证所有 Backend、Queue、Playground 和 migration Job，而不仅是浏览器入口。

## 身份模式的不可逆边界

| 模式 | 用途 | 约束 |
| --- | --- | --- |
| None | 仅基础设施验证 | 功能受限，禁止生产 |
| Basic Auth | 试用/无外部 IdP | 单一 Default Organization；初始密码需安全旁路传递 |
| OAuth2/OIDC SSO | 生产推荐 | Authorization Code + Client Secret；需 OIDC compliant IdP |

- Basic 可升级到 OAuth Client Secret，但不能再切回 Basic。
- 不能同时启用 Basic 与 OAuth。
- OAuth Client Secret 与旧 PKCE 模式不能互转；PKCE 已 deprecated。
- 从 Basic 切 OAuth 前，必须确认同一邮箱能通过 IdP 登录，否则会锁死管理员。

## Secret 与供应链

可让 Helm 引用预建的 `langsmith-secrets`、PostgreSQL、Redis、ClickHouse Secret，结构与 key 必须完全符合 chart。`api_key_salt` 一旦启用不可更换；变更会永久使组织内现有 API key 全部失效。

Air-gapped/私有 Registry 可镜像所有 chart 引用的镜像。0.16.21（chart `0.16.0-rc.17`）以后多个服务合并到 `langsmith-backend`，旧版本仍需旧镜像集合。应固定 digest，验证 Cosign 签名与 SBOM，而非只复制 tag。

FIPS/air-gapped rollout 必须先与 LangChain 确认 entitlement 和支持矩阵。v15 起 LangChain 自有镜像有 `-fips` 变体；这只证明镜像密码模块边界，不自动证明整套客户环境或业务流程已通过 FIPS 认证。

## Mission Control

Mission Control 是集群内运维控制台，默认通过 `kubectl port-forward` 访问，无需公网 Ingress。可用安装脚本或逐条手工 Helm 命令；受控环境应先审阅脚本、values、RBAC 权限和镜像。卸载控制台不应删除 LangSmith 数据，但仍需先核对 Helm release 与 namespace target。

## 安装验收

1. 外部服务连通、TLS 主机名校验、工作负载身份和最小权限。
2. Migration Job 完成，Frontend/Backend/Queue/Playground/ACE 全部 Ready。
3. 登录、API key、Trace 写入与查询、模型 Playground smoke test。
4. 节点/AZ 故障、Pod 驱逐、数据库 failover 和队列重试。
5. Ingress 仅暴露预期端点，内部 Service/metrics 不可公网访问。
6. Secret 未出现在 values、日志、命令历史或镜像层。
7. 备份、恢复、升级与证书轮换均有演练记录。