12. 生产部署策略 - Langgraph 速读教程

当代码在本地运行无误，图结构在 Studio 中调试通过，接下来的问题自然指向如何将这个状态化的智能体系统推向生产环境。LangGraph 的设计初衷就是解决长时运行、有状态应用的部署难题，但生产部署从来不是简单地把代码扔到服务器上那么简单。我们需要在控制平面、数据平面、网络隔离、许可证管理之间做出权衡，本章将梳理这些决策点。

生产环境部署选项

LangGraph Platform 提供了四种部署模型，每种模型在控制权与便利性之间占据不同位置。选择哪种模型，取决于数据驻留要求、团队运维能力以及预算约束。

部署模式	控制平面位置	数据平面位置	CI/CD 管理	适用场景
Cloud SaaS	LangChain 云端	LangChain 云端	平台托管	快速验证、无特殊合规要求
自托管数据平面	LangChain 云端	你的基础设施	自行管理	数据主权要求、需控制计算资源
自托管控制平面	你的基础设施	你的基础设施	自行管理	完全隔离、强合规要求
独立容器	无	你的基础设施	自行管理	边缘部署、特殊网络环境

Cloud SaaS 是最省心的选择。连接 GitHub 仓库，在 LangSmith 界面点击部署，平台会自动处理构建、数据库配置、扩缩容。开发环境默认使用 1 CPU / 1 GB 内存，生产环境可支撑每秒 500 请求，存储自动备份。但便利意味着让步：所有数据存储在 LangChain 的 PostgreSQL 中，无法自定义数据库版本，也无法接入内部监控系统。

自托管数据平面是折中方案。控制平面仍由 LangChain 管理，通过 UI 或 API 创建部署，但实际运行的 LangGraph Server、PostgreSQL、Redis 都部署在你的 Kubernetes 集群或 ECS 服务中。这种模式适合有数据驻留要求但不想维护控制平面的团队。需要向控制平面开放对 https://api.host.langchain.com 和 https://api.smith.langchain.com 的出站访问，以便监听部署变更。

自托管控制平面是最高隔离级别。整个平台，包括 UI、API、数据库都运行在你的 Kubernetes 中。这需要 Enterprise 许可证，并且必须先部署自托管 LangSmith。好处是彻底掌控：可以修改 Helm Chart 中的资源模板，接入内部 Prometheus，甚至修改控制平面代码。代价是运维复杂度完全由自己承担。

独立容器模式最灵活，没有控制平面。用 langgraph build 构建 Docker 镜像后，可以部署到任何支持容器的环境：Kubernetes、ECS、甚至边缘设备。这种模式适合已有成熟部署流水线的团队，或者需要部署到隔离网络的场景。但需要自己管理数据库、Redis、许可证验证等所有基础设施。

自托管控制平面搭建

选择自托管控制平面意味着接受一整套 Kubernetes 运维责任。开始前，请确认已满足以下硬性要求：

现有 Kubernetes 集群，版本 1.25+
已部署自托管 LangSmith，并配置好 Ingress
集群可访问你的 Docker 镜像仓库
安装 KEDA 用于自动扩缩容
集群有动态 PV 供应器或预创建 PV
可出站访问 https://beacon.langchain.com（用于许可证验证）

安装 KEDA 的命令如下：

helm repo add kedacore https://kedacore.github.io/charts
helm install keda kedacore/keda --namespace keda --create-namespace

接下来，在 LangSmith 的 Helm Chart 中启用 langgraphPlatform 选项。编辑 langsmith_config.yaml：

config:
  langgraphPlatform:
    enabled: true
    langgraphPlatformLicenseKey: "YOUR_LANGGRAPH_PLATFORM_LICENSE_KEY"

同时需要配置两个额外的镜像地址，在 values.yaml 中指定：

hostBackendImage:
  repository: "docker.io/langchain/hosted-langserve-backend"
  pullPolicy: IfNotPresent
operatorImage:
  repository: "docker.io/langchain/langgraph-operator"
  pullPolicy: IfNotPresent

升级 LangSmith 后，控制平面会创建四个核心组件：

listener：监听控制平面变更，创建或更新 CRD
LangGraphPlatform CRD：定义部署规范
operator：处理 CRD 变更，管理实际资源
host-backend：控制平面的 API 服务

