记一次在Windows下部署FastAPI+LangGraph项目的踩坑实录
作者：技术小白
发布时间：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（后来切换为CMD）
Python版本：3.12
Docker Desktop：已安装但未启动
项目地址：
fastapi-langgraph-agent-production-ready-template
💥 第一劫：source命令无效
错误现场
powershell
PS D:\project> source .venv/bin/activate source : 无法将“source”项识别为 cmdlet、函数、脚本文件...
原因分析
source是Unix/Linux的shell内置命令，用于在当前shell中执行脚本（常用来激活虚拟环境）。Windows下的PowerShell和CMD均不支持该命令。
解决方案
在PowerShell中，应使用：
powershell
.\.venv\Scripts\Activate.ps1
如果遇到执行策略报错，先执行：
powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
在CMD中，使用：
cmd
.venv\Scripts\activate.bat
💡 小贴士：激活成功后，命令行提示符前会出现
(.venv)，表明已在虚拟环境中。
💥 第二劫：make命令不存在
错误现场
powershell
make install make : 无法将“make”项识别为 cmdlet、函数、脚本文件...
原因分析
项目使用Makefile来管理构建任务（如安装依赖、启动服务等），但Windows默认没有make命令。
解决方案
备选方案一：直接执行Makefile中的实质命令。通常
make install对应的是pip install -r requirements.txt或pip install -e .，可以手动运行：cmd
pip install -r requirements.txt
或
cmd
pip install -e .
备选方案二：安装Windows版make（通过Scoop或Chocolatey），然后即可直接使用
make。但建议新手先采用方案一，避免额外工具依赖。
💥 第三劫：uv命令无法识别
错误现场
powershell
uv sync uv : 无法将“uv”项识别为 cmdlet、函数、脚本文件...
原因分析
该项目的依赖管理使用uv（一个极快的Python包管理器），但系统并未安装uv，或者虽然已通过pip install uv安装在用户目录，但可执行文件未加入系统PATH，导致终端找不到uv命令。
解决方案
我选择了最稳妥的方式：在虚拟环境中安装uv，并利用Python模块方式运行。
cmd
pip install uv python -m uv sync
python -m uv会直接执行uv模块，无需uv命令在PATH中。执行后看到：
text
Resolved 172 packages in 3ms Checked 153 packages in 713ms
表明依赖安装成功。
💡 如果希望今后直接使用
uv命令，可在虚拟环境内重新安装（确保python -m pip install uv），此时uv.exe会出现在.venv\Scripts下，即可直接用uv sync。
💥 第四劫：Docker Compose 环境变量未设置 & 镜像拉取失败
错误现场
cmd
docker-compose up -d time="..." level=warning msg="The \"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文件
将示例文件复制为.env（CMD下）：
cmd
copy .env.example .env
并检查其中是否包含必要的数据库配置，如：
text
POSTGRES_DB=myapp POSTGRES_USER=admin POSTGRES_PASSWORD=123456 POSTGRES_HOST=postgres POSTGRES_PORT=5432
3. 绕过不可拉的镜像（临时方案）
docker-compose.yml中包含了cadvisor、Prometheus、Grafana等监控组件，但这些镜像可能被墙。如果只想启动核心服务（PostgreSQL和Redis/Valkey），可以只启动这两个服务：
先查看docker-compose.yml中的服务名（通常为postgres和valkey或redis），然后执行：
cmd
docker-compose up -d postgres valkey
如果确实需要全量启动，可修改docker-compose.yml，注释掉cadvisor、prometheus、grafana块，再执行docker-compose up -d。
4. 验证运行
cmd
docker ps
看到数据库和缓存容器正常Up，即大功告成。
✅ 最终成功启动应用
完成以上步骤后，虚拟环境已就绪，依赖已安装，数据库容器已启动。最后一步：运行FastAPI应用。
cmd
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
如果项目使用Alembic等迁移工具，还需在启动前执行：
cmd
python -m alembic upgrade head
浏览器访问http://localhost:8000/docs，看到自动生成的API文档，说明部署成功！🎉
📝 经验总结与避坑指南
Unix命令不等于Windows命令：
source、make等在Windows下需寻找替代或手动执行等价操作。虚拟环境激活脚本因终端而异：PowerShell用
.ps1，CMD用.bat，Git Bash可用source。Python工具链兼容性：
uv虽好，但需确保其可执行文件在PATH中，或使用python -m uv方式调用。Docker Compose与.env：务必在项目根目录创建
.env文件，否则Compose无法注入环境变量。镜像拉取问题：国内用户可配置Docker镜像加速器，或暂时跳过非必需服务。
多看Makefile和README：项目作者通常会在Makefile中写明所有命令，我们只需读懂并手动翻译为Windows可执行的命令即可。
🔗 相关资源
uv官方文档
Docker Desktop for Windows
Make for Windows (GnuWin32)
希望这篇博客能帮助到同样在Windows下挣扎的小伙伴。如果你也有其他踩坑经历，欢迎在评论区分享交流！😊