hair_change_color/docs/DEPLOYMENT.md

发型更换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. 进入后端目录

   cd backend
   

3. 安装依赖

   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 启动服务

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

   pip install gunicorn
   

2. 启动服务

   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 反向代理

   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 调用地址：

// 修改 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 文件，添加或修改发型数据：

{
  "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 响应数据格式