127 lines
2.9 KiB
Markdown
127 lines
2.9 KiB
Markdown
# 后端启动与停止说明（Windows 优先）
|
||
|
||
本文档用于 `offline-backend-20260512/backend` 目录下 DeerFlow 后端的日常启动、停止与排障。
|
||
|
||
## 1. 前置条件
|
||
|
||
- 已安装 Python 3.12+
|
||
- 已安装 `uv`
|
||
- 已在项目中准备好配置文件（通常是项目根目录 `config.yaml`）
|
||
|
||
## 2. 进入后端目录
|
||
|
||
```powershell
|
||
cd F:\react\deeflow-code\deerflow-server-master\offline-backend-20260512\backend
|
||
```
|
||
|
||
## 3. 首次安装依赖
|
||
|
||
### 方案 A（优先，跨平台）
|
||
|
||
```powershell
|
||
uv sync
|
||
```
|
||
|
||
### 方案 B（如果你的环境里 `make` 可用）
|
||
|
||
```powershell
|
||
make install
|
||
```
|
||
|
||
> Windows 上部分 `make.exe` 与 GNU Make 不兼容，若报错请直接使用 `uv sync`。
|
||
|
||
## 4. 启动后端
|
||
|
||
### 4.1 生产样式（无热重载）
|
||
|
||
```powershell
|
||
$env:PYTHONPATH='.'
|
||
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
|
||
```
|
||
|
||
### 4.2 开发样式（热重载）
|
||
|
||
```powershell
|
||
$env:PYTHONPATH='.'
|
||
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
|
||
```
|
||
|
||
如果你的 `make` 可用，也可以：
|
||
|
||
```powershell
|
||
make gateway # 无热重载
|
||
make dev # 热重载
|
||
```
|
||
|
||
## 5. 验证是否启动成功
|
||
|
||
启动后可访问：
|
||
|
||
- 文档页：`http://127.0.0.1:8001/docs`
|
||
- OpenAPI：`http://127.0.0.1:8001/openapi.json`
|
||
- 健康检查：`http://127.0.0.1:8001/health`
|
||
|
||
PowerShell 快速检查：
|
||
|
||
```powershell
|
||
(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8001/health).StatusCode
|
||
```
|
||
|
||
返回 `200` 即正常。
|
||
|
||
## 6. 停止后端
|
||
|
||
### 6.1 前台启动时
|
||
|
||
在运行窗口按 `Ctrl + C`。
|
||
|
||
### 6.2 后台或端口占用时（Windows）
|
||
|
||
按 8001 端口查进程并强制结束：
|
||
|
||
```powershell
|
||
Get-NetTCPConnection -LocalPort 8001 -State Listen | Select-Object OwningProcess
|
||
Stop-Process -Id <PID> -Force
|
||
```
|
||
|
||
一键方式（自动停止 8001 的监听进程）：
|
||
|
||
```powershell
|
||
$procIds = @(Get-NetTCPConnection -LocalPort 8001 -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess -Unique)
|
||
foreach ($oneId in $procIds) { Stop-Process -Id $oneId -Force -ErrorAction SilentlyContinue }
|
||
```
|
||
|
||
## 7. 常见问题
|
||
|
||
### 7.1 `make gateway` 报 unknown action keyword
|
||
|
||
说明当前 `make` 不是预期版本（Windows 常见）。直接改用：
|
||
|
||
```powershell
|
||
$env:PYTHONPATH='.'
|
||
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
|
||
```
|
||
|
||
### 7.2 PowerShell 报 `&&` 语法错误
|
||
|
||
PowerShell 5 不支持 Bash 风格 `&&`。请改成分号：
|
||
|
||
```powershell
|
||
uv sync; $env:PYTHONPATH='.'; uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
|
||
```
|
||
|
||
### 7.3 Git 切分支时 `.deer-flow/data/*.db-wal|*.db-shm` 无法删除
|
||
|
||
通常是后端进程仍占用 SQLite 文件。先停掉 8001 端口进程，再执行 Git 操作。
|
||
|
||
## 8. 推荐日常流程（Windows）
|
||
|
||
```powershell
|
||
cd F:\react\deeflow-code\deerflow-server-master\offline-backend-20260512\backend
|
||
uv sync
|
||
$env:PYTHONPATH='.'
|
||
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
|
||
```
|
||
|
||
停止时按 `Ctrl + C`。
|