自托管架构、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 安装顺序

获取 Enterprise license，准备符合版本要求的集群、DNS、TLS 与存储。
先安装基础 LangSmith，验证 UI/API、Trace ingestion、数据库迁移和用户登录。
再按需启用 Deployment、Fleet、Insights、Chat、Sandboxes、Engine；不要一次开启所有 add-on 后再定位故障。
Queue/Deployment 自动扩容安装 KEDA；验证 CRD 与 Metrics API 后再启用 HPA/KEDA。
记录实际 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。

安装验收

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