自托管独立服务器 - 以编程方式使用文档

本指南介绍如何直接部署独立 Agent Server ，无需控制平面。您可以独立部署服务器，仍可将追踪发送至 LangSmith（self-hosted or 云端）进行可观测性和评估。独立服务器已就绪生产，提供运行代理的最轻量级选项。

概述

您管理一个简化的数据平面，由 Agent Server 及其所需的后备服务（PostgreSQL、Redis 等）组成：

Component	Responsibilities	Where it runs	Who manages it
控制平面	n/a	n/a	n/a
数据平面	<ul><li>Agent Server</li><li>Postgres, Redis, etc.</li></ul>	Your infrastructure	You

This option gives you full control over scaling, deployment, and CI/CD pipelines, while still allowing optional integration with LangSmith for tracing and evaluation.

工作流

使用 langgraph-cli or Studio.
在本地定义和测试您的图。
将 Agent Server 部署到您选择的计算平台（Kubernetes、Docker、VM）。
（可选）配置 LangSmith API 密钥和端点，以便服务器将跟踪和评估报告回 LangSmith（自托管或 SaaS）。

支持的计算平台

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

前提条件

1. 使用 LangGraph CLI to 在本地测试您的应用程序. 2. 使用 LangGraph CLI 构建 Docker 镜像（即 langgraph build). 3. 数据平面部署需要以下环境变量。 1. REDIS_URI：Redis 实例的连接详情。Redis 将用作发布-订阅代理，以支持从后台运行流式传输实时输出。该值的 REDIS_URI 必须是有效的 Redis 连接 URI. <aside class="callout"><strong>提示</strong>

共享 Redis 实例 多个自托管部署可以共享同一个 Redis 实例。例如，对于 Deployment A, REDIS_URI 可设置为 redis://<hostname_1>:<port>/1 而对于 Deployment B, REDIS_URI 可设置为 redis://<hostname_1>:<port>/2.

1 和 2 是同一实例中的不同数据库编号，但 <hostname_1> 是共享的。 **同一数据库编号不能用于独立的部署**. </aside>

2. DATABASE_URI：Postgres 连接详情。Postgres 将用于存储助手、线程、运行状态，持久化线程状态和长期记忆，并使用'恰好一次'语义管理后台任务队列的状态。该值的 DATABASE_URI 必须是有效的 Postgres 连接 URI. <aside class="callout"><strong>提示</strong>

共享 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> 是共享的。 **同一数据库不能用于独立的部署**. </aside>

LANGSMITH_API_KEY：LangSmith API 密钥。
LANGGRAPH_CLOUD_LICENSE_KEY：LangSmith 许可证密钥。这将在服务器启动时使用一次进行身份验证。
LANGSMITH_ENDPOINT：要将追踪发送到自托管 LangSmith 实例，请设置 LANGSMITH_ENDPOINT 为自托管 LangSmith 实例的主机名。
从您的网络出口到 https://beacon.langchain.com 。如果不以气隙模式运行，则这是许可证验证和使用报告所必需的。请参阅出口文档了解更多详情。

<a id="helm"></a> ## Kubernetes

使用此 Helm 图表将 Agent Server 部署到 Kubernetes 集群。这是生产环境独立服务器部署的推荐配置。

The Helm chart (v0.2.6+) supports MongoDB checkpointing with a bundled instance (dev/testing) or an external deployment (production). Set mongo.enabled: true 在您的 values 文件中。请参阅配置检查点后端获取完整配置详情。

Docker

此 docker 示例适用于本地开发和测试。

运行以下 docker command:

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

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 在与此文件相同的文件夹中。

With MongoDB checkpointing

要将检查点存储在 MongoDB 而不是 PostgreSQL 中，请添加 MongoDB 服务并配置检查点后端。将后端设置为 "mongo" 在您的 langgraph.json 或使用 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 （如需更改端口映射，请在 langgraph-api 中进行修改）。测试应用程序是否正常运行：

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

假设一切正常运行，你应该会看到类似这样的响应：

{"ok":true}