企业官网建设流程全解析

最近把一个基于 LangGraph 的多智能体工作流应用从本地脚本改成 Docker 容器化部署，中间踩了不少坑，也把整个链路重新梳理了一遍。LangGraph 这类图编排框架，本地跑 demo 非常简单，状态一推进、节点一调用，结果就出来了。但一旦准备上生产，环境、依赖、状态存储、并发、可观测性全都会变成绕不开的问题。这篇文章会把容器化改造的完整思路、核心决策、Dockerfile 写法、Compose 编排、生产配置以及常见故障排查全部展开，适合已经用 LangGraph 写出了原型、正准备把应用部署出去的开发者。读完你至少能把一个可用的 LangGraph 服务稳定跑在容器里，并且知道哪些地方最容易被坑。

1. 为什么要给 LangGraph 应用做容器化部署

1.1 本地能跑与生产可用的差距

刚开始用 LangGraph 搭应用，大多数人都是本地建一个虚拟环境，写一个脚本，把图定义好，graph.invoke({...})一调，结果出来了，很开心。但这种状态离生产可用差得很远。生产环境需要处理环境复现、版本一致、部署迁移、故障恢复、并发扩展。一个 LangGraph 应用，本质上是描述节点如何编排、状态如何流转的程序，它运行得好不好，受 Python 环境、第三方包、系统库、网络、密钥配置影响非常大。裸机部署时，机器一变，环境就不一样，今天在 A 机器上跑得好好的，到 B 机器就报ModuleNotFoundError或者内存溢出。

容器把这一层隔离开，应用和宿主机解耦，这正是容器化的核心价值。镜像里装的就是那一份代码、那一组依赖版本，不管放到哪台机器上，跑起来的执行环境是一致的。对 LangGraph 项目来说，这点尤其重要，因为 LangChain 生态的依赖非常重，Pydantic、OpenAI SDK、各种集成包，版本稍微错一点，接口行为就完全变了。我见过太多“在我电脑上好的”的案例，容器化之后，这类话术就再也没有意义了。

还有一个更加隐蔽的状态问题。LangGraph 的图本身是临时执行的，真正的业务状态拿到手之后，要么写在内存里，要么持久化到外部存储。如果申请了一个容器，跑一个 LangGraph 应用，进程一重启，对话历史、工作流中间态全没了，这会造成直接的生产事故。容器化部署的正确姿势是：让应用进程尽可能无状态，所有状态交给外部中间件，比如 Redis 或 Postgres。应用容器可以被随时杀掉、重建、扩容，这才是容器化真正的意义。很多第一次做容器化的人把目光放在写 Dockerfile 上，其实核心的功夫在图的设计和状态存储选型上。

1.2 两个影响容器化难度的设计决策

第一个决策，图的定义要和 API 层解耦。我见过不少项目，直接在 FastAPI 路由里 new 一个 graph 出来。这样做 demo 没问题，但容器化之后会很难受：CI/CD 里跑测试要 mock 图构建逻辑很痛苦，本地调试要连生产 Redis 又要改代码。更好的做法是把图的构建函数单独放一个模块，比如graph_factory.py里的create_agent_graph(config)，API 层只负责接收 HTTP 请求、调用图执行、转换结果。图本身就是一个可以被实例化的对象，运行时通过工厂函数注入配置。这样后面镜像里跑测试、本地点项目、生产起服务，入口完全一致。

第二个决策，所有可变参数必须走环境变量。模型名、模型密钥、checkpoint 的数据库地址、日志级别、worker 数，全部从环境变量读取，再通过配置对象传给图。有人喜欢写死配置文件，进了容器还保留各种内置常量，我建议不要这样写。容器环境里环境变量是最通用的配置入口，docker-compose 可以统一注入，以后上编排平台也有标准的配置注入机制。只要这两点做到位，后面写 Dockerfile 和 Compose 就会非常顺。反之，如果图构建逻辑和路由强耦合、模型名写在代码里，容器化改造会变成一次大重构。

2. 项目结构与依赖准备

2.1 把脚本、测试、配置从主代码里剥开

我在项目里习惯把服务拆成几个目录：app放 API 和启动入口，graph放 StateGraph 定义、节点函数、状态模型，core放配置读取、日志、通用中间件，tests放集成测试。目录设计没有标准答案，但有一条原则要守住：构建 Docker 镜像时，COPY 到镜像里的文件范围必须可控。用.dockerignore把tests、data、docs、本地虚拟环境、.git全部排除掉，既能加快构建，也能减小镜像体积，还能避免把不必要的东西误打进生产镜像。很多人一开始不在意，有一天在容器里发现居然有.git目录或者本地测试数据，那就尴尬了。

