chore(dev): 按端口杀进程树,避免 Windows 孤儿监听

新增 stop.bat/ps1/sh,并写入本地开发规则:停服务用脚本、停后复核端口。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-09-16 07:27:45 +08:00
parent 3e135542d3
commit 5052bcd805
7 changed files with 120 additions and 3 deletions

View File

@@ -1,5 +1,5 @@
---
description: 本地开发启动约定:后端工作目录、唯一数据目录、单实例,避免头像/上传 404
description: 本地开发启动/停止约定:工作目录、单实例、按端口杀进程树,避免孤儿进程与头像 404
alwaysApply: true
---
@@ -30,6 +30,33 @@ npm.cmd run dev
`:3000` 把 `/uploads` rewrite 到 `:3001`。头像 404 先查后端 `dataDir`,不要改前端。
## 进程生命周期(Windows 孤儿进程)
根因:Cursor/agent 停掉的往往是 **shell 父进程**;`go run` / `npm` 拉起的 `go.exe`/`node.exe`/编译产物仍在听端口,任务管理器里才看得见。
### Agent 必须遵守
1. **先查再启**:启动前用端口探测;`:3000`/`:3001` 已在听 → **复用**,禁止再开一份
2. **停服务优先跑脚本**(仓库根):
- Windows:`stop.bat`(内部调用 `stop.ps1`)
- Unix:`./stop.sh`
3. **禁止**只依赖「结束终端 / Ctrl+C / 杀 shell PID」当作已停干净
4. 无脚本时,Windows 用 **按端口 + 进程树** 清理(PowerShell):
```powershell
foreach ($port in 3000,3001) {
Get-NetTCPConnection -LocalPort $port -State Listen -EA SilentlyContinue |
Select-Object -ExpandProperty OwningProcess -Unique |
ForEach-Object { if ($_ -gt 0) { taskkill /T /F /PID $_ } }
}
```
5. 声称已停止后,**再查一次**端口是否空闲;仍占用则继续 `/T` 杀树,勿让用户去任务管理器
6. 默认**不动** Docker Postgres;用户要停库再 `docker compose down`
7. 会话结束前若本会话启动过前后端:主动清理或明确告知用户执行 `stop.bat`
### 用户侧
双击 / 运行仓库根 `stop.bat`(或 `./stop.sh`)即可,无需开任务管理器。
## 遗留目录
`backend/cmd/jiang13/data/` 是错误 cwd 的产物,禁止当数据源。发现后把 `uploads/` 合并进 `backend/data/uploads/`,再删遗留目录。