165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
# 身体平衡评估系统 - 后端打包说明
|
||
|
||
本文档说明如何将后端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. 依赖版本是否兼容
|
||
|
||
---
|
||
|
||
**注意**：首次打包可能需要较长时间，请耐心等待。建议在虚拟环境中进行打包以避免依赖冲突。 |