aiagent/docs/startup-deploy/(红头)Windows服务器启动与重启唯一指南.md

(红头)Windows 服务器启动与重启唯一指南

本文是 D:\aaa\aiagent 在 Windows 本地开发环境下的唯一启动/重启文档。
后续只看这一份即可。

---

0. 统一结论（先看）

• 推荐端口：
  • 前端：3001
  • 后端 API：8037（若被占用，一键启动会自动改用备用 8041）
  • Redis：6379
• 一键脚本目录：均在仓库内 scripts\startup\，在根目录 D:\aaa\aiagent 下执行时路径为 .\scripts\startup\*.ps1（勿写成根目录下的 .\start_aiagent.ps1）。
• backend/.env 必须与实际 Redis 端口一致：
  • 推荐：REDIS_URL=redis://localhost:6379/0
• 任何 .env / 依赖 / 工具代码变更后，至少重启：
  • API + Celery（scripts\startup\restart_backend_celery.ps1）
• 若出现 timeout of 30000ms exceeded，优先检查：
  1. Redis 是否可连
  2. Celery Worker 是否在跑
  3. API 与 Worker 是否使用同一 backend\venv

---

1. 一键启动 / 停止 / 重启

在 PowerShell 中执行（仓库根目录）：

cd D:\aaa\aiagent

1.1 一键启动（全套）

powershell -ExecutionPolicy Bypass -File .\scripts\startup\start_aiagent.ps1

默认目标：

• 前端：http://localhost:3001
• 后端文档：优先 http://127.0.0.1:8037/docs；若脚本提示已切到 8041，则打开 http://127.0.0.1:8041/docs
• Redis：127.0.0.1:6379

一键启动会为每个进程新开 PowerShell 窗口（含 Celery Worker 与 Celery Beat）。若控制台一闪退出，请到该窗口里看报错。

1.2 一键停止（全套）

powershell -ExecutionPolicy Bypass -File .\scripts\startup\stop_aiagent.ps1

1.3 仅重启后端 + Celery（最常用）

powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1

适用场景：改了 .env、Python 依赖、内置工具实现、Agent 执行逻辑。

说明：该脚本固定把 API 起在 8037。若本机 8037 被其它程序或异常状态占用，请先 stop 全套或释放端口后再执行。

1.4 仅重启前端（不动 Redis / 后端）

适用：只改了前端代码或 Vite 配置，需要刷新 dev 进程。

1. 结束占用 3001 的进程（任务管理器结束对应 node/pnpm，或用资源监视器按端口查 PID 后结束）。
2. 确认当前 API 端口（一般为 8037；若全套启动时曾提示改用 8041，则与之一致）。
3. 新开 PowerShell：

cd D:\aaa\aiagent\frontend
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'   # 若 API 在 8041，改为 ...8041
pnpm dev --port 3001

浏览器请优先用 http://localhost:3001 访问（Vite 常只绑 [::1]，用 127.0.0.1:3001 可能连不上，属正常现象）。

---

2. 标准“重启服务器”流程（推荐照抄）

cd D:\aaa\aiagent
powershell -ExecutionPolicy Bypass -File .\scripts\startup\stop_aiagent.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\startup\start_aiagent.ps1

若 start 输出中出现 Port 8037 is occupied, switching to 8041，则本次 API 在 8041，下文健康检查与文档地址请改用 8041（前端新窗口里的 AIAGENT_API_PROXY 已指向该端口）。

完成后立刻验证（PowerShell 中 curl 多为 Invoke-WebRequest 别名，建议用 curl.exe）：

netstat -ano | findstr :6379
netstat -ano | findstr :8037
netstat -ano | findstr :8041
netstat -ano | findstr :3001
curl.exe -s -o NUL -w "%{http_code}" http://127.0.0.1:8037/health
curl.exe -s -o NUL -w "%{http_code}" http://127.0.0.1:8041/health

若 API 实际在 8041，刚启动后 10～20 秒内 /health 可能仍超时，属 uvicorn 拉起过程；前端 3001 可先就绪。

---

3. 本次故障复盘（学生作业管理助手超时）

3.1 现象

• Agent 对话区报错：发送失败: timeout of 30000ms exceeded
• 前端可打开，但执行一直超时。

3.2 根因

1. backend/.env 配置为：
   • REDIS_URL=redis://localhost:6380/0
2. 实际 Redis 监听在：
   • 6379
