init template
This commit is contained in:
+42
-2
@@ -65,5 +65,45 @@ temp/
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Git temporary files
|
||||
.git/
|
||||
# Coverage reports
|
||||
htmlcov/
|
||||
.coverage
|
||||
.coverage.*
|
||||
coverage.xml
|
||||
*.cover
|
||||
.pytest_cache/
|
||||
|
||||
# Docker
|
||||
docker-compose.override.yml
|
||||
.dockerignore
|
||||
|
||||
# Frontend specific
|
||||
.cache/
|
||||
.parcel-cache/
|
||||
.next/
|
||||
.nuxt/
|
||||
.vuepress/dist
|
||||
|
||||
# Testing
|
||||
.tox/
|
||||
.nox/
|
||||
|
||||
# MyPy
|
||||
.mypy_cache/
|
||||
.dmypy.json
|
||||
dmypy.json
|
||||
|
||||
# Jupyter Notebook
|
||||
.ipynb_checkpoints
|
||||
|
||||
# pyenv
|
||||
.python-version
|
||||
|
||||
# Certificates and keys
|
||||
*.pem
|
||||
*.key
|
||||
*.crt
|
||||
|
||||
# Local configuration
|
||||
config.local.js
|
||||
config.local.json
|
||||
@@ -0,0 +1,459 @@
|
||||
# 项目模板使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
这是一个生产级的 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 - 自由使用和修改
|
||||
|
||||
---
|
||||
|
||||
**祝你的项目开发顺利!** 🚀
|
||||
@@ -0,0 +1,288 @@
|
||||
# 模板快速使用指南
|
||||
|
||||
## 三种使用方式
|
||||
|
||||
### 🚀 方式一: 自动化脚本 (最推荐)
|
||||
|
||||
```bash
|
||||
# 1. 运行创建脚本
|
||||
./create-from-template.sh
|
||||
|
||||
# 2. 按提示输入项目信息
|
||||
# 3. 脚本会自动完成所有配置
|
||||
# 4. 进入新项目目录开始开发
|
||||
```
|
||||
|
||||
**优点**:
|
||||
- ✅ 一键创建，无需手动配置
|
||||
- ✅ 自动替换所有配置项
|
||||
- ✅ 自动生成安全的 SECRET_KEY
|
||||
- ✅ 自动初始化 Git 仓库
|
||||
|
||||
---
|
||||
|
||||
### 📋 方式二: 手动复制
|
||||
|
||||
```bash
|
||||
# 1. 复制项目
|
||||
cp -r /path/to/pager /path/to/your-new-project
|
||||
cd /path/to/your-new-project
|
||||
|
||||
# 2. 清理不需要的文件
|
||||
rm -rf .git backend/__pycache__ backend/*.db backend/uploads/* frontend/node_modules frontend/dist
|
||||
|
||||
# 3. 配置后端
|
||||
cd backend
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，修改必要配置
|
||||
|
||||
# 4. 配置前端
|
||||
cd frontend
|
||||
# 编辑 package.json，修改项目名称
|
||||
|
||||
# 5. 初始化 Git
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔗 方式三: Git 模板方式
|
||||
|
||||
```bash
|
||||
# 1. 克隆为模板
|
||||
git clone /path/to/pager your-new-project
|
||||
cd your-new-project
|
||||
|
||||
# 2. 移除原有 Git 历史
|
||||
rm -rf .git
|
||||
|
||||
# 3. 按方式二的步骤 3-5 操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心配置清单
|
||||
|
||||
### ✅ 必须修改的配置
|
||||
|
||||
**后端 `backend/.env`:**
|
||||
```bash
|
||||
# 1. 数据库连接 (必须)
|
||||
DATABASE_URL=postgresql://user:pass@host:port/dbname
|
||||
|
||||
# 2. 密钥 (必须，生产环境)
|
||||
SECRET_KEY=<生成一个长随机字符串>
|
||||
|
||||
# 3. AI API Key (如需 AI 功能)
|
||||
OPENROUTER_API_KEY=<your-api-key>
|
||||
```
|
||||
|
||||
**前端 `frontend/package.json`:**
|
||||
```json
|
||||
{
|
||||
"name": "your-project-name-frontend"
|
||||
}
|
||||
```
|
||||
|
||||
**前端 `frontend/index.html`:**
|
||||
```html
|
||||
<title>Your Project Name</title>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔧 可选修改的配置
|
||||
|
||||
**端口配置:**
|
||||
- 后端: `backend/main.py` 或 `.env` 中的 `PORT`
|
||||
- 前端: `vite.config.js` 中的 `server.port`
|
||||
|
||||
**API 地址:**
|
||||
- `frontend/src/config/index.js`
|
||||
|
||||
---
|
||||
|
||||
## 快速命令参考
|
||||
|
||||
### 开发环境
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
cd backend
|
||||
pip install -r requirements.txt # 安装依赖
|
||||
python main.py # 启动服务
|
||||
|
||||
# 前端
|
||||
cd frontend
|
||||
npm install # 安装依赖
|
||||
npm run dev # 启动开发服务器
|
||||
|
||||
# 或使用启动脚本
|
||||
./start.sh # 同时启动前后端
|
||||
./status.sh # 查看运行状态
|
||||
./stop.sh # 停止所有服务
|
||||
```
|
||||
|
||||
### 数据库操作
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python main.py # 首次运行自动创建表
|
||||
python migrate_db.py # 手动迁移数据库
|
||||
```
|
||||
|
||||
### 生产构建
|
||||
|
||||
```bash
|
||||
# 前端构建
|
||||
cd frontend
|
||||
npm run build # 构建到 dist/ 目录
|
||||
npm run preview # 预览生产构建
|
||||
|
||||
# 后端生产运行
|
||||
cd backend
|
||||
uvicorn main:app --host 0.0.0.0 --port 8888
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 项目结构速览
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── backend/ # FastAPI 后端
|
||||
│ ├── main.py # 主应用 (所有 API 在这里)
|
||||
│ ├── .env # 环境变量 (从 .env.example 复制)
|
||||
│ └── requirements.txt # Python 依赖
|
||||
│
|
||||
├── frontend/ # Vue 3 前端
|
||||
│ ├── src/
|
||||
│ │ ├── views/ # 页面组件
|
||||
│ │ ├── stores/ # Pinia 状态管理
|
||||
│ │ ├── router/ # 路由配置
|
||||
│ │ └── config/ # 配置管理
|
||||
│ └── package.json # 前端依赖
|
||||
│
|
||||
├── create-from-template.sh # 模板创建脚本
|
||||
├── TEMPLATE_GUIDE.md # 完整使用指南
|
||||
└── start.sh # 开发启动脚本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 开发工作流
|
||||
|
||||
### 添加新功能
|
||||
|
||||
**1. 后端 API:**
|
||||
```python
|
||||
# backend/main.py
|
||||
@app.get("/api/your-endpoint")
|
||||
async def your_endpoint(current_user: User = Depends(get_current_user)):
|
||||
return {"message": "Hello"}
|
||||
```
|
||||
|
||||
**2. 前端页面:**
|
||||
```bash
|
||||
# 创建组件
|
||||
touch frontend/src/views/YourPage.vue
|
||||
|
||||
# 注册路由 (frontend/src/router/index.js)
|
||||
{
|
||||
path: '/your-page',
|
||||
component: () => import('../views/YourPage.vue')
|
||||
}
|
||||
```
|
||||
|
||||
**3. 状态管理:**
|
||||
```javascript
|
||||
// frontend/src/stores/yourStore.js
|
||||
import { defineStore } from 'pinia'
|
||||
|
||||
export const useYourStore = defineStore('your-store', () => {
|
||||
// 定义状态和方法
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题速查
|
||||
|
||||
| 问题 | 解决方法 |
|
||||
|------|---------|
|
||||
| 端口被占用 | 修改 `.env` 中的 `PORT` 或 `vite.config.js` |
|
||||
| CORS 错误 | 检查 `backend/main.py` 的 CORS 配置 |
|
||||
| 数据库连接失败 | 检查 `DATABASE_URL` 格式和数据库服务状态 |
|
||||
| 前端请求失败 | 检查 `frontend/src/config/index.js` 的 API_BASE_URL |
|
||||
| JWT 认证失败 | 确保 `SECRET_KEY` 正确且前后端一致 |
|
||||
|
||||
---
|
||||
|
||||
## 安全检查清单
|
||||
|
||||
- [ ] 修改了 `SECRET_KEY` (生产环境必须)
|
||||
- [ ] 不提交 `.env` 文件到 Git
|
||||
- [ ] 生产环境设置 `DEBUG=false`
|
||||
- [ ] 限制 CORS 允许的域名
|
||||
- [ ] 使用 HTTPS (生产环境)
|
||||
- [ ] 定期更新依赖包
|
||||
- [ ] 保护 API keys 安全
|
||||
|
||||
---
|
||||
|
||||
## 生成安全密钥
|
||||
|
||||
```bash
|
||||
# 方法 1: OpenSSL
|
||||
openssl rand -base64 32
|
||||
|
||||
# 方法 2: Python
|
||||
python -c "import secrets; print(secrets.token_urlsafe(32))"
|
||||
|
||||
# 方法 3: Node.js
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 部署选项
|
||||
|
||||
### Docker
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### PM2
|
||||
```bash
|
||||
pm2 start backend/main.py --name api
|
||||
pm2 serve frontend/dist 3000 --name frontend
|
||||
```
|
||||
|
||||
### 云服务器
|
||||
- 阿里云 ECS
|
||||
- 腾讯云 CVM
|
||||
- AWS EC2
|
||||
- DigitalOcean Droplet
|
||||
|
||||
---
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- 📖 完整文档: `TEMPLATE_GUIDE.md`
|
||||
- 🏗️ 项目架构: `CLAUDE.md`
|
||||
- 📋 部署指南: `README.md`
|
||||
- ⚙️ 配置说明: `backend/.env.example`
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
1. ✅ 使用 `create-from-template.sh` 创建新项目
|
||||
2. ✅ 配置 `backend/.env`
|
||||
3. ✅ 安装依赖 (后端+前端)
|
||||
4. ✅ 启动开发服务器
|
||||
5. ✅ 开始开发你的功能
|
||||
|
||||
**祝你的项目开发顺利!** 🎉
|
||||
+169
-10
@@ -1,23 +1,182 @@
|
||||
# =============================================================================
|
||||
# Database Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# For SQLite (recommended for development):
|
||||
# DATABASE_URL=sqlite:///./database_name.db
|
||||
#
|
||||
# For PostgreSQL (recommended for production):
|
||||
# DATABASE_URL=postgresql://username:password@host:port/database_name
|
||||
#
|
||||
# For MySQL:
|
||||
# DATABASE_URL=mysql://username:password@host:port/database_name
|
||||
#
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/wordmaster
|
||||
|
||||
# JWT Configuration
|
||||
SECRET_KEY=your-super-secret-and-secure-key-change-me
|
||||
# =============================================================================
|
||||
# Security Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# IMPORTANT: Change SECRET_KEY in production!
|
||||
# Generate a secure key with: openssl rand -base64 32
|
||||
# Or: python -c "import secrets; print(secrets.token_urlsafe(32))"
|
||||
#
|
||||
SECRET_KEY=your-super-secret-and-secure-key-change-me-in-production
|
||||
|
||||
# JWT algorithm (HS256 is recommended)
|
||||
ALGORITHM=HS256
|
||||
|
||||
# Token expiration time in minutes
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
|
||||
# OpenRouter AI Configuration (for Claude Sonnet 4.5 access)
|
||||
# =============================================================================
|
||||
# OpenRouter AI Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# Get your API key from: https://openrouter.ai/keys
|
||||
OPENROUTER_API_KEY=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
|
||||
# Required if you want to use AI-powered features
|
||||
#
|
||||
OPENROUTER_API_KEY=your-openrouter-api-key-here
|
||||
|
||||
# =============================================================================
|
||||
# AI Model Selection
|
||||
# Available models:
|
||||
# - anthropic/claude-sonnet-4.5 (默认，通用能力强)
|
||||
# - google/gemini-3-pro-preview (数学能力强，推荐数学试卷使用)
|
||||
# - openai/gpt-4o
|
||||
# - openai/gpt-4-turbo
|
||||
# =============================================================================
|
||||
#
|
||||
# Available models through OpenRouter:
|
||||
#
|
||||
# Claude Models (Anthropic):
|
||||
# - anthropic/claude-sonnet-4.5 (Default, best general performance)
|
||||
# - anthropic/claude-opus-4 (Most capable, slower)
|
||||
# - anthropic/claude-haiku-3.5 (Fast, cost-effective)
|
||||
#
|
||||
# Gemini Models (Google):
|
||||
# - google/gemini-3-pro-preview (Great for math, recommended for math exams)
|
||||
# - google/gemini-pro-1.5 (Good general performance)
|
||||
#
|
||||
# GPT Models (OpenAI):
|
||||
# - openai/gpt-4o (Latest GPT-4 with vision)
|
||||
# - openai/gpt-4-turbo (Fast GPT-4)
|
||||
# - openai/gpt-3.5-turbo (Fastest, most economical)
|
||||
#
|
||||
AI_MODEL=anthropic/claude-sonnet-4.5
|
||||
|
||||
# =============================================================================
|
||||
# Parser Configuration
|
||||
# Set to "true" to use Claude AI parser by default, "false" to use traditional parser
|
||||
# =============================================================================
|
||||
#
|
||||
# Use AI-powered parser for better accuracy (requires OPENROUTER_API_KEY)
|
||||
# Set to "false" to use traditional rule-based parser
|
||||
#
|
||||
USE_CLAUDE_PARSER=true
|
||||
|
||||
# =============================================================================
|
||||
# Application Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# Server host and port
|
||||
HOST=0.0.0.0
|
||||
PORT=8888
|
||||
|
||||
# Environment: development, staging, production
|
||||
ENVIRONMENT=development
|
||||
|
||||
# Enable debug mode (set to false in production)
|
||||
DEBUG=true
|
||||
|
||||
# =============================================================================
|
||||
# CORS Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# Allowed origins for CORS (comma-separated)
|
||||
# Use "*" for development, specific domains for production
|
||||
#
|
||||
# Examples:
|
||||
# CORS_ORIGINS=http://localhost:3000,http://localhost:3001
|
||||
# CORS_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
|
||||
#
|
||||
CORS_ORIGINS=*
|
||||
|
||||
# =============================================================================
|
||||
# File Upload Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# Maximum file size in MB
|
||||
MAX_UPLOAD_SIZE=50
|
||||
|
||||
# Allowed file extensions (comma-separated)
|
||||
ALLOWED_EXTENSIONS=.pdf,.jpg,.jpeg,.png,.doc,.docx
|
||||
|
||||
# Upload directory (relative to backend/)
|
||||
UPLOAD_DIR=uploads
|
||||
|
||||
# =============================================================================
|
||||
# Logging Configuration
|
||||
# =============================================================================
|
||||
#
|
||||
# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
|
||||
LOG_LEVEL=INFO
|
||||
|
||||
# Log file path (leave empty to disable file logging)
|
||||
LOG_FILE=logs/app.log
|
||||
|
||||
# =============================================================================
|
||||
# Feature Flags
|
||||
# =============================================================================
|
||||
#
|
||||
# Enable/disable specific features
|
||||
#
|
||||
ENABLE_AI_FEATURES=true
|
||||
ENABLE_PDF_PROCESSING=true
|
||||
ENABLE_FILE_UPLOAD=true
|
||||
ENABLE_ANALYTICS=true
|
||||
|
||||
# =============================================================================
|
||||
# Rate Limiting (Optional)
|
||||
# =============================================================================
|
||||
#
|
||||
# Requests per minute per user
|
||||
RATE_LIMIT_PER_MINUTE=60
|
||||
|
||||
# =============================================================================
|
||||
# Email Configuration (Optional)
|
||||
# =============================================================================
|
||||
#
|
||||
# SMTP settings for sending emails
|
||||
# Leave empty if not using email features
|
||||
#
|
||||
# SMTP_HOST=smtp.gmail.com
|
||||
# SMTP_PORT=587
|
||||
# SMTP_USER=your-email@gmail.com
|
||||
# SMTP_PASSWORD=your-app-password
|
||||
# SMTP_FROM=noreply@yourdomain.com
|
||||
|
||||
# =============================================================================
|
||||
# Redis Configuration (Optional)
|
||||
# =============================================================================
|
||||
#
|
||||
# For caching and session management
|
||||
# Leave empty if not using Redis
|
||||
#
|
||||
# REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# =============================================================================
|
||||
# Sentry Configuration (Optional)
|
||||
# =============================================================================
|
||||
#
|
||||
# For error tracking and monitoring
|
||||
# Get your DSN from: https://sentry.io
|
||||
#
|
||||
# SENTRY_DSN=your-sentry-dsn-here
|
||||
|
||||
# =============================================================================
|
||||
# Notes
|
||||
# =============================================================================
|
||||
#
|
||||
# 1. Copy this file to .env and update the values
|
||||
# 2. Never commit .env to version control
|
||||
# 3. Use strong, unique values for SECRET_KEY in production
|
||||
# 4. Set DEBUG=false in production
|
||||
# 5. Use specific CORS_ORIGINS in production
|
||||
# 6. Keep API keys secure and rotate them regularly
|
||||
#
|
||||
# =============================================================================
|
||||
|
||||
Executable
+513
@@ -0,0 +1,513 @@
|
||||
#!/bin/bash
|
||||
|
||||
# 项目模板创建脚本
|
||||
# 用法: ./create-from-template.sh [目标目录]
|
||||
|
||||
set -e # 遇到错误立即退出
|
||||
|
||||
# 颜色定义
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# 打印带颜色的消息
|
||||
print_success() {
|
||||
echo -e "${GREEN}✓ $1${NC}"
|
||||
}
|
||||
|
||||
print_info() {
|
||||
echo -e "${BLUE}ℹ $1${NC}"
|
||||
}
|
||||
|
||||
print_warning() {
|
||||
echo -e "${YELLOW}⚠ $1${NC}"
|
||||
}
|
||||
|
||||
print_error() {
|
||||
echo -e "${RED}✗ $1${NC}"
|
||||
}
|
||||
|
||||
print_header() {
|
||||
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo -e "${BLUE} $1${NC}"
|
||||
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
}
|
||||
|
||||
# 获取当前模板目录
|
||||
TEMPLATE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
# 欢迎信息
|
||||
clear
|
||||
print_header "FastAPI + Vue 3 项目模板生成器"
|
||||
echo ""
|
||||
print_info "此脚本将基于当前模板创建一个新项目"
|
||||
echo ""
|
||||
|
||||
# 获取目标目录
|
||||
if [ -n "$1" ]; then
|
||||
TARGET_DIR="$1"
|
||||
else
|
||||
read -p "$(echo -e ${BLUE}请输入新项目目录 [默认: ../my-new-project]: ${NC})" TARGET_DIR
|
||||
TARGET_DIR=${TARGET_DIR:-../my-new-project}
|
||||
fi
|
||||
|
||||
# 转换为绝对路径
|
||||
TARGET_DIR=$(cd "$(dirname "$TARGET_DIR")" 2>/dev/null && pwd)/$(basename "$TARGET_DIR") || TARGET_DIR="$TARGET_DIR"
|
||||
|
||||
# 检查目标目录是否已存在
|
||||
if [ -d "$TARGET_DIR" ]; then
|
||||
print_warning "目录 $TARGET_DIR 已存在"
|
||||
read -p "$(echo -e ${YELLOW}是否覆盖? [y/N]: ${NC})" OVERWRITE
|
||||
if [[ ! $OVERWRITE =~ ^[Yy]$ ]]; then
|
||||
print_info "已取消"
|
||||
exit 0
|
||||
fi
|
||||
rm -rf "$TARGET_DIR"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
print_header "项目配置"
|
||||
echo ""
|
||||
|
||||
# 收集项目信息
|
||||
read -p "$(echo -e ${BLUE}项目名称 (小写,用连字符) [my-app]: ${NC})" PROJECT_NAME
|
||||
PROJECT_NAME=${PROJECT_NAME:-my-app}
|
||||
|
||||
read -p "$(echo -e ${BLUE}项目显示名称 [My Application]: ${NC})" PROJECT_DISPLAY_NAME
|
||||
PROJECT_DISPLAY_NAME=${PROJECT_DISPLAY_NAME:-My Application}
|
||||
|
||||
read -p "$(echo -e ${BLUE}数据库名称 [${PROJECT_NAME//-/_}_db]: ${NC})" DATABASE_NAME
|
||||
DATABASE_NAME=${DATABASE_NAME:-${PROJECT_NAME//-/_}_db}
|
||||
|
||||
read -p "$(echo -e ${BLUE}后端 API 端口 [8888]: ${NC})" API_PORT
|
||||
API_PORT=${API_PORT:-8888}
|
||||
|
||||
read -p "$(echo -e ${BLUE}前端开发端口 [3000]: ${NC})" FRONTEND_PORT
|
||||
FRONTEND_PORT=${FRONTEND_PORT:-3000}
|
||||
|
||||
read -p "$(echo -e ${BLUE}域名 (可选,按回车跳过): ${NC})" DOMAIN_NAME
|
||||
|
||||
# 数据库类型
|
||||
echo ""
|
||||
echo -e "${BLUE}选择数据库类型:${NC}"
|
||||
echo " 1) SQLite (默认,适合开发)"
|
||||
echo " 2) PostgreSQL (推荐生产环境)"
|
||||
read -p "$(echo -e ${BLUE}请选择 [1]: ${NC})" DB_TYPE
|
||||
DB_TYPE=${DB_TYPE:-1}
|
||||
|
||||
if [ "$DB_TYPE" = "2" ]; then
|
||||
read -p "$(echo -e ${BLUE}PostgreSQL 主机 [localhost]: ${NC})" PG_HOST
|
||||
PG_HOST=${PG_HOST:-localhost}
|
||||
|
||||
read -p "$(echo -e ${BLUE}PostgreSQL 端口 [5432]: ${NC})" PG_PORT
|
||||
PG_PORT=${PG_PORT:-5432}
|
||||
|
||||
read -p "$(echo -e ${BLUE}PostgreSQL 用户名 [postgres]: ${NC})" PG_USER
|
||||
PG_USER=${PG_USER:-postgres}
|
||||
|
||||
read -s -p "$(echo -e ${BLUE}PostgreSQL 密码: ${NC})" PG_PASSWORD
|
||||
echo ""
|
||||
|
||||
DATABASE_URL="postgresql://${PG_USER}:${PG_PASSWORD}@${PG_HOST}:${PG_PORT}/${DATABASE_NAME}"
|
||||
else
|
||||
DATABASE_URL="sqlite:///./${DATABASE_NAME}.db"
|
||||
fi
|
||||
|
||||
# 生成随机 SECRET_KEY
|
||||
SECRET_KEY=$(openssl rand -base64 32 2>/dev/null || python3 -c "import secrets; print(secrets.token_urlsafe(32))")
|
||||
|
||||
# 确认信息
|
||||
echo ""
|
||||
print_header "配置确认"
|
||||
echo ""
|
||||
echo -e "${BLUE}项目名称:${NC} $PROJECT_NAME"
|
||||
echo -e "${BLUE}显示名称:${NC} $PROJECT_DISPLAY_NAME"
|
||||
echo -e "${BLUE}数据库名称:${NC} $DATABASE_NAME"
|
||||
echo -e "${BLUE}数据库 URL:${NC} $DATABASE_URL"
|
||||
echo -e "${BLUE}API 端口:${NC} $API_PORT"
|
||||
echo -e "${BLUE}前端端口:${NC} $FRONTEND_PORT"
|
||||
echo -e "${BLUE}域名:${NC} ${DOMAIN_NAME:-未设置}"
|
||||
echo -e "${BLUE}目标目录:${NC} $TARGET_DIR"
|
||||
echo ""
|
||||
|
||||
read -p "$(echo -e ${BLUE}确认创建项目? [Y/n]: ${NC})" CONFIRM
|
||||
if [[ $CONFIRM =~ ^[Nn]$ ]]; then
|
||||
print_info "已取消"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# 开始创建项目
|
||||
echo ""
|
||||
print_header "创建项目"
|
||||
echo ""
|
||||
|
||||
# 1. 创建目标目录
|
||||
print_info "创建目录: $TARGET_DIR"
|
||||
mkdir -p "$TARGET_DIR"
|
||||
|
||||
# 2. 复制文件
|
||||
print_info "复制项目文件..."
|
||||
rsync -a --progress "$TEMPLATE_DIR/" "$TARGET_DIR/" \
|
||||
--exclude='.git' \
|
||||
--exclude='node_modules' \
|
||||
--exclude='__pycache__' \
|
||||
--exclude='*.pyc' \
|
||||
--exclude='dist' \
|
||||
--exclude='backend/wordmaster.db' \
|
||||
--exclude='backend/uploads/*' \
|
||||
--exclude='frontend/.env.local' \
|
||||
--exclude='.DS_Store'
|
||||
|
||||
print_success "文件复制完成"
|
||||
|
||||
# 3. 替换配置
|
||||
print_info "更新配置文件..."
|
||||
|
||||
cd "$TARGET_DIR"
|
||||
|
||||
# 替换后端配置
|
||||
if [ -f "backend/main.py" ]; then
|
||||
# macOS 和 Linux 兼容的 sed
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
sed -i '' "s/wordmaster/$DATABASE_NAME/g" backend/main.py
|
||||
sed -i '' "s/学习助手 Pro/$PROJECT_DISPLAY_NAME/g" backend/main.py
|
||||
else
|
||||
sed -i "s/wordmaster/$DATABASE_NAME/g" backend/main.py
|
||||
sed -i "s/学习助手 Pro/$PROJECT_DISPLAY_NAME/g" backend/main.py
|
||||
fi
|
||||
fi
|
||||
|
||||
# 创建 .env 文件
|
||||
cat > backend/.env << EOF
|
||||
# Database Configuration
|
||||
DATABASE_URL=$DATABASE_URL
|
||||
|
||||
# JWT Configuration
|
||||
SECRET_KEY=$SECRET_KEY
|
||||
ALGORITHM=HS256
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
|
||||
# OpenRouter AI Configuration (for Claude Sonnet 4.5 access)
|
||||
# Get your API key from: https://openrouter.ai/keys
|
||||
OPENROUTER_API_KEY=your-openrouter-api-key-here
|
||||
|
||||
# AI Model Selection
|
||||
# Available models:
|
||||
# - anthropic/claude-sonnet-4.5 (默认，通用能力强)
|
||||
# - google/gemini-3-pro-preview (数学能力强，推荐数学试卷使用)
|
||||
# - openai/gpt-4o
|
||||
# - openai/gpt-4-turbo
|
||||
AI_MODEL=anthropic/claude-sonnet-4.5
|
||||
|
||||
# Parser Configuration
|
||||
USE_CLAUDE_PARSER=true
|
||||
EOF
|
||||
|
||||
print_success "后端配置已更新"
|
||||
|
||||
# 替换前端配置
|
||||
if [ -f "frontend/package.json" ]; then
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
sed -i '' "s/\"name\": \"wordmaster-frontend\"/\"name\": \"$PROJECT_NAME-frontend\"/g" frontend/package.json
|
||||
else
|
||||
sed -i "s/\"name\": \"wordmaster-frontend\"/\"name\": \"$PROJECT_NAME-frontend\"/g" frontend/package.json
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ -f "frontend/index.html" ]; then
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
sed -i '' "s/<title>.*<\/title>/<title>$PROJECT_DISPLAY_NAME<\/title>/g" frontend/index.html
|
||||
else
|
||||
sed -i "s/<title>.*<\/title>/<title>$PROJECT_DISPLAY_NAME<\/title>/g" frontend/index.html
|
||||
fi
|
||||
fi
|
||||
|
||||
# 更新前端配置文件
|
||||
if [ -f "frontend/src/config/index.js" ]; then
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
sed -i '' "s/:8888/:$API_PORT/g" frontend/src/config/index.js
|
||||
else
|
||||
sed -i "s/:8888/:$API_PORT/g" frontend/src/config/index.js
|
||||
fi
|
||||
fi
|
||||
|
||||
print_success "前端配置已更新"
|
||||
|
||||
# 4. 创建 README
|
||||
print_info "生成项目 README..."
|
||||
|
||||
cat > README.md << EOF
|
||||
# $PROJECT_DISPLAY_NAME
|
||||
|
||||
基于 FastAPI + Vue 3 全栈模板创建的项目。
|
||||
|
||||
## 快速启动
|
||||
|
||||
### 后端
|
||||
|
||||
\`\`\`bash
|
||||
cd backend
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 启动服务
|
||||
python main.py
|
||||
# 访问 http://localhost:$API_PORT
|
||||
# API 文档: http://localhost:$API_PORT/docs
|
||||
\`\`\`
|
||||
|
||||
### 前端
|
||||
|
||||
\`\`\`bash
|
||||
cd frontend
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
# 访问 http://localhost:$FRONTEND_PORT
|
||||
\`\`\`
|
||||
|
||||
### 使用启动脚本
|
||||
|
||||
\`\`\`bash
|
||||
# 同时启动前后端
|
||||
./start.sh
|
||||
|
||||
# 查看状态
|
||||
./status.sh
|
||||
|
||||
# 停止所有服务
|
||||
./stop.sh
|
||||
\`\`\`
|
||||
|
||||
## 配置
|
||||
|
||||
### 环境变量
|
||||
|
||||
后端配置文件: \`backend/.env\`
|
||||
|
||||
主要配置项:
|
||||
- \`DATABASE_URL\`: 数据库连接
|
||||
- \`SECRET_KEY\`: JWT 密钥 (已自动生成)
|
||||
- \`OPENROUTER_API_KEY\`: AI API 密钥 (可选)
|
||||
|
||||
### 端口配置
|
||||
|
||||
- 后端 API: $API_PORT
|
||||
- 前端开发: $FRONTEND_PORT
|
||||
|
||||
## 数据库
|
||||
|
||||
- 类型: $([ "$DB_TYPE" = "2" ] && echo "PostgreSQL" || echo "SQLite")
|
||||
- 数据库名: $DATABASE_NAME
|
||||
$([ "$DB_TYPE" = "2" ] && echo "- 连接: $PG_HOST:$PG_PORT" || echo "- 文件: $DATABASE_NAME.db")
|
||||
|
||||
首次运行时会自动创建数据库表。
|
||||
|
||||
## 技术栈
|
||||
|
||||
**后端:**
|
||||
- FastAPI - 高性能 Web 框架
|
||||
- SQLAlchemy - ORM
|
||||
- JWT - 身份认证
|
||||
- Pydantic - 数据验证
|
||||
|
||||
**前端:**
|
||||
- Vue 3 - 渐进式框架
|
||||
- Element Plus - UI 组件库
|
||||
- Pinia - 状态管理
|
||||
- Vite - 构建工具
|
||||
|
||||
## 文档
|
||||
|
||||
- 查看 \`TEMPLATE_GUIDE.md\` 了解详细开发指南
|
||||
- 查看 \`CLAUDE.md\` 了解项目架构
|
||||
|
||||
## 部署
|
||||
|
||||
请参考 \`TEMPLATE_GUIDE.md\` 中的部署章节。
|
||||
|
||||
---
|
||||
|
||||
创建时间: $(date +%Y-%m-%d)
|
||||
EOF
|
||||
|
||||
print_success "README 已生成"
|
||||
|
||||
# 5. 初始化 git
|
||||
print_info "初始化 Git 仓库..."
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial commit: Created from template
|
||||
|
||||
Project: $PROJECT_DISPLAY_NAME
|
||||
Database: $DATABASE_NAME
|
||||
API Port: $API_PORT
|
||||
Frontend Port: $FRONTEND_PORT
|
||||
"
|
||||
|
||||
print_success "Git 仓库已初始化"
|
||||
|
||||
# 6. 创建启动帮助文档
|
||||
cat > GETTING_STARTED.md << EOF
|
||||
# 快速开始指南
|
||||
|
||||
## 第一次运行
|
||||
|
||||
### 1. 配置环境
|
||||
|
||||
#### 后端配置
|
||||
已自动生成 \`backend/.env\` 文件，主要配置:
|
||||
- ✅ 数据库已配置: $DATABASE_NAME
|
||||
- ✅ JWT 密钥已生成
|
||||
- ⚠️ 如需 AI 功能，请在 \`backend/.env\` 中设置 \`OPENROUTER_API_KEY\`
|
||||
|
||||
#### 前端配置
|
||||
默认配置已就绪，无需修改。
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
#### 后端依赖
|
||||
\`\`\`bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
\`\`\`
|
||||
|
||||
推荐使用虚拟环境:
|
||||
\`\`\`bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# 或
|
||||
venv\\Scripts\\activate # Windows
|
||||
pip install -r requirements.txt
|
||||
\`\`\`
|
||||
|
||||
#### 前端依赖
|
||||
\`\`\`bash
|
||||
cd frontend
|
||||
npm install
|
||||
# 或使用 yarn
|
||||
yarn install
|
||||
\`\`\`
|
||||
|
||||
### 3. 启动开发服务器
|
||||
|
||||
#### 方式一: 使用启动脚本 (推荐)
|
||||
\`\`\`bash
|
||||
./start.sh
|
||||
\`\`\`
|
||||
|
||||
#### 方式二: 手动启动
|
||||
|
||||
**后端:**
|
||||
\`\`\`bash
|
||||
cd backend
|
||||
python main.py
|
||||
\`\`\`
|
||||
|
||||
**前端:**
|
||||
\`\`\`bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
\`\`\`
|
||||
|
||||
### 4. 访问应用
|
||||
|
||||
- 前端界面: http://localhost:$FRONTEND_PORT
|
||||
- 后端 API: http://localhost:$API_PORT
|
||||
- API 文档: http://localhost:$API_PORT/docs
|
||||
|
||||
### 5. 默认账户
|
||||
|
||||
首次访问需要注册账户。系统会自动创建数据库表。
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 添加新功能
|
||||
|
||||
1. **后端 API**
|
||||
- 编辑 \`backend/main.py\`
|
||||
- 添加新的端点和数据模型
|
||||
- 自动重载会生效
|
||||
|
||||
2. **前端页面**
|
||||
- 在 \`frontend/src/views/\` 创建新组件
|
||||
- 在 \`frontend/src/router/index.js\` 注册路由
|
||||
- Vite 会自动热更新
|
||||
|
||||
3. **状态管理**
|
||||
- 在 \`frontend/src/stores/\` 创建新 store
|
||||
- 使用 Pinia 管理全局状态
|
||||
|
||||
### 调试技巧
|
||||
|
||||
**后端调试:**
|
||||
- 查看终端日志
|
||||
- 访问 http://localhost:$API_PORT/docs 测试 API
|
||||
- 使用 Python 调试器
|
||||
|
||||
**前端调试:**
|
||||
- 使用浏览器开发者工具
|
||||
- Vue DevTools 扩展
|
||||
- 检查网络请求
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 端口被占用
|
||||
修改配置文件中的端口号:
|
||||
- 后端: \`backend/.env\` 或 \`backend/main.py\`
|
||||
- 前端: \`frontend/vite.config.js\`
|
||||
|
||||
### 数据库连接失败
|
||||
- SQLite: 检查文件权限
|
||||
- PostgreSQL: 检查连接字符串和服务状态
|
||||
|
||||
### 前端 API 请求失败
|
||||
检查 \`frontend/src/config/index.js\` 中的 API_BASE_URL 配置
|
||||
|
||||
## 下一步
|
||||
|
||||
- 📖 阅读 \`TEMPLATE_GUIDE.md\` 了解完整功能
|
||||
- 🔧 根据需求定制功能模块
|
||||
- 🚀 参考部署指南发布应用
|
||||
|
||||
祝开发顺利! 🎉
|
||||
EOF
|
||||
|
||||
print_success "快速开始指南已生成"
|
||||
|
||||
# 完成
|
||||
echo ""
|
||||
print_header "项目创建完成!"
|
||||
echo ""
|
||||
echo -e "${GREEN}✨ 项目已成功创建在: $TARGET_DIR${NC}"
|
||||
echo ""
|
||||
echo -e "${BLUE}下一步:${NC}"
|
||||
echo ""
|
||||
echo -e " 1. 进入项目目录:"
|
||||
echo -e " ${YELLOW}cd $TARGET_DIR${NC}"
|
||||
echo ""
|
||||
echo -e " 2. 安装后端依赖:"
|
||||
echo -e " ${YELLOW}cd backend && pip install -r requirements.txt${NC}"
|
||||
echo ""
|
||||
echo -e " 3. 安装前端依赖:"
|
||||
echo -e " ${YELLOW}cd frontend && npm install${NC}"
|
||||
echo ""
|
||||
echo -e " 4. 启动项目:"
|
||||
echo -e " ${YELLOW}./start.sh${NC}"
|
||||
echo ""
|
||||
echo -e " 5. 访问应用:"
|
||||
echo -e " ${YELLOW}http://localhost:$FRONTEND_PORT${NC}"
|
||||
echo ""
|
||||
echo -e "${BLUE}📚 详细文档:${NC}"
|
||||
echo -e " - GETTING_STARTED.md - 快速开始"
|
||||
echo -e " - TEMPLATE_GUIDE.md - 完整指南"
|
||||
echo -e " - README.md - 项目说明"
|
||||
echo ""
|
||||
print_success "祝您开发顺利! 🚀"
|
||||
echo ""
|
||||
@@ -0,0 +1,114 @@
|
||||
{
|
||||
"template": {
|
||||
"name": "FastAPI-Vue3 Full-Stack Template",
|
||||
"version": "1.0.0",
|
||||
"description": "A production-ready full-stack template with FastAPI backend and Vue 3 frontend",
|
||||
"author": "Your Name",
|
||||
"license": "MIT"
|
||||
},
|
||||
|
||||
"features": {
|
||||
"backend": {
|
||||
"framework": "FastAPI",
|
||||
"database": "PostgreSQL/SQLite",
|
||||
"authentication": "JWT",
|
||||
"fileUpload": true,
|
||||
"aiIntegration": true,
|
||||
"pdfProcessing": true
|
||||
},
|
||||
"frontend": {
|
||||
"framework": "Vue 3",
|
||||
"uiLibrary": "Element Plus",
|
||||
"stateManagement": "Pinia",
|
||||
"buildTool": "Vite",
|
||||
"router": true
|
||||
}
|
||||
},
|
||||
|
||||
"configurable": {
|
||||
"projectName": {
|
||||
"description": "Your new project name",
|
||||
"default": "my-app",
|
||||
"placeholder": "my-awesome-app"
|
||||
},
|
||||
"projectDisplayName": {
|
||||
"description": "Display name for your application",
|
||||
"default": "My Application",
|
||||
"placeholder": "My Awesome App"
|
||||
},
|
||||
"databaseName": {
|
||||
"description": "Database name",
|
||||
"default": "myapp_db",
|
||||
"placeholder": "your_database_name"
|
||||
},
|
||||
"apiPort": {
|
||||
"description": "Backend API port",
|
||||
"default": 8888,
|
||||
"placeholder": 8888
|
||||
},
|
||||
"frontendPort": {
|
||||
"description": "Frontend development server port",
|
||||
"default": 3000,
|
||||
"placeholder": 3000
|
||||
},
|
||||
"domainName": {
|
||||
"description": "Production domain (optional)",
|
||||
"default": "",
|
||||
"placeholder": "your-domain.com"
|
||||
}
|
||||
},
|
||||
|
||||
"replacements": {
|
||||
"backend": [
|
||||
{
|
||||
"file": "backend/main.py",
|
||||
"patterns": [
|
||||
{"find": "wordmaster", "replace": "{{databaseName}}"},
|
||||
{"find": "学习助手 Pro", "replace": "{{projectDisplayName}}"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"file": "backend/.env.example",
|
||||
"patterns": [
|
||||
{"find": "wordmaster", "replace": "{{databaseName}}"},
|
||||
{"find": "8888", "replace": "{{apiPort}}"}
|
||||
]
|
||||
}
|
||||
],
|
||||
"frontend": [
|
||||
{
|
||||
"file": "frontend/package.json",
|
||||
"patterns": [
|
||||
{"find": "wordmaster-frontend", "replace": "{{projectName}}-frontend"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"file": "frontend/src/config/index.js",
|
||||
"patterns": [
|
||||
{"find": "8888", "replace": "{{apiPort}}"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"file": "frontend/index.html",
|
||||
"patterns": [
|
||||
{"find": "学习助手 Pro", "replace": "{{projectDisplayName}}"}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"cleanupFiles": [
|
||||
"backend/wordmaster.db",
|
||||
"backend/uploads/*",
|
||||
"backend/__pycache__",
|
||||
"frontend/node_modules",
|
||||
"frontend/dist",
|
||||
".git"
|
||||
],
|
||||
|
||||
"keepExampleFiles": [
|
||||
"backend/.env.example",
|
||||
"TEMPLATE_GUIDE.md",
|
||||
"template.config.json"
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user