BodyBalanceEvaluation/backend/BUILD_README.md

# 身体平衡评估系统 - 后端打包说明

本文档说明如何将后端Python应用程序打包成独立的exe可执行文件。

## 📋 打包前准备

### 1. 环境要求
- Python 3.8+ (推荐 3.9-3.11)
- Windows 10/11 操作系统
- 至少 2GB 可用磁盘空间

### 2. 依赖检查
确保以下核心依赖已安装：
```bash
pip install Flask Flask-CORS Flask-SocketIO
pip install numpy opencv-python psutil
pip install PyInstaller
```

## 🚀 快速打包

### 方法一：使用批处理脚本（推荐）
1. 在backend目录下双击运行 `build_backend.bat`
2. 脚本会自动完成所有打包步骤
3. 等待打包完成

### 方法二：手动打包
1. 打开命令提示符，切换到backend目录
2. 运行打包脚本：
   ```bash
   python build_exe.py
   ```

### 方法三：直接使用PyInstaller
```bash
# 生成spec文件
pyinstaller --onefile --windowed --name=BodyBalanceBackend app.py

# 或使用自定义spec文件
pyinstaller backend.spec --clean --noconfirm
```

## 📁 输出文件结构

打包完成后，在 `dist/` 目录下会生成：

```
dist/
├── BodyBalanceBackend.exe     # 主可执行文件
├── start_backend.bat          # 启动脚本
├── config.ini                 # 配置文件
├── config.json               # JSON配置文件
└── logs/                     # 日志目录（运行时创建）
```

## 🔧 配置说明

### PyInstaller配置 (backend.spec)
- **--onefile**: 打包成单个exe文件
- **--windowed**: 隐藏控制台窗口（可选）
- **--add-data**: 包含数据文件
- **--add-binary**: 包含二进制文件（如DLL）
- **--hidden-import**: 包含隐式导入的模块

### 包含的文件
- 配置文件：`config.ini`, `config.json`
- 动态库：`dll/k4a.dll`（如果存在）
- 数据目录：`data/`, `captured_images/`, `tests/`

## 🚀 部署和运行

### 1. 部署到目标机器
1. 将整个 `dist/` 文件夹复制到目标机器
2. 确保目标机器安装了必要的运行时库

### 2. 运行方式

**方式一：直接运行**
```bash
BodyBalanceBackend.exe
```

**方式二：使用启动脚本**
```bash
start_backend.bat
```

**方式三：命令行运行**
```bash
cd dist
BodyBalanceBackend.exe
```

### 3. 访问服务
- 服务器地址：`http://localhost:5000`
- 健康检查：`http://localhost:5000/health`
- API文档：`http://localhost:5000/api/health`

## 🔍 故障排除

### 常见问题

**1. 打包失败**
- 检查Python版本是否兼容
- 确保所有依赖已正确安装
- 检查磁盘空间是否充足

**2. exe运行失败**
- 检查是否缺少Visual C++ Redistributable
- 查看logs目录下的错误日志
- 确保配置文件存在且格式正确

**3. 模块导入错误**
- 在spec文件中添加缺失的模块到 `hiddenimports`
- 检查第三方库的兼容性

**4. 文件路径问题**
- 确保所有相对路径正确
- 检查数据文件是否正确包含

### 调试方法

**1. 启用控制台输出**
修改spec文件中的 `console=True`

**2. 查看详细日志**
```bash
BodyBalanceBackend.exe --debug
```

**3. 测试模式运行**
```bash
python app.py
```

## 📝 自定义打包

### 修改打包配置
编辑 `build_exe.py` 文件，可以自定义：
- 输出文件名
- 包含的文件和目录
- 隐式导入的模块
- 图标文件

### 添加新的依赖
1. 在 `requirements_build.txt` 中添加新依赖
2. 在spec文件的 `hiddenimports` 中添加模块名
3. 重新打包

## 🔒 安全注意事项

1. **配置文件安全**：确保配置文件中不包含敏感信息
2. **网络安全**：默认绑定所有接口(0.0.0.0)，生产环境建议修改
3. **文件权限**：确保exe文件有适当的执行权限

## 📞 技术支持

如果遇到问题，请检查：
1. 日志文件：`logs/backend.log`
2. 系统要求是否满足
3. 依赖版本是否兼容

---

**注意**：首次打包可能需要较长时间，请耐心等待。建议在虚拟环境中进行打包以避免依赖冲突。