320 lines
5.2 KiB
Markdown
320 lines
5.2 KiB
Markdown
# 🚀 启动指南
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：本地开发 (推荐)
|
||
|
||
**前置条件：**
|
||
- Python 3.9+
|
||
- Node.js 18+
|
||
- PostgreSQL 14+ (需要单独启动)
|
||
|
||
**Windows PowerShell:**
|
||
```powershell
|
||
.\start.ps1
|
||
```
|
||
|
||
**Windows CMD:**
|
||
```cmd
|
||
start.bat
|
||
```
|
||
|
||
**Mac/Linux:**
|
||
```bash
|
||
chmod +x start.sh
|
||
./start.sh
|
||
```
|
||
|
||
然后选择选项 `1` 进行本地开发。
|
||
|
||
**访问地址：**
|
||
- 前端: http://localhost:5173
|
||
- 后端: http://localhost:8000
|
||
- API文档: http://localhost:8000/docs
|
||
|
||
---
|
||
|
||
### 方式二：Docker Compose (完全隔离)
|
||
|
||
**前置条件：**
|
||
- Docker Desktop (包含 Docker Compose)
|
||
|
||
**启动：**
|
||
```powershell
|
||
.\start-docker.ps1
|
||
```
|
||
|
||
或直接使用 docker-compose:
|
||
```bash
|
||
docker-compose up --build
|
||
```
|
||
|
||
**访问地址：**
|
||
- 前端: http://localhost:3000
|
||
- 后端: http://localhost:8000
|
||
- API文档: http://localhost:8000/docs
|
||
- 数据库: localhost:5432 (用户: pharma / 密码: pharma123)
|
||
|
||
---
|
||
|
||
## 详细说明
|
||
|
||
### 方式一：本地开发
|
||
|
||
#### Windows
|
||
|
||
1. **启动脚本：**
|
||
- PowerShell: `.\start.ps1`
|
||
- CMD: `start.bat`
|
||
|
||
2. **脚本会自动：**
|
||
- 检查 Python 和 Node.js
|
||
- 创建虚拟环境 (如需要)
|
||
- 安装依赖包
|
||
- 在新窗口启动后端和前端
|
||
|
||
3. **手动启动（可选）：**
|
||
|
||
**后端：**
|
||
```powershell
|
||
cd backend
|
||
python -m venv venv
|
||
.\venv\Scripts\Activate.ps1
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
**前端（新终端）：**
|
||
```powershell
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
4. **PostgreSQL 配置：**
|
||
- 确保 PostgreSQL 已启动
|
||
- 默认连接: `postgresql://pharma:pharma123@localhost/pharma_news`
|
||
- 如需修改，编辑 `.env` 文件
|
||
|
||
#### Mac/Linux
|
||
|
||
```bash
|
||
# 给脚本执行权限
|
||
chmod +x start.sh
|
||
|
||
# 运行脚本
|
||
./start.sh
|
||
```
|
||
|
||
---
|
||
|
||
### 方式二：Docker Compose
|
||
|
||
#### 基本命令
|
||
|
||
```bash
|
||
# 启动所有服务（首次需要构建）
|
||
docker-compose up
|
||
|
||
# 重新构建并启动
|
||
docker-compose up --build
|
||
|
||
# 在后台运行
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 查看特定服务日志
|
||
docker-compose logs -f backend
|
||
docker-compose logs -f frontend
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
|
||
# 完全清理（包括数据）
|
||
docker-compose down -v
|
||
```
|
||
|
||
#### 常见问题
|
||
|
||
**问：如何修改端口？**
|
||
|
||
编辑 `docker-compose.yml`:
|
||
```yaml
|
||
ports:
|
||
- "8080:8000" # 后端: 外部:内部
|
||
- "3001:80" # 前端: 外部:内部
|
||
```
|
||
|
||
**问：如何在容器内执行命令？**
|
||
|
||
```bash
|
||
# 后端
|
||
docker-compose exec backend python -m alembic upgrade head
|
||
|
||
# 前端
|
||
docker-compose exec frontend npm run build
|
||
```
|
||
|
||
**问：如何清理 Docker 数据？**
|
||
|
||
```bash
|
||
# 停止并删除所有容器和卷
|
||
docker-compose down -v
|
||
|
||
# 重新启动会创建新的数据库
|
||
docker-compose up --build
|
||
```
|
||
|
||
---
|
||
|
||
## 环境变量配置
|
||
|
||
### 后端 (.env)
|
||
|
||
```env
|
||
# PostgreSQL
|
||
DATABASE_URL=postgresql://pharma:pharma123@localhost:5432/pharma_news
|
||
|
||
# LLM 服务
|
||
LLM_API_KEY=your_api_key
|
||
LLM_MODEL=gpt-4
|
||
|
||
# 其他配置
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
### 前端 (.env.local)
|
||
|
||
```env
|
||
VITE_API_BASE_URL=http://localhost:8000/api
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 后端无法启动
|
||
|
||
```bash
|
||
# 1. 检查端口是否被占用
|
||
netstat -ano | findstr :8000 # Windows
|
||
lsof -i :8000 # Mac/Linux
|
||
|
||
# 2. 检查 Python 和依赖
|
||
python --version
|
||
pip list | grep fastapi
|
||
|
||
# 3. 检查数据库连接
|
||
# 确保 PostgreSQL 已启动，用户名和密码正确
|
||
```
|
||
|
||
### 前端无法启动
|
||
|
||
```bash
|
||
# 1. 清理依赖
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
|
||
# 2. 检查 Node 版本
|
||
node --version
|
||
npm --version
|
||
|
||
# 3. 清理 Vite 缓存
|
||
rm -rf dist .vite
|
||
```
|
||
|
||
### Docker 容器无法启动
|
||
|
||
```bash
|
||
# 查看详细错误日志
|
||
docker-compose logs
|
||
|
||
# 重建镜像
|
||
docker-compose build --no-cache
|
||
|
||
# 清理所有容器和镜像
|
||
docker system prune -a
|
||
```
|
||
|
||
---
|
||
|
||
## 开发建议
|
||
|
||
### 热重载
|
||
|
||
- **后端**: Uvicorn 自动热重载 (修改文件后自动重启)
|
||
- **前端**: Vite 自动热重载 (修改代码后自动更新浏览器)
|
||
|
||
### 调试
|
||
|
||
**后端：**
|
||
```python
|
||
# 在代码中添加断点
|
||
import pdb; pdb.set_trace()
|
||
|
||
# 或使用 IDE 的调试功能
|
||
```
|
||
|
||
**前端：**
|
||
- 使用浏览器 DevTools (F12)
|
||
- VS Code Debugger (需要配置 launch.json)
|
||
|
||
### 性能监测
|
||
|
||
```bash
|
||
# 后端性能
|
||
docker-compose stats backend
|
||
|
||
# 前端性能
|
||
npm run build # 检查构建体积
|
||
```
|
||
|
||
---
|
||
|
||
## 生产部署
|
||
|
||
### 使用 Docker
|
||
|
||
```bash
|
||
# 构建生产镜像
|
||
docker-compose -f docker-compose.yml -f docker-compose.prod.yml build
|
||
|
||
# 启动生产环境
|
||
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
### 本地生产预览
|
||
|
||
```bash
|
||
# 后端
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
|
||
# 前端
|
||
npm run build
|
||
npm run preview
|
||
```
|
||
|
||
---
|
||
|
||
## 脚本文件说明
|
||
|
||
| 文件 | 说明 | 环境 |
|
||
|------|------|------|
|
||
| `start.ps1` | 本地开发启动脚本 | Windows PowerShell |
|
||
| `start.bat` | 本地开发启动脚本 | Windows CMD |
|
||
| `start.sh` | 本地开发启动脚本 | Mac/Linux |
|
||
| `start-docker.ps1` | Docker Compose 启动脚本 | Windows PowerShell |
|
||
|
||
---
|
||
|
||
## 更多帮助
|
||
|
||
- FastAPI 文档: https://fastapi.tiangolo.com/
|
||
- Vue.js 文档: https://vuejs.org/
|
||
- Vite 文档: https://vitejs.dev/
|
||
- PostgreSQL 文档: https://www.postgresql.org/docs/
|
||
- Docker 文档: https://docs.docker.com/
|
||
|