部署完成后，在 LangSmith UI 中会出现 LangGraph Platform 管理界面，可以像使用 Cloud SaaS 一样创建部署。区别在于，所有资源都运行在你的集群中，数据库也使用你提供的 PostgreSQL 实例。

自托管数据平面配置

自托管数据平面的架构相对简单：控制平面由 LangChain 管理，数据平面由你的基础设施承载。这种模式适合需要数据主权但不想维护控制平面的场景。

首先，确保集群满足前提条件：

Kubernetes 集群，版本 1.25+
安装 KEDA
配置 Ingress 控制器
集群有充足资源，建议启用 Cluster Autoscaler
可出站访问 https://api.host.langchain.com 和 https://api.smith.langchain.com

然后，向 LangChain 提供你的组织 ID，申请启用自托管数据平面功能。获得许可后，添加 Helm 仓库并安装数据平面：

helm repo add langchain https://langchain-ai.github.io/helm/
helm repo update
helm upgrade -i langgraph-dataplane langchain/langgraph-dataplane --values langgraph-dataplane-values.yaml

langgraph-dataplane-values.yaml 需要配置以下关键信息：

config:
  langsmithApiKey: ""  # 你的 Workspace API Key
  langsmithWorkspaceId: ""  # Workspace ID
  hostBackendUrl: "https://api.host.langchain.com"  # 欧盟用户需改为 eu.api.host.langchain.com
  smithBackendUrl: "https://api.smith.langchain.com"  # 欧盟用户需改为 eu.api.smith.langchain.com

安装成功后，会看到两个服务启动：

NAME                                          READY   STATUS              RESTARTS   AGE
langgraph-dataplane-listener-7fccd788-wn2dx   0/1     Running             0          9s
langgraph-dataplane-redis-0                   0/1     ContainerCreating   0          9s

listener 会持续轮询控制平面，当在 UI 中创建部署时，它会自动在集群中创建对应的 LangGraph Server、PostgreSQL 和 Redis。数据库和缓存完全隔离，存储在你的 PV 中。

独立 Docker 容器部署

如果不需要控制平面的编排能力，或者想将 LangGraph Server 嵌入现有系统，独立容器是最直接的选择。这种模式不依赖 Kubernetes，可以用 Docker Compose 甚至单机 Docker 运行。

前置准备

首先用 langgraph build 构建应用镜像：

langgraph build -t my-langgraph-app:latest

构建完成后，需要准备三个环境变量：

REDIS_URI：Redis 连接串，格式为 redis://hostname:port/db。多个部署可共享同一 Redis 实例，但数据库编号必须不同
DATABASE_URI：PostgreSQL 连接串，格式为 postgres://user:password@/dbname?host=hostname。多个部署可共享同一 PostgreSQL 实例，但数据库名必须不同
LANGSMITH_API_KEY：用于发送追踪数据到 LangSmith（可选）

Docker 运行

最简单的启动方式：

docker run \
  --env-file .env \
  -p 8123:8000 \
  -e REDIS_URI="redis://redis-host:6379/0" \
  -e DATABASE_URI="postgres://user:pass@/mydb?host=pg-host" \
  -e LANGSMITH_API_KEY="lsv2..." \
  my-langgraph-app:latest

容器启动后，访问 http://localhost:8123/ok 验证健康状态，应返回 {"ok":true}。

Docker Compose 部署

生产环境建议使用 Docker Compose 管理多服务依赖。以下配置同时启动 Redis、PostgreSQL 和应用：

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:
      - "5433: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
      POSTGRES_URI: postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable

将上述内容保存为 docker-compose.yml，然后执行：

export IMAGE_NAME=my-langgraph-app:latest
docker compose up

Compose 会自动处理服务依赖和健康检查，确保数据库和缓存就绪后才启动应用。

依赖与环境变量管理

无论选择哪种部署模式，正确管理依赖和环境变量都是成功的基础。LangGraph 使用 langgraph.json 作为核心配置文件，它决定了构建和运行时的行为。

项目结构规范

典型的 Python 项目结构如下：

my-app/
├── my_agent/                      # 所有业务代码
│   ├── utils/                     # 工具模块
│   │   ├── __init__.py
│   │   ├── tools.py              # 工具函数
│   │   ├── nodes.py              # 节点实现
│   │   └── state.py              # 状态定义
│   ├── __init__.py
│   └── agent.py                  # 图编译入口
├── .env                          # 环境变量
├── requirements.txt              # 依赖列表
└── langgraph.json               # LangGraph 配置

