自托管独立服务器

使用 Docker、Docker Compose 或 Kubernetes 部署独立的 Agent Servers，无需 LangSmith 控制平面。

本指南展示如何直接部署独立的 Agent Servers，而无需控制平面。你可以独立部署服务器，同时仍将追踪发送到 LangSmith（自托管或 Cloud）以进行可观测性和评估。独立服务器已可用于生产，并提供运行 agent 的最轻量选项。

概述

你管理一个简化的

数据平面

，它由 Agent Servers 及其所需的后端服务（PostgreSQL、Redis 等）组成：

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

此选项让你完全控制扩缩容、部署和 CI/CD 流水线，同时仍可选择与 LangSmith 集成以进行追踪和评估。

WARNING

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

工作流

1. 使用 langgraph-cli 或 Studio 在本地定义并测试你的图。
2. 将 agent 打包为 Docker 镜像。
3. 将 Agent Server 部署到你选择的计算平台（Kubernetes、Docker、VM）。
4. （可选）配置 LangSmith API 密钥和端点，使服务器将追踪和评估报告回 LangSmith（自托管或 SaaS）。

支持的计算平台

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

WARNING

对于生产部署，请使用 Kubernetes 和受维护的 LangSmith Helm chart。这是 LangChain 定期测试的生产路径。LangChain 不会定期测试其他编排器。

非 Kubernetes 部署存在已知缺口，你必须自行实现和维护。随着 Helm chart 的演进，这些部署可能进一步偏离经过测试的生产路径：

• 独立的队列自动扩缩容：为突发、写入密集型工作负载配置扩缩容策略和队列指标。
• 优雅的运行排空：配置关闭排空和足够的终止窗口，以便在部署和缩容事件期间完成进行中的运行。
• 拆分模式接线：预配并连接单独的 API 和队列服务。当 queue.enabled 为 true 时，Helm chart 会处理此事项。
• 参考扩缩容配置：将 Agent Server 扩缩容设置（包括 api.replicas、queue.replicas、numberOfJobsPerWorker 和只读副本）转换为编排器的任务定义和扩缩容策略。
• 版本升级和支持：维护任务定义并应用版本更新。LangChain 会测试并发布受支持的 Helm chart 版本更新。

前置条件

1. 使用 LangGraph CLI在本地测试你的应用。
2. 使用 LangGraph CLI 构建 Docker 镜像（即 langgraph build）。
3. 数据平面部署需要以下环境变量。
4. REDIS_URI：Redis 实例的连接详情。Redis 将用作 pub-sub 代理，以启用后台运行的实时输出流式传输。REDIS_URI 的值必须是有效的 Redis 连接 URI。

NOTE

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

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

5. DATABASE_URI：Postgres 连接详情。Postgres 将用于存储助手、线程、运行，持久化线程状态和长期记忆，并以“恰好一次”语义管理后台任务队列的状态。DATABASE_URI 的值必须是有效的 Postgres 连接 URI。

NOTE

共享 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>。同一数据库不能用于不同的部署。

TIP

你可以选择将检查点数据存储在 MongoDB 而不是 PostgreSQL 中。所有其他服务器数据仍需要 PostgreSQL。有关详情，请参阅配置检查点后端。

6. LANGSMITH_API_KEY：LangSmith API 密钥。
7. LANGGRAPH_CLOUD_LICENSE_KEY：LangSmith 许可证密钥。这将在服务器启动时进行一次性身份验证。
8. LANGSMITH_ENDPOINT：要将追踪发送到自托管 LangSmith 实例，请将 LANGSMITH_ENDPOINT 设置为该自托管 LangSmith 实例的主机名。不要在 URL 末尾添加斜杠，因为这可能导致身份验证错误。
9. 从你的网络出站访问 https://beacon.langchain.com。如果未在气隙模式下运行，许可证验证和使用情况报告需要此访问。有关更多详细信息，请参阅出站文档。

NOTE

自 0.14.0 起，Agent Server 服务默认同时监听 IPv4 和 IPv6。双栈集群无需额外配置。要仅监听单一地址族，请将 LANGGRAPH_SERVER_HOST 设置为 0.0.0.0（仅 IPv4）或 ::（仅 IPv6）。请参阅自托管 Agent Server 环境变量。

Kubernetes

使用此 Helm chart 将 Agent Server 部署到 Kubernetes 集群。这是生产独立服务器部署的推荐设置。

Helm chart（v0.2.6+）支持使用捆绑实例（开发/测试）或外部部署（生产）的 MongoDB 检查点。在 values 文件中设置 mongo.enabled: true。有关完整配置详情，请参阅配置检查点后端。

Docker

WARNING

此 Docker 示例适用于本地开发和测试。生产环境请使用 Kubernetes 部署。

运行以下 docker 命令：

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

NOTE

• 你需要将 my-image 替换为在前置步骤中构建的镜像名称（来自 langgraph build）

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

• 如果你的应用需要额外的环境变量，可以用类似方式传入。

Docker Compose

WARNING

此 Docker Compose 示例适用于本地开发和测试。生产环境请使用 Kubernetes 部署。

使用以下 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}

---