自托管独立服务器

本指南介绍如何直接部署独立的 Agent Server，无需控制平面。你可以独立部署服务器，同时仍将跟踪信息发送到 LangSmith（自托管版或云版），以进行可观测性和评估。独立服务器已准备好用于生产环境，并且是运行代理最轻量的方式。

概览

你需要管理一个简化的，其中包括 Agent Server 及其所需的后端服务（PostgreSQL、Redis 等）：

组件	职责	运行位置	管理方
控制平面	不适用	不适用	不适用
数据平面	Agent Server Postgres、Redis 等	你的基础设施	你

这种方式让你可以完全控制扩展、部署以及 CI/CD 流水线，同时仍可选择与 LangSmith 集成，以进行跟踪和评估。

不要在无服务器环境中运行独立服务器。缩容到零可能会导致任务丢失，并且扩容无法可靠运行。

工作流

使用 langgraph-cli 或 Studio 在本地定义并测试图。
将代理打包为 Docker 镜像。
将 Agent Server 部署到你选择的计算平台（Kubernetes、Docker、虚拟机）。
你也可以配置 LangSmith API 密钥和端点，让服务器将跟踪信息和评估结果发送回 LangSmith（自托管版或 SaaS 版）。

支持的计算平台

Kubernetes：使用 LangSmith Helm chart 在 Kubernetes 集群中运行 Agent Server。这是生产级部署的推荐选项。
Docker：在任何支持 Docker 的计算平台上运行（本地开发机、虚拟机、ECS 等）。这最适合开发或小规模工作负载。

前提条件

使用 LangGraph CLI 在本地测试你的应用。
使用 LangGraph CLI 构建 Docker 镜像（即 langgraph build）。
数据平面部署需要以下环境变量。
REDIS_URI：Redis 实例的连接信息。Redis 将作为发布-订阅代理，用于从后台运行中流式传输实时输出。REDIS_URI 的值必须是有效的 Redis 连接 URI。
共享 Redis 实例 多个自托管部署可以共享同一个 Redis 实例。例如，对于 Deployment A，可以将 REDIS_URI 设置为 redis://<hostname_1>:<port>/1；对于 Deployment B，可以将 REDIS_URI 设置为 redis://<hostname_1>:<port>/2。1 和 2 是同一实例中的不同数据库编号，而 <hostname_1> 是共享的。不同部署不能使用相同的数据库编号。
DATABASE_URI：Postgres 连接信息。Postgres 将用于存储 assistants、threads、runs，持久化线程状态和长期记忆，并以“恰好一次”语义管理后台任务队列的状态。DATABASE_URI 的值必须是有效的 Postgres 连接 URI。
共享 Postgres 实例 多个自托管部署可以共享同一个 Postgres 实例。例如，对于 Deployment A，可以将 DATABASE_URI 设置为 postgres://<user>:<password>@/<database_name_1>?host=<hostname_1>；对于 Deployment B，可以将 DATABASE_URI 设置为 postgres://<user>:<password>@/<database_name_2>?host=<hostname_1>。<database_name_1> 和 database_name_2 是同一实例中的不同数据库，而 <hostname_1> 是共享的。不同部署不能使用同一个数据库。

你也可以选择将检查点数据存储在 MongoDB 中，而不是 PostgreSQL 中。其他所有服务器数据仍然需要 PostgreSQL。详情请参阅配置检查点后端。
LANGSMITH_API_KEY：LangSmith API 密钥。
LANGGRAPH_CLOUD_LICENSE_KEY：LangSmith 许可证密钥。服务器启动时将使用此密钥进行一次身份验证。
LANGSMITH_ENDPOINT：要将跟踪信息发送到自托管 LangSmith 实例，请将 LANGSMITH_ENDPOINT 设置为自托管 LangSmith 实例的主机名。
你的网络需要能够向 https://beacon.langchain.com 出站连接。如果未在气隙模式下运行，则许可证验证和使用情况报告需要此连接。详情请参阅出站连接文档。

Kubernetes

使用此 Helm chart 将 Agent Server 部署到 Kubernetes 集群。这是生产环境独立服务器部署的推荐设置。 Helm chart（v0.2.6 及更高版本）支持使用捆绑实例（开发/测试）或外部部署（生产）进行 MongoDB 检查点存储。在 values 文件中设置 mongo.enabled: true。完整配置详情请参阅配置检查点后端。

Docker

此 docker 示例用于本地开发和测试。运行以下 docker 命令：

