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