LangGraph 1.0 部署实战：从裸机到K8s的三种落地路径

LangGraph 在 0.x 时代给我的感觉是一个能把 Agent 工作流用图结构表达清楚的框架写 Demo 很爽真要往生产环境放总觉得缺了点什么。2025 年 LangGraph 1.0 正式发布后这个情况彻底改变了——它不再只是一个 Python 库而是一整套带 API 服务、持久化层、分布式调度能力的运行时平台。这篇博文想把我最近大半年在真实项目里的部署经验完整梳理一遍围绕三种主流落地路径展开独立服务器裸机部署、Docker Compose 容器化编排、企业级 K8s 集群部署。不管你是一个人维护一台内网服务器还是要在几十个节点的集群里支撑对外业务下面这套从环境准备、配置拆解到踩坑排查的过程基本都可以直接抄作业。看标题可能觉得一键搞定有点夸张实际上如果你把部署模板化、把变量收敛好确实可以做到在三种模式下用一套脚本快速拉起。但前提是你对底下的机制足够了解不然一键就变成一键接锅了。所以这篇我不光给命令也会解释每一步为什么这么干。1. 部署前先搞清楚LangGraph 1.0 的运行时到底由什么组成很多人部署 LangGraph 失败问题出在把它当成普通 Web 服务来理解。普通 FastAPI 服务是无状态的拿到代码pip install然后uvicorn app:app --port 8000就完事了横向扩容随便扩反正每个副本都一样。LangGraph 完全不是这个套路它本质上是有状态的图执行引擎核心业务逻辑是管理一段对话/一个任务流程在不同节点间的状态流转。这意味着部署一套 LangGraph 服务你实际上要部署四个部分图执行引擎也就是 LangGraph API Server 本体负责加载你定义的图Graph、接收客户端请求、调度节点执行、推进状态机。持久化层PostgreSQL。每一条会话线程Thread的 checkpoint 状态、消息记录、最终结果都存在这里。图执行到一半崩溃了恢复后靠 checkpoint 从断点继续。调度与缓存层Redis。LangGraph 1.0 用 Redis 做任务队列、定时器sleep 到点唤醒、分布式锁和跨副本的并发协调。接入网关对外暴露 REST API也可以是 Stream 接口实时流式输出让上层应用调用。打个不严格的比方它更像是一个状态机数据库 消息队列消费者 HTTP 服务的结合体而不是单纯的计算服务。这也是为什么官方部署文档里一定会有 PostgreSQL 和 Redis 这两个前置依赖。1.1 一个 LangGraph 1.0 服务端的标准文件结构部署前最好先理清项目里需要交付哪些东西。我这边一个常规生产仓库通常长这样/opt/langgraph-application/ ├── langgraph.json # 核心配置文件声明依赖和图入口 ├── my_agent.py # 图定义文件包含 StateGraph、节点函数等 ├── tools.py # 工具函数 ├── requirements.txt # Python 依赖 └── .env # 环境变量生产环境换成密钥管理其中langgraph.json是整个部署的入口LangGraph API Server 启动时会先读这个文件搞清楚依赖、graphs 在哪个模块、环境变量从哪里来。写法大致是{ dependencies: [.], graphs: { agent: ./my_agent.py:graph }, env: { REDIS_URI: redis://localhost:6379/0 } }这里dependencies可以是本地路径也可以直接写 Python 包名比如[langgraph, requests, psycopg]。graphs字段的关键在于把{模块路径}:{变量名}指向真正构建好的图对象。部署时服务端会动态导入这个图对象然后按请求里的assistant_id路由到对应图执行。1.2 为什么 1.0 的部署复杂度明显高于普通 Web 服务关键差异在有状态这三个字上。普通 Web 服务多个副本之间没有共享状态你扩十个实例不会出问题。LangGraph 服务则不同同一个thread_id的多次请求可能被负载均衡打到不同副本上副本之间必须通过共享的 PostgreSQL 和 Redis 协调状态与任务。举一个真实场景用户在一次多轮对话中途发了一条新消息这条消息被负载均衡器分发到 Pod B而这条会话之前的 checkpoint 存在 Postgres 里Pod B 要先通过thread_id把历史状态捞出来再把新消息作为输入继续推进图。如果并发刷新或者多个请求同时操作同一线程还需要有锁机制避免状态写坏。这就是为什么多副本部署时Postgres 和 Redis 的性能往往比 LangGraph 服务本身的 CPU 更早成为瓶颈。所以在选部署模式之前先想清楚一件事你的核心诉求是快速跑起来证明流程可用还是保证长时间高并发稳定运行。前者用独立服务器裸机就够后者必须考虑容器化编排甚至集群化。下面的三种模式本质上就是沿着这个复杂度阶梯逐级向上。2. 模式一独立服务器裸机部署——最直接也最容易被低估第一种模式不是我最常用的生产方案但它是理解后两种模式的基石也是很多私有化交付场景里客户最熟悉的方式。我之前有个内部工具项目跑在公司内网一台 Ubuntu 服务器上没有容器平台也不想引入 Docker这时候裸机部署反而是最轻的路径。2.1 环境清单与依赖安装LangGraph 1.0 服务端对 Python 版本有一定要求我自己实测用的是 Python 3.11 和 3.12都很稳。系统层面需要 PostgreSQL 和 Redis版本不用太激进PostgreSQL 14/15、Redis 6/7 都可以。sudo apt update sudo apt install -y python3.12 python3.12-venv python3.12-dev postgresql redis-server安装之后先把数据库建好。这里有几个细节很容易踩坑UTF-8 编码、read committed事务隔离级别、时区。LangGraph 的 Postgres Checkpointer 对这几个参数有要求如果角色默认配置不对后面会出现状态写入乱码甚至事务阻塞。CREATE USER langgraph WITH PASSWORD change_me_strong_password; CREATE DATABASE langgraph OWNER langgraph; \c langgraph ALTER ROLE langgraph SET client_encoding TO utf8; ALTER ROLE langgraph SET default_transaction_isolation TO read committed; ALTER ROLE langgraph SET timezone TO UTC; GRANT ALL PRIVILEGES ON DATABASE langgraph TO langgraph;Redis 默认就能用但生产环境记得关掉protected-mode之外的裸露端口至少绑内网 IP不要绑0.0.0.0。2.2 创建虚拟环境、初始化项目与启动服务我不建议在系统级 Python 环境里直接装 LangGraph CLI因为依赖冲突会非常难受。用虚拟环境隔离是标准做法sudo mkdir -p /opt/langgraph-application sudo chown $USER:$USER /opt/langgraph-application cd /opt/langgraph-application python3.12 -m venv .venv source .venv/bin/activate pip install langgraph-cli[inmem] langgraph checkpoints-postgres然后按第一节列出的文件结构把langgraph.json、my_agent.py等文件放进来。启动开发模式验证一下langgraph dev --host 0.0.0.0 --port 8123langgraph dev自带热重载和调试 UI本地验证流程用起来很舒服。但生产环境不要用 dev 模式直接用langgraph upDATABASE_URIpostgresql://langgraph:change_me_strong_passwordlocalhost:5432/langgraph \ REDIS_URIredis://localhost:6379/0 \ langgraph up --host 0.0.0.0 --port 8123这里有一个细节langgraph up会先执行依赖解析和图加载如果langgraph.json里写了不存在的模块它不会像普通 FastAPI 那样启动时只报个 warning而是直接启动失败。所以每次改langgraph.json后建议先langgraph build --base_image或者至少跑一次langgraph up看日志。2.3 用 systemd 把服务守护起来裸机部署最大的痛点是没有编排系统进程挂了不会自动拉起。我的做法是写一个 systemd unit把 LangGraph 服务作为受管进程跑起来[Unit] DescriptionLangGraph API Server Afternetwork.target postgresql.service redis-server.service Requirespostgresql.service redis-server.service [Service] Userlanggraph Grouplanggraph WorkingDirectory/opt/langgraph-application EnvironmentFile/etc/langgraph.env ExecStart/opt/langgraph-application/.venv/bin/langgraph up --host 0.0.0.0 --port 8123 Restartalways RestartSec5 TimeoutStartSec120 [Install] WantedBymulti-user.targetEnvironmentFile里放敏感环境变量比如DATABASE_URI、REDIS_URI这样不用把密码写进进程命令行避免被别人ps aux直接看到。启用并启动sudo systemctl daemon-reload sudo systemctl enable langgraph sudo systemctl start langgraph到这里一个裸机的 LangGraph 1.0 服务就起来了。不过裸机部署的短板在扩容和高可用上很明显——进程挂了能拉起不错但同一台机器的内存、CPU 总是有限的副本之间还要手动处理状态协调流量一大就吃力。所以如果你预估并发会持续提升建议直接看第二种模式。3. 模式二Docker Compose 容器化编排——从能跑到好管的中间形态我实际项目里用得最多的就是这个模式尤其是中小团队没有专职运维的时候。Docker Compose 可以在一台服务器上把 LangGraph、Postgres、Redis 三个服务编排起来一条命令拉起整套应用比裸机干净太多。3.1 镜像选型与版本锁定策略LangGraph 官方提供了 API Server 的预构建镜像Docker Hub 上是langchain/langgraph-api。这里我想强调一个重要习惯生产环境千万不要用latesttag。镜像更新节奏很快latest可能昨天还能跑今天升级后某个接口行为就变了。我在项目里固定到了具体版本比如langchain/langgraph-api:1.0.3以你实际拉到的版本为准并且在 CI 里也把镜像 digest 记录下来方便回滚。你的项目代码怎么进镜像有两种思路基于官方镜像做二次构建把项目文件 COPY 进去FROM langchain/langgraph-api:1.0.3 COPY requirements.txt /app/requirements.txt RUN pip install -r /app/requirements.txt COPY langgraph.json /app/langgraph.json COPY my_agent.py /app/my_agent.py COPY tools.py /app/tools.py通过挂载卷把代码动态覆盖进容器适合快速迭代但生产环境不推荐因为镜像和代码的一致性很难保证。我推荐第一种至少生产环境用自定义镜像这样版本、依赖、图代码全部绑定在一个可追溯的镜像里。3.2 完整的 docker-compose.yml 拆解一份可以直接抄的基础版编排文件如下version: 3.9 services: postgres: image: postgres:15 container_name: lg-postgres environment: POSTGRES_USER: langgraph POSTGRES_PASSWORD: ${PG_PASSWORD:-langgraph} POSTGRES_DB: langgraph volumes: - pgdata:/var/lib/postgresql/data networks: - lg-net healthcheck: test: [CMD-SHELL, pg_isready -U langgraph -d langgraph] interval: 10s timeout: 5s retries: 5 restart: unless-stopped redis: image: redis:7-alpine container_name: lg-redis command: [redis-server, --appendonly, yes] volumes: - redisdata:/data networks: - lg-net healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 restart: unless-stopped langgraph: build: . image: myregistry/langgraph-api:1.0.3 container_name: lg-server ports: - 8123:8000 environment: DATABASE_URI: postgresql://langgraph:${PG_PASSWORD:-langgraph}postgres:5432/langgraph REDIS_URI: redis://redis:6379/0 depends_on: postgres: condition: service_healthy redis: condition: service_healthy networks: - lg-net restart: unless-stopped volumes: pgdata: redisdata: networks: lg-net: driver: bridge几个关键点端口映射8123:8000是因为 LangGraph API Server 容器内默认监听 8000而我习惯在宿主机上暴露 8123 给 Nginx 反代。你完全可以按自己习惯调整但要保证内外一致别搞混。depends_on配合condition: service_healthy可以确保 Postgres 和 Redis 真正就绪后才启动 LangGraph而不是只等容器启动。这个对首次初始化尤其重要LangGraph 启动时要建表如果数据库还没 ready启动会失败。Redis 开启--appendonly yes是为了让调度任务和缓存数据在容器重启后不丢。Postgres 数据放在独立 volume 里同理。3.3 数据卷备份与迁移容器化部署最容易被忽略的是数据备份。docker-compose up -d玩得很溜但一旦宿主机磁盘坏了整个状态库灰飞烟灭。我在生产环境里对这两个 volume 做了冷备和增量备份Postgres 用pg_dump每天导出到对象存储docker exec lg-postgres pg_dump -U langgraph langgraph | gzip backup_$(date %F).sql.gzRedis 的 AOF 文件随 volume 一起做快照备份。另外迁移到新服务器时不用直接拷贝 volume 目录容易出现权限和版本兼容问题更推荐的方式是先在新机器上拉起空的 Postgres 和 Redis再用pg_restore恢复数据最后启动 LangGraph 指向新库。这套流程我走过好几遍稳定可靠。Docker Compose 模式已经能满足大部分中小流量的业务场景。但如果业务要走向多副本、弹性扩缩容、故障自愈或者公司有上 K8s的硬性要求那就得进入第三种模式。4. 模式三企业级 K8s 集群部署——弹性伸缩与高可用的最终形态K8s 模式是我现在服务端主力业务在跑的部署方式。相比前两种模式K8s 带来的不只是能跑起来而是把扩缩容、滚动发布、自愈这些能力全部标准化。但代价是学习曲线陡峭而且架构设计上要做一些调整。4.1 从 Compose 到 K8s架构上有哪些变化点在 Docker Compose 模式里Postgres、Redis、LangGraph 三者都在同一台机器上相互通信走 Docker 内网。到 K8s 里我的建议是Postgres 和 Redis 尽量使用云托管服务或者至少部署成独立的有状态服务不要让它们跟 LangGraph 应用挤在同一个 Deployment 里。原因很简单K8s 的 Deployment 是按无状态应用设计的Pod 随时可能被调度到新节点、被重新创建。如果 Postgres 和 Redis 也做成 Deployment 挂在临时存储上重启一次状态就没了这是灾难。LangGraph 的多副本机制依赖于稳定的 Postgres 和 Redis这两个状态依赖稳定了应用层才能无脑扩容。架构上最终的形态是应用层LangGraph Server 做成 Deployment多个副本对外提供服务。状态层PostgreSQL云 RDS 或集群内 Operator 管理 Redis云版或哨兵模式。接入层Service Ingress 暴露 APIHPA 根据 CPU/内存自动伸缩副本。这里想特别说一下为什么 LangGraph 应用层可以做多副本。LangGraph 1.0 的调度器会把任务状态写入 Postgres把并发锁、定时事件交给 Redis所以同一线程的不同步骤请求即使被分到不同 Pod也能通过外部状态协调起来。所以多副本不是能不能的问题而是状态层够不够稳的问题。4.2 核心 K8s 资源清单拆解下面是我在项目中的最小可用配置逐块解释Deployment应用层apiVersion: apps/v1 kind: Deployment metadata: name: langgraph-server namespace: ai-platform spec: replicas: 3 selector: matchLabels: app: langgraph-server template: metadata: labels: app: langgraph-server spec: containers: - name: langgraph image: myregistry/langgraph-api:1.0.3 ports: - containerPort: 8000 protocol: TCP env: - name: DATABASE_URI valueFrom: secretKeyRef: name: langgraph-secrets key: database-uri - name: REDIS_URI valueFrom: secretKeyRef: name: langgraph-secrets key: redis-uri resources: requests: cpu: 500m memory: 512Mi limits: cpu: 2 memory: 2Gi readinessProbe: httpGet: path: /ok port: 8000 initialDelaySeconds: 15 periodSeconds: 10 timeoutSeconds: 3 livenessProbe: httpGet: path: /ok port: 8000 initialDelaySeconds: 30 periodSeconds: 15readinessProbe用的是/ok这个健康检查端点LangGraph API Server 默认提供。Pod 只有通过健康检查才会被纳入 Service 的负载均衡这样滚动发布时不会把流量打到还没 ready 的实例上。Service Ingress接入层apiVersion: v1 kind: Service metadata: name: langgraph-server namespace: ai-platform spec: selector: app: langgraph-server ports: - port: 8123 targetPort: 8000 type: ClusterIPIngress 用 Nginx 或 Traefik 都行把域名代理到 Service 的 8123 端口并配置 TLS 证书apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: langgraph-ingress namespace: ai-platform annotations: nginx.ingress.kubernetes.io/proxy-read-timeout: 300 nginx.ingress.kubernetes.io/proxy-send-timeout: 300 spec: tls: - hosts: - llm-api.example.com secretName: llm-api-tls rules: - host: llm-api.example.com http: paths: - path: / pathType: Prefix backend: service: name: langgraph-server port: number: 8123上面的proxy-read-timeout和proxy-send-timeout注释很重要。LangGraph 的流式接口Stream Mode可能会让 HTTP 连接长时间保持打开默认的 60 秒超时会导致前端 stream 中断。我第一次部署时没加这个配置跑了一个小时才发现流式输出会在整点附近断掉最后定位到就是 Nginx 超时加上这俩注解后解决。HPA弹性伸缩apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: langgraph-server-hpa namespace: ai-platform spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: langgraph-server minReplicas: 3 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 60HPA 的扩缩容策略要看业务特征。LangGraph 如果是处理大量长耗时、流式任务CPU 使用率可能并不高这时候只盯 CPU 不够可能要加自定义指标比如基于 Prometheus 的排队请求数。我这边一开始只配了 CPU 阈值后来发现高峰期流量涨了但 CPU 没涨多少因为瓶颈在 Postgres 连接数和 Redis 任务队列长度后面改成了按请求队列深度伸缩。4.3 用 Helm Chart 还是手工 YAML在 K8s 里管理 LangGraph 服务可以直接用kubectl apply -f也可以用 Helm。我的建议是如果只有一个环境、三五套资源手工 YAML 完全够用。如果要多环境dev/staging/prod部署强烈建议用 Helm Chart 把公共模板抽出来用values.yaml区分环境差异。我目前是 Helm Argo CD 的 GitOps 流程。Chart 里把DATABASE_URI、REDIS_URI这些区分环境的配置抽成参数提交到 Git 仓库Argo CD 自动同步到集群。这样每次部署都有审计记录回滚也快。4.4 高可用与运维的注意事项到了 K8s 模式真正决定系统高可用的不是应用镜像而是状态层的设计。我踩过一个很深的坑集群里用了一个单副本的 Postgres Deployment结果节点维护时 Pod 被调度走LangGraph 服务集体报数据库连接错误业务直接熔断。后来把数据库迁到了云托管的 RDS才算真正解决。如果不想用云托管在集群内部署 PostgreSQL Operator比如 CloudNativePG也是可行方案它能帮你管理主从、备份和故障切换。Redis 同理至少要哨兵模式或集群版否则单点问题会在高并发时被放大。5. 三种部署模式怎么选参数对照与决策矩阵做了这么多年运维和开发我最大的体会是没有最好的模式只有当前阶段最合适的模式。如果把这三个模式放到同一张表里对比决策会清晰很多对比维度独立服务器裸机Docker ComposeK8s 集群上手成本低会 Linux 就能搞中需要理解容器高需要懂 K8s 概念单机并发上限中受进程资源限制中可调优但单机有限高多副本横向扩展高可用能力差单点故障中依赖宿主机强自愈、多副本弹性伸缩手动调整进程/集群手动扩缩容需改 compose自动 HPA状态可靠性依赖本地 Postgres/Redis依赖宿主机 volume可依赖云托管或 Operator运维成本高手工维护中编排简化部署中高需要持续学习适用场景内网工具、私有化交付、快速验证中小流量稳定运行、单一客户项目对外生产业务、SLA 要求高、多团队协作那具体怎么选按下面三个问题走一遍基本就有答案你的预估并发是多少如果 QPS 长期在几十以下独立服务器裸机或 Compose 完全够用如果 QPS 经常破百且伴随长连接流式输出K8s 多副本优势就很明显。你的团队有没有人懂 K8s没有的话硬上 K8s光一个 Ingress 配置和证书轮换就能消耗大量精力。反而不如先用 Compose 撑住业务等团队能力到位再迁移。你的业务对可用性要求多高内网工具挂了十分钟没人管裸机没问题对外付费服务断了五分钟就要被投诉那直接走 K8s。从我自己的项目路径来看通常是先用裸机验证图逻辑再切换到 Compose 跑正式业务等到确实需要横向扩容或公司开始统一容器平台时再把服务迁到 K8s。这三步之间的迁移成本其实不高因为图代码和langgraph.json完全不用改变的只是运行环境和周边依赖的部署方式。6. 实战踩坑记录从独立服务器走上 K8s我踩过的三个关键坑最后这部分是全文最想分享的实操内容。都说部署文档千篇一律真正的坑在文档之外。我挑三个印象最深的把完整的排查链路和最终解法写出来。6.1 坑一Postgres 连接被占满LangGraph 请求集体超时现象业务高峰时段LangGraph 接口大量报超时和 500 错误日志里频繁出现connection pool timeout、psycopg_pool.PoolTimeout。排查过程先看 LangGraph 日志确认错误集中在数据库连接层而不是图执行逻辑本身。连到 Postgres 上执行select * from pg_stat_activity;发现连接数接近max_connections上限大量连接处于idle in transaction状态。进一步翻 LangGraph 的配置发现连接池默认上限偏小而我又把requests的并发调得很高导致连接池里的连接不够分。解决把DATABASE_URI中连接池上限调大同时把 Postgres 的max_connections适当提高注意服务器文件句柄数的限制。举例DATABASE_URIpostgresql://langgraph:passpostgres:5432/langgraph?pool_size20同时在 Postgres 配置里max_connections 100根据实际内存预期调整。这里有一点要提醒不同小版本连接池参数名可能略有差异改之前先在目标版本上测一下避免配置项不识别被静默忽略。6.2 坑二K8s 多副本导致同一线程的 checkpoint 冲突现象上 K8s 后开了 3 个副本刚开始一切正常直到有用户高频刷新对话同一个thread_id的多条请求被同时打到不同 Pod日志出现 checkpoint 唯一约束冲突、图状态回滚甚至直接 500。排查过程看 Postgres 日志出现 duplicate key 类的错误定位到 checkpoint 表。复现请求发现同一 thread_id 的请求确实被 Service 负载均衡到了不同 Pod。意识到问题的本质是多个 Pod 同时读同一个 checkpoint 并尝试各自推进状态写回时产生冲突。解决在 LangGraph 服务端开启任务/线程级别的锁机制让同一线程的任务在任意时刻只有一个执行者另一个辅助手段是在应用层做路由让同一thread_id的请求尽量固定到同一 Pod但这不是根治方案因为 Pod 重启或扩缩容后路由可能会变化。最终我以服务端锁为准业务层路由只做优化。这个坑提醒我K8s 给的是并发能力但并发能力需要业务层配合使用和状态一致性做权衡。6.3 坑三企业内网拉不到 Docker Hub 镜像现象在公司内网环境部署 K8sPod 一直ImagePullBackOff查看事件发现拉取langchain/langgraph-api镜像超时或被拒绝。排查过程kubectl describe pod看事件错误是网络问题。确认内网节点无法直接访问 Docker Hub。临时改docker pull到一台有外网的机器docker save打成 tar 包传到内网再用docker load导入节点。长期方案是搭一个内网私有 Registry比如 Harbor在有外网的机器上拉取镜像后docker push到 HarborK8s 节点配置从 Harbor 拉取的镜像地址和凭据。这个坑其实很普遍尤其企业网络环境下。写出来是希望大家在规划 K8s 部署时第一件事就确认清楚镜像拉取策略不要像我一样等到 Pod 起不来才回头看。7. 写在最后我的一点部署建议其实部署 LangGraph 1.0 这件事技术难点并不在于某个具体的命令而在于你是否真的理解了它有状态 分布式调度 持久化这套运行逻辑。我见过很多团队把 LangGraph 当成普通 FastAPI 服务直接部署结果一上并发就各种超时、状态错乱最后归咎于框架不行。实际上框架给了足够的扩展机制只是部署姿势没跟上。如果让我给刚开始上手的朋友一个路径建议我会说先用裸机或 Compose 把图和流程跑通让业务方看到可用价值等流量和稳定性要求上去了再平滑迁移到 K8s。迁移过程没那么可怕因为langgraph.json和图代码基本不动你需要处理的核心是 Postgres、Redis 的高可用和网络层的超时配置。最后分享一个小技巧无论哪种模式务必把langgraph.json里的依赖声明清理干净。LangGraph 1.0 对依赖解析严格了很多部署失败甚至运行时行为异常多半是依赖没写清楚导致的。这个文件是部署链路里最不起眼但最容易出问题的一环我在三个模式里都因为它在同一个地方栽过跟头。