依赖管理这块，我建议直接用requirements.txt加版本锁定，至少把顶层依赖钉死。LangGraph、langchain、FastAPI、redis、pydantic 这些核心包的版本，在本地确认能跑之后，用固定版本号写进文件。团队如果用 Poetry 也没有问题，但要保证生成的锁文件提交到仓库，构建时用poetry install --no-dev。为什么这么强调锁版本？因为 LangGraph 这类框架迭代很快，接口变化频繁，一旦构建镜像时拉到新的大版本，很容易出现图定义报错或者 checkpoint 接口对不上。镜像构建应该是可复现的，今天构建的镜像，半年后同一份配置还能构建出一样的内容，这在生产环境非常重要。

2.2 Python 版本与基础镜像的兼容性

Python 版本我建议选 3.11 或者 3.12，不要用 3.11 以下的老版本。LangGraph 和 langchain 对新语法依赖不少，老版本即便能装上，跑起来也可能出一些诡异的接口兼容问题。Docker 基础镜像，我推荐python:3.12-slim。不要一上来就选 alpine，虽然 alpine 体积小，但很多 Python 的 C 扩展轮子到 alpine 上要现编或者干脆不兼容，比如 Pydantic 这类对构建工具链有要求的包，在 alpine 的 musl 环境里经常要踩编译坑。slim 基于 Debian 的 glibc 环境，离线轮子兼容性最好，镜像体积也就是多几十 MB，完全值得。

我踩过的一个典型坑是：最初为了把镜像压到最小，换成 alpine，结果pip install时开始编译 pydantic，构建时间变得很长，后面还因为缺少gcc和musl-dev报错。最后老老实实回到 slim。如果真的非常在意体积，等应用稳定后，可以考虑多阶段构建，并把运行时需要的文件单独拷出来。但这些都是后话，先保证能跑，再去优化体积。

2.3 容器化之前先保证本地跑通

动手写 Dockerfile 之前，我一定先在本地把服务完整跑起来。一个最简单的入口：FastAPI 应用暴露三个端点，POST /invoke同步执行图，POST /stream用 SSE 返回流式结果，GET /healthz做存活检查。先把这三个端点调通，再去看容器里的表现。本地跑通了，后面构建镜像之后如果出了故障，就能明确区分到底是网络问题、依赖问题，还是应用代码本身的问题。

这个最小 API 还有一个好处：你可以在容器外就把整个执行链路验证一边，相当于给后面的容器化排查留下了对比基准。我甚至会在项目里写一个启动脚本，把本地环境的启动命令固定下来，这样团队其他人也能一键复现。镜像构建完以后，再跑同一个测试脚本，如果结果一致，说明容器化没有引入额外变量，后面加编排、加配置都放心得多。别小看这一步，很多人在容器里排查半天，最后发现本地本来就是坏的。

3. 核心设计：Checkpoint 持久化与可配置图

3.1 让 StateGraph 的每个节点都通过 config 改变行为

LangGraph 里面，StateGraph是核心抽象，节点函数收到两个参数：当前状态和一个 config 对象。节点内部读模型、读参数，都应该从 config 走。比如多租户场景里，不同用户使用的模型、温度、系统提示词可能都不一样，你不可能每次都改代码。用configurable字段就可以在调用时动态传参，比如：

def route_node(state: dict, config: dict) -> dict: model_name = config.get("configurable", {}).get("model_name", "default-model") # 根据 model_name 实例化模型并调用

到了 API 层，graph.invoke(payload, config={"configurable": {"thread_id": "user-001", "model_name": "advanced"}})。这样图的结构是固定的，行为完全由外部配置驱动。容器化时，镜像内容就是图的结构和代码，而模型名、密钥、参数全部来自环境变量注入的 config，镜像本身不需要关心用户差异。

有些人的做法是把图构建好之后全局复用。如果图没有持久的内部状态，全局复用没问题，性能也好。但如果图里挂了 Checkpointer，有状态后就要注意：不同用户之间的 thread_id 必须隔离，否则所有用户共享同一份历史。你可以在节点内部用 thread_id 拼一个隔离键，也可以靠外部调用方保证 thread_id 唯一。这里最容易遗漏的是，测试和生产共用一个 checkpoint 存储，测试产生的脏数据污染了生产对话历史。我当时用环境变量区分不同存储的库名，生产一个 Redis 库，开发一个 Redis 库，简单有效。

