> ## 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.

# 配置检查点后端

> 配置 Agent Server 使用 PostgreSQL、MongoDB 或自定义实现来存储检查点。

[Agent Server](/langsmith/agent-server) 使用检查点后端来持久化图状态。默认情况下，LangSmith 将检查点与其他服务器数据一起存储在 PostgreSQL 中。您可以切换到 MongoDB 或提供自定义实现。

<Note>
  无论使用哪种检查点后端，LangSmith 始终需要 PostgreSQL 来存储线程、运行记录、助手、定时任务以及[内存存储](/oss/python/langgraph/persistence#memory-store)。检查点后端仅控制检查点数据的存储位置。
</Note>

## 可用后端

| 后端        | 存储         | 配置                                                        | 使用场景                                                |
| --------- | ---------- | --------------------------------------------------------- | --------------------------------------------------- |
| `default` | PostgreSQL | 无需配置（内置）                                                  | 标准部署                                                |
| `mongo`   | MongoDB    | `langgraph.json` 或 `LS_DEFAULT_CHECKPOINTER_BACKEND` 环境变量 | 已有 MongoDB 基础设施的团队                                  |
| `custom`  | 用户提供       | `langgraph.json`                                          | 自定义存储后端（参见[自定义检查点](/langsmith/custom-checkpointer)） |

## 默认（PostgreSQL）

PostgreSQL 是默认的检查点后端。无需额外配置。要使用自定义 PostgreSQL 实例，请设置 [`POSTGRES_URI_CUSTOM`](/langsmith/env-var#postgres_uri_custom) 环境变量。

## 设置 MongoDB 检查点

<Info>
  需要 Agent Server v0.7.64 或更高版本。
</Info>

### 先决条件

* 一个 MongoDB **副本集**（不支持独立的 `mongod`）。可以是自管理的副本集、`mongos` 路由器或托管服务（如 MongoDB Atlas）。
* 一个在路径中包含数据库名称的连接 URI（例如 `/langgraph`）。

### 选择后端

通过以下方法之一将后端设置为 `"mongo"`：

**在 `langgraph.json` 中**（应用级别——与您的应用程序代码捆绑）：

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "backend": "mongo",
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200,
      "sweep_interval_minutes": 10
    }
  }
}
```

**通过环境变量**（平台级别——适用于管理独立部署的操作员）：

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
LS_DEFAULT_CHECKPOINTER_BACKEND=mongo
```

环境变量为未在 `langgraph.json` 中指定后端的代理服务器设置默认后端。如果 `langgraph.json` 包含了 `backend` 值，则其优先级更高。

### 提供 MongoDB URI

在部署时设置 `LS_MONGODB_URI` 环境变量：

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
LS_MONGODB_URI="mongodb://user:password@host:27017/langgraph?replicaSet=rs0"
```

### 连接 URI 要求

URI 必须：

* 指向副本集成员或 `mongos` 路由器
* 在路径中包含目标数据库名称

有效示例：

```
mongodb://user:password@host:27017/langgraph?replicaSet=rs0
mongodb://host1:27017,host2:27017,host3:27017/mydb?replicaSet=prod-rs
mongodb+srv://user:password@cluster.example.net/langgraph
```

### 按环境部署

<Tabs>
  <Tab title="独立部署 (Kubernetes)">
    [langgraph-cloud Helm chart](https://github.com/langchain-ai/helm/blob/main/charts/langgraph-cloud/README.md)（v0.2.6+）内置了 MongoDB 支持。在您的 values 文件中启用它：

    **捆绑的 MongoDB**（开发和测试）：

    ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    mongo:
      enabled: true
      resources:
        requests:
          cpu: 500m
          memory: 1Gi
      persistence:
        size: 8Gi
    ```

    该 chart 会部署一个单节点 MongoDB 副本集，并自动配置服务器使用它。

    **外部 MongoDB**（生产环境）：

    ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    mongo:
      enabled: true
      external:
        enabled: true
        connectionUrl: "mongodb://user:password@mongo.example.net:27017/langgraph?replicaSet=rs0"
    ```

    或者引用现有的 Kubernetes secret：

    ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    mongo:
      enabled: true
      external:
        enabled: true
        existingSecretName: "my-mongo-secret"
    ```

    secret 必须包含一个 `mongodb_connection_url` 键。
  </Tab>

  <Tab title="独立部署 (Docker)">
    如果您的 `langgraph.json` 已将 `backend` 设置为 `"mongo"`，则只需提供 URI。否则，需要同时设置两个环境变量：

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    docker run \
        --env-file .env \
        -p 8123:8000 \
        -e REDIS_URI="redis://redis:6379" \
        -e DATABASE_URI="postgres://postgres:postgres@postgres:5432/postgres" \
        -e LS_DEFAULT_CHECKPOINTER_BACKEND=mongo \
        -e LS_MONGODB_URI="mongodb://mongo:27017/langgraph?replicaSet=rs0" \
        -e LANGSMITH_API_KEY="..." \
        my-image
    ```

    有关包含 MongoDB 的完整 Docker Compose 示例，请参阅[独立服务器指南](/langsmith/deploy-standalone-server)。
  </Tab>

  <Tab title="云部署">
    在您的 `langgraph.json` 中将 `backend` 设置为 `"mongo"`，然后在 LangSmith UI 的部署设置中将 `LS_MONGODB_URI` 添加为环境变量。

    您的 MongoDB 实例必须能从云数据平面访问。托管服务如 [MongoDB Atlas](https://www.mongodb.com/atlas) 非常适合此用途。

    PostgreSQL 仍会为非检查点数据自动配置。
  </Tab>
</Tabs>

## 自定义检查点

要使用 PostgreSQL 或 MongoDB 之外的存储后端，请实现自定义的 [BaseCheckpointSaver](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.base.BaseCheckpointSaver)。有关详细信息，请参阅[添加自定义检查点](/langsmith/custom-checkpointer)。

## 相关链接

* [配置 TTL](/langsmith/configure-ttl) 以设置检查点和存储项的过期时间
* LangGraph 中的[持久化概念](/oss/python/langgraph/persistence)
* [数据平面](/langsmith/data-plane)架构
* [环境变量](/langsmith/env-var)参考

***

<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\configure-checkpointer.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>