开源Agent框架LangGraph生产环境部署踩坑

开源Agent框架 LangGraph 在生产环境部署时，最容易踩的坑不是图逻辑写不对，而是运行时环境、依赖版本、状态存储和启动方式这些基础设施问题。
本文整理了一次从零开始部署 LangGraph 服务的实操记录，包含准备条件、Docker 化步骤、高频报错和验证方法，照做即可跑通基础架构。

部署前要准备什么

建议使用 Linux 服务器，提前装好 Docker 和 Docker Compose。
如果是裸机环境，至少要准备 Python 3.11 及以上版本，因为低版本 Python 会导致 langgraph 部分语法兼容失败。

需要确认以下信息：

• 模型 API 地址和密钥，例如 OpenAI 兼容接口的 base_url 与 api_key
• 服务器能访问外网，拉取依赖和镜像需要网络通畅
• 规划好服务端口，默认可以使用 8000

先用官方 CLI 跑通本地流程

不要直接写一堆生产配置，先用最小 Demo 验证 LangGraph 本身能工作。
在项目目录下安装官方 CLI：

pip install langgraph-cli
langgraph new demo-agent
cd demo-agent
cp .env.example .env

编辑 .env，把模型 Key 填好。
然后启动开发服务：

langgraph dev

看到 Assistant is ready 类似输出，说明基础链路没问题。
这里如果报 ModuleNotFoundError: No module named 'langgraph'，通常是当前 Python 环境和安装 CLI 的环境不一致。
建议用 python -m pip 强制安装，或创建独立虚拟环境。

Docker 化部署的配置要点

Demo 跑通后，将它迁移到 Docker 部署。
项目根目录创建 Dockerfile：

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt \
    && pip install langgraph-cli
COPY . .
EXPOSE 8000
CMD ["langgraph", "dev", "--host", "0.0.0.0", "--port", "8000"]

这里不要用默认的 --reload 参数，生产环境开启自动重载会频繁重启进程，严重时导致请求中断。

再创建 docker-compose.yml：

services:
  langgraph-agent:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped

执行：

docker compose up -d --build

高频报错与避坑处理

1. 容器内启动后马上退出

查看日志：

docker compose logs langgraph-agent

最常见原因是 .env 文件中的 API Key 带引号，或者 base_url 末尾多了一个 /。
LangGraph 请求模型时会拼接路径，多这个斜杠往往导致 404。

2. 图运行时报 Invalid graph

这个错误出现原因是入口点识别失败。
在 pyproject.toml 或 langgraph.json 中要正确声明图对象。
建议明确定义：

{
  "graphs": {
    "agent": "./my_agent.py:graph"
  },
  "env": ".env"
}

确保 graph 是由 StateGraph 编译后的对象，不是节点函数。

3. 并发一高就出现 SQLite 锁问题

LangGraph 默认使用 SQLite 持久化检查点，生产多线程写入会出现 database is locked。
建议把检查点存储切换到 PostgreSQL 或 Redis，至少使用独立 SQLite 文件并开启 WAL 模式。
临时缓解可以给启动命令加：

PRAGMA journal_mode=WAL;

长期运行仍建议接 PostgreSQL，避免状态写入阻塞。

如何验证生产部署是否成功

先确认服务端口监听：

curl http://127.0.0.1:8000/health

正常情况下应返回类似 {"status":"ok"} 的 JSON。
然后调用一次真实对话接口，确认 Agent 能完成完整推理，再观察容器日志是否存在报错或重试。

最后建议打包一个压测脚本，模拟 10 个并发请求，持续运行 3 分钟，重点观察内存增长和响应耗时。
若内存持续飙升，优先检查图内是否使用了全局变量缓存，或在代码中手动释放不再使用的上下文。

如果你正在处理 LangGraph 生产环境部署踩坑问题，建议先按上述流程跑通最小服务，再逐步叠加 Agent 业务逻辑。
所有报错都先看日志原文，不要直接搜索片段，因为同一个报错在不同 Python 版本下原因可能完全不同。
线上环境变更前，务必先备份 .env 和运行时数据目录。