配置检查点后端

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

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

无论使用哪种检查点后端，LangSmith 始终需要 PostgreSQL 来存储线程、运行记录、助手、定时任务以及内存存储。检查点后端仅控制检查点数据的存储位置。

可用后端

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

默认（PostgreSQL）

PostgreSQL 是默认的检查点后端。无需额外配置。要使用自定义 PostgreSQL 实例，请设置 POSTGRES_URI_CUSTOM 环境变量。

设置 MongoDB 检查点

需要 Agent Server v0.7.64 或更高版本。

先决条件

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

选择后端

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

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

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "backend": "mongo",
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200,
      "sweep_interval_minutes": 10
    }
  }
}

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

LS_DEFAULT_CHECKPOINTER_BACKEND=mongo

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

提供 MongoDB URI

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

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:[e-mail]/langgraph

按环境部署

独立部署 (Kubernetes)

langgraph-cloud Helm chart（v0.2.6+）内置了 MongoDB 支持。在您的 values 文件中启用它：

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

mongo:
  enabled: true
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
  persistence:
    size: 8Gi

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

外部 MongoDB（生产环境）：

mongo:
  enabled: true
  external:
    enabled: true
    connectionUrl: "mongodb://user:[e-mail]:27017/langgraph?replicaSet=rs0"

或者引用现有的 Kubernetes secret：

mongo:
  enabled: true
  external:
    enabled: true
    existingSecretName: "my-mongo-secret"

secret 必须包含一个 mongodb_connection_url 键。

独立部署 (Docker)

如果您的 langgraph.json 已将 backend 设置为 "mongo"，则只需提供 URI。否则，需要同时设置两个环境变量：

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 示例，请参阅独立服务器指南。

云部署

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

您的 MongoDB 实例必须能从云数据平面访问。托管服务如 MongoDB Atlas 非常适合此用途。

PostgreSQL 仍会为非检查点数据自动配置。

自定义检查点

要使用 PostgreSQL 或 MongoDB 之外的存储后端，请实现自定义的 BaseCheckpointSaver。有关详细信息，请参阅添加自定义检查点。

相关链接

• 配置 TTL 以设置检查点和存储项的过期时间
• LangGraph 中的持久化概念
• 数据平面架构
• 环境变量参考

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.