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

105 lines
3.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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(将 <PID> 换成上一步输出的数字;若有多个可多次执行)
Stop-Process -Id <PID> -Force
```
使用 `--reload` 时可能存在 **父进程(监视)+ 子进程(工作进程)**;若端口仍被占用,对查到的多个 PID 分别 `Stop-Process`,或关闭对应终端会话。
### 方式三:macOS / Linux
```bash
# 若已知 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](SETUP.md) 与 [CONFIGURATION.md](CONFIGURATION.md)。