langgraph build 本地构建失败怎么办？

如果 langgraph build 在本地失败而服务器 Docker 环境正常，可以把项目迁到目标 Linux 服务器完成构建；但配置、依赖和图导入错误必须先修掉，否则换机器仍会失败。

更稳妥的顺序是先保留完整报错，把故障分成 CLI 启动、Docker daemon、镜像构建、应用配置和容器运行五层。配置、依赖或图导入错误属于项目自身的问题，应先在本地修复；只有本地 Docker 服务、资源、网络或架构条件不满足，且目标服务器环境正常时，迁移构建才有意义。

先定位失败在哪一层

排查时不要只看最后一行报错。langgraph build 的失败位置并不固定：可能连 CLI 都没有启动，也可能已经生成镜像，最后才在容器启动阶段暴露问题。

先在当前 shell 中确认实际使用的命令和 Python 环境：

command -v langgraph
python --version
langgraph build --help
docker version
docker info
docker compose version

command -v langgraph 没有输出，说明当前 PATH 中没有 LangGraph CLI，或者它安装在另一个虚拟环境里。此时先确认项目虚拟环境是否已经激活，再按当前版本文档安装 CLI。python --version 只显示解释器版本，不能证明 CLI 安装在同一个环境；必要时还要检查 Python 包安装位置和依赖冲突。

langgraph build --help 能正常执行，只能证明 CLI 可以启动，不能证明 Docker daemon、项目配置或依赖没有问题。真正有诊断价值的是构建命令的第一处错误：

set -o pipefail
langgraph build 2>&1 | tee build.log

这里加上 pipefail，是为了避免 tee 正常退出而掩盖 langgraph build 的失败状态。日志可以保留完整上下文，但对外发布前应检查 API Key、数据库连接串、代理凭据和其他环境变量值。

判断该修本地还是迁服务器

迁移服务器不能解决项目自身的错误。langgraph.json 写错、图模块无法导入、依赖只存在于本机虚拟环境，这些问题换到服务器后仍然存在。相反，本地 Docker Desktop 没有启动、WSL 引擎异常、磁盘不足或基础镜像拉取失败，通常属于环境问题，放在条件合适的服务器上更容易解决。

可以按下面的边界作判断：

报错现象	更可能属于	处理方向
command not found、Python 包缺失	CLI 或虚拟环境	先修当前 Python 环境
JSON 解析失败、模块路径错误、图对象导入失败	项目配置或代码	先修项目
锁文件与依赖声明不一致、原生扩展编译失败	依赖与构建环境	固定依赖并检查基础镜像
无法连接 Docker daemon、socket 权限错误	本地 Docker 服务	修 Docker 或迁服务器
基础镜像或依赖下载超时	构建网络	检查代理、仓库和服务器出口
本机镜像架构与服务器不匹配	平台差异	在目标架构上构建或显式跨架构构建
镜像生成后容器立即退出	运行时配置	转查环境变量、数据库、任务队列和端口

如果本地和服务器都报同一个 Python traceback，就不要继续从 Docker 方向排查。先沿着 traceback 找到第一个项目文件，再核对配置和依赖。

本地 Docker 没有正常提供服务

相关资料中的典型输出如下：

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

这表示客户端找到了 Docker socket，但无法连接到 daemon。 它不等于 LangGraph 项目本身有问题。

Linux 服务器可以继续检查服务状态、尝试启动并读取服务日志：

systemctl status docker
sudo systemctl start docker
journalctl -u docker.service

如果服务已经运行，但当前用户仍然收到 socket 权限错误，应检查当前用户的组、Docker context 和 socket 所有者。不要为了绕过问题直接给 socket 开放全局写权限，那会把 Docker 控制权限暴露给更多本机用户。

macOS 和 Windows 通常由 Docker Desktop 管理 daemon，不能直接照搬 systemctl 命令。Windows 环境下还要分别确认 Docker Desktop 是否运行、当前终端是否位于启用了 Docker 的 WSL 发行版，以及 WSL integration 是否已经打开。

daemon 无法启动也可能由磁盘或内存不足引起，可同时检查：

df -h
free -h
docker system df

free -h 和 systemctl 适用于 Linux。不要把 docker system prune 当作自动修复命令；先确认待清理对象，其中可能包含仍在使用的镜像、缓存和已停止的容器。

依赖下载或构建上下文让构建中断

