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

(红头)Windows 服务器启动与重启唯一指南（1.0 版本）

替代旧版，后续只看这一份。
仓库路径：D:\workspace\aiagent（若你的路径不同，替换下文所有路径即可）

---

0. 快速参考卡片

cd D:\workspace\aiagent

# 最常用 — 全套重启
powershell -ExecutionPolicy Bypass -File .\scripts\startup\manage.ps1 restart

# 查看服务状态
powershell -ExecutionPolicy Bypass -File .\scripts\startup\manage.ps1 status

# 只改后端代码后（保留 Redis + 前端）
powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1

服务	端口	说明
前端 Vite	3001	http://localhost:3001
后端 API	8037（主）/ 8041（备）	http://127.0.0.1:8037/docs
Redis	6379	restart_backend_celery.ps1 会自动守护
Celery Worker	—	Agent 异步执行
Celery Beat	—	定时任务调度

---

1. manage.ps1 — 统一管理（推荐）

一条命令管理所有服务，替代原来散落的 start/stop/restart。

cd D:\workspace\aiagent
powershell -ExecutionPolicy Bypass -File .\scripts\startup\manage.ps1 <动作>

动作	功能
status	检查所有服务状态（端口 + 健康检查）
start	启动全部：Redis → API(自动选端口) → Celery → 前端
stop	停止全部服务，显示端口释放情况
restart	= stop + start，推荐用于全套重启

1.1 start 自动处理

• 端口探测：8037 被占用自动切 8041
• Redis 守护：不在运行则自动拉起
• 前端代理对齐：自动设置 AIAGENT_API_PROXY 指向实际 API 端口
• 健康检查：启动后等待最多 30s，确认 API /docs 和前端端口可达

1.2 输出示例

== 启动所有服务 ==
>>> 1/5 Redis
  [OK] Redis 已启动 (端口 6379)
>>> 2/5 后端 API 端口探测
  [OK] 端口 8037 可用
>>> 3/5 后端 API (端口 8037)
  [OK] 后端 API 已启动 (PID=12345)
>>> 4/5 Celery Worker + Beat
  [OK] Celery Worker 已在新窗口启动 (PID=12346)
  [OK] Celery Beat 已在新窗口启动 (PID=12347)
>>> 5/5 前端 Vite (端口 3001)
  [OK] 前端 Vite 已启动 (PID=12348)

>>> 健康检查（等待服务就绪，最多 30 秒）
  [OK] 所有服务就绪（耗时 12s）

═══════════════════════════════════════════
  启动完成
═══════════════════════════════════════════
  后端文档: http://127.0.0.1:8037/docs
  前端页面: http://localhost:3001
  Agent对话: http://localhost:3001/agent-chat

---

2. restart_backend_celery.ps1 — 仅重启后端（保留 Redis + 前端）

适用场景：只改了 Python 代码、.env、依赖、工具实现。

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

关键改进（1.0 新增）：

• 重启 API + Celery 后自动检查 Redis 是否在运行
• Redis 不在则自动拉起（不再出现"重启后登录报 500"）
• 不会主动停止 Redis 或前端

---

3. 手动应急启动（manage.ps1 不可用时）

开 3~5 个终端：

1) Redis

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

2) API

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

3) Celery Worker

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

4) 前端

cd D:\workspace\aiagent\frontend
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'
npx vite --port 3001 --host 0.0.0.0

5) Celery Beat（定时任务，可选）

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

---

4. 常见故障速查

4.1 登录报 500 / "服务器内部错误"

根因：Redis 未运行。 restart_backend_celery.ps1 旧版只重启 API+Celery，不检查 Redis。1.0 版已修复。

手动修复：

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

4.2 TTS 朗读声音机械不自然

根因： 后端 edge-tts CLI 子进程找不到，降级到浏览器机械语音。

日志特征：

ERROR | Edge TTS 失败:
POST /api/v1/voice/tts - 状态码: 502

已修复： voice.py 改用 Python 库直接调用，不再依赖外部 CLI PATH。

详细排查见 docs/troubleshooting/TTS朗读声音机械不自然.md。

4.3 端口 8037 被僵尸进程占用

现象： netstat 显示 8037 LISTENING，但 tasklist 找不到对应 PID。

解决：

• manage.ps1 start 会自动探测并切换到 8041
• 必须清理 8037：重启 Windows，或 netsh interface ipv4 show excludedportrange protocol=tcp 检查是否与 Hyper-V 动态端口冲突

4.4 Agent 执行超时 timeout of 30000ms exceeded

优先检查：

1. Redis 是否在 6379 监听：netstat -ano | findstr :6379
2. .env 中 REDIS_URL 是否与 Redis 实际端口一致（应为 redis://localhost:6379/0）
3. Celery Worker 是否在运行

4.5 一键脚本报 PowerShell 解析错误

Set-ExecutionPolicy -Scope Process Bypass

或将脚本保存为 UTF-8 with BOM 重新执行。

---

5. 端口说明

服务	主端口	备用端口	启动方式
前端 Vite	3001	—	manage.ps1 / 手动
后端 API	8037	8041	manage.ps1 自动探测
Redis	6379	—	manage.ps1 自动守护

---

6. 访问地址

• 前端：http://localhost:3001
• Agent 对话：http://localhost:3001/agent-chat
• 后端文档：http://127.0.0.1:8037/docs（若切到 8041 则改端口）
• 健康检查：curl.exe -s -o NUL -w "%{http_code}" http://127.0.0.1:8037/docs（返回 200 即正常）

---

7. 维护规则（强制）

• 所有启动/重启内容只维护本文件
• 建议用 manage.ps1 替代旧脚本进行全套操作
• restart_backend_celery.ps1 仅用于"只改后端代码"的场景
• 修改启动逻辑后，先更新本文档