3.2 Checkpoint 为什么必须放到容器外

LangGraph 的 checkpoint 机制是为了支持对话历史、图执行状态在多次调用之间延续。默认的MemorySaver把 checkpoint 放在进程内存里，一旦进程退出，全部丢失；只要容器重启，会话就断了。生产环境里，容器会被滚动重启、扩容缩容，进程随时可能重生，所以 checkpoint 必须落在容器外的持久化存储里。

官方提供了 Postgres 和 Redis 的实现。我把 Redis 作为默认方案，因为接入最简单：启动一个 Redis 容器，连接串走环境变量，代码里初始化RedisSaver，再通过compile(checkpointer=saver)交给 LangGraph。这样，多副本部署时，每个副本都能读到同一份会话状态，不会出现用户这次请求打在 A 副本有历史、下次打在 B 副本没历史的尴尬情况。对生产来说，这意味着你可以放心地把 API 服务启动多个 worker 或者多个副本，状态存储不依赖某个进程。

3.3 Redis 和 Postgres 怎么选

如果你的 LangGraph 应用主要存对话历史、临时工作流状态，Redis 足够合适。Redis 性能高，操作简单，运维也成熟；配合 AOF 持久化，重启不丢数据。但是要注意，Redis 的数据模型是 KV，如果以后要对会话状态做复杂查询、关联分析，就比较笨拙。而且 Redis 主从切换、持久化配置如果不认真处理，某些极端情况下会有丢数据的风险，对这类应用通常可以接受，但你要心里有数。

如果应用里涉及订单、任务状态这类严格要求一致性的场景，Postgres 是更稳的选择。Postgres 事务能力强，数据不容易丢，还方便做备份和审计。使用官方的 checkpoint-postgres 实现，表结构会自动建，不用手工建模。部署上稍微重一点，但换来的是更强的数据保障。我的建议是：前期用 Redis 把产品跑起来，等确认数据可靠性要求高，再平滑切到 Postgres。切换成本主要就是改连接串和初始化代码，图定义不用变。

4. Dockerfile 与镜像构建实操

4.1 多阶段构建：先装依赖再用轻量运行层

多阶段构建是 LangGraph 这类 Python 应用最实用的模式。第一个阶段叫 builder，负责编译安装依赖；第二个阶段才是最终运行镜像。省略多阶段，直接把所有依赖装进运行镜像，会残留大量编译工具和中转文件，镜像体积大，安全审计也不好看。

FROM python:3.12-slim AS builder WORKDIR /build COPY requirements.txt . RUN pip install --prefix=/install --no-cache-dir -r requirements.txt FROM python:3.12-slim AS runtime WORKDIR /app COPY --from=builder /install /usr/local COPY app/ ./app/ COPY graph/ ./graph/ ENV PYTHONUNBUFFERED=1 \ PYTHONDONTWRITEBYTECODE=1 \ PATH="/usr/local/bin:$PATH" RUN groupadd -r appuser && useradd -r -g appuser appuser USER appuser EXPOSE 8000 HEALTHCHECK CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz')" || exit 1 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

这个 Dockerfile 有几个关键设计。pip install --prefix=/install把依赖装到独立目录，runtime 层直接 COPY 过去，避免了 builder 层留下的 pip 缓存和临时文件进入最终镜像。PYTHONUNBUFFERED=1保证日志实时输出到容器标准输出，不然docker logs会延迟。创建非 root 用户运行服务，是安全加固的基本要求，容器被攻破后拿不到 root 权限。HEALTHCHECK用 Python 原生库请求健康检查接口，比依赖 curl 更省事，slim 镜像里不一定有 curl。

4.2 利用层缓存加速构建和减小体积

Docker 构建速度的一个重要经验：把COPY requirements.txt和COPY 代码分开。依赖安装只跟 requirements 内容相关，代码里哪怕改一行，都不会触发pip install重跑，层缓存能直接命中。很多新手把全部项目代码 COPY 进去之后再 pip install，代码一改，整个依赖层作废，构建时间直接翻倍。所以，先 COPY 依赖描述文件，再 pip install，最后 COPY 代码，这个顺序在 Dockerfile 里非常关键。

