我要开发一个h5的项目。 目标平台是PC浏览器和手机浏览器。 分为前端和后端。 后端采用python 不需要数据库，直接用文件系统，启动的时候读取到内存就可以。
功能 1、是前端能从后端拉起一组图片，分类为“男”，“女”。 这个图片是保存到oss文件系统的，后端需要提供图片的url。 2、前端可以选择一个图片，手动端可以拍摄图片或者选择图片。 3、前端发起更换发型的请求，把选择的图片和对应要更换的发型ID发给后端。 4、前端收到后端更换发型的请求后处理图片返回给前端。 5、后端实际处理更换发型请求的时候会调用另外一个远程的http接口来实现。 先帮我把项目结构，产品文档，系统框架等做出来。
This commit is contained in:
@@ -0,0 +1,285 @@
|
||||
# 发型更换H5项目启动和部署文档
|
||||
|
||||
## 1. 项目结构
|
||||
|
||||
```
|
||||
hair_change_color/
|
||||
├── backend/ # 后端Python服务
|
||||
│ ├── app.py # Flask应用主文件
|
||||
│ ├── config.py # 配置文件
|
||||
│ ├── data/ # 数据目录
|
||||
│ │ └── hairstyles.json # 发型数据配置
|
||||
│ └── requirements.txt # Python依赖
|
||||
├── frontend/ # 前端H5
|
||||
│ ├── index.html # 首页
|
||||
│ ├── css/ # CSS文件
|
||||
│ │ └── style.css # 主样式文件
|
||||
│ ├── js/ # JavaScript文件
|
||||
│ │ ├── main.js # 主逻辑
|
||||
│ │ └── api.js # API调用封装
|
||||
│ └── images/ # 前端静态图片
|
||||
└── docs/ # 文档
|
||||
├── PRD.md # 产品需求文档
|
||||
├── ARCHITECTURE.md # 系统架构文档
|
||||
└── DEPLOYMENT.md # 部署文档
|
||||
```
|
||||
|
||||
## 2. 开发环境搭建
|
||||
|
||||
### 2.1 后端环境
|
||||
|
||||
#### 2.1.1 依赖安装
|
||||
1. 确保已安装 Python 3.8+
|
||||
2. 进入后端目录
|
||||
```bash
|
||||
cd backend
|
||||
```
|
||||
3. 安装依赖
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
#### 2.1.2 配置修改
|
||||
1. 编辑 `config.py` 文件，修改以下配置：
|
||||
- `REMOTE_API_URL`：远程发型更换API地址
|
||||
- `API_TIMEOUT`：API请求超时时间
|
||||
|
||||
2. 编辑 `data/hairstyles.json` 文件，添加或修改发型数据：
|
||||
- 确保每个发型对象包含 `id`、`name`、`gender` 和 `image_url` 字段
|
||||
- `gender` 字段值为 `male` 或 `female`
|
||||
- `image_url` 为发型图片的OSS地址
|
||||
|
||||
#### 2.1.3 启动服务
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
服务将在 `http://127.0.0.1:5000` 启动
|
||||
|
||||
### 2.2 前端环境
|
||||
|
||||
#### 2.2.1 开发模式
|
||||
在开发环境中，前端文件通过后端Flask服务提供，无需单独配置。
|
||||
|
||||
1. 启动后端服务后，访问 `http://127.0.0.1:5000` 即可看到前端页面
|
||||
2. 前端代码修改后，刷新浏览器即可看到变化
|
||||
|
||||
## 3. 生产环境部署
|
||||
|
||||
### 3.1 后端部署
|
||||
|
||||
#### 3.1.1 使用 Gunicorn 部署
|
||||
1. 安装 Gunicorn
|
||||
```bash
|
||||
pip install gunicorn
|
||||
```
|
||||
|
||||
2. 启动服务
|
||||
```bash
|
||||
gunicorn -w 4 -b 0.0.0.0:5000 app:app
|
||||
```
|
||||
- `-w 4`：使用4个worker进程
|
||||
- `-b 0.0.0.0:5000`：绑定到所有网络接口的5000端口
|
||||
|
||||
#### 3.1.2 使用 Nginx 作为反向代理
|
||||
1. 安装 Nginx
|
||||
2. 配置 Nginx 反向代理
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:5000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 前端部署
|
||||
|
||||
#### 3.2.1 静态文件部署
|
||||
在生产环境中，建议将前端文件部署到 CDN 或静态文件服务器，以提高加载速度。
|
||||
|
||||
1. 复制前端文件到静态文件服务器
|
||||
2. 修改前端 `js/main.js` 中的 API 地址，指向后端服务地址
|
||||
|
||||
#### 3.2.2 配置示例
|
||||
修改前端 API 调用地址：
|
||||
```javascript
|
||||
// 修改 API 调用地址
|
||||
async function getHairstyles() {
|
||||
try {
|
||||
const response = await axios.get('https://api.example.com/api/hairstyles');
|
||||
return response.data;
|
||||
} catch (error) {
|
||||
console.error('获取发型列表失败:', error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function changeHair(imageFile, hairstyleId) {
|
||||
try {
|
||||
const formData = new FormData();
|
||||
formData.append('image', imageFile);
|
||||
formData.append('hairstyle_id', hairstyleId);
|
||||
|
||||
const response = await axios.post('https://api.example.com/api/change-hair', formData, {
|
||||
headers: {
|
||||
'Content-Type': 'multipart/form-data'
|
||||
}
|
||||
});
|
||||
return response.data;
|
||||
} catch (error) {
|
||||
console.error('更换发型失败:', error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 系统配置
|
||||
|
||||
### 4.1 后端配置
|
||||
|
||||
#### 4.1.1 主要配置项
|
||||
编辑 `backend/config.py` 文件：
|
||||
|
||||
| 配置项 | 描述 | 默认值 |
|
||||
|-------|------|-------|
|
||||
| APP_NAME | 应用名称 | "Hair Change Color" |
|
||||
| REMOTE_API_URL | 远程发型更换API地址 | "https://api.example.com/change-hair" |
|
||||
| API_TIMEOUT | API请求超时时间（秒） | 30 |
|
||||
| MAX_CONTENT_LENGTH | 文件上传大小限制 | 16MB |
|
||||
| ALLOWED_EXTENSIONS | 允许的文件类型 | {'png', 'jpg', 'jpeg', 'gif'} |
|
||||
| DEBUG | 调试模式 | True |
|
||||
|
||||
#### 4.1.2 发型数据配置
|
||||
编辑 `backend/data/hairstyles.json` 文件，添加或修改发型数据：
|
||||
|
||||
```json
|
||||
{
|
||||
"hairstyles": [
|
||||
{
|
||||
"id": "hair_001",
|
||||
"name": "时尚短发",
|
||||
"gender": "male",
|
||||
"image_url": "https://oss.example.com/hairstyles/male/hair_001.jpg"
|
||||
},
|
||||
// 更多发型...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 前端配置
|
||||
|
||||
#### 4.2.1 响应式设计
|
||||
前端页面采用响应式设计，自动适配不同屏幕尺寸：
|
||||
- 移动端：< 768px
|
||||
- 平板：768px - 1024px
|
||||
- PC端：> 1024px
|
||||
|
||||
#### 4.2.2 浏览器兼容性
|
||||
支持的浏览器：
|
||||
- Chrome (最新版)
|
||||
- Firefox (最新版)
|
||||
- Safari (最新版)
|
||||
- Edge (最新版)
|
||||
- 移动端浏览器
|
||||
|
||||
## 5. 常见问题与解决方案
|
||||
|
||||
### 5.1 后端服务启动失败
|
||||
- **问题**：`ModuleNotFoundError: No module named 'Flask'`
|
||||
**解决方案**：运行 `pip install -r requirements.txt` 安装依赖
|
||||
|
||||
- **问题**：`FileNotFoundError: [Errno 2] No such file or directory: 'data/hairstyles.json'`
|
||||
**解决方案**：确保 `data` 目录存在且包含 `hairstyles.json` 文件
|
||||
|
||||
### 5.2 前端页面无法访问
|
||||
- **问题**：后端服务未启动
|
||||
**解决方案**：运行 `python app.py` 启动后端服务
|
||||
|
||||
- **问题**：API 调用失败
|
||||
**解决方案**：检查浏览器控制台的网络请求，确认 API 地址是否正确
|
||||
|
||||
### 5.3 发型更换功能不工作
|
||||
- **问题**：远程 API 调用失败
|
||||
**解决方案**：检查 `config.py` 中的 `REMOTE_API_URL` 配置是否正确
|
||||
|
||||
- **问题**：上传图片失败
|
||||
**解决方案**：检查图片大小是否超过限制（默认16MB），以及文件类型是否被允许
|
||||
|
||||
## 6. 性能优化建议
|
||||
|
||||
### 6.1 前端优化
|
||||
- **图片压缩**：上传前压缩图片，减少传输时间
|
||||
- **缓存策略**：缓存发型列表数据，减少 API 调用
|
||||
- **懒加载**：实现发型图片懒加载，提高页面加载速度
|
||||
|
||||
### 6.2 后端优化
|
||||
- **使用生产服务器**：在生产环境中使用 Gunicorn 或 uWSGI 替代开发服务器
|
||||
- **启用 Gzip 压缩**：减少响应数据大小
|
||||
- **增加 worker 数量**：根据服务器配置增加 Gunicorn worker 数量
|
||||
|
||||
## 7. 安全建议
|
||||
|
||||
### 7.1 前端安全
|
||||
- **使用 HTTPS**：在生产环境中使用 HTTPS 协议
|
||||
- **验证文件类型**：前端验证上传文件类型，防止恶意文件
|
||||
|
||||
### 7.2 后端安全
|
||||
- **配置 CORS**：正确配置跨域资源共享，只允许指定域名访问
|
||||
- **限制文件大小**：设置合理的文件上传大小限制
|
||||
- **API 限流**：对发型更换接口实施限流，防止滥用
|
||||
- **验证请求参数**：验证所有请求参数，防止注入攻击
|
||||
|
||||
## 8. 监控与维护
|
||||
|
||||
### 8.1 日志管理
|
||||
- **Flask 日志**：后端服务日志默认输出到控制台
|
||||
- **访问日志**：使用 Nginx 等反向代理时，配置访问日志记录
|
||||
|
||||
### 8.2 健康检查
|
||||
- **API 健康检查**：定期检查 `/api/hairstyles` 接口是否正常响应
|
||||
- **服务状态监控**：监控后端服务运行状态，确保服务稳定
|
||||
|
||||
## 9. 部署流程总结
|
||||
|
||||
1. **准备环境**：
|
||||
- 安装 Python 3.8+
|
||||
- 安装依赖：`pip install -r backend/requirements.txt`
|
||||
|
||||
2. **配置项目**：
|
||||
- 修改 `backend/config.py` 中的远程 API 地址
|
||||
- 编辑 `backend/data/hairstyles.json` 添加发型数据
|
||||
|
||||
3. **启动服务**：
|
||||
- 开发环境：`python backend/app.py`
|
||||
- 生产环境：使用 Gunicorn 或 uWSGI 启动
|
||||
|
||||
4. **访问应用**：
|
||||
- 开发环境：`http://127.0.0.1:5000`
|
||||
- 生产环境：配置域名后访问
|
||||
|
||||
5. **维护更新**：
|
||||
- 更新发型数据：修改 `hairstyles.json` 文件
|
||||
- 更新代码：部署新代码后重启服务
|
||||
|
||||
## 10. 故障排除
|
||||
|
||||
### 10.1 服务无法启动
|
||||
- 检查端口是否被占用
|
||||
- 检查依赖是否安装完整
|
||||
- 检查配置文件是否正确
|
||||
|
||||
### 10.2 API 调用失败
|
||||
- 检查网络连接
|
||||
- 检查远程 API 服务是否可用
|
||||
- 检查 API 地址配置是否正确
|
||||
|
||||
### 10.3 前端页面异常
|
||||
- 清除浏览器缓存
|
||||
- 检查浏览器控制台错误信息
|
||||
- 验证 API 响应数据格式
|
||||
Reference in New Issue
Block a user