> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排除

本指南将引导您解决在运行自托管 LangSmith 实例时可能遇到的常见问题。

运行 LangSmith 时，您可能会遇到意外的 500 错误、性能缓慢或其他问题。本指南将帮助您诊断并解决这些问题。

## 获取有用信息

要诊断和解决问题，首先需要获取一些相关信息。以下部分将说明如何在 Kubernetes 或 Docker 设置中执行此操作，以及如何提取有用的浏览器信息。

通常，您需要分析的主要服务包括：

* `langsmith-backend`：处理 CRUD API 请求、业务逻辑、来自前端和 SDK 的请求、用于数据摄取的追踪准备以及 hub API。
* `langsmith-platform-backend`：处理身份验证、运行数据摄取和其他高容量任务。
* `langsmith-queue`：处理传入的追踪和反馈、异步数据摄取和持久化到数据存储、数据完整性检查，以及在数据库错误或连接问题时的重试。

有关这些服务的更多详细信息，请参阅[自托管概述](/langsmith/self-hosted)。

#### Kubernetes

故障排除的第一步是收集有关 LangSmith 部署的重要调试信息。服务日志、Kubernetes 事件和容器的资源利用率可以帮助确定问题的根本原因。

您可以运行我们的 [k8s 故障排除脚本](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/scripts/get_k8s_debugging_info.sh)，该脚本将提取所有相关的 Kubernetes 信息并将其输出到一个文件夹中供调查。该脚本还会将此文件夹压缩为 zip 文件以便共享。以下是如何运行此脚本的示例，假设您的 langsmith 部署在 `langsmith` 命名空间中启动：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
bash get_k8s_debugging_info.sh --namespace langsmith
```

然后，您可以检查生成的文件夹内容，查找任何相关的错误或信息。如果您希望 LangSmith 团队协助调试，请将此 zip 文件分享给团队。

#### Docker

如果在 Docker 上运行，您可以通过运行以下命令检查部署的日志：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
docker compose logs >> logs.txt
```

#### 浏览器错误

