BodyBalanceEvaluation/install

最小功能测试框架

概述

这是一个最小功能测试框架，用于验证 Flask + SocketIO + threading 技术栈在打包成 exe 后的可用性。

功能特性

• ✅ Flask HTTP 服务
• ✅ SocketIO WebSocket 服务
• ✅ 强制使用 threading 异步模式
• ✅ 完整的前端测试界面
• ✅ HTTP API 测试
• ✅ WebSocket 连接测试
• ✅ 实时消息收发测试
• ✅ 系统信息显示

文件结构

install/
├── minimal_test_app.py      # 主应用文件
├── build_minimal.py         # 打包脚本
├── requirements_minimal.txt # 最小依赖列表
└── README.md               # 说明文档

快速开始

1. 安装依赖

pip install -r requirements_minimal.txt

2. 测试运行

python minimal_test_app.py

然后在浏览器中访问 http://localhost:5000 进行测试。

3. 打包成 exe

python build_minimal.py

4. 测试 exe

打包完成后，运行：

# 方式1：直接运行
dist/MinimalTestApp.exe

# 方式2：使用脚本
dist/start_test.bat

测试步骤

HTTP API 测试

1. 点击「测试 HTTP API」按钮
2. 确认返回成功响应
3. 检查响应数据包含服务器信息

WebSocket 测试

1. 页面加载时会自动连接 WebSocket
2. 确认连接状态显示为「已连接」
3. 点击「发送测试消息」
4. 确认能收到服务器响应
5. 测试断开和重连功能

系统信息检查

• 服务器时间：确认时间正确
• SocketIO模式：确认显示为 "threading"
• Flask版本：确认版本信息

技术要点

异步模式选择

# 强制使用 threading 模式，避免 eventlet/gevent 依赖问题
socketio = SocketIO(
    app, 
    cors_allowed_origins='*', 
    async_mode='threading',  # 关键配置
    logger=False,
    engineio_logger=False
)

打包配置

# PyInstaller 隐藏导入配置
hiddenimports=[
    'flask',
    'flask_socketio',
    'socketio',
    'engineio',
    'engineio.async_drivers.threading',  # 关键：threading 驱动
    'socketio.namespace',
    'dns',
    'dns.resolver',
    'dns.asyncresolver'
],
# 排除不需要的异步模式
excludes=[
    'eventlet',
    'gevent', 
    'gevent_uwsgi'
]

故障排除

常见问题

1. "Invalid async_mode specified" 错误

   • 确认已安装所有依赖
   • 检查 PyInstaller 隐藏导入配置
   • 确认排除了不需要的异步模式

2. WebSocket 连接失败

   • 检查防火墙设置
   • 确认端口 5000 未被占用
   • 查看控制台错误信息

3. 打包失败

   • 确认 PyInstaller 版本兼容
   • 检查依赖版本冲突
   • 查看详细错误输出

调试模式

如需调试，可以修改 minimal_test_app.py：

# 启用调试模式
socketio.run(
    app,
    host='0.0.0.0',
    port=5000,
    debug=True,  # 启用调试
    allow_unsafe_werkzeug=True
)

扩展指南

添加新功能

1. 新增 HTTP 路由

   @app.route('/api/new-endpoint')
   def new_endpoint():
       return jsonify({'message': 'New endpoint'})
   

2. 新增 SocketIO 事件

   @socketio.on('new_event')
   def handle_new_event(data):
       emit('response', {'status': 'received'})
   

3. 添加依赖

   • 更新 requirements_minimal.txt
   • 更新 build_minimal.py 中的 hiddenimports
   • 重新测试打包

渐进式集成

按照以下顺序逐步添加业务功能：

1. ✅ 基础 Flask + SocketIO（当前阶段）
2. 🔄 添加数据库支持
3. 🔄 添加文件操作
4. 🔄 添加外部库依赖
5. 🔄 添加硬件设备支持

每个阶段都要确保打包和运行正常，出现问题时更容易定位。

版本信息

• Flask: 2.3.3
• Flask-SocketIO: 5.3.6
• PyInstaller: 6.1.0
• Python: 3.8+

许可证

MIT License