erp-ass/docs/ONE_CLICK_START.md

# 一键启动指南

## 🚀 快速开始

### 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