From d23d871878819f157c680eee789515737c8e53b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= Date: Wed, 13 May 2026 14:09:55 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BB=A3=E7=A0=81=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- frontend-web/.env.development | 4 + frontend-web/.env.example | 7 ++ .../backend/docs/本地服务启停说明.md | 104 ++++++++++++++++++ offline-backend-20260512/backend/uv.lock | 2 + 4 files changed, 117 insertions(+) create mode 100644 frontend-web/.env.development create mode 100644 frontend-web/.env.example create mode 100644 offline-backend-20260512/backend/docs/本地服务启停说明.md diff --git a/frontend-web/.env.development b/frontend-web/.env.development new file mode 100644 index 00000000..075f4896 --- /dev/null +++ b/frontend-web/.env.development @@ -0,0 +1,4 @@ +# 本地开发：直连 Gateway（与 offline-backend-20260512/backend 默认端口一致） +# 修改端口时请同步改这里，并重启 `npm run dev` +VITE_BACKEND_BASE_URL=http://127.0.0.1:8001 +VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api diff --git a/frontend-web/.env.example b/frontend-web/.env.example new file mode 100644 index 00000000..92f07d02 --- /dev/null +++ b/frontend-web/.env.example @@ -0,0 +1,7 @@ +# 复制为 .env 或 .env.development 后按需修改（Vite 仅暴露以 VITE_ 开头的变量） +# +# Gateway 根地址（REST：`/api/models`、`/api/threads/...` 等） +VITE_BACKEND_BASE_URL=http://127.0.0.1:8001 +# +# LangGraph SDK 的 apiUrl：须指向带 `/api` 的前缀，以便请求落在 `/api/threads`、`/api/assistants` 等路由上 +VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api diff --git a/offline-backend-20260512/backend/docs/本地服务启停说明.md b/offline-backend-20260512/backend/docs/本地服务启停说明.md new file mode 100644 index 00000000..f52116b3 --- /dev/null +++ b/offline-backend-20260512/backend/docs/本地服务启停说明.md @@ -0,0 +1,104 @@ +# 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)。 diff --git a/offline-backend-20260512/backend/uv.lock b/offline-backend-20260512/backend/uv.lock index 378bbb84..43e8f4d5 100644 --- a/offline-backend-20260512/backend/uv.lock +++ b/offline-backend-20260512/backend/uv.lock @@ -745,6 +745,7 @@ version = "0.1.0" source = { virtual = "." } dependencies = [ { name = "bcrypt" }, + { name = "croniter" }, { name = "deerflow-harness" }, { name = "dingtalk-stream" }, { name = "email-validator" }, @@ -778,6 +779,7 @@ dev = [ [package.metadata] requires-dist = [ { name = "bcrypt", specifier = ">=4.0.0" }, + { name = "croniter", specifier = ">=6.2.2" }, { name = "deerflow-harness", editable = "packages/harness" }, { name = "deerflow-harness", extras = ["postgres"], marker = "extra == 'postgres'", editable = "packages/harness" }, { name = "dingtalk-stream", specifier = ">=0.24.3" },