Files
2026-05-13 14:09:55 +08:00

3.3 KiB
Raw Permalink Blame History

DeerFlow Gateway 本地启停说明

后端目录:offline-backend-20260512/backend(下文简称 backend 目录)。

默认监听:http://0.0.0.0:8001(本机访问可用 http://127.0.0.1:8001)。


前置条件

  1. 已安装 Python 3.12+ 与 uv。
  2. 在 backend 目录 下存在 config.yaml(可从项目文档中的示例自行整理;仓库内 config.yaml 通常被 git 忽略)。
  3. 若 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。