docker run \
    --env-file .env \
    -p 8123:8000 \
    -e REDIS_URI="foo" \
    -e DATABASE_URI="bar" \
    -e LANGSMITH_API_KEY="baz" \
    my-image

你需要将 my-image 替换为前提步骤中构建的镜像名称（通过 langgraph build 构建）。

并且，你应为 REDIS_URI、DATABASE_URI 和 LANGSMITH_API_KEY 提供适当的值。

如果你的应用需要其他环境变量，可以使用类似方式传入。

Docker Compose

此 Docker Compose 示例用于本地开发和测试。使用以下 Docker Compose 文件：

volumes:
    langgraph-data:
        driver: local
services:
    langgraph-redis:
        image: redis:6
        healthcheck:
            test: redis-cli ping
            interval: 5s
            timeout: 1s
            retries: 5
    langgraph-postgres:
        image: postgres:16
        ports:
            - "5432:5432"
        environment:
            POSTGRES_DB: postgres
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
        volumes:
            - langgraph-data:/var/lib/postgresql/data
        healthcheck:
            test: pg_isready -U postgres
            start_period: 10s
            timeout: 1s
            retries: 5
            interval: 5s
    langgraph-api:
        image: ${IMAGE_NAME}
        ports:
            - "8123:8000"
        depends_on:
            langgraph-redis:
                condition: service_healthy
            langgraph-postgres:
                condition: service_healthy
        env_file:
            - .env
        environment:
            REDIS_URI: redis://langgraph-redis:6379
            LANGSMITH_API_KEY: ${LANGSMITH_API_KEY}
            DATABASE_URI: postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable

在包含此文件的同一文件夹中运行 docker compose up。

使用 MongoDB 进行检查点存储

要将检查点存储在 MongoDB 而不是 PostgreSQL 中，请添加 MongoDB 服务并配置检查点后端。在 langgraph.json 中将后端设置为 "mongo"，或使用 LS_DEFAULT_CHECKPOINTER_BACKEND 环境变量。其他所有服务器数据仍然需要 PostgreSQL。

volumes:
    langgraph-data:
        driver: local
    langgraph-mongo-data:
        driver: local
services:
    langgraph-redis:
        image: redis:6
        healthcheck:
            test: redis-cli ping
            interval: 5s
            timeout: 1s
            retries: 5
    langgraph-postgres:
        image: postgres:16
        ports:
            - "5432:5432"
        environment:
            POSTGRES_DB: postgres
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
        volumes:
            - langgraph-data:/var/lib/postgresql/data
        healthcheck:
            test: pg_isready -U postgres
            start_period: 10s
            timeout: 1s
            retries: 5
            interval: 5s
    langgraph-mongo:
        image: mongo:7
        command: ["mongod", "--replSet", "rs0"]
        ports:
            - "27017:27017"
        volumes:
            - langgraph-mongo-data:/data/db
        healthcheck:
            test: mongosh --eval "try { rs.status().ok } catch(e) { rs.initiate({_id:'rs0',members:[{_id:0,host:'langgraph-mongo:27017'}]}).ok }" --quiet
            interval: 5s
            timeout: 10s
            retries: 10
            start_period: 10s
    langgraph-api:
        image: ${IMAGE_NAME}
        ports:
            - "8123:8000"
        depends_on:
            langgraph-redis:
                condition: service_healthy
            langgraph-postgres:
                condition: service_healthy
            langgraph-mongo:
                condition: service_healthy
        env_file:
            - .env
        environment:
            REDIS_URI: redis://langgraph-redis:6379
            LANGSMITH_API_KEY: ${LANGSMITH_API_KEY}
            DATABASE_URI: postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable
            LS_DEFAULT_CHECKPOINTER_BACKEND: mongo
            LS_MONGODB_URI: mongodb://langgraph-mongo:27017/langgraph?replicaSet=rs0

有关 MongoDB 配置选项的更多详情，请参阅配置检查点后端。

这将在端口 8123 上启动一个 Agent Server（如有需要，请更改 langgraph-api 中的端口映射）。测试应用是否运行正常：

curl --request GET --url 0.0.0.0:8123/ok

如果一切运行正常，你应该会看到类似以下的响应：

{"ok":true}

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

Edit this page on GitHub or file an issue.

Configure

Reference

概览

工作流

支持的计算平台

前提条件

Kubernetes

Docker

Docker Compose

​概览

​工作流

​支持的计算平台

​前提条件

​Kubernetes

​Docker

​Docker Compose

概览

工作流

支持的计算平台

前提条件

Kubernetes

Docker

Docker Compose