BodyBalanceEvaluation/backend/BUILD_README.md

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

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

📋 打包前准备

1. 环境要求

• Python 3.8+ (推荐 3.9-3.11)
• Windows 10/11 操作系统
• 至少 2GB 可用磁盘空间

2. 依赖检查

确保以下核心依赖已安装：

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. 运行打包脚本：

   python build_exe.py
   

方法三：直接使用PyInstaller

# 生成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. 运行方式

方式一：直接运行

BodyBalanceBackend.exe

方式二：使用启动脚本

start_backend.bat

方式三：命令行运行

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. 查看详细日志

BodyBalanceBackend.exe --debug

3. 测试模式运行

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. 依赖版本是否兼容

---

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