本页面提供诊断步骤，帮助你在联系支持团队之前排查自托管 LangSmith Deployment 的问题。请按照以下步骤系统地识别并解决常见的部署问题。
如果完成这些诊断步骤后仍需要帮助，请参阅本指南末尾的 支持，了解在联系支持团队之前需要收集哪些信息。

​
前置条件

开始诊断前，请确保你具备：
  • 对 Kubernetes 集群的 kubectl 访问权限。
  • 查看 Pod、部署、服务等资源的适当权限。
  • 熟悉你的 Helm chart 配置。

​
步骤 1：了解你的部署

确认已部署的内容，并了解系统的基准状态。这有助于你认识正常运行状态，并在问题发生时识别偏差。 运行以下命令查看所有已部署的 Kubernetes 资源。
在运行本节中的命令时，请确保你处于正确的命名空间。或者，使用 -n 标志显式指定命名空间。例如：kubectl get deployments -n langsmith。
列出所有部署：
列出所有 Pod：
列出所有服务：
列出所有 lgps 资源（仅在创建 Agent Server 后存在）：

​
已部署的关键组件

你的部署包含以下核心组件：
  • langsmith-frontend：LangSmith 前端 UI，你可以在其中创建 Agent Server 部署。此应用会向 langsmith-host-backend 发起 API 调用。它属于控制平面的一部分。
  • langsmith-host-backend：LangSmith Deployment 的控制平面，接收来自 langsmith-frontend 的请求，并将部署请求持久化到控制平面 Postgres 数据库中。
  • langsmith-listener：LangSmith Deployment 数据平面的一部分。它通过 HTTP API 轮询 langsmith-host-backend，获取需要创建、更新或删除的部署，并将任务加入队列，交由工作进程处理。
  • langsmith-redis：作为 langsmith-listener 任务队列的 Redis 实例。监听器会在此处加入任务，工作进程则从该队列中提取任务。
  • langsmith-operator：用于协调 lgps 资源底层 Kubernetes 资源的 lgps Kubernetes operator。它属于数据平面基础设施的一部分。
根据你的配置，部署中可能还会包含其他组件。有关概览，请参阅 LangSmith Deployment 组件。

​
步骤 2：启用调试日志

排查问题时，通常第一步是启用调试级别的日志，以收集系统运行情况的更多详细信息。

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

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

​
对于 Agent Server 部署

如果问题出在单个 Agent Server 部署上：
  1. 在 LangSmith UI 中导航到 Deployments 选项卡。
  2. 在某个部署的视图中，选择 + New Revision。
  3. 添加新的环境变量 LOG_LEVEL，并将其设置为 DEBUG。
你还可以在 UI 中查看调试日志：进入部署视图，点击 Server Logs，然后在 Log level: Info 下拉菜单中选择 Debug。

​
对于大范围问题

如果你不确定问题的来源，请在所有位置启用 DEBUG 日志（控制平面、数据平面以及所有 Agent Server 部署）。

​
查看应用程序日志

跟踪每个 Pod 的日志，以了解系统的基准行为：
然后查找以下日志行：
  • langsmith-listener：Reconciling projects...（每 10 秒出现一次）
  • langsmith-operator：Starting reconciliation（定期出现）
在健康的部署中，你不应看到任何错误。所有日志都应表现正常且属于常规运行信息。

​
解读调试日志

请查找以下问题迹象：
  • 异常或堆栈跟踪。
  • 错误消息（包含单词 "ERROR"）。
  • 与正常运行情况不同的异常模式。
根据你发现的错误：
  • 配置问题：如果你怀疑是配置问题，请向执行 helm install 的人员报告。
  • 用户代码错误：如果你怀疑是用户代码中的错误（例如 LangGraph OSS 图的实现问题），请向创建 langgraph.json 文件的 Agent Server 应用负责人报告。

​
步骤 3：描述部署和 Pod

描述 Kubernetes 资源可以显示应用程序日志中可能未出现的错误事件和状态。这些错误通常由配置或基础设施问题引起，而不是应用程序代码错误。描述资源还会显示其配置（例如环境变量），这对调试很有帮助。 运行以下命令描述资源。 描述 Kubernetes 部署：
描述 Kubernetes Pod：
描述 lgps 资源（仅在创建 Agent Server 后才相关）：

​
解读结果

查看输出中的 Events: 部分，并确认一切正常。常见问题包括：
  • 存活探针或就绪探针失败
  • 镜像拉取错误
  • 资源限制（CPU、内存）
  • 卷挂载问题
  • 配置错误
确保不存在错误事件，并且所有事件都表明系统运行正常。

​
其他资源

如需了解更多故障排除信息，请参阅：
  • 故障排除：包含常见问题解决方案的通用故障排除指南。
  • 自托管概览：介绍系统架构和组件之间的交互。

​
支持

如果你已完成上述诊断步骤但仍需要帮助，请在联系支持团队之前收集以下信息：
  • 诊断步骤的输出。
  • 你的 Helm chart 配置。
  • 相关错误消息和日志。
  • 问题发生时你正在尝试执行的操作的描述。
准备好这些信息后，支持团队可以更快速地诊断并解决你的问题。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.