镜像体积上，除了多阶段把编译工具隔离在外，还要用好.dockerignore。像__pycache__、.pytest_cache、.venv、*.pyc、.git这些都应该排除。Python 运行时本身就要几十 MB，LangChain 生态依赖又多，一个镜像两三百 MB 很正常，不用太焦虑瘦身。但把明显无关的文件扣掉之后，镜像既干净又不容易因为残留内容出敏感信息问题。镜像体积和构建速度往往是一体的，依赖层缓存住，体积控制住，构建效率和运行效率都会好。

4.3 为什么运行时不能只依赖内存状态

有些人在写 Dockerfile 时会把检查点文件直接写到容器内路径，比如部署一个 SQLite 数据库文件装在/data/agent.db。在本地这样跑当然行，但进到容器环境就是个大坑：容器一删，文件全部消失；多副本时，每个副本各写各的，状态互相隔离。这就是我前面说 Checkpoint 必须外置的原因。设计 Dockerfile 时，可以预置一个/data目录，但千万不要把业务状态假设成容器里的文件。容器只跑应用进程，数据放外部存储，这个思维一定要扭转过来，不然后面扩容、迁移时会非常被动。

5. docker-compose 编排与生产配置

5.1 用 Compose 把 API 和 Redis 一次性拉起来

单机部署 LangGraph 服务，docker-compose 是最顺手的编排方式。它可以直接定义两个服务：API 应用、Redis 存储，并处理好依赖顺序和网络通信。

services: api: build: . environment: REDIS_URL: redis://redis:6379/0 APP_LOG_LEVEL: INFO ports: - "8000:8000" depends_on: redis: condition: service_healthy restart: unless-stopped redis: image: redis:7-alpine command: ["redis-server", "--appendonly", "yes"] volumes: - redis-data:/data healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s timeout: 3s retries: 5 volumes: redis-data:

注意depends_on的condition: service_healthy。默认情况下，depends_on 只等容器启动，不等它真正就绪，API 服务启动时就可能连不上 Redis。改成service_healthy后，Compose 会等 Redis 的 healthcheck 返回成功后，才去启动 API。这个配置救过我很多次，不写它，应用起来大概率会报一次连接错误，虽然应用有重试可能自己恢复，但第一次启动就报错非常影响体验。

Redis 容器打开--appendonly yes，数据写到redis-data卷里，容器删了数据还在。这就是生产侧“进程无状态、数据有归属”的具体落地。这个 Compose 文件本身也可以提交到仓库里，团队其他人 clone 后一个docker compose up --build就能把整套环境拉起来。

5.2 环境变量、资源限制和并发控制

环境变量的管理，我在项目里统一用一个.env文件，Compose 启动时自动读取。默认值写进compose.yaml，敏感内容比如 API 密钥不提交到仓库，用部署平台的密钥管理去注入。分环境时，可以用多个 env 文件，比如compose.yaml加--env-file参数切换。关键是：应用代码里不出现任何硬编码的密钥和地址。

资源限制必须设置。Compose 的deploy.resources.limits可以对容器做 CPU 和内存限定。LangGraph 执行图的时候，大批量并发请求可能把内存顶上去，不设限制很可能把整个宿主机拖垮。比如给 API 服务配memory: 2g、cpus: "2.0"，给 Redis 配memory: 1g，让每个容器在资源上互相隔离。Uvicorn 的 worker 数量，我一般设在 CPU 数附近，--workers 2起步。更重要的一点：LangGraph 节点内部大量调用模型 API，是 IO 密集型，用异步接口比多开 worker 的收益更明显，先把单进程协程吃满，再考虑加 worker。

超时控制也不能忽略。模型调用一般都有自己的超时，但图整体调用也要设一个上限，不然某个节点卡住，整个请求一直挂着，连接池和线程都会被占满。我通常在 API 层给图执行包一个asyncio.wait_for，超时后直接返回统一的错误响应。再配合请求级别的限流，比如简单的信号量控制最大并发，可以在资源吃紧时主动拒绝新请求，而不是把服务拖死。

5.3 健康检查与日志策略不能省

健康检查分存活和就绪两个维度。/healthz只检查进程活着，/readyz再额外检查 Redis 连接是否正常、图是否能初始化。API 服务自身要在启动时做一次依赖探测，比如连不上 Redis 就快速失败，而不是带着病继续接受流量。容器编排器会根据健康检查结果决定重启、流量摘除，这一步做得越细，运维越省心。

