LangGraph 项目部署知识点总结
1. 部署概述
LangGraph 应用基于LangSmith Deployment构建，它建立在开源的 LangGraph 框架之上，用于开发有状态的应用程序。
- LangGraph 提供核心抽象和执行模型
- LangSmith 支持从开发到生产的整个生命周期，包括托管基础设施、可观察性、部署选项、助手和并发控制等。
整个流程将 Agent 应用打包、构建为Agent Server，并进行部署。
2. 自托管部署的核心组件
| 组件 | 角色 | 功能 |
|---|---|---|
| Agent Server | 核心运行时环境 | 提供标准化 API，处理执行、状态管理和持久化 |
| LangGraph CLI | 命令行工具 | 本地构建、打包图，并为部署做准备 |
| Studio | 集成开发环境 | 可视化、交互和调试图，可连接本地 Agent Server |
| Python SDK（自行了解） | 开发工具包 | 编程接口，与已部署的图和 Agent Server 交互 |
| RemoteGraph（自行了解） | 本地代理包装器 | 像调用本地图一样调用远程部署的图 |
| Control Plane（自行了解） | 管理和配置层 | 创建、更新和管理 Agent Server 部署的 UI/API |
| Data plane（自行了解） | 执行层 | 实际运行图的运行时层，包含 Agent Server 实例及后端（PostgreSQL、Redis 等） |
开发者使用 CLI 和 Studio 在本地开发测试图，然后部署为 Agent Server。应用程序通过 SDK、RemoteGraph 或 Agent Server 提供的 API 调用服务。
3. 本地启动与测试
3.1 修改langgraph.json配置文件
在配置文件中添加新增的图：
{"$schema":"https://langgra.ph/schema.json","dependencies":["."],"graphs":{"house_agent":"./src/agent/graph.py:graph","recommend_agent":"./src/agent/recommend.py:recommended_graph","reserve_agent":"./src/agent/reserve.py:reserve_graph","extend_agent":"./src/agent/extend.py:extend_graph"},"env":".env","image_distro":"wolfi"}3.2 启动本地开发服务器
langgraph dev- 该命令以内存模式启动 Agent Server，适合开发和测试。
- 启动后会提供 API 和 Studio UI 的访问地址。
3.3 测试 Graph
通过 Studio 或 API 发送测试问题，例如：
在西安，我的预算是1000-2000一个月，帮我推荐4套房子。要求在雁塔区。 我想在北京海淀租个1室1厅1卫，预算5000以内，最好近地铁。 帮我推荐几套房子 # 会触发信息收集中断4. LangSmith 部署方式
Agent Server 可根据基础设施采用不同部署方式：
| 方式 | 说明 |
|---|---|
| 云部署（自行研究） | 完全托管模式，LangChain 负责基础设施、更新、扩展；从 GitHub 部署；自动 CI/CD；全面访问 LangSmith UI |
| 带 Control Plane 的混合/自托管（自行研究） | 本地构建 Docker 镜像，推送到注册表，通过 LangSmith UI 部署到 Kubernetes |
| 独立服务器（本文重点） | 直接部署 Agent Server，不通过 Control Plane 和 LangSmith UI，作为独立服务运行 |
5. 独立部署 Agent Server（详细步骤）
5.1 工作流程
- 使用 CLI 或 Studio 在本地定义和测试图
- 将应用服务打包为Docker 镜像
- 将 Agent Server 部署到平台：
- Kubernetes：使用 LangSmith Helm 图表（生产推荐）
- Docker：在本地开发机、VM、ECS 等运行（适合开发或小规模）
5.2 部署前准备工作
Agent Server 部署时需要以下组件：
- PostgreSQL：作为数据库，存储所有持久化数据（检查点、助手等）
- Redis：作为任务队列，用于发布/订阅连接，实现事件实时流传输
若使用 LangSmith 云部署，这些组件自动管理；独立部署需自行搭建。
启动 Redis 容器（示例）
sudodockerrun-d\--nameredis-6380\-p6380:6379\-vredis-data:/data\redis:7-alpine\redis-server--appendonlyyes--requirepass"your_password"启动 PostgreSQL 容器（示例）
dockerpull postgres:latestdockerrun--namepostgres-sql-ePOSTGRES_PASSWORD=bit-p5432:5432-dpostgres配置.env文件
# DOCKER 必须 DATABASE_URI=postgresql://postgres:bit@192.168.100.233:5432/postgres REDIS_URI=redis://:bite%40123@192.168.100.233:63805.3 部署姿势 1：构建 Docker 镜像并运行
使用langgraph build命令构建镜像。
sudolanggraph build-thouse-agent-image查看镜像：
sudodockerimage list# REPOSITORY TAG IMAGE ID CREATED SIZE# house-agent-image latest 7884c6e8d937 39 minutes ago 626MB运行容器（指定.env文件，映射端口）：
sudodockerrun --env-file .env-p8001:8000 house-agent-image# Starting API server- 默认端口为 8000
- 必须设置
REDIS_URI和DATABASE_URI
5.4 部署姿势 2：生成 Dockerfile 并组合 Docker Compose
生成 Dockerfile
sudolanggraph dockerfile-clanggraph.json Dockerfile该命令将
langgraph.json中的配置转换成 Dockerfile 命令。每次更新langgraph.json后需重新运行。
编写 Docker Compose 文件
方案一：仅包含服务（使用已有的 Redis 和 PostgreSQL）
volumes:langgraph-data:driver:localservices:langgraph-api:build:.ports:-"8002:8000"env_file:-.env方案二：完整包含 Redis + PostgreSQL + Agent Server
volumes:langgraph-data:driver:localservices:langgraph-redis:image:redis:6healthcheck:test:redis-cli pinginterval:5stimeout:1sretries:5langgraph-postgres:image:postgres:16ports:-"5432:5432"environment:POSTGRES_DB:postgresPOSTGRES_USER:postgresPOSTGRES_PASSWORD:postgresvolumes:-langgraph-data:/var/lib/postgresql/datahealthcheck:test:pg_isready-U postgresstart_period:10stimeout:1sretries:5interval:5slanggraph-api:image:${IMAGE_NAME}# 需提前构建镜像ports:-"8123:8000"depends_on:langgraph-redis:condition:service_healthylanggraph-postgres:condition:service_healthyenv_file:-.envenvironment:REDIS_URI:redis://langgraph-redis:6379LANGSMITH_API_KEY:${LANGSMITH_API_KEY}DATABASE_URI:postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable启动服务
sudodockercompose up# 源代码更新后可重新构建sudodockercompose up--build服务名5.5 部署姿势 3：使用langgraph up命令
sudolanggraph up-p8000- 该命令依赖 Docker，会构建并启动 LangGraph API 服务
- 查看镜像：
sudodockerimage list# REPOSITORY TAG IMAGE ID CREATED SIZE# house-langgraph-api latest 90ae2bcbab92 39 minutes ago 626MB可能遇到的问题
- 若
.env中DATABASE_URI指向与之前本地使用的 PostgreSQL 同一库，可能导致数据库迁移失败。
原因：checkpoints表的thread_id为text类型，而thread表的thread_id为uuid类型，类型不一致无法建立外键关系。
解决方案：新建一个数据库，实现环境隔离。
6. 配置文件关键说明
6.1langgraph.json主要字段（总结）
| 字段 | 必需 | 描述 |
|---|---|---|
$schema | 是 | Schema 验证 URL |
dependencies | 是 | 依赖项（如.表示本地包，或路径、包名） |
graphs | 是 | 图定义映射，格式{"图ID": "文件路径:导出对象"} |
auth | 否 | 自定义认证配置 |
base_image | 否 | 基础 Docker 镜像 |
image_distro | 否 | Linux 发行版（debian/wolfi/bookworm/bullseye） |
env | 否 | 环境变量（文件路径或键值对） |
store | 否 | 存储配置（语义搜索索引、TTL） |
checkpointer | 否 | 检查点配置（TTL、序列化） |
http | 否 | HTTP 服务器配置（CORS、中间件等） |
webhooks | 否 | 出站 Webhook 配置 |
python_version | 否 | Python 版本（3.11/3.12/3.13） |
node_version | 否 | Node.js 版本 |
pip_installer | 否 | 包安装器（auto/pip/uv） |
api_version | 否 | LangGraph API 服务器语义版本 |
6.2.env环境变量（示例）
LANGSMITH_PROJECT=new-agent2 LANGSMITH_API_KEY=lsv2... LANGSMITH_TRACING=true OPENAI_API_KEY=... DATABASE_URI=postgresql://... REDIS_URI=redis://...7. 项目扩展（自行研究，简要提及）
PDF 最后列举了可进一步探索的方向：
- 主图中进行消息管理：在适当位置进行历史会话修剪、总结，避免消息过多导致 LLM 调用错误。
- 结构化输出用户期望信息：与数据库表字段映射，生成更准确的 SQL。
- 执行 SQL 前加入中断：人工审核 SQL 准确性。
- 自定义流式输出：前端展示更详细、流式的执行过程。
8. 总结
- LangGraph 项目部署依赖Agent Server+PostgreSQL+Redis。
- 本地开发使用
langgraph dev快速测试。 - 独立部署可通过构建 Docker 镜像并运行，或使用
dockerfile+docker compose，或langgraph up命令。 - 必须正确配置
langgraph.json和.env，注意数据库迁移时的类型兼容问题。 - 部署后可通过 API 或 Studio 与 Agent Server 交互，实现完整的智能应用生命周期管理。