3.3 KiB
3.3 KiB
DeerFlow Gateway 本地启停说明
后端目录:offline-backend-20260512/backend(下文简称 backend 目录)。
默认监听:http://0.0.0.0:8001(本机访问可用 http://127.0.0.1:8001)。
前置条件
- 已安装 Python 3.12+ 与 uv。
- 在 backend 目录 下存在
config.yaml(可从项目文档中的示例自行整理;仓库内config.yaml通常被 git 忽略)。 - 若
config.yaml里模型使用$OPENAI_API_KEY等形式,必须在环境中提供对应变量,否则启动时配置解析会失败。
启动(Windows PowerShell)
在 backend 目录 打开终端,执行:
cd f:\react01\deeflow\deerflow-server-master\offline-backend-20260512\backend
# 依赖(首次或依赖变更后)
uv sync
# 建议的环境变量(可按需增删)
$env:PYTHONPATH = "."
$env:OPENAI_API_KEY = "你的真实 API Key"
$env:DEER_FLOW_AUTH_DISABLED = "true"
$env:CORS_ORIGINS = "http://localhost:5173,http://localhost:3000"
# 开发模式:代码变更自动重载
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
无热重载(更接近生产单次进程):
$env:PYTHONPATH = "."
$env:OPENAI_API_KEY = "你的真实 API Key"
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
验证:浏览器或命令行访问 http://127.0.0.1:8001/health,应返回 JSON 且含 "status":"healthy"。API 文档:http://127.0.0.1:8001/docs。
启动(macOS / Linux,可选)
若已安装 make 且 Makefile 可用,在 backend 目录:
export OPENAI_API_KEY="你的真实 API Key"
make install # 等价 uv sync
make dev # 带 --reload,端口 8001
停止(暂停)服务
「暂停」在本地开发里一般指 结束 Gateway 进程,而不是挂起进程。
方式一:前台运行时(推荐)
在运行 uvicorn 的终端窗口按 Ctrl + C,等待进程退出即可。
方式二:需释放 8001 端口(Windows)
在 管理员或普通 PowerShell 中:
# 查看占用 8001 的监听进程 PID
Get-NetTCPConnection -LocalPort 8001 -State Listen -ErrorAction SilentlyContinue |
Select-Object -ExpandProperty OwningProcess -Unique
# 结束指定 PID(将 <PID> 换成上一步输出的数字;若有多个可多次执行)
Stop-Process -Id <PID> -Force
使用 --reload 时可能存在 父进程(监视)+ 子进程(工作进程);若端口仍被占用,对查到的多个 PID 分别 Stop-Process,或关闭对应终端会话。
方式三:macOS / Linux
# 若已知 uvicorn 在前台,仍用 Ctrl+C
# 或按端口查杀(示例)
lsof -i :8001
kill <PID>
常见问题
| 现象 | 处理 |
|---|---|
Environment variable OPENAI_API_KEY not found |
设置 $env:OPENAI_API_KEY(PowerShell)或写入 .env 后重启(项目会加载 dotenv)。 |
Address already in use / 端口占用 |
先按上文 停止 释放 8001,再启动。 |
| 前端跨域失败 | 将前端实际地址加入 CORS_ORIGINS(逗号分隔多个)。 |
更完整的配置说明见同目录下的 SETUP.md 与 CONFIGURATION.md。