erp-ass/docs/ONE_CLICK_START.md

一键启动指南

🚀 快速开始

Linux/Mac 用户

# 添加执行权限（首次使用）
chmod +x start.sh stop.sh restart.sh status.sh

# 启动项目
./start.sh

# 查看状态
./status.sh

# 停止项目
./stop.sh

# 重启项目
./restart.sh

Windows 用户

# 启动项目
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. 后端配置

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. 前端配置

cd frontend

# 安装依赖
npm install

3. 一键启动

# Linux/Mac
./start.sh

# Windows
start.bat

📊 日志查看

实时查看日志

# 查看后端日志
tail -f logs/backend.log

# 查看前端日志
tail -f logs/frontend.log

# 同时查看两个日志
tail -f logs/*.log

日志内容

后端日志包含：

• 服务启动信息
• API 请求日志
• 错误和异常
• SQL 执行日志

前端日志包含：

• Vite 构建信息
• 开发服务器状态
• 网络请求错误

🎯 使用场景

场景 1: 日常开发

# 早上启动
./start.sh

# 查看状态
./status.sh

# 晚上下班停止
./stop.sh

场景 2: 快速重启

修改配置后重启：

./restart.sh

场景 3: 查看日志排查问题

# 查看状态
./status.sh

# 查看日志
tail -f logs/backend.log

场景 4: 团队协作

团队成员可以直接运行：

./start.sh

无需记忆复杂的启动命令！

🔍 故障排查

问题 1: 端口被占用

症状: 启动失败，提示端口已被使用

解决方案:

# 查看占用端口的进程
lsof -i :8000  # 后端
lsof -i :5173  # 前端

# 停止进程
./stop.sh

# 或手动杀进程
kill -9 <PID>

问题 2: 虚拟环境不存在

症状: ✗ 后端虚拟环境不存在

解决方案:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

问题 3: 前端依赖未安装

症状: ✗ 前端依赖未安装

解决方案:

cd frontend
npm install

问题 4: .env 文件缺失

症状: 配置错误或环境变量未设置

解决方案:

脚本会自动从 .env.example 创建 .env，但你需要手动填入真实配置：

cd backend
vi .env  # 编辑配置文件

问题 5: 进程残留

症状: 启动时有旧进程干扰

解决方案:

# 停止所有服务
./stop.sh

# 确认进程已停止
./status.sh

# 重新启动
./start.sh

💡 高级用法

后台运行（生产环境）

如果需要在生产环境后台运行：

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

uvicorn.run(app, host="0.0.0.0", port=8000)  # 修改这里的端口

前端端口: frontend/vite.config.js

server: {
  port: 5173,  // 修改这里的端口
}

开机自启动

创建 systemd 服务（Linux）：

sudo vi /etc/systemd/system/erp-ass.service

内容：

[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

启用服务：

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:

cd backend
source venv/bin/activate
python -m app.main

终端 2:

cd frontend
npm run dev

一键启动

./start.sh

优势：

• ✅ 一个命令完成所有启动
• ✅ 自动环境检查
• ✅ 统一日志管理
• ✅ 进程 PID 管理
• ✅ 健康检查

📚 相关文档

• 快速上手指南
• 局域网访问配置
• 依赖问题修复
• Gitea 配置

---

创建时间: 2026-03-22 版本: 1.0.0 兼容性: Linux, macOS, Windows