构建日志里最后出现的 “failed to solve” 通常只是汇总，应向前找第一处失败。基础镜像拉取失败，优先检查服务器到镜像仓库的 DNS、出口网络和代理；Python 依赖下载失败，则要区分软件源不可达、代理没有传给构建器、自定义 CA 未被信任，以及锁定了当前源无法提供的版本。

原生扩展还可能因为基础镜像缺少编译器、Python 开发头文件或系统库而失败。此时应先确认失败扩展及其版本，再决定补齐构建阶段依赖还是调整基础镜像，不要在 Dockerfile 中无目标地安装整套编译工具。

构建上下文过大也会让构建在上传上下文阶段中断。.dockerignore 至少要排除本机虚拟环境、缓存和敏感文件。下面是一份常见的起点配置，项目需要时应按实际目录调整：

.git/
.venv/
venv/
__pycache__/
*.py[cod]
.pytest_cache/
.mypy_cache/
.ruff_cache/
.DS_Store
.env
.env.*
!.env.example

模型目录只有在确实不应进入镜像时才排除。如果运行时必须使用这些文件，应通过明确的数据卷或制品流程提供，而不是无意间打进镜像。

依赖锁定文件、图配置和构建真正需要的静态文件则要保留。镜像的价值在于固化已经验证过的依赖组合，避免服务器在每次部署时重新解析版本而发生漂移。

图配置在构建或启动时被拒绝

先做 JSON 语法检查：

python -m json.tool langgraph.json >/dev/null

这一步只能证明它是合法 JSON，不能证明字段符合当前 CLI 版本的要求。还要核对当前版本支持的配置结构、图模块路径、导出对象以及依赖声明，不能直接复制旧教程或其他语言模板。

如果项目当前允许使用开发服务器，可以先用开发服务器模式缩小问题范围：

langgraph dev

相关资料中的 LangGraph 本地部署示例使用了 langgraph dev 进行本地开发和运行调试。 比较开发服务器和 Docker 构建的结果，可以缩小排查范围：

如果 langgraph dev 能运行而 Docker 构建失败，优先检查打包文件、依赖声明、构建上下文和镜像内的工作目录。如果两者都失败，通常应先处理图配置、导入路径或运行所需环境变量。langgraph dev 成功也不能证明生产依赖已经进入镜像，更不能替代数据库和任务队列检查。

对齐本地与服务器的运行差异

迁移前应同时记录两端的操作系统、CPU 架构、Docker 版本、Compose 版本和资源余量：

uname -m
cat /etc/os-release
docker version
docker compose version
df -h
free -h
docker buildx ls

不要默认“能在本机运行的镜像”在服务器上也能运行。macOS 上的 ARM 镜像、Linux 服务器上的 amd64 镜像，以及虚拟化环境中的架构标识需要分别核对。Windows 目录挂载、路径大小写和文件权限也与 Linux 原生目录不同；正式构建前，最好让源码位于服务器上的 Linux 原生路径，而不是依赖 WSL 或挂载盘。

镜像生成后可以检查它的系统与架构：

docker image inspect --format '{{.Os}}/{{.Architecture}}' <image>

离线镜像案例记录过从本地 arm64 环境构建 linux/amd64 镜像并交付 tar 的过程，也说明跨架构构建不能只看 Dockerfile 是否执行成功，还要检查最终镜像架构。

权限方面也要留意容器用户和宿主机目录的 UID、GID 是否匹配，尤其是数据卷写入、配置文件读取和日志目录。不要用 chmod -R 777 掩盖所有权问题。

把项目完整搬到服务器

源码迁移优先使用 Git，这样能保留提交记录，也便于确认服务器使用的版本。项目至少应包含源码、langgraph.json、依赖声明和锁定文件，以及项目实际使用的 Dockerfile、Compose 文件与启动脚本。

临时同步可以使用 rsync 或 scp，但不要顺手复制本机虚拟环境、缓存和明文 .env。例如：

rsync -av \
  --exclude='.git/' \
  --exclude='.venv/' \
  --exclude='venv/' \
  --exclude='.env' \
  ./ user@server:/srv/langgraph-app/

到达服务器后，先检查目录权限、脚本换行符和敏感文件，再验证 Compose 配置：

docker compose config >/dev/null

如果这里失败，应先修复 YAML、环境变量插值或缺失的运行时配置，不必立即执行构建。

服务器构建还依赖镜像仓库和软件源。如果服务器不能访问外网，应提前确认经过批准的代理、内部镜像源或私有仓库。不要在构建脚本里临时加入来源不明的下载地址；同样，运行时密钥也不应因为服务器不方便配置，就被烘焙进镜像。

在服务器构建可追踪的镜像

