第 25 章 部署：LangGraph Server / Cloud / 自托管 FastAPI
25.1 部署形态与 langgraph.json 配置
LangGraph 1.2.x 提供四种部署形态，选型对比如表：
| 形态 | 适用场景 | 运维成本 | 流式/中断 | Studio 支持 |
|---|---|---|---|---|
| LangGraph CLI（langgraph dev） | 本地开发 | 无 | 原生支持 | 是 |
| LangGraph Server（Docker 镜像 langchain/langgraph-api） | 生产自托管 | 中 | 原生支持 | 是（连接远端） |
| LangGraph Cloud | SaaS 托管 | 低 | 原生支持 | 是 |
| 自建 FastAPI | 深度定制/混合架构 | 高 | 需自行实现 SSE 协议 | 否 |
LangGraph Server 与 CLI 都依赖 langgraph.json 配置文件声明图、环境、依赖与存储后端：
{
"dependencies": ["."],
"graphs": {
"agent": "./src/agent.py:graph",
"rag_agent": "./src/rag.py:graph"
},
"env": ".env",
"store": {
"backend": "postgres",
"postgres_url": "postgresql://user:pass@db:5432/langgraph"
},
"checkpointer": {
"backend": "postgres",
"postgres_url": "postgresql://user:pass@db:5432/langgraph"
}
}字段说明：graphs 将图名映射到 Python 模块路径（格式 path:variable）；env 指向环境变量文件；dependencies 声明 pip 依赖路径；store/checkpointer 指定语义记忆与 checkpoint 的持久化后端，生产推荐 Postgres。
25.2 Server REST 协议与 Assistants
LangGraph Server 暴露标准 REST + SSE 协议，核心端点：
POST /threads创建线程，返回thread_id；POST /threads/{tid}/runs/wait同步等待执行完成，返回最终 state；POST /threads/{tid}/runs/streamSSE 流式执行，事件类型包括metadata、updates、messages/partial、interrupt、error、end；POST /threads/{tid}/runs/cron创建定时任务；GET /threads/{tid}/state查询当前状态；POST /threads/{tid}/history获取历史 checkpoint 列表；POST /threads/{tid}/runs/{rid}/cancel取消运行；POST /threads/{tid}/interrupt主动触发中断；- 恢复执行通过
runs/wait或runs/stream请求体携带Command(resume=...)完成。
Assistants 是服务端版本化的"图配置"概念：同一个图可以基于不同 model、prompt、tools 注册多个 assistant，客户端调用时指定 assistant_id 即可运行对应配置，便于灰度与 A/B。
LangGraph Studio 本地开发通过 langgraph dev 启动 API Server + Studio UI，默认 http://127.0.0.1:2024，提供图可视化、单步调试、状态查看、interrupt 注入、历史回放能力。
Docker 部署：langgraph up 根据 langgraph.json 生成 docker-compose.yml，默认包含 API Server + Postgres；生产环境需替换为外部托管 Postgres，并根据需要增加 Redis 作为任务队列后端。
LangGraph Cloud 提供托管 SaaS，完成注册后通过 GitHub 集成部署，支持 API Key/OAuth 鉴权、Cron 任务、Webhook、Threads 持久化；按执行时间与调用次数计费，适合不想自建基础设施的团队。
25.3 自建 FastAPI 与生产配置
自建 FastAPI 路线适合需要把 Agent 嵌入现有后端、复用已有鉴权/限流/中间件栈的团队，需自行实现 SSE 协议与 interrupt 恢复。骨架如下：
# pip install fastapi uvicorn langgraph sse-starlette
import asyncio
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from my_agent import graph # 已编译的 LangGraph 图
from langgraph.types import Command
app = FastAPI()
thread_states = {} # 生产应使用 Postgres checkpointer
class RunReq(BaseModel):
thread_id: str
message: str
resume: str | None = None
@app.post("/invoke")
async def invoke(req: RunReq):
cfg = {"configurable": {"thread_id": req.thread_id}}
if req.resume is not None:
return await graph.ainvoke(Command(resume=req.resume), cfg)
return await graph.ainvoke({"messages": [("user", req.message)]}, cfg)
@app.get("/stream")
async def stream(thread_id: str, message: str):
async def gen():
cfg = {"configurable": {"thread_id": thread_id}}
async for evt in graph.astream({"messages":[("user",message)]}, cfg, stream_mode="updates"):
yield f"data: {evt}\n\n"
yield "data: [DONE]\n\n"
return StreamingResponse(gen(), media_type="text/event-stream")鉴权使用 API Key 或 OAuth2/JWT（fastapi-security 栈）；限流用 slowapi 或 starlette-ratelimit；横向扩展通过无状态 API 节点 + 共享 Postgres Checkpointer + 负载均衡，长任务拆分为后台 worker 消费队列。Nginx 反代需关闭缓冲以支持 SSE：
location / {
proxy_pass http://langgraph_api:8000;
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_read_timeout 3600s;
add_header X-Accel-Buffering no;
}健康检查通过 /ok 端点；监控队列深度、checkpointer 写入延迟、SSE 连接数、每线程平均恢复时长。Docker Compose 示例：
# docker-compose.yml
version: "3.9"
services:
api:
image: langchain/langgraph-api:1.2
ports: ["8000:8000"]
env_file: .env
depends_on: [db]
volumes: ["./:/app"]
db:
image: postgres:16
environment:
POSTGRES_USER: lg; POSTGRES_PASSWORD: lg; POSTGRES_DB: langgraph
volumes: ["pgdata:/var/lib/postgresql/data"]
ports: ["5432:5432"]
volumes:
pgdata: {}本章小结：langgraph.json 是 Server/CLI/Cloud 通用的部署描述文件；REST+SSE 协议标准化了线程、运行、状态、中断、恢复；自建 FastAPI 灵活但需自行处理流式与中断协议；生产部署必须配合共享 Checkpointer、反代调优、鉴权限流与健康检查。
常见错误：在 async FastAPI 路由里调用同步 graph.invoke() 阻塞事件循环，吞吐量骤降；Nginx 默认缓冲把 SSE 攒包发送，前端长时间"无响应"；langgraph.json 图路径写错（相对路径/模块名不一致）导致 Server 启动后返回空；多 uvicorn worker 使用 MemorySaver 导致同 thread_id 在不同 worker 上状态不一致；未配置 CORS 前端跨域被拦截。
生产建议：生产优先选择 Docker 版 LangGraph Server + 外部 Postgres，自建 FastAPI 仅在必须深度定制时使用；API Key/JWT 鉴权 + 按 tenant 限流；SSE 长连接独立连接池并配置 read timeout 不小于 30 分钟；checkpointer 与 store 使用独立数据库实例并开启备份；健康检查区分 liveness（进程存活）与 readiness（DB 可用、模型 API 可用）；发布前用 langgraph dev 在本地 Studio 完整演练 interrupt/resume 路径。