3. 导致 Celery 任务队列链路异常（或 Worker 无法稳定消费），Agent 执行超时。

3.3 修复

1. 将 backend/.env 改为：
   • REDIS_URL=redis://localhost:6379/0
2. 执行：
   • powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1
3. 验证：
   • 6379/8037/3001 监听正常
   • /health 返回 200
   • Celery worker 进程存在

3.4 预防

• 不要混用两套端口约定（6379 与 6380）。
• 每次重启后先做 1 分钟健康检查（端口 + /health + 1 条 Agent 测试消息）。

---

4. 常见问题与快速处理

4.1 执行策略拦截脚本

Set-ExecutionPolicy -Scope Process Bypass

4.2 start_aiagent.ps1 报 PowerShell 解析错误

症状：出现 ParserError、字符串终止符缺失、[OK] 附近报错。

处理：

1. 临时手动启动（见 4.3）
2. 将脚本保存为 UTF-8（建议无 BOM）/ ASCII 兼容内容，避免中文引号或异常字符

4.3 一键脚本不可用时的手动拉起（应急）

开 5 个终端（与一键启动对齐；若暂不需要定时任务可省略 Beat）：

1. Redis

cd D:\aaa\aiagent\backend\redis
.\redis-server.exe --port 6379

2. API

cd D:\aaa\aiagent\backend
.\venv\Scripts\Activate.ps1
python -m uvicorn app.main:app --host 0.0.0.0 --port 8037

3. Celery

cd D:\aaa\aiagent\backend
.\venv\Scripts\Activate.ps1
python -m celery -A app.core.celery_app worker --loglevel=info --pool=threads --concurrency=8

4. 前端

cd D:\aaa\aiagent\frontend
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'
pnpm dev --port 3001

5. Celery Beat（与一键 start_aiagent.ps1 对齐；定时任务依赖此项）

cd D:\aaa\aiagent\backend
.\venv\Scripts\Activate.ps1
python -m celery -A app.core.celery_app beat --loglevel=info

4.4 8037「占用」与 netstat 幽灵 PID（实践经验）

部分 Windows 环境会出现：

• start_aiagent.ps1 提示 8037 被占用，自动改用 8041；
• netstat 仍显示 0.0.0.0:8037 LISTENING 且带某一 PID，但 tasklist 查不到该 PID（或无法 Stop-Process）。

此时以 start 脚本打印的实际端口为准（多为 8041），用 http://127.0.0.1:8041/docs 与对应 /health 验证即可。若必须清理 8037，可本机执行 netsh interface ipv4 show excludedportrange protocol=tcp 查看是否与 Hyper-V / 动态端口保留冲突，或重启 Windows 后再全套启动。

4.5 stop 已正常但 start 报「8037 与 8041 均占用」

曾出现：stop 对后端端口打印 SKIP，端口检查却仍显示 LISTEN，随后 start 抛出双端口占用。根因是旧版 stop_aiagent.ps1 中 ForEach-Object 内误用 return（会从整个函数提前返回）以及内层 $pid 变量名与 PowerShell 只读自动变量冲突，导致未真正枚举监听 PID。

当前仓库内 scripts\startup\stop_aiagent.ps1 已按上述问题修复；若你本地脚本被回退或拷贝了旧版，请与仓库版本对齐后再执行全套重启。

---

5. OCR（上传图片识别）必查项

backend/.env 建议：

TESSERACT_CMD=C:/Program Files/Tesseract-OCR/tesseract.exe
TESSERACT_TESSDATA_DIR=D:/aaa/aiagent/tessdata

自检：

cd D:\aaa\aiagent\backend
.\venv\Scripts\python scripts\check_ocr_env.py

若新增依赖后仍报 OCR 缺失，重启 Celery。

---

6. 访问地址

• 前端：http://localhost:3001（推荐用 localhost，避免与 [::1] 绑定不一致）
• 后端 API（默认）：http://127.0.0.1:8037
• 后端文档（默认）：http://127.0.0.1:8037/docs
• 健康检查（默认）：http://127.0.0.1:8037/health
• 若一键启动提示改用 8041：将上述三项中的端口改为 8041 即可。

---

7. 维护规则（强制）

• 所有 Windows 启动/重启内容只维护本文件。
• 其他旧文档仅保留跳转，不再写重复步骤。
• 修改启动逻辑后，先更新本文件再通知团队。