> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/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` 中指定后端的 Agent Server 设置默认后端。如果 `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="terminal-2">
    [通过 MCP 将这些文档](/use-these-docs)连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/configure-checkpointer.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>