使用 CLI 构建前，先以当前安装版本的帮助信息确认参数：

langgraph build --help

然后记录完整构建日志：

set -o pipefail
langgraph build 2>&1 | tee build.log
docker image ls

如果当前版本支持自定义镜像标签，应使用包含应用版本或 Git 提交号的不可变标签。不要让生产环境只依赖 latest，因为它无法说明当前运行的究竟是哪次提交，也不适合作为可靠的回滚依据。

如果项目已经提供完整 Dockerfile 和 Compose 编排，并且这是仓库约定的构建入口，就按项目文档执行：

docker compose build

构建成功后再检查镜像架构和标签。需要推送到私有仓库时，确认目标平台允许写入该仓库和标签，再执行推送；不要在构建日志中输出仓库密码。

完全离线的服务器可以接收在联网机器上构建好的镜像，但目标架构必须匹配：

docker save -o langgraph-image.tar <image>
docker load -i langgraph-image.tar

在另一台机器上执行：

docker image inspect --format '{{.Os}}/{{.Architecture}}' <image>

已有实际案例可参考这种离线镜像交付流程。 但“能够导入”仍不等于“能够运行”，后续还要验证 Python 依赖、系统库和运行时配置。

容器启动失败要换一条排查路径

镜像构建成功只证明制品已经生成。容器立即退出时，应转查启动命令、环境变量、密钥、端口、数据库连接和任务队列。

docker compose up -d
docker compose ps
docker compose logs --tail=200 -f

如果 docker compose ps 显示容器持续重启，先从日志里找第一条异常，而不是只看最终退出状态。常见情况是运行时环境变量没有注入、镜像里缺少项目依赖、图模块导入失败、数据库连接参数错误、任务队列不可达，或者宿主机端口已被占用。

关于 LangGraph Server 部署的资料指出，部署对象不只包含一个或多个图，还包括用于持久化的数据库和任务队列。 因此应根据当前部署模式确认数据库、队列、连接串和相应服务是否可用。宿主机能连接数据库，不代表容器内也能通过 Compose 网络访问同一地址。

如果目标只是运行自己的 LangGraph 服务，可以把范围限定在 standalone server；需要控制平面或部署管理时，则属于另一条产品路线。 两种路线的配置和运行组件不能按同一套假设处理。

清理容器时也要先核对卷配置。不要把下面这条命令当成普通重启：

docker compose down -v

其中的 -v 会移除 Compose 管理的卷，可能连同需要保留的持久化数据一起删除。

用实际图调用完成验收

端口能建立 TCP 连接不代表服务已经可用。验收至少应覆盖以下几项：

1. 容器没有持续重启或退出，docker compose ps 能看到稳定运行状态。
2. 按当前版本文档定义的健康路径检查服务，而不是自行猜测一个固定接口。
3. 至少一个实际图能够接收请求并返回有效结果。
4. 创建一条带状态的调用，记录 thread 或项目实际使用的标识，验证关键状态已写入配置的后端。
5. 重启容器后再次读取同一状态，确认持久化确实生效。
6. 从反向代理或真实调用方一侧访问服务，而不是只在服务器本机测试。

重启验证可以使用：

docker compose restart

LangGraph 用于长时间运行、有状态的工作流，持久执行和状态存储本来就是其运行能力的一部分。 因此持久化验收应针对实际图和实际存储后端，不能用“容器还活着”代替。

如果任务图依赖队列，还应提交一次真实任务并确认它完成。否则，HTTP 接口正常但后台任务持续积压的问题仍会留到上线后。

发布更新与回滚

生产部署还要处理访问入口和运行生命周期。反向代理与 TLS 应指向实际容器服务，防火墙只开放必要端口；运行时密钥通过部署环境注入，容器重启策略、日志轮转、数据库或队列的数据卷也要明确配置。具体配置项应按当前 LangGraph、Compose 和服务器运行环境核对，不应直接套用其他版本模板。

更新流程保持固定：

1. 使用新版本或 Git 提交号构建不可变标签镜像。
2. 启动候选容器。
3. 调用实际图并验证状态持久化。
4. 切换反向代理或调用方流量。
5. 保留上一版本镜像及其配置。
6. 必要时将流量切回旧镜像并再次验证。

回滚不能只理解为重新启动旧容器。如果新版本改变了状态结构或执行了数据迁移，切回旧镜像可能还需要对应的数据迁移方案；这类变更应在发布前单独验证。生产更新时也不要立即清理上一镜像，至少保留到回滚路径完成一次实际验证。