JavaScript 项目类似，只是将 .py 文件换成 .ts 或 .js，requirements.txt 换成 package.json。

依赖声明方式

LangGraph 支持三种依赖声明方式，按优先级排序：

pyproject.toml：现代 Python 项目的标准，支持版本约束和构建配置
requirements.txt：简单直接，每行一个包名
setup.py：传统方式，功能强大但较为复杂

如果项目根目录没有这些文件，可以在 langgraph.json 中直接指定依赖数组。

推荐的 requirements.txt 示例：

langgraph>=0.3.27
langgraph-sdk>=0.1.66
langgraph-checkpoint>=2.0.23
langchain-core>=0.2.38
langsmith>=0.1.63
orjson>=3.9.7,<3.10.17
httpx>=0.25.0
tenacity>=8.0.0
uvicorn>=0.26.0
sse-starlette>=2.1.0,<2.2.0
uvloop>=0.18.0
httptools>=0.5.0
jsonschema-rs>=0.20.0
structlog>=24.1.0
cloudpickle>=3.0.0

这些依赖会被自动安装，版本范围经过兼容性测试。自定义依赖（如 langchain_openai、tavily-python）可以追加到文件末尾。

langgraph.json 配置详解

langgraph.json 是部署的核心，它告诉平台如何构建和运行应用。一个完整配置示例如下：

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./my_agent/agent.py:graph"
  },
  "env": ".env",
  "python_version": "3.11",
  "pip_config_file": "./pip.conf",
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y libpq-dev"
  ]
}

各字段含义：

dependencies：依赖列表。. 表示当前目录下的 Python 包，也可以指定相对路径或 PyPI 包名
graphs：图定义映射。键是图 ID（API 调用时使用），值是模块路径和变量名，格式为 ./path/to/file.py:variable_name
env：环境变量文件路径，或内联对象如 {"KEY": "value"}
python_version：指定 Python 3.11、3.12 或 3.13，默认 3.11
pip_config_file：pip 配置文件路径，用于指定私有仓库
dockerfile_lines：插入到 Dockerfile 的自定义命令，适合安装系统依赖

对于 JavaScript 项目，配置类似，只需添加 "node_version": 20 并确保 package.json 存在。

环境变量管理

环境变量分为两类：非敏感配置和敏感密钥。非敏感变量可以直接写在 langgraph.json 中，但敏感信息必须通过 .env 文件或部署界面设置。

.env 文件示例：

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
TAVILY_API_KEY=tvly-...
LANGSMITH_API_KEY=lsv2...
LANGSMITH_TRACING=true

部署到 Cloud SaaS 时，在创建部署的界面中，将敏感变量添加到 "Secrets" 区域，这些值会被加密存储，不会出现在日志或环境变量明文列表中。

自托管部署时，建议通过 Kubernetes Secret 或 Docker Compose 的 env_file 机制注入环境变量，避免将密钥硬编码在镜像中。

高级配置技巧

对于复杂项目，可能需要自定义 Dockerfile 或添加系统依赖。dockerfile_lines 字段支持任意 Dockerfile 指令：

{
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y \\"",
    "    libpq-dev \\"",
    "    gcc \\"",
    "    && rm -rf /var/lib/apt/lists/*",
    "COPY ./custom-ca.crt /usr/local/share/ca-certificates/",
    "RUN update-ca-certificates"
  ]
}

这些行会被插入到依赖安装之后、代码复制之前，适合安装编译工具或企业根证书。

如果项目使用私有 PyPI 仓库，创建 pip.conf：

[global]
index-url = https://pypi.org/simple
extra-index-url = https://my-private-repo/simple
trusted-host = my-private-repo

然后在 langgraph.json 中引用：

{
  "pip_config_file": "./pip.conf"
}

这样构建时会自动使用私有源，无需在 Dockerfile 中硬编码认证信息。

生产部署的本质是在控制与便利之间找到平衡点。Cloud SaaS 适合快速迭代，自托管满足合规要求，独立容器提供最大灵活性。无论选择哪种模式，清晰的依赖管理和安全的密钥处理都是不可妥协的基础。下一章将讨论如何在这些部署之上构建认证与安全防护体系，确保智能体服务既能被合法调用，又能抵御恶意访问。