289 lines
5.8 KiB
Markdown
289 lines
5.8 KiB
Markdown
# 模板快速使用指南
|
|
|
|
## 三种使用方式
|
|
|
|
### 🚀 方式一: 自动化脚本 (最推荐)
|
|
|
|
```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. ✅ 开始开发你的功能
|
|
|
|
**祝你的项目开发顺利!** 🎉
|