记一次在Windows下部署FastAPI+LangGraph项目的踩坑实录

记一次在Windows下部署FastAPILangGraph项目的踩坑实录作者技术小白发布时间2026-08-06关键词Windows、Python虚拟环境、uv、make、Docker、FastAPI、LangGraph 写在前面最近在GitHub上找到一个非常赞的项目 ——fastapi-langgraph-agent-production-ready-template这是一个基于FastAPI和LangGraph的Agent生产级模板集成了PostgreSQL、Redis、监控等全套基础设施。项目文档很全但当我克隆下来准备在本地Windows环境运行调试时却遭遇了一连串的“水土不服”。本文完整记录了我从零开始成功跑起该项目的全过程希望给同样在Windows下折腾开源项目的你一些帮助。 环境说明操作系统Windows 11终端工具PowerShell后来切换为CMDPython版本3.12Docker Desktop已安装但未启动项目地址fastapi-langgraph-agent-production-ready-template 第一劫source命令无效错误现场powershellPS D:\project source .venv/bin/activate source : 无法将“source”项识别为 cmdlet、函数、脚本文件...原因分析source是Unix/Linux的shell内置命令用于在当前shell中执行脚本常用来激活虚拟环境。Windows下的PowerShell和CMD均不支持该命令。解决方案在PowerShell中应使用powershell.\.venv\Scripts\Activate.ps1如果遇到执行策略报错先执行powershellSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser在CMD中使用cmd.venv\Scripts\activate.bat 小贴士激活成功后命令行提示符前会出现(.venv)表明已在虚拟环境中。 第二劫make命令不存在错误现场powershellmake install make : 无法将“make”项识别为 cmdlet、函数、脚本文件...原因分析项目使用Makefile来管理构建任务如安装依赖、启动服务等但Windows默认没有make命令。解决方案备选方案一直接执行Makefile中的实质命令。通常make install对应的是pip install -r requirements.txt或pip install -e .可以手动运行cmdpip install -r requirements.txt或cmdpip install -e .备选方案二安装Windows版make通过Scoop或Chocolatey然后即可直接使用make。但建议新手先采用方案一避免额外工具依赖。 第三劫uv命令无法识别错误现场powershelluv sync uv : 无法将“uv”项识别为 cmdlet、函数、脚本文件...原因分析该项目的依赖管理使用uv一个极快的Python包管理器但系统并未安装uv或者虽然已通过pip install uv安装在用户目录但可执行文件未加入系统PATH导致终端找不到uv命令。解决方案我选择了最稳妥的方式在虚拟环境中安装uv并利用Python模块方式运行。cmdpip install uv python -m uv syncpython -m uv会直接执行uv模块无需uv命令在PATH中。执行后看到textResolved 172 packages in 3ms Checked 153 packages in 713ms表明依赖安装成功。 如果希望今后直接使用uv命令可在虚拟环境内重新安装确保python -m pip install uv此时uv.exe会出现在.venv\Scripts下即可直接用uv sync。 第四劫Docker Compose 环境变量未设置 镜像拉取失败错误现场cmddocker-compose up -d time... levelwarning msgThe \POSTGRES_DB\ variable is not set. Defaulting to a blank string. ... Error response from daemon: failed to resolve reference gcr.io/cadvisor/cadvisor:latest: ...原因分析Docker Compose依赖.env文件中的变量如数据库账号密码但项目提供的示例文件是.env.example并未自动创建.env。另外镜像gcr.io/cadvisor/cadvisor在国内无法直接拉取网络问题且Docker守护进程未启动也会导致连接失败。解决方案按顺序1. 启动Docker Desktop确保Docker Desktop已启动任务栏右下角鲸鱼图标稳定。验证docker version。2. 创建.env文件将示例文件复制为.envCMD下cmdcopy .env.example .env并检查其中是否包含必要的数据库配置如textPOSTGRES_DBmyapp POSTGRES_USERadmin POSTGRES_PASSWORD123456 POSTGRES_HOSTpostgres POSTGRES_PORT54323. 绕过不可拉的镜像临时方案docker-compose.yml中包含了cadvisor、Prometheus、Grafana等监控组件但这些镜像可能被墙。如果只想启动核心服务PostgreSQL和Redis/Valkey可以只启动这两个服务先查看docker-compose.yml中的服务名通常为postgres和valkey或redis然后执行cmddocker-compose up -d postgres valkey如果确实需要全量启动可修改docker-compose.yml注释掉cadvisor、prometheus、grafana块再执行docker-compose up -d。4. 验证运行cmddocker ps看到数据库和缓存容器正常Up即大功告成。✅ 最终成功启动应用完成以上步骤后虚拟环境已就绪依赖已安装数据库容器已启动。最后一步运行FastAPI应用。cmduvicorn app.main:app --reload --host 0.0.0.0 --port 8000如果项目使用Alembic等迁移工具还需在启动前执行cmdpython -m alembic upgrade head浏览器访问http://localhost:8000/docs看到自动生成的API文档说明部署成功 经验总结与避坑指南Unix命令不等于Windows命令source、make等在Windows下需寻找替代或手动执行等价操作。虚拟环境激活脚本因终端而异PowerShell用.ps1CMD用.batGit Bash可用source。Python工具链兼容性uv虽好但需确保其可执行文件在PATH中或使用python -m uv方式调用。Docker Compose与.env务必在项目根目录创建.env文件否则Compose无法注入环境变量。镜像拉取问题国内用户可配置Docker镜像加速器或暂时跳过非必需服务。多看Makefile和README项目作者通常会在Makefile中写明所有命令我们只需读懂并手动翻译为Windows可执行的命令即可。 相关资源uv官方文档Docker Desktop for WindowsMake for Windows (GnuWin32)希望这篇博客能帮助到同样在Windows下挣扎的小伙伴。如果你也有其他踩坑经历欢迎在评论区分享交流