第23章 Auto-Updater（自动更新器）

概述

Voicebox 使用 Tauri 内置的自动更新器向用户推送经过签名的更新。系统会在安装前对更新包进行加密验证。

工作原理

Voicebox 启动时（仅限生产环境的 Tauri 构建），会从 GitHub Releases 拉取 latest.json 清单检查是否有新版本。如果发现更新的版本：

1. 通知 — 应用顶部出现更新横幅 2. 下载 — 用户点击"立即安装"下载更新包 3. 验证 — 使用 tauri.conf.json 中内嵌的公钥对下载的更新包进行加密验证 4. 安装 — 验证通过后安装更新 5. 重启 — 应用自动重启并运行新版本

用户也可以通过"设置 → 检查更新"手动检查更新。

配置

更新器在 tauri/src-tauri/tauri.conf.json 中配置：

```json { "plugins": { "updater": { "active": true, "dialog": false, "endpoints": [ "https://github.com/jamiepine/voicebox/releases/latest/download/latest.json" ], "pubkey": "PASTE_PUBLIC_KEY_CONTENT_HERE" } } } ```

关键配置项：

- endpoints — latest.json 清单的 URL（应用启动时检查） - pubkey — 用于验证更新签名的公钥 - dialog — 设为 false（我们使用自定义 UI，而非 Tauri 内置对话框）

发布清单

latest.json 文件定义了各平台可用的更新：

```json { "version": "0.2.0", "notes": "Bug fixes and improvements", "pub_date": "2026-01-25T12:00:00Z", "platforms": { "darwin-aarch64": { "signature": "base64_encoded_signature", "url": "https://github.com/jamiepine/voicebox/releases/download/v0.2.0/voicebox_0.2.0_aarch64.app.tar.gz" }, "darwin-x86_64": { "signature": "base64_encoded_signature", "url": "https://github.com/jamiepine/voicebox/releases/download/v0.2.0/voicebox_0.2.0_x64.app.tar.gz" }, "linux-x86_64": { "signature": "base64_encoded_signature", "url": "https://github.com/jamiepine/voicebox/releases/download/v0.2.0/voicebox_0.2.0_amd64.AppImage" }, "windows-x86_64": { "signature": "base64_encoded_signature", "url": "https://github.com/jamiepine/voicebox/releases/download/v0.2.0/voicebox_0.2.0_x64_en-US.msi" } } } ```

签名

更新包必须经过加密签名才能被接受。签名流程如下：

1. 生成密钥（一次性设置）：

```bash bun tauri signer generate -w ~/.tauri/voicebox.key ```

这会生成：

- 私钥：~/.tauri/voicebox.key（存放在 GitHub Secrets 中，绝不提交到仓库） - 公钥：~/.tauri/voicebox.key.pub（粘贴到 tauri.conf.json 中）

2. 带签名构建（由 GitHub Actions 处理）： - 设置 TAURI_SIGNING_PRIVATE_KEY 环境变量 - Tauri 在构建过程中对更新包签名 - 在安装包旁生成 .sig 签名文件

3. 验证 — 更新器在安装前将签名与公钥比对

GitHub Actions 工作流

发布工作流（.github/workflows/release.yml）会自动：

- 为 macOS、Windows 和 Linux 构建带签名的发布包 - 生成包含签名的 latest.json 清单 - 将所有文件上传到 GitHub Release

通过推送 git 标签触发：

```bash git tag v0.2.0 && git push --tags ```

环境变量

GitHub Actions 需要设置以下 Secrets：

- TAURI_SIGNING_PRIVATE_KEY — ~/.tauri/voicebox.key 的内容 - TAURI_SIGNING_PRIVATE_KEY_PASSWORD — 密钥密码（如果设置了）

安全性

重要：切勿提交私钥。私钥只能存放在 GitHub Secrets 中。tauri.conf.json 中的公钥可以安全地提交和分发。

- 更新包使用 Ed25519 加密签名 - 禁用 HTTP 端点（仅允许 HTTPS） - 安装前进行签名验证 - 验证失败将中止更新

故障排查

"Invalid signature"（签名无效）错误

- tauri.conf.json 中的公钥与签名所用私钥不匹配 - 签名文件未上传到 Release

存在新版本却提示"No update available"（无可用更新）

- latest.json 中的版本号不高于当前版本 - 配置中的端点 URL 有误 - 清单尚未同步到 GitHub CDN

