diff --git a/docs/BACKEND_FIX.md b/docs/BACKEND_FIX.md new file mode 100644 index 0000000..01781de --- /dev/null +++ b/docs/BACKEND_FIX.md @@ -0,0 +1,120 @@ +# 后端服务问题修复 + +## 🐛 问题原因 + +**错误现象:** +- 前端访问报错:`Error: connect ECONNREFUSED 127.0.0.1:8000` +- 后端服务启动后立即关闭 + +**根本原因:** +后端使用了 `reload=settings.DEBUG` 模式,与 nohup 后台运行冲突,导致进程管理混乱。 + +## ✅ 已修复 + +已修改 `start.sh` 启动脚本: + +**修复前:** +```bash +nohup python -m app.main >> "$BACKEND_LOG" 2>&1 & +``` + +**修复后:** +```bash +nohup uvicorn app.main:app --host 0.0.0.0 --port 8000 >> "$BACKEND_LOG" 2>&1 & +``` + +**改进:** +- 直接使用 uvicorn 命令启动 +- 不使用 reload 模式(适合生产环境) +- 进程管理更稳定 + +## 🔄 重启服务 + +**方式 1: 一键重启(推荐)** + +```bash +./stop.sh && sleep 2 && ./start.sh +``` + +**方式 2: 手动重启** + +```bash +# 停止所有服务 +pkill -f "uvicorn" +pkill -f "vite" + +# 等待进程完全停止 +sleep 2 + +# 重新启动 +./start.sh +``` + +**方式 3: 使用 Makefile** + +```bash +make restart +``` + +## 🧪 验证修复 + +重启后,检查服务状态: + +```bash +./status.sh +``` + +应该看到: +``` +后端服务: + 状态: ✓ 运行中 + 地址: http://localhost:8000 + +前端服务: + 状态: ✓ 运行中 + 地址: http://localhost:5173 +``` + +**测试后端:** +```bash +curl http://localhost:8000/health +# 应返回: {"status":"healthy","version":"1.0.0"} +``` + +**测试前端:** +打开浏览器访问 http://localhost:5173 + +## 📝 相关文件 + +- 修改: `start.sh` - 后端启动命令 +- 文档: `docs/BACKEND_FIX.md` - 本文档 + +## 💡 技术说明 + +### uvicorn reload 模式 + +**reload 模式的特点:** +- 监控文件变化,自动重启服务 +- 适合开发环境(前台运行) +- 不适合后台运行(nohup/systemd) + +**生产环境建议:** +- 不使用 reload +- 使用进程管理工具(systemd, supervisor) +- 或使用容器化部署(Docker) + +### 为什么修复后有效 + +**使用 `uvicorn app.main:app` 直接启动:** +- 单进程模式,稳定运行 +- 不依赖 reload 机制 +- 适合 nohup 后台运行 + +**日志输出:** +- 所有日志写入 `logs/backend.log` +- 可使用 `tail -f logs/backend.log` 查看 + +--- + +**修复时间**: 2026-03-22 +**状态**: ✅ 已修复,需要重启服务 \ No newline at end of file diff --git a/start.sh b/start.sh index 44660ae..0266359 100755 --- a/start.sh +++ b/start.sh @@ -68,7 +68,7 @@ fi echo -e "${GREEN}启动后端服务...${NC}" cd "$BACKEND_DIR" source venv/bin/activate -nohup python -m app.main >> "$BACKEND_LOG" 2>&1 & +nohup uvicorn app.main:app --host 0.0.0.0 --port 8000 >> "$BACKEND_LOG" 2>&1 & BACKEND_PID=$! echo "$BACKEND_PID" >> "$PID_FILE" echo -e " PID: $BACKEND_PID"