进阶 docs.voicebox.sh 2026-10-11 09:58:06 · 25 阅读

第22章构建指南：PyInstaller 与 Tauri 打包实践

第 22 章：构建

开发者向
概述
Voicebox 采用两阶段构建流程：

Python 服务器二进制文件：使用 PyInstaller 将 FastAPI 后端打包为独立可执行文件
Tauri 桌面应用：将 React 前端、Rust 封装层和 Python 服务器作为 sidecar 打包在一起

构建命令

just build          # 构建所有内容（服务器 + Tauri）
just build-server   # 仅构建 Python 服务器二进制文件
just build-tauri    # 仅构建 Tauri 应用

服务器二进制文件构建

构建脚本

# 确定平台（例如 x86_64-apple-darwin）
PLATFORM=$(rustc --print host-tuple)

# 通过 build_binary.py 运行 PyInstaller
cd backend
python build_binary.py

# 复制到 Tauri 的二进制目录
cp dist/voicebox-server ../tauri/src-tauri/binaries/voicebox-server-${PLATFORM}

PyInstaller 配置
backend/build_binary.py 包含 PyInstaller 的配置细节：

入口点：使用 server.py（而非 main.py）以支持 Tauri sidecar
关键选项：
- --onefile：生成单个可执行文件
- --hidden-import：显式导入 PyInstaller 无法自动检测的模块
- --collect-all：为 mlx、zipvoice 等包捆绑数据文件和原生库
- --exclude-module：在 CPU 构建中剔除 NVIDIA 相关包

平台特定逻辑：

# Apple Silicon — 包含 MLX 后端
if is_apple_silicon() and not cuda:
    args.extend([
        "--hidden-import", "mlx",
        "--collect-all", "mlx",        # 捆绑 .dylib 和 .metallib 文件
    ])

# CUDA 构建 — 包含 torch.cuda
if cuda:
    args.extend(["--hidden-import", "torch.cuda"])

# CPU 构建 — 排除 NVIDIA 包以节省约 3GB 空间
else:
    for pkg in ["nvidia", "nvidia.cublas", "nvidia.cudnn", ...]:
        args.extend(["--exclude-module", pkg])

环境变量：

export QWEN_TTS_PATH=~/path/to/Qwen3-TTS  # 使用本地 Qwen3-TTS 源码

CUDA 二进制文件
由于体积原因（约 2.43 GB，而 CPU 版本仅约 410 MB），支持 CUDA 的服务器需单独构建：

cd backend
python build_binary.py --cuda

生成的二进制文件过大，无法直接托管在 GitHub Releases 上，因此会被拆分成分卷进行分发（下载机制详见 Auto-Updater 文档）。

Tauri 应用构建

Tauri 将所有组件整合在一起：

cd tauri
bun run tauri build

构建过程包含以下操作：

Vite 构建 React 前端
Rust 编译 Tauri 封装层
从 src-tauri/binaries/ 复制 sidecar 二进制文件
生成特定平台的安装包（DMG、MSI、AppImage）

输出位置：

dmg/msi/nsis/appimage/

Sidecar 配置

在 tauri.conf.json 中，服务器二进制文件被声明为外部二进制文件：

{
  "tauri": {
    "bundle": {
      "externalBin": ["binaries/voicebox-server"]
    }
  }
}

Tauri 会在 src-tauri/binaries/ 中查找 voicebox-server-${PLATFORM} 并将其打包。

GitHub Actions 发布

.github/workflows/release.yml 自动化了完整构建流程。

矩阵策略

平台	目标架构	后端	备注
macos-latest	aarch64-apple-darwin	MLX	Apple Silicon 原生
macos-15-intel	x86_64-apple-darwin	PyTorch	Intel Mac
windows-latest	x86_64-pc-windows-msvc	PyTorch	Windows，可选 CUDA

构建步骤

环境配置：安装 Python、Rust、Bun 及依赖项
构建服务器：在 Unix 上使用 build-server.sh，在 Windows 上使用 build_binary.py
构建 Tauri：使用带签名密钥的 tauri-action
上传：发布 Release 产物和 latest.json

代码签名

macOS：

从 secrets 导入 Apple Developer 证书
通过 App Store Connect API 进行公证

Windows：

Tauri 通过 TAURI_SIGNING_PRIVATE_KEY 处理签名

CUDA 二进制文件（独立任务）

build-cuda-windows 任务独立运行：

安装带 CUDA 12.8 的 PyTorch
运行 build_binary.py --cuda 构建（生成 --onedir 输出）
使用 scripts/package_cuda.py 打包为两个归档文件：
- voicebox-server-cuda-windows-x86_64.tar.gz — 服务器核心（约 945 MB）
- cuda-libs-windows-x86_64-cu128-v1.tar.gz — NVIDIA 运行时库（约 1.7 GB，独立缓存）
将归档文件作为 Release 产物上传

build-gpu-linux 矩阵任务在 ubuntu-latest 上执行相同流程，支持 CUDA（cu128）和 ROCm（PyTorch rocm7.2 索引），生成 voicebox-server-{cuda,rocm}-linux-x86_64.tar.gz 和 {cuda,rocm}-libs-linux-x86_64-<version>.tar.gz。

该二进制文件仅在用户于设置中启用 CUDA 时按需下载。CUDA 库归档仅在 CUDA 工具包版本变更时重新下载，而非每次应用更新时都下载。