# 后端启动与停止说明（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`。