自托管部署的故障排除

在联系支持之前，用于排查自托管 LangSmith Deployment 问题的诊断步骤。

本页提供诊断步骤，帮助你在联系支持之前排查自托管 LangSmith Deployment 的问题。系统地遵循这些步骤以识别并解决常见的部署问题。

INFO

如果你完成了这些诊断步骤但仍需要协助，请参阅本指南末尾的支持，了解联系前应收集哪些信息。

前置条件

在开始诊断步骤之前，请确保你具备：

• 对你 Kubernetes 集群的 kubectl 访问权限。
• 查看 pods、deployments、services 等的适当权限。
• 熟悉你的 Helm chart 配置。

步骤 1. 了解你的部署

验证部署了什么并了解你系统的基线状态。这有助于你认识到正常运行是什么样，并在问题发生时识别偏差。

运行以下命令以查看所有已部署的 Kubernetes 资源。

NOTE

请确保你在运行本节命令时处于正确的命名空间中。或者用 -n 标志显式指定命名空间。例如：kubectl get deployments -n langsmith。

列出所有 deployment：

kubectl get deployments

列出所有 pod：

kubectl get pods

列出所有 service：

kubectl get services

列出所有 lgps 资源（仅在创建 Agent Server 后存在）：

kubectl get lgps

关键部署组件

你的部署包括以下核心组件：

• langsmith-frontend：你创建 Agent Server 部署所在的 LangSmith 前端 UI。该应用向 langsmith-host-backend 发起 API 调用。属于控制平面的一部分。
• langsmith-host-backend：LangSmith Deployment 控制平面，它接收来自 langsmith-frontend 的请求，并将部署请求持久化到控制平面 Postgres 数据库。
• langsmith-listener：LangSmith Deployment 数据平面的一部分。通过 HTTP API 轮询 langsmith-host-backend 以获取要创建、更新或删除的部署。为 worker 进程要处理的任务入队。
• langsmith-redis：充当 langsmith-listener 任务队列的 Redis 实例。listener 在此处入队任务，worker 从该队列拉取任务。
• langsmith-operator：lgps Kubernetes operator，它协调 lgps 资源的底层 Kubernetes 资源。属于数据平面基础设施的一部分。

NOTE

根据你的配置，你的部署中可能存在额外的组件。有关概览，参阅 LangSmith Deployment 组件。

步骤 2. 启用调试日志

排查问题时，第一步通常是启用调试级别的日志，以收集关于系统中正在发生什么的更详细信息。

对于控制平面或数据平面部署

如果你在使用控制平面部署（例如 langsmith-host-backend）或数据平面部署（例如 langsmith-listener）时遇到问题，请使用 LOG_LEVEL=DEBUG 环境变量重新安装 Helm chart。将以下内容添加到你的 values.yaml 文件：

extraEnv:
  - name: LOG_LEVEL
    value: DEBUG

对于 Agent Server 部署

如果问题出在单个 Agent Server 部署上：

1. 导航到 LangSmith UI中的 Deployments 标签。
2. 在某个部署的视图上，选择 + New Revision。
3. 添加一个新的环境变量 LOG_LEVEL 并将其设为 DEBUG。

NOTE

你也可以在 UI 上某个部署的视图中找到调试日志，点击 Server Logs，并为 Log level: Info 下拉菜单选择 Debug。

对于广泛的问题

如果你不确定问题源自何处，就在所有地方（控制平面、数据平面以及所有 Agent Server 部署）启用 DEBUG 日志。

查看应用日志

跟踪每个 pod 的日志以了解基线行为：

kubectl logs -f <pod_name>

然后寻找这些日志行：

• langsmith-listener：Reconciling projects...（每 10 秒出现一次）
• langsmith-operator：Starting reconciliation（周期性地出现）

在一个健康的部署中，你不应当看到任何错误。所有日志都应当显得正常且常规。

解读调试日志

寻找以下问题指示：

• 异常或堆栈跟踪。
• 错误消息（"ERROR" 一词）。
• 与正常操作不同的异常模式。

根据你发现的错误：

• 配置问题：如果你怀疑是配置问题，向运行了 helm install 的人提出该问题。
• 用户代码缺陷：如果你怀疑是用户代码中的缺陷（例如 LangGraph OSS 图实现），向创建了 langgraph.json 文件的 Agent Server 应用所有者提出该问题。

步骤 3. 描述 deployment 和 pod

描述 Kubernetes 资源会揭示那些可能不会出现在应用日志中的错误事件和状态。这类错误通常由配置或基础设施问题而非应用代码缺陷导致。描述资源还会显示其配置（例如环境变量），这对调试很有帮助。

运行以下命令以描述你的资源。

描述一个 Kubernetes deployment：

kubectl describe deployment <deployment_name>

描述一个 Kubernetes pod：

kubectl describe pod <pod_name>

描述一个 lgps 资源（仅在创建 Agent Server 后相关）：

kubectl describe lgps <lgps_name>

解读结果

查看输出的 Events: 部分并核实一切都正常。常见出现的问题包括：

• 存活或就绪探针失败
• 镜像拉取错误
• 资源限制（CPU、内存）
• 卷挂载问题
• 配置错误

确保没有错误事件，且所有事件都表明运行健康。

其他资源

有关更多故障排除信息，参阅：

• 故障排除：带有常见问题解决方案的通用故障排除指南。
• 自托管概览：关于系统架构和组件交互的详情。

支持

如果你遵循了这些诊断步骤但仍需要协助，请收集以下信息并联系技术支持：

• 捕获诊断包。
• 对问题发生时你正试图做什么的描述。

在工单中提供这些信息将帮助支持团队更快地诊断和解决你的问题。

---