日志方面，我建议应用直接把结构化日志打到标准输出，不要挂卷写日志文件。容器平台要么自带收集，要么你可以用docker logs直接看。结构化日志至少包含时间、级别、请求 ID、调用图耗时。一个 LangGraph 请求要经过多个节点，模型调用时间长，请求 ID 要贯穿整条链路，才能把一次请求的日志串起来排查。我一般给每个请求生成一个 UUID，在 FastAPI 中间件里注入日志上下文。千万别把日志文件塞进容器目录，重启就没了，排查问题时会非常被动。

6. 常见故障与排查实录

6.1 六类典型问题与定位思路

第一类，API 容器无法连接 Redis。症状是启动时反复Connection refused。通常是编排层没等 Redis 健康就启动 API，或者连接串写成了localhost。容器网络里要用服务名，比如redis://redis:6379/0，不能用127.0.0.1，因为 API 容器和 Redis 容器不共享网络栈。我见过有人把localhost从宿主机搬进容器，换了容器环境后怎么连都不对。

第二类，会话历史丢失。图表上看，每次请求都像新用户。这通常是 checkpoint 没配置，或者用了MemorySaver。你重启容器后，内存全部清空，历史自然没有。排查时先看启动日志里有没有初始化 checkpointer，再看 Redis 连接是否成功。有时 Redis 连的是开发库，生产库并没有数据，也会出现历史忽然没了的错觉。

第三类，流式输出到客户端卡住。本地直接调接口正常，一到容器或域名访问就变成攒一堆才返回。这多半是中间代理层缓冲了响应。如果你用 Nginx 做反向代理，需要在 location 里关闭代理缓冲，对 SSE 或者流式响应很关键。还有一个点是压缩，对流式响应可能会造成延迟，也要评估。

第四类，镜像构建特别慢。检查 Dockerfile 里依赖安装步骤是否每次都因代码变更而失效。把 COPY requirements 提到代码之前，利用层缓存，能大幅加速。另外，pip 安装时网络抖动也会导致卡顿，可以根据网络环境选择可用的镜像源，但企业内部要考虑网络策略。

第五类，内存持续上涨。LangGraph 图执行过程中会累积部分状态，特别是对话历史长、checkpoint 数据在内存中缓存。要限制领域状态的大小，及时清理过期的 thread 历史，给 checkpoint 存储设过期策略。LLM 客户端网络重试也可能占住协程，形成背压，表现为请求排队长。这种问题要靠监控和压测发现，光看日志很难定位。

第六类，多 worker 下状态串线。如果你用 Gunicorn 起了多个 worker，每个 worker 内存不同。同样是MemorySaver，请求落在不同 worker 上，历史就串不起来。解决办法很简单，切到外部 Redis 或 Postgres 存储。这类问题往往以“偶发丢历史”的形式出现，排查时要先问自己：checkpoint 存储是不是进程外。

6.2 排查 LangGraph 容器故障的实用命令

这里分享一套我在现场排查的标准操作。容器起不来，先docker compose logs api看应用报错；再docker inspect --format '{{.State.Health}}'看健康检查状态。如果怀疑网络问题，docker exec -it api bash进容器，拿出一段 Python 直接连 Redis：python -c "import redis; r = redis.from_url('redis://redis:6379/0'); print(r.ping())"。能返回 True 说明网络通，那就继续看应用层。

如果接口报 500，而日志里没有详细堆栈，可以在本地写一个最小复现脚本，进容器里直接调用图的某个节点，把挂载的输入跑一遍。因为容器内的环境和你本地完全一致，问题更容易复现。排查 LangGraph 相关的故障，我最后的兜底工具永远是给应用加一段带请求 ID 的日志，节点进出各打一条。只要看到节点执行到哪一步，问题基本就在那附近，不用盲猜。

自己做 LangGraph 应用容器化改造这几轮下来，最深的感触是：容器化的难点从来不在 Dockerfile 本身，而在于你想清楚应用的状态放哪里、配置从哪里来、失败时怎么恢复。只要把图的定义、状态存储、运行时配置这三件事做扎实，镜像就是顺理成章的结果。如果你现在只在自己的电脑上跑 LangGraph，建议先把 checkpoint 移到外部存储，再把图和 API 层拆开，这两步做完，后面上生产几乎就是改几个环境变量的事。如果你已经在容器里踩坑了，我希望这篇文章里那些常见问题能帮你少走几圈弯路。