6.5 KiB

Raw Permalink Blame History

Python Core 分发解决方案

问题背景

当前项目使用 python -m python_core.services.xxx 的方式调用Python模块，这在开发环境下工作正常，但打包成exe后会遇到以下问题：

Python环境依赖：用户机器可能没有安装Python或缺少依赖包
模块路径问题：python_core目录不在用户的Python路径中
分发复杂性：需要用户单独安装Python环境

解决方案：Tauri Sidecar + PyInstaller

方案概述

使用PyInstaller将Python代码打包成独立可执行文件，作为Tauri的sidecar与主应用一起分发。

优势

无需Python环境：用户无需安装Python
依赖自包含：所有Python依赖都打包在内
分发简单：单个exe文件包含所有功能
性能优化：避免Python解释器启动开销
安全性：代码被编译，不易被逆向

实现步骤

1. 创建Python入口文件

文件: python_core/main.py

这是PyInstaller的入口点，提供统一的命令行接口：

# 支持模块映射
MODULE_MAP = {
    'template_manager': 'services.template_manager',
    'project_manager': 'services.project_manager',
    # ... 更多模块
}

# 统一的执行接口
def execute_action(module_name, action, params=None, progress_callback=None):
    # 动态加载和执行模块函数

2. PyInstaller配置

文件: python_core/build.spec

配置打包选项：

隐藏导入：确保所有模块被包含
数据文件：包含配置和资源文件
排除模块：减少打包大小
单文件模式：生成单个可执行文件

3. 自动化构建脚本

文件: scripts/build_python_core.py

提供完整的构建流程：

安装构建依赖
清理构建目录
运行PyInstaller
复制到sidecar目录
更新Tauri配置
验证构建结果

4. Rust代码适配

文件: src-tauri/src/python_executor.rs

添加sidecar支持：

自动检测sidecar可用性
开发环境使用系统Python
生产环境使用sidecar
统一的API接口

使用方法

构建Python Core

Windows

scripts\build_python_core.bat

Linux/macOS

./scripts/build_python_core.sh

手动构建

python scripts/build_python_core.py

开发和测试

# 开发模式（使用系统Python）
cargo tauri dev

# 生产构建（包含sidecar）
cargo tauri build

API调用

// 新的模块化API
use crate::python_executor::execute_python_module_action;

#[tauri::command]
pub async fn my_command(app: AppHandle) -> Result<String, String> {
    let params = serde_json::json!({
        "folder_path": "/path/to/templates",
        "force_reimport": false
    });
    
    execute_python_module_action(
        app,
        "template_manager",  // 模块名
        "batch_import",      // 动作名
        Some(params),        // 参数
        None                 // 配置
    ).await
}

文件结构

project/
├── python_core/
│   ├── main.py              # PyInstaller入口文件
│   ├── build.spec           # PyInstaller配置
│   ├── services/            # 服务模块
│   ├── utils/               # 工具模块
│   └── ...
├── scripts/
│   ├── build_python_core.py # 构建脚本
│   ├── build_python_core.bat# Windows批处理
│   └── build_python_core.sh # Linux/macOS脚本
├── src-tauri/
│   ├── binaries/            # sidecar可执行文件
│   │   └── mixvideo-python-core(.exe)
│   ├── src/
│   │   └── python_executor.rs # 更新的执行器
│   └── tauri.conf.json      # 更新的配置
└── docs/
    └── PYTHON_CORE_DISTRIBUTION.md

配置说明

Tauri配置更新

src-tauri/tauri.conf.json:

{
  "bundle": {
    "externalBin": [
      {
        "name": "mixvideo-python-core",
        "src": "binaries/mixvideo-python-core",
        "targets": ["all"]
      }
    ]
  }
}

环境检测逻辑

fn should_use_sidecar() -> bool {
    #[cfg(not(debug_assertions))]
    {
        // 生产环境：检查sidecar是否存在
        return get_sidecar_path().is_some();
    }
    
    // 开发环境：使用系统Python
    false
}

性能对比

方案	启动时间	内存占用	分发大小	依赖管理
系统Python	慢	低	小	复杂
PyInstaller	快	中	大	简单

故障排除

常见问题

1. 构建失败

# 检查Python环境
python --version
pip --version

# 安装构建依赖
pip install pyinstaller requests Pillow opencv-python-headless

2. 模块导入错误

检查 build.spec 中的 hiddenimports
添加缺失的模块到隐藏导入列表

3. 资源文件缺失

检查 build.spec 中的 datas 配置
确保所有资源文件都被包含

4. sidecar不可用

检查 src-tauri/binaries/ 目录
验证可执行文件权限
查看Tauri配置中的sidecar设置

调试方法

1. 测试sidecar

# 直接测试可执行文件
./src-tauri/binaries/mixvideo-python-core --version
./src-tauri/binaries/mixvideo-python-core --module template_manager --action get_templates

2. 查看日志

// 在Rust代码中添加调试输出
println!("Using sidecar: {}", should_use_sidecar());
println!("Sidecar path: {:?}", get_sidecar_path());

3. 环境变量

# 强制使用系统Python（调试用）
export MIXVIDEO_FORCE_SYSTEM_PYTHON=1

最佳实践

1. 开发流程

在开发环境使用系统Python进行开发和测试
定期构建sidecar验证打包正确性
在CI/CD中自动化构建流程

2. 版本管理

为sidecar添加版本信息
在主应用中检查sidecar版本兼容性
提供版本不匹配时的降级方案

3. 错误处理

提供详细的错误信息
实现自动重试机制
支持降级到系统Python

4. 性能优化

使用单文件模式减少启动时间
排除不必要的模块减少大小
考虑使用UPX压缩可执行文件

未来改进

短期计划

添加自动更新机制
支持插件化架构
优化启动性能

长期计划

考虑使用Rust重写核心逻辑
支持多语言sidecar
集成云端分发

通过这个解决方案，我们成功解决了Python代码分发的问题，为用户提供了无需Python环境的一体化体验。

6.5 KiB Raw Permalink Blame History Unescape Escape