文档修改

服务启停说明.md

@@ -0,0 +1,113 @@
+# 后端服务启停说明（Windows）
+
+你当前是 **Windows + PowerShell** 环境，下面这份是可直接用的后端启停命令。
+
+> 说明：仓库里的 `scripts/*.sh` 是 Bash 脚本，Windows 原生 PowerShell 不能直接执行，所以会出现“启动不了”。
+
+## 一、后端目录
+
+后端目录：
+
+```text
+offline-backend-20260512/backend/
+```
+
+下面命令默认都在这个目录执行。
+
+---
+
+## 二、Windows 下推荐启动方式
+
+### 1) 开发模式启动（热重载）
+
+```powershell
+uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
+```
+
+### 2) 普通模式启动（无热重载）
+
+```powershell
+uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+```
+
+> 如果你习惯 `make dev / make gateway`，Windows 上通常还需要额外安装 make，建议直接用上面两条 `uv run uvicorn` 更稳。
+
+---
+
+## 三、停止后端
+
+如果后端在当前窗口前台运行：
+
+- 直接按 `Ctrl + C`
+
+如果窗口已经关了，或你想强制结束 8001 端口进程：
+
+```powershell
+netstat -ano | findstr :8001
+```
+
+记下最后一列 PID 后执行：
+
+```powershell
+taskkill /PID <PID> /F
+```
+
+---
+
+## 四、首次安装依赖（只需一次）
+
+在 `offline-backend-20260512/backend` 目录执行：
+
+```powershell
+uv sync
+```
+
+如果 `uv` 命令不存在，先安装（任选其一）：
+
+```powershell
+pip install uv
+```
+
+或（已安装 winget 时）：
+
+```powershell
+winget install --id Astral-sh.uv -e
+```
+
+---
+
+## 五、快速自检
+
+启动后浏览器访问：
+
+- [http://localhost:8001/health](http://localhost:8001/health)
+
+返回健康状态即表示后端正常。
+
+---
+
+## 六、常见问题
+
+### 1) 报错：端口 8001 被占用
+
+先执行：
+
+```powershell
+netstat -ano | findstr :8001
+```
+
+然后 `taskkill` 对应 PID，再重启后端。
+
+### 2) 报错：`uv` 不是内部或外部命令
+
+先安装 `uv`（见上面的“首次安装依赖”），安装后重开一个 PowerShell 窗口再试。
+
+### 3) 报错：模块/依赖缺失
+
+重新执行：
+
+```powershell
+uv sync
+```
+
+再启动。