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