460 lines
9.4 KiB
Markdown
460 lines
9.4 KiB
Markdown
# 项目模板使用指南
|
|
|
|
## 概述
|
|
|
|
这是一个生产级的 FastAPI + Vue 3 全栈应用模板，包含完整的用户认证、文件上传、数据库操作和现代化前端界面。
|
|
|
|
## 模板特性
|
|
|
|
### 后端 (FastAPI)
|
|
- ✅ RESTful API 设计
|
|
- ✅ JWT 身份认证
|
|
- ✅ SQLAlchemy ORM (支持 PostgreSQL/SQLite)
|
|
- ✅ 文件上传处理
|
|
- ✅ PDF 处理能力
|
|
- ✅ AI 模型集成 (Claude, Gemini)
|
|
- ✅ 自动 API 文档 (Swagger/OpenAPI)
|
|
- ✅ CORS 配置
|
|
- ✅ 环境变量管理
|
|
|
|
### 前端 (Vue 3)
|
|
- ✅ Composition API
|
|
- ✅ Element Plus UI 组件库
|
|
- ✅ Pinia 状态管理
|
|
- ✅ Vue Router 路由
|
|
- ✅ Vite 构建工具
|
|
- ✅ 响应式设计
|
|
- ✅ 统一配置管理
|
|
- ✅ API 服务封装
|
|
|
|
## 快速开始
|
|
|
|
### 方法一: 使用自动化脚本 (推荐)
|
|
|
|
```bash
|
|
# 1. 运行创建脚本
|
|
./create-from-template.sh
|
|
|
|
# 2. 根据提示输入项目信息
|
|
Project name: my-awesome-app
|
|
Display name: My Awesome App
|
|
Database name: myapp_db
|
|
API port: 8888
|
|
Frontend port: 3000
|
|
|
|
# 3. 脚本会自动:
|
|
# - 创建新项目目录
|
|
# - 复制所有文件
|
|
# - 替换配置项
|
|
# - 清理临时文件
|
|
# - 初始化 git 仓库
|
|
```
|
|
|
|
### 方法二: 手动创建
|
|
|
|
#### 1. 复制项目
|
|
|
|
```bash
|
|
# 复制整个项目到新目录
|
|
cp -r /path/to/pager /path/to/your-new-project
|
|
cd /path/to/your-new-project
|
|
|
|
# 清理不需要的文件
|
|
rm -rf .git backend/__pycache__ backend/wordmaster.db backend/uploads/* frontend/node_modules frontend/dist
|
|
```
|
|
|
|
#### 2. 配置后端
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# 复制环境变量配置
|
|
cp .env.example .env
|
|
|
|
# 编辑 .env 文件，修改以下配置:
|
|
# - DATABASE_URL: 数据库连接字符串
|
|
# - SECRET_KEY: JWT 密钥 (必须修改!)
|
|
# - OPENROUTER_API_KEY: AI API 密钥 (如需要)
|
|
# - AI_MODEL: AI 模型选择
|
|
|
|
# 安装依赖
|
|
pip install -r requirements.txt
|
|
|
|
# 初始化数据库
|
|
python main.py
|
|
```
|
|
|
|
#### 3. 配置前端
|
|
|
|
```bash
|
|
cd frontend
|
|
|
|
# 编辑 package.json
|
|
# 修改 "name": "your-project-frontend"
|
|
|
|
# 安装依赖
|
|
npm install
|
|
|
|
# 配置开发环境变量 (可选)
|
|
# 编辑 .env.development
|
|
# VITE_API_BASE_URL=http://localhost:8888/api
|
|
```
|
|
|
|
#### 4. 修改项目名称和品牌
|
|
|
|
需要修改的文件:
|
|
|
|
**后端:**
|
|
- `backend/main.py`: 数据库名称、应用描述
|
|
- `backend/.env`: 数据库连接字符串
|
|
|
|
**前端:**
|
|
- `frontend/package.json`: 项目名称
|
|
- `frontend/index.html`: 页面标题
|
|
- `frontend/src/config/index.js`: API 端口配置
|
|
|
|
#### 5. 启动项目
|
|
|
|
```bash
|
|
# 后端 (在 backend 目录)
|
|
python main.py
|
|
# 或
|
|
uvicorn main:app --host 0.0.0.0 --port 8888 --reload
|
|
|
|
# 前端 (在 frontend 目录)
|
|
npm run dev
|
|
```
|
|
|
|
## 项目结构详解
|
|
|
|
```
|
|
your-project/
|
|
├── backend/ # FastAPI 后端
|
|
│ ├── main.py # 主应用文件 (所有 API 端点)
|
|
│ ├── requirements.txt # Python 依赖
|
|
│ ├── .env.example # 环境变量示例
|
|
│ ├── migrate_db.py # 数据库迁移脚本
|
|
│ ├── pdf_splitter_*.py # PDF 处理模块
|
|
│ ├── claude_exam_parser.py # AI 解析器
|
|
│ ├── utils/ # 工具函数
|
|
│ └── uploads/ # 文件上传目录
|
|
│
|
|
├── frontend/ # Vue 3 前端
|
|
│ ├── src/
|
|
│ │ ├── main.js # 应用入口
|
|
│ │ ├── App.vue # 根组件
|
|
│ │ ├── router/ # 路由配置
|
|
│ │ ├── stores/ # Pinia 状态管理
|
|
│ │ ├── views/ # 页面组件
|
|
│ │ ├── components/ # 可复用组件
|
|
│ │ ├── config/ # 配置管理
|
|
│ │ └── services/ # API 服务
|
|
│ ├── package.json # 前端依赖
|
|
│ └── vite.config.js # Vite 配置
|
|
│
|
|
├── start.sh # 开发启动脚本
|
|
├── stop.sh # 停止脚本
|
|
├── status.sh # 状态检查脚本
|
|
├── template.config.json # 模板配置
|
|
└── TEMPLATE_GUIDE.md # 本文档
|
|
```
|
|
|
|
## 核心功能模块
|
|
|
|
### 1. 用户认证系统
|
|
|
|
**后端实现** (`backend/main.py`):
|
|
```python
|
|
# 注册
|
|
@app.post("/api/auth/register")
|
|
|
|
# 登录
|
|
@app.post("/api/auth/login")
|
|
|
|
# 获取当前用户
|
|
def get_current_user(credentials: HTTPAuthorizationCredentials)
|
|
```
|
|
|
|
**前端实现** (`frontend/src/stores/auth.js`):
|
|
```javascript
|
|
// 登录
|
|
async login(username, password)
|
|
|
|
// 注册
|
|
async register(username, password)
|
|
|
|
// 登出
|
|
logout()
|
|
|
|
// 自动加载用户信息
|
|
loadUser()
|
|
```
|
|
|
|
### 2. 数据库模型
|
|
|
|
**基础模型结构** (`backend/main.py`):
|
|
```python
|
|
class User(Base):
|
|
__tablename__ = "users"
|
|
id = Column(Integer, primary_key=True)
|
|
username = Column(String, unique=True)
|
|
password_hash = Column(String)
|
|
created_at = Column(DateTime)
|
|
|
|
# 添加你自己的模型
|
|
class YourModel(Base):
|
|
__tablename__ = "your_table"
|
|
# 定义字段...
|
|
```
|
|
|
|
### 3. 文件上传
|
|
|
|
**后端示例**:
|
|
```python
|
|
@app.post("/api/upload")
|
|
async def upload_file(
|
|
file: UploadFile = File(...),
|
|
current_user: User = Depends(get_current_user)
|
|
):
|
|
# 保存到 uploads/{user_id}/
|
|
file_path = f"uploads/{current_user.id}/{file.filename}"
|
|
# 处理文件...
|
|
return {"file_path": file_path}
|
|
```
|
|
|
|
**前端示例** (使用 Element Plus):
|
|
```vue
|
|
<el-upload
|
|
:action="uploadUrl"
|
|
:headers="headers"
|
|
:on-success="handleSuccess"
|
|
>
|
|
<el-button>上传文件</el-button>
|
|
</el-upload>
|
|
```
|
|
|
|
### 4. 状态管理 (Pinia)
|
|
|
|
创建新的 store (`frontend/src/stores/yourStore.js`):
|
|
```javascript
|
|
import { defineStore } from 'pinia'
|
|
import { ref } from 'vue'
|
|
|
|
export const useYourStore = defineStore('your-store', () => {
|
|
const data = ref([])
|
|
|
|
async function fetchData() {
|
|
// API 调用...
|
|
}
|
|
|
|
return { data, fetchData }
|
|
})
|
|
```
|
|
|
|
### 5. 路由配置
|
|
|
|
添加新路由 (`frontend/src/router/index.js`):
|
|
```javascript
|
|
{
|
|
path: '/your-page',
|
|
name: 'YourPage',
|
|
component: () => import('../views/YourPage.vue'),
|
|
meta: { requiresAuth: true } // 需要登录
|
|
}
|
|
```
|
|
|
|
## 自定义和扩展
|
|
|
|
### 添加新的 API 端点
|
|
|
|
在 `backend/main.py` 中:
|
|
```python
|
|
@app.get("/api/your-endpoint")
|
|
async def your_endpoint(
|
|
current_user: User = Depends(get_current_user),
|
|
db: Session = Depends(get_db)
|
|
):
|
|
# 你的逻辑
|
|
return {"data": "your data"}
|
|
```
|
|
|
|
### 添加新的前端页面
|
|
|
|
1. 创建组件: `frontend/src/views/YourPage.vue`
|
|
```vue
|
|
<template>
|
|
<div class="your-page">
|
|
<h1>{{ title }}</h1>
|
|
</div>
|
|
</template>
|
|
|
|
<script setup>
|
|
import { ref } from 'vue'
|
|
|
|
const title = ref('Your Page Title')
|
|
</script>
|
|
```
|
|
|
|
2. 在路由中注册 (见上面路由配置)
|
|
|
|
### 修改数据库模型
|
|
|
|
1. 编辑 `backend/main.py` 中的模型定义
|
|
2. 运行迁移:
|
|
```bash
|
|
cd backend
|
|
python migrate_db.py
|
|
```
|
|
|
|
## 部署指南
|
|
|
|
### 环境变量配置
|
|
|
|
**生产环境必须修改**:
|
|
```bash
|
|
# backend/.env
|
|
SECRET_KEY=your-very-long-random-secret-key-min-32-chars
|
|
DATABASE_URL=postgresql://user:password@host:port/dbname
|
|
```
|
|
|
|
### Docker 部署
|
|
|
|
创建 `Dockerfile` (后端):
|
|
```dockerfile
|
|
FROM python:3.9-slim
|
|
WORKDIR /app
|
|
COPY requirements.txt .
|
|
RUN pip install -r requirements.txt
|
|
COPY . .
|
|
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8888"]
|
|
```
|
|
|
|
创建 `Dockerfile` (前端):
|
|
```dockerfile
|
|
FROM node:18-alpine
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm install
|
|
COPY . .
|
|
RUN npm run build
|
|
CMD ["npm", "run", "preview"]
|
|
```
|
|
|
|
### Nginx 配置
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name your-domain.com;
|
|
|
|
location / {
|
|
root /var/www/frontend/dist;
|
|
try_files $uri $uri/ /index.html;
|
|
}
|
|
|
|
location /api {
|
|
proxy_pass http://localhost:8888;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
}
|
|
}
|
|
```
|
|
|
|
## 最佳实践
|
|
|
|
### 1. 安全性
|
|
- ✅ 修改默认 SECRET_KEY
|
|
- ✅ 使用 HTTPS (生产环境)
|
|
- ✅ 限制 CORS 源
|
|
- ✅ 定期更新依赖
|
|
- ✅ 不要提交 .env 文件
|
|
|
|
### 2. 性能优化
|
|
- ✅ 启用数据库索引
|
|
- ✅ 使用连接池
|
|
- ✅ 前端代码分割
|
|
- ✅ 静态资源 CDN
|
|
- ✅ API 响应缓存
|
|
|
|
### 3. 开发规范
|
|
- ✅ 遵循 RESTful API 设计
|
|
- ✅ 使用 TypeScript (可选)
|
|
- ✅ 编写单元测试
|
|
- ✅ 代码审查
|
|
- ✅ Git 提交规范
|
|
|
|
## 常见问题
|
|
|
|
### Q: 如何切换数据库?
|
|
|
|
**从 SQLite 到 PostgreSQL:**
|
|
```python
|
|
# 修改 DATABASE_URL
|
|
DATABASE_URL = "postgresql://user:password@localhost:5432/dbname"
|
|
|
|
# 重新创建表
|
|
python main.py
|
|
```
|
|
|
|
### Q: 如何添加新的 AI 模型?
|
|
|
|
编辑 `backend/.env`:
|
|
```bash
|
|
AI_MODEL=google/gemini-3-pro-preview
|
|
# 或
|
|
AI_MODEL=openai/gpt-4o
|
|
```
|
|
|
|
### Q: 前端如何跨域请求?
|
|
|
|
开发环境在 `vite.config.js` 配置代理:
|
|
```javascript
|
|
export default defineConfig({
|
|
server: {
|
|
proxy: {
|
|
'/api': {
|
|
target: 'http://localhost:8888',
|
|
changeOrigin: true
|
|
}
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### Q: 如何部署到云服务器?
|
|
|
|
1. 购买云服务器 (阿里云/腾讯云/AWS)
|
|
2. 配置安全组开放端口
|
|
3. 使用 Docker 或 PM2 部署
|
|
4. 配置域名和 HTTPS
|
|
|
|
## 模板更新
|
|
|
|
如果模板有更新，你可以:
|
|
|
|
1. **选择性合并**:
|
|
```bash
|
|
git remote add template /path/to/template
|
|
git fetch template
|
|
git cherry-pick <commit-hash>
|
|
```
|
|
|
|
2. **手动更新**:
|
|
比较新旧文件，手动复制需要的功能
|
|
|
|
## 技术支持
|
|
|
|
- 查看 `CLAUDE.md` 了解详细项目文档
|
|
- 查看 `README.md` 了解部署指南
|
|
- FastAPI 文档: https://fastapi.tiangolo.com
|
|
- Vue 3 文档: https://vuejs.org
|
|
- Element Plus 文档: https://element-plus.org
|
|
|
|
## 许可证
|
|
|
|
MIT License - 自由使用和修改
|
|
|
|
---
|
|
|
|
**祝你的项目开发顺利!** 🚀
|