开发模式下更新检查失败

更新器仅在生产环境的 Tauri 构建中生效，在 just dev 或 web 模式下不会运行。

构建时签名报错

- GitHub Secrets 配置有误 - 私钥文件缺失或损坏 - 密钥格式错误（应以 dW50cnVzdGVkIGNvbW1lbnQ6 开头）

CUDA 后端更新

支持 CUDA 的后端与主应用分开分发，因为如果捆绑 CUDA，安装包会膨胀好几个 GB，而这对没有 NVIDIA GPU 的用户来说是多余的。与 Tauri 自动更新器不同，CUDA 后端采用 Python 服务器内置的自定义下载系统。

体积对比（约值）：

- 标准 CPU 包（包含在安装包中）：约 200–400 MB - CUDA 服务器核心：约 945 MB（随每次 Voicebox 发布更新版本） - CUDA 库（NVIDIA 运行时 DLL）：约 1.7 GB（独立版本管理，升级时可复用缓存）

双压缩包拆分

从 v0.4 开始，CUDA 二进制文件拆分为两个压缩包分发：

- 服务器核心（voicebox-server-cuda-<platform>.tar.gz，<platform> 为 windows-x86_64 或 linux-x86_64）— Python 服务器 + PyTorch 代码，每次发布都会更新。 - CUDA 库（cuda-libs-<platform>-cu128-v1.tar.gz）— 体积较大的 NVIDIA CUDA/cuDNN DLL，只在 CUDA 工具链大版本变化时才需要重新下载。

这意味着大多数 Voicebox 升级只需重新下载约 945 MB 的服务器核心，而不是完整的约 2.5 GB 包。

下载流程

当用户在"设置 → GPU"中点击"安装 CUDA 后端"时：

1. 服务器核心包 — 从 GitHub Releases 下载并解压 2. CUDA 库包 — 单独下载（如果已安装的版本匹配则直接复用） 3. 验证 — 通过 SHA-256 校验和验证完整性 4. 放置 — 解压到 {data_dir}/backends/cuda/ 5. 重启 — Voicebox 服务器重启并切换到 CUDA 后端

启动时自动更新

启动时，后端会比对已安装的 CUDA 服务器核心版本与当前应用版本。如果不一致，会在后台拉取核心包。如果新版本锁定的库版本也发生了变化（较少见，例如 cu126 → cu128 升级），会提示用户确认这次较大的下载。

存储位置

下载的 CUDA 二进制文件存放在应用的数据目录中：

``` {data_dir}/backends/cuda/ voicebox-server-cuda.exe # Windows voicebox-server-cuda # macOS/Linux ```

API 端点

| 端点 | 方法 | 说明 | | --- | --- | --- | | /backend/cuda-status | GET | 检查 CUDA 后端是否可用/激活，以及已安装的版本 | | /backend/download-cuda | POST | 触发服务器核心 + 库的下载 | | /backend/cuda-progress | GET | SSE 下载进度流 | | /backend/cuda | DELETE | 移除已下载的 CUDA 后端 |

进度追踪

下载进度通过 Server-Sent Events（SSE）上报：

``` GET /backend/cuda-progress

event: progress data: {"current": 52428800, "total": 945000000, "filename": "voicebox-server-cuda-windows-x86_64.tar.gz", "status": "downloading"} ```

前端订阅该端点以实时展示进度，包括当前正在下载的是哪个包（服务器核心还是库）。

发布产物

每次支持 CUDA 的发布都会上传以下文件到 GitHub：

- voicebox-server-cuda-<platform>.tar.gz — 服务器核心包 - voicebox-server-cuda-<platform>.tar.gz.sha256 — 校验和 - cuda-libs-<platform>-cu128-v1.tar.gz — CUDA 运行时库（仅在库版本升级时） - cuda-libs-<platform>-cu128-v1.tar.gz.sha256 — 校验和

其中 <platform> 为 windows-x86_64（由 build-cuda-windows 构建）或 linux-x86_64（由 build-gpu-linux 矩阵任务构建，该任务同时发布 voicebox-server-rocm-linux-x86_64.tar.gz 和 rocm-libs-linux-x86_64-rocm7.2-v1.tar.gz）。客户端通过 backend/utils/platform_detect.py 中的 server_asset_platform() 选择对应的标识符。macOS 和 Linux arm64 没有 GPU 资源，会在开始任何下载前直接拒绝。