如果您遇到的问题表现为浏览器错误，检查 HAR 文件也可能有所帮助，其中可能包含关键信息。要获取 HAR 文件，您可以按照[此指南](https://support.langchain.com/articles/9042697994-how-to-generate-a-har-file-for-troubleshooting)操作，该指南解释了针对各种浏览器的简短流程。

然后，您可以使用 [Google 的 HAR 分析器](https://toolbox.googleapps.com/apps/har_analyzer/) 进行调查。您也可以将 HAR 文件发送给 LangSmith 团队以帮助调试。

## 常见问题

### *DB::Exception: Cannot reserve 1.00 MiB, not enough space: While executing WaitForAsyncInsert. (NOT\_ENOUGH\_SPACE)*

当 ClickHouse 磁盘空间不足时会发生此错误。您需要增加 ClickHouse 可用的磁盘空间。

#### Kubernetes

在 Kubernetes 中，您需要增加 ClickHouse PVC 的大小。为此，您可以执行以下步骤：

1. 获取 PVC 的存储类：`kubectl get pvc data-langsmith-clickhouse-0 -n <namespace> -o jsonpath='{.spec.storageClassName}'`

2. 确保存储类具有 AllowVolumeExpansion: true：`kubectl get sc <storage-class-name> -o jsonpath='{.allowVolumeExpansion}'`

   * 如果为 false，某些存储类可以更新以允许卷扩展。
   * 要更新存储类，可以运行 `kubectl patch sc <storage-class-name> -p '{"allowVolumeExpansion": true}'`
   * 如果失败，您可能需要创建一个具有正确设置的新存储类。

3. 编辑您的 PVC 以设置新的大小：`kubectl edit pvc data-langsmith-clickhouse-0 -n <namespace>` 或 `kubectl patch pvc data-langsmith-clickhouse-0 '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}' -n <namespace>`

4. 更新您的 helm chart `langsmith_config.yaml` 中的大小为新的值（例如 `100 Gi`）

5. 删除 clickhouse statefulset `kubectl delete statefulset langsmith-clickhouse --cascade=orphan -n <namespace>`

6. 应用更新了大小的 helm chart（您可以按照[升级指南](/langsmith/self-host-upgrades)操作）

7. 您的 PVC 现在应该具有新的大小。通过运行 `kubectl get pvc` 和 `kubectl exec langsmith-clickhouse-0 -- bash -c "df"` 进行验证。

#### Docker

在 Docker 中，您需要增加 ClickHouse 卷的大小。为此，您可以执行以下步骤：

1. 停止您的 LangSmith 实例。`docker compose down`
2. 如果使用绑定挂载，您需要增加挂载点的大小。
3. 如果使用 docker `volume`，您需要为卷/docker 分配更多空间。

### *error: Dirty database version 'version'. fix and force version*

当 ClickHouse 数据库与我们的迁移处于不一致状态时会发生此错误。您需要重置到较早的数据库版本，然后重新运行升级/迁移。

#### Kubernetes

1. 强制迁移到较早的版本，其中 version = dirty version - 1。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
kubectl exec -it deployments/langsmith-backend -- bash -c 'migrate -source "file://clickhouse/migrations" -database "clickhouse://$CLICKHOUSE_HOST:$CLICKHOUSE_NATIVE_PORT?username=$CLICKHOUSE_USER&password=$CLICKHOUSE_PASSWORD&database=$CLICKHOUSE_DB&x-multi-statement=true&x-migrations-table-engine=MergeTree&secure=$CLICKHOUSE_TLS" force <version>'
```

1. 重新运行您的升级/迁移。

#### Docker

1. 强制迁移到较早的版本，其中 version = dirty version - 1。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
docker compose exec langchain-backend migrate -source "file://clickhouse/migrations" -database "clickhouse://$CLICKHOUSE_HOST:$CLICKHOUSE_NATIVE_PORT?username=$CLICKHOUSE_USER&password=$CLICKHOUSE_PASSWORD&database=$CLICKHOUSE_DB&x-multi-statement=true&x-migrations-table-engine=MergeTree&secure=$CLICKHOUSE_TLS" force <version>
```

1. 重新运行您的升级/迁移。

### *413 - request entity too large*

当请求大小超过允许的最大值时会发生此错误。您需要在 Nginx 配置中增加最大请求大小。

#### Kubernetes

1. 编辑您的 `langsmith_config.yaml` 并增加 `frontend.maxBodySize` [值](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/values.yaml#L519)。可能如下所示：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
frontend:
  maxBodySize: "100M"
```

2. 将更改应用到集群。

### *Details: code: 497, message: default: Not enough privileges. to execute this query, it's necessary to have the grant CREATE ROW POLICY ON default.feedbacks\_rmt*

当您的用户在 Clickhouse 中没有创建行策略的必要权限时会发生此错误。部署 Docker 部署时，您还需要从 github 仓库复制 `users.xml` 文件。这会将 `<access_management>` 标签添加到 `users.xml` 文件中，从而允许用户创建行策略。以下是我们期望使用的默认 `users.xml` 文件。

```xml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
<clickhouse>
    <users>
        <default>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
            <show_named_collections>1</show_named_collections>
            <show_named_collections_secrets>1</show_named_collections_secrets>
            <profile>default</profile>
        </default>
    </users>
    <profiles>
        <default>
            <async_insert>1</async_insert>
            <async_insert_max_data_size>2000000</async_insert_max_data_size>
            <wait_for_async_insert>0</wait_for_async_insert>
            <parallel_view_processing>1</parallel_view_processing>
            <allow_simdjson>0</allow_simdjson>
            <lightweight_deletes_sync>0</lightweight_deletes_sync>
        </default>
    </profiles>
</clickhouse>
```

在某些环境中，您的挂载点可能无法被容器写入。在这些情况下，我们建议构建一个包含 `users.xml` 文件的自定义镜像。

示例 `Dockerfile`：

```dockerfile theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
FROM clickhouse/clickhouse-server:24.8
COPY ./users.xml /etc/clickhouse-server/users.d/users.xml
```

然后执行以下步骤：

1. 构建您的自定义镜像。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
docker build -t <image-name> .
```

2. 更新您的 `docker-compose.yaml` 以使用自定义镜像。确保移除 users.xml 挂载点。

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langchain-clickhouse:
  image: <image-name>
```

3. 重新启动您的 LangSmith 实例。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
docker compose down --volumes
docker compose up
```

### *在运行带有 AquaSec 的集群时，ClickHouse 无法启动*

在某些环境中，AquaSec 可能会阻止 ClickHouse 正确启动。这可能表现为 ClickHouse pod 不输出任何日志且无法标记为就绪状态。
通常这是由于 AquaSec 设置了 `LD_PRELOAD`，干扰了 ClickHouse。要解决此问题，您可以将以下环境变量添加到 ClickHouse 部署中：

#### Kubernetes

编辑您的 `langsmith_config.yaml`（或相应的配置文件）并设置 `AQUA_SKIP_LD_PRELOAD` 环境变量：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
clickhouse:
  statefulSet:
    extraEnv:
      - name: AQUA_SKIP_LD_PRELOAD
        value: "true"
```

#### Docker

编辑您的 `docker-compose.yaml` 并设置 `AQUA_SKIP_LD_PRELOAD` 环境变量：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langchain-clickhouse:
  environment:
    - AQUA_SKIP_LD_PRELOAD=true
```

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\troubleshooting.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>