企业级落地指南：在 Kubernetes 上自托管 LangSmith 全流程实战

摘要： 随着大模型应用深入企业核心业务，数据隐私与合规性成为了不可逾越的红线。LangSmith 作为 LLM 应用的“黑盒透视镜”，其官方托管版虽好，但对于金融、政务等高度敏感的行业，自托管才是唯一的出路。本文将详细解读 LangSmith 的企业级自托管方案，从架构依赖、资源规划到基于 Helm 的实战部署，助你在 Kubernetes 集群中构建一套完全可控的 LLM 可观测性平台。

1. 前言：为什么企业需要自托管 LangSmith？

LangSmith 能够追踪大模型应用的每一次调用，这对调试和优化至关重要。然而，默认的云端托管服务意味着你的代码运行数据、Prompt 细节甚至用户交互内容都会上传到第三方平台。对于以下场景，这是不可接受的：

• 数据合规：受 GDPR、HIPAA 或国内《数据安全法》严格监管的行业。
• 代码安全：核心算法或业务逻辑不希望暴露在任何外部环境。
• 网络隔离：部署在内网或私有云环境，无法访问公网。
  LangSmith 的企业计划提供了自托管能力，让企业可以在自己的 VPC 或物理机房内完整运行 LangSmith。

2. 核心架构与依赖分析

在开始部署前，我们需要理解 LangSmith 的资源需求。这不仅仅是一个 Web 应用，它是一个包含数据库、缓存、时序存储的完整数据处理平台。

2.1 技术栈与存储依赖

LangSmith 的基础安装会包含以下核心组件，它们都需要持久化存储（PV）支持：

组件	用途	存储需求
PostgreSQL	存储元数据、用户信息、项目配置	需高可靠 SSD 存储
Redis	缓存会话、队列任务	需低延迟存储
ClickHouse	核心组件，存储海量的追踪日志（Trace）	需极高性能的 SSD，推荐 7000 IOPS

⚠️ 注意：ClickHouse 是一个资源消耗大户。默认配置下，它会请求 4 vCPU 和 16GB 内存。请确保你的 Kubernetes 集群至少有一个节点能满足这个“可分配”资源的要求。

2.2 集群规模建议

为了支撑生产环境的稳定运行，官方建议的集群最低配置如下：

• 总资源：至少 16 vCPU 和 64GB 可用内存。
• 存储类：强烈建议使用支持卷扩展（Volume Expansion）的 SSD 存储类，因为追踪数据量会随时间快速增长。
• 自动伸缩：建议配置 Cluster Autoscaler，以便根据负载自动伸缩节点。

3. 先决条件与密钥生成

在动手之前，请确保以下工具和凭证已准备就绪。

3.1 工具准备

• kubectl：已配置好上下文，能访问目标集群。
• helm：包管理工具，用于部署应用。

3.2 密钥与凭证准备

你需要生成几个关键密钥，用于加密和认证。

• API 密钥盐 (API Key Salt)：用于加密 API 密钥。

    openssl rand -base64 32

• JWT 密钥 (JWT Secret)：用于签署 Basic Auth 的 JWT 令牌。

    openssl rand -base64 32

LangSmith 许可证密钥：这是企业版的功能，需要联系 LangChain 官方（sales@langchain.dev）获取。

3.3 网络要求

出站访问：即便是在内网部署，LangSmith 也需要访问 https://beacon.langchain.com 进行许可证验证和使用情况报告。请确保防火墙放行此地址（除非在完全离线模式下运行）。

4. 实战部署：基于 Helm 的一键安装

Helm 是管理 Kubernetes 应用最标准的方式。LangChain 官方提供了维护良好的 Helm Chart。

4.1 添加 Helm 仓库

首先，将 LangChain 的 Helm 仓库添加到本地：

helm repo add langchain https://github.langchain.ac.cn/helm/
helm repo update

4.2 查看可用版本

查看最新的 Chart 版本，通常建议使用最新稳定版：

helm search repo langchain/langsmith --versions

4.3 创建配置文件

创建一个名为 langsmith_config.yaml 的文件，这是部署的核心。以下是一个最小化可用配置，启用了基本认证。

config:
  # 1. 企业许可证密钥
  langsmithLicenseKey: "<YOUR_LICENSE_KEY>"
  
  # 2. API 密钥盐
  apiKeySalt: "<YOUR_API_KEY_SALT>"
  
  # 认证类型：mixed 支持同时使用 API Key 和 Basic Auth
  authType: mixed
  
  # 3. 基本认证配置
  basicAuth:
    enabled: true
    # 初始管理员邮箱
    initialOrgAdminEmail: "admin@your-company.com"
    # 初始管理员密码（需至少12位，含大小写字母和符号）
    initialOrgAdminPassword: "Secure-P@ssw0rd!"
    # JWT 签名密钥
    jwtSecret: "<YOUR_JWT_SECRET>"

| 💡 提示：对于生产环境，强烈建议配置外部 PostgreSQL 和 Redis 实例（如云厂商的 RDS 和 ElastiCache），而不是依赖 Chart 内置的数据库，以获得更好的性能和可靠性。

4.4 执行部署

执行 Helm 安装命令。我们将应用部署到一个名为 langsmith 的新命名空间中。

# 创建命名空间
kubectl create namespace langsmith

# 执行安装
# --version: 指定 Chart 版本（使用上一步查到的最新版本）
# --values: 指定配置文件
helm install langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version 0.10.14 \
  -n langsmith \
  --debug

这个过程可能需要几分钟，因为 Helm 会拉取镜像、创建 StatefulSets（用于数据库）和 Deployments（用于应用服务），并运行初始化作业。

5. 验证与访问

部署完成后，我们需要验证所有 Pod 是否正常运行。

5.1 检查 Pod 状态

运行以下命令，确保所有 Pod 都处于 Running 状态。

kubectl get pods -n langsmith

预期输出应包含以下关键组件：

langsmith-backend-xxx        1/1     Running   0          5m
langsmith-frontend-xxx       1/1     Running   0          5m
langsmith-hub-backend-xxx    1/1     Running   0          5m
langsmith-playground-xxx     1/1     Running   0          5m
langsmith-postgres-0         1/1     Running   0          5m
langsmith-queue-xxx          1/1     Running   0          5m
langsmith-redis-0            1/1     Running   0          5m

5.2 获取服务访问地址

查看 Service，找到 langsmith-frontend 的 EXTERNAL-IP。如果是 LoadBalancer 类型，云厂商会分配一个公网 IP；如果是 NodePort 或 ClusterIP，你需要配置 Ingress 或端口转发来访问。

kubectl get svc -n langsmith

5.3 登录验证

• 在浏览器中访问 http://{EXTERNAL-IP} 。
• 使用你在 langsmith_config.yaml 中配置的 initialOrgAdminEmail 和 initialOrgAdminPassword 登录。
• 你应该能看到熟悉的 LangSmith UI 界面，并且是完全私有的实例！

6. 生产环境进阶配置

部署成功只是第一步，要让它在生产环境真正可靠，还需要进行一系列加固。

6.1 网络与安全

• 配置 DNS：为 LangSmith 的前端服务配置一个域名（如 langsmith.internal.yourcompany.com）。
• 配置 SSL/TLS：强烈建议为你的域名配置 HTTPS 证书。你可以使用 cert-manager 自动申请 Let’s Encrypt 证书，或使用公司现有的证书。追踪数据在传输过程中必须加密。
• 配置 SSO：对接公司现有的身份提供商（如 Okta, Azure AD, Keycloak），实现单点登录，这是企业级安全的基本要求。

6.2 性能与高可用

• 外部数据库：将 PostgreSQL 和 Redis 迁移到云厂商的托管服务（如 AWS RDS, ElastiCache），实现自动备份和故障转移。
• ClickHouse 优化：根据实际追踪量调整 ClickHouse 的资源请求和限制，并考虑配置副本集以提高可用性。
• 备份策略：即使使用了外部数据库，也要定期备份 LangSmith 的元数据。

7. 总结

自托管 LangSmith 是一个涉及存储、网络、安全、认证多个领域的复杂工程。但它带来的价值——完全的数据主权、深度的集成定制、合规的审计追踪——对于任何严肃的 LLM 应用开发团队来说，都是值得投入的。

通过 Helm Chart，我们极大地简化了部署过程。现在，你可以放心地在企业内部网络中追踪大模型的每一次“思考”，而无需担心数据泄露的风险。

参考资源：

LangSmith 官方文档 - Self Hosting
LangChain Helm Chart Repository
希望这篇指南能帮助你在企业内部成功落地 LangSmith！🚀