From 0cbd137b4f161c99891c675a05e09f2587fb1ddb Mon Sep 17 00:00:00 2001
From: fengxiangdebaozi <10845145+fengxiangdebaozi@user.noreply.gitee.com>
Date: Wed, 13 May 2026 16:38:34 +0800
Subject: [PATCH] wendang1xiug1

---
 offline-backend-20260512/backend/CLAUDE.md    |   1 +
 offline-backend-20260512/backend/README.md    |   1 +
 .../backend/docs/BACKEND_RUN_STOP_ZH.md       | 126 ++++++++++++++++++
 offline-backend-20260512/backend/uv.lock      |   2 +
 4 files changed, 130 insertions(+)
 create mode 100644 offline-backend-20260512/backend/docs/BACKEND_RUN_STOP_ZH.md

diff --git a/offline-backend-20260512/backend/CLAUDE.md b/offline-backend-20260512/backend/CLAUDE.md
index ad89c1aa..c269035e 100644
--- a/offline-backend-20260512/backend/CLAUDE.md
+++ b/offline-backend-20260512/backend/CLAUDE.md
@@ -569,3 +569,4 @@ See `docs/` directory for detailed documentation:
 - [PATH_EXAMPLES.md](docs/PATH_EXAMPLES.md) - Path types and usage
 - [summarization.md](docs/summarization.md) - Context summarization
 - [plan_mode_usage.md](docs/plan_mode_usage.md) - Plan mode with TodoList
+- [BACKEND_RUN_STOP_ZH.md](docs/BACKEND_RUN_STOP_ZH.md) - Windows-first backend start/stop and troubleshooting guide
diff --git a/offline-backend-20260512/backend/README.md b/offline-backend-20260512/backend/README.md
index b8f0d62b..40e7e03b 100644
--- a/offline-backend-20260512/backend/README.md
+++ b/offline-backend-20260512/backend/README.md
@@ -411,6 +411,7 @@ uv run pytest
 - [Path Examples](docs/PATH_EXAMPLES.md)
 - [Context Summarization](docs/summarization.md)
 - [Plan Mode](docs/plan_mode_usage.md)
+- [Backend Run/Stop Guide (ZH)](docs/BACKEND_RUN_STOP_ZH.md)
 - [Setup Guide](docs/SETUP.md)
 
 ---
diff --git a/offline-backend-20260512/backend/docs/BACKEND_RUN_STOP_ZH.md b/offline-backend-20260512/backend/docs/BACKEND_RUN_STOP_ZH.md
new file mode 100644
index 00000000..e31c553c
--- /dev/null
+++ b/offline-backend-20260512/backend/docs/BACKEND_RUN_STOP_ZH.md
@@ -0,0 +1,126 @@
+# 后端启动与停止说明（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`。
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" },