feat: add one-click startup scripts for project management

- Add start.sh/start.bat for one-click startup (backend + frontend) - Add stop.sh/stop.bat for stopping all services - Add restart.sh for restarting services - Add status.sh for checking service status - Add Makefile with convenient management commands - Add comprehensive documentation (ONE_CLICK_START.md) - Update README with one-click startup instructions Features: - Automatic environment checking (venv, node_modules) - Process management with PID tracking - Unified log management (logs/*.log) - Health checking after startup - Support for Linux, macOS, and Windows - No more need for multiple terminal windows Usage: ./start.sh # Start all services ./stop.sh # Stop all services ./status.sh # Check service status ./restart.sh # Restart services make start # Alternative using Makefile Benefits: - One command instead of multiple terminals - Automatic environment validation - Centralized logging - Process lifecycle management - Developer-friendly output messages
2026-03-22 02:49:22 +00:00
parent acd73431ae
commit 344a750cfb
11 changed files with 1521 additions and 9 deletions
--- a/docs/ONE_CLICK_START.md
+++ b/docs/ONE_CLICK_START.md
@@ -0,0 +1,409 @@
+# 一键启动指南
+
+## 🚀 快速开始
+
+### Linux/Mac 用户
+
+```bash
+# 添加执行权限（首次使用）
+chmod +x start.sh stop.sh restart.sh status.sh
+
+# 启动项目
+./start.sh
+
+# 查看状态
+./status.sh
+
+# 停止项目
+./stop.sh
+
+# 重启项目
+./restart.sh
+```
+
+### Windows 用户
+
+```cmd
+# 启动项目
+start.bat
+
+# 停止项目
+stop.bat
+```
+
+## 📋 功能说明
+
+### start.sh / start.bat
+
+**功能**：一键启动前后端服务
+
+**自动完成**：
+- ✅ 检查依赖环境（虚拟环境、node_modules）
+- ✅ 检查配置文件（.env）
+- ✅ 清理旧进程
+- ✅ 启动后端服务（端口 8000）
+- ✅ 启动前端服务（端口 5173）
+- ✅ 保存进程 PID
+- ✅ 健康检查
+
+**输出信息**：
+- 服务访问地址
+- 日志文件位置
+- 管理命令提示
+
+### stop.sh / stop.bat
+
+**功能**：停止所有服务
+
+**自动完成**：
+- ✅ 读取 PID 文件
+- ✅ 优雅停止进程
+- ✅ 强制清理残留进程
+- ✅ 清理 PID 文件
+
+### restart.sh
+
+**功能**：重启服务（Linux/Mac）
+
+**流程**：
+1. 停止服务
+2. 等待 2 秒
+3. 启动服务
+
+### status.sh
+
+**功能**：查看服务状态
+
+**显示信息**：
+- 后端服务状态和地址
+- 前端服务状态和地址
+- 进程信息（PID、命令）
+- 日志查看命令
+
+## 📁 目录结构
+
+```
+/data/erp-ass/
+├── start.sh          # Linux/Mac 启动脚本
+├── stop.sh           # Linux/Mac 停止脚本
+├── restart.sh        # Linux/Mac 重启脚本
+├── status.sh         # Linux/Mac 状态查看
+├── start.bat         # Windows 启动脚本
+├── stop.bat          # Windows 停止脚本
+├── logs/             # 日志目录（自动创建）
+│   ├── backend.log   # 后端日志
+│   ├── frontend.log  # 前端日志
+│   └── pids.txt      # 进程 PID 记录
+├── backend/
+└── frontend/
+```
+
+## 🔧 配置说明
+
+### 首次使用
+
+**1. 后端配置**
+
+```bash
+cd backend
+
+# 创建虚拟环境
+python3 -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 配置环境变量
+cp .env.example .env
+# 编辑 .env 文件填入数据库和 API 配置
+```
+
+**2. 前端配置**
+
+```bash
+cd frontend
+
+# 安装依赖
+npm install
+```
+
+**3. 一键启动**
+
+```bash
+# Linux/Mac
+./start.sh
+
+# Windows
+start.bat
+```
+
+## 📊 日志查看
+
+### 实时查看日志
+
+```bash
+# 查看后端日志
+tail -f logs/backend.log
+
+# 查看前端日志
+tail -f logs/frontend.log
+
+# 同时查看两个日志
+tail -f logs/*.log
+```
+
+### 日志内容
+
+**后端日志包含**：
+- 服务启动信息
+- API 请求日志
+- 错误和异常
+- SQL 执行日志
+
+**前端日志包含**：
+- Vite 构建信息
+- 开发服务器状态
+- 网络请求错误
+
+## 🎯 使用场景
+
+### 场景 1: 日常开发
+
+```bash
+# 早上启动
+./start.sh
+
+# 查看状态
+./status.sh
+
+# 晚上下班停止
+./stop.sh
+```
+
+### 场景 2: 快速重启
+
+修改配置后重启：
+
+```bash
+./restart.sh
+```
+
+### 场景 3: 查看日志排查问题
+
+```bash
+# 查看状态
+./status.sh
+
+# 查看日志
+tail -f logs/backend.log
+```
+
+### 场景 4: 团队协作
+
+团队成员可以直接运行：
+
+```bash
+./start.sh
+```
+
+无需记忆复杂的启动命令！
+
+## 🔍 故障排查
+
+### 问题 1: 端口被占用
+
+**症状**: 启动失败，提示端口已被使用
+
+**解决方案**:
+
+```bash
+# 查看占用端口的进程
+lsof -i :8000  # 后端
+lsof -i :5173  # 前端
+
+# 停止进程
+./stop.sh
+
+# 或手动杀进程
+kill -9 <PID>
+```
+
+### 问题 2: 虚拟环境不存在
+
+**症状**: `✗ 后端虚拟环境不存在`
+
+**解决方案**:
+
+```bash
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 问题 3: 前端依赖未安装
+
+**症状**: `✗ 前端依赖未安装`
+
+**解决方案**:
+
+```bash
+cd frontend
+npm install
+```
+
+### 问题 4: .env 文件缺失
+
+**症状**: 配置错误或环境变量未设置
+
+**解决方案**:
+
+脚本会自动从 `.env.example` 创建 `.env`，但你需要手动填入真实配置：
+
+```bash
+cd backend
+vi .env  # 编辑配置文件
+```
+
+### 问题 5: 进程残留
+
+**症状**: 启动时有旧进程干扰
+
+**解决方案**:
+
+```bash
+# 停止所有服务
+./stop.sh
+
+# 确认进程已停止
+./status.sh
+
+# 重新启动
+./start.sh
+```
+
+## 💡 高级用法
+
+### 后台运行（生产环境）
+
+如果需要在生产环境后台运行：
+
+```bash
+# 使用 nohup
+nohup ./start.sh > logs/startup.log 2>&1 &
+
+# 或使用 screen
+screen -S erp-ass
+./start.sh
+# 按 Ctrl+A+D 分离会话
+
+# 或使用 tmux
+tmux new -s erp-ass
+./start.sh
+# 按 Ctrl+B+D 分离会话
+```
+
+### 自定义端口
+
+如果需要修改端口，编辑：
+
+**后端端口**: `backend/app/main.py`
+```python
+uvicorn.run(app, host="0.0.0.0", port=8000)  # 修改这里的端口
+```
+
+**前端端口**: `frontend/vite.config.js`
+```javascript
+server: {
+  port: 5173,  // 修改这里的端口
+}
+```
+
+### 开机自启动
+
+创建 systemd 服务（Linux）：
+
+```bash
+sudo vi /etc/systemd/system/erp-ass.service
+```
+
+内容：
+```ini
+[Unit]
+Description=ERP AI Assistant
+After=network.target
+
+[Service]
+Type=forking
+User=your-user
+WorkingDirectory=/data/erp-ass
+ExecStart=/data/erp-ass/start.sh
+ExecStop=/data/erp-ass/stop.sh
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启用服务：
+```bash
+sudo systemctl enable erp-ass
+sudo systemctl start erp-ass
+```
+
+## 📱 访问地址
+
+启动成功后，可以通过以下地址访问：
+
+- **前端界面**: http://localhost:5173
+- **后端 API**: http://localhost:8000
+- **API 文档**: http://localhost:8000/docs
+- **健康检查**: http://localhost:8000/health
+
+**局域网访问**:
+- 前端: http://192.168.x.x:5173
+- 后端: http://192.168.x.x:8000
+
+## 🎨 对比传统方式
+
+### 传统方式（需要两个终端）
+
+**终端 1**:
+```bash
+cd backend
+source venv/bin/activate
+python -m app.main
+```
+
+**终端 2**:
+```bash
+cd frontend
+npm run dev
+```
+
+### 一键启动
+
+```bash
+./start.sh
+```
+
+**优势**：
+- ✅ 一个命令完成所有启动
+- ✅ 自动环境检查
+- ✅ 统一日志管理
+- ✅ 进程 PID 管理
+- ✅ 健康检查
+
+## 📚 相关文档
+
+- [快速上手指南](QUICK_START.md)
+- [局域网访问配置](LAN_ACCESS.md)
+- [依赖问题修复](DEPENDENCY_FIXES.md)
+- [Gitea 配置](GITEA_CONFIG.md)
+
+---
+
+**创建时间**: 2026-03-22
+**版本**: 1.0.0
+**兼容性**: Linux, macOS, Windows