2.9 KiB
2.9 KiB
后端启动与停止说明（Windows 优先）
本文档用于 offline-backend-20260512/backend 目录下 DeerFlow 后端的日常启动、停止与排障。
1. 前置条件
- 已安装 Python 3.12+
- 已安装
uv - 已在项目中准备好配置文件（通常是项目根目录
config.yaml）
2. 进入后端目录
cd F:\react\deeflow-code\deerflow-server-master\offline-backend-20260512\backend
3. 首次安装依赖
方案 A（优先，跨平台）
uv sync
方案 B（如果你的环境里 make 可用）
make install
Windows 上部分
make.exe与 GNU Make 不兼容，若报错请直接使用uv sync。
4. 启动后端
4.1 生产样式（无热重载）
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
4.2 开发样式（热重载）
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
如果你的 make 可用，也可以：
make gateway # 无热重载
make dev # 热重载
5. 验证是否启动成功
启动后可访问：
- 文档页：
http://127.0.0.1:8001/docs - OpenAPI：
http://127.0.0.1:8001/openapi.json - 健康检查：
http://127.0.0.1:8001/health
PowerShell 快速检查：
(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8001/health).StatusCode
返回 200 即正常。
6. 停止后端
6.1 前台启动时
在运行窗口按 Ctrl + C。
6.2 后台或端口占用时（Windows）
按 8001 端口查进程并强制结束：
Get-NetTCPConnection -LocalPort 8001 -State Listen | Select-Object OwningProcess
Stop-Process -Id <PID> -Force
一键方式（自动停止 8001 的监听进程）：
$procIds = @(Get-NetTCPConnection -LocalPort 8001 -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess -Unique)
foreach ($oneId in $procIds) { Stop-Process -Id $oneId -Force -ErrorAction SilentlyContinue }
7. 常见问题
7.1 make gateway 报 unknown action keyword
说明当前 make 不是预期版本（Windows 常见）。直接改用：
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
7.2 PowerShell 报 && 语法错误
PowerShell 5 不支持 Bash 风格 &&。请改成分号：
uv sync; $env:PYTHONPATH='.'; uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
7.3 Git 切分支时 .deer-flow/data/*.db-wal|*.db-shm 无法删除
通常是后端进程仍占用 SQLite 文件。先停掉 8001 端口进程，再执行 Git 操作。
8. 推荐日常流程（Windows）
cd F:\react\deeflow-code\deerflow-server-master\offline-backend-20260512\backend
uv sync
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
停止时按 Ctrl + C。