diff --git a/服务启停说明.md b/服务启停说明.md new file mode 100644 index 00000000..348fa7e6 --- /dev/null +++ b/服务启停说明.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 /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 +``` + +再启动。