cc-switch/docs/updater-plan.md

# 更新功能开发计划（Tauri v2 Updater）

> 目标：为桌面应用（macOS `.app`、Windows）集成并验证基于 Tauri v2 官方 Updater 插件的自动更新能力，覆盖版本检测、下载、安装与重启的完整闭环，并建立可复用的发布与测试流程。

## 一、范围与目标
- 核心能力：
  - 检查更新 → 下载 → 安装 → 应用重启。
  - 支持静态 JSON 与动态接口两种更新源。
  - 版本通道（stable/beta）与运行时切换端点（可选）。
- 平台覆盖：
  - macOS `.app`（优先级高）。
  - Windows（推荐安装器路径 NSIS/MSI；便携版说明限制）。
- 安全要求：
  - Updater 更新签名（Ed25519）强制开启：客户端 `pubkey` 校验服务端签名。
  - 不强制平台代码签名（macOS/Windows），但建议上线前完善。

## 二、方案概述
- 插件：`tauri-plugin-updater`（Rust/JS 双端 API），前端重启依赖 `@tauri-apps/plugin-process`。
- 核心配置：
  - `src-tauri/tauri.conf.json`
    - `bundle.createUpdaterArtifacts: true`
    - `plugins.updater.pubkey: "<PUBLICKEY.PEM 内容>"`
    - `plugins.updater.endpoints: ["<更新源 URL 列表>"]`
    - Windows 可选：`plugins.updater.windows.installMode: "passive|basicUi|quiet"`
  - `src-tauri/capabilities/default.json` 增加：`"updater:default"`
- 构建与签名：
  - 生成密钥：`tauri signer generate` → 注入构建环境变量 `TAURI_SIGNING_PRIVATE_KEY`（及可选密码）。
  - 构建产出带签名的更新制品（各平台包 + sig）。

## 三、交付物
- 可运行的自动更新能力（含前端触发入口与进度反馈）。
- 配置完善：`tauri.conf.json`、`capabilities/default.json`、插件初始化。
- 本地更新测试用 `latest.json` 模板与脚本（或说明）。
- 文档：
  - 更新源格式说明（静态/动态）。
  - 发布与回滚操作说明。
  - 常见问题排查清单。

## 四、里程碑与任务拆解
1) 准备与密钥
- 生成更新签名密钥对（Ed25519）。
- 将公钥填入 `plugins.updater.pubkey`，在构建环境配置 `TAURI_SIGNING_PRIVATE_KEY`。

2) 插件集成（Rust 侧）
- 注册插件：`tauri_plugin_updater::Builder::new().build()`。
- 可选：在 `setup` 中后台自动检查与安装；或暴露 `invoke` 命令由前端驱动。
- 可选：`updater_builder()` 覆盖网络参数（超时/代理/headers）与动态端点。

3) 前端接入（Renderer）
- 依赖：`@tauri-apps/plugin-updater`、`@tauri-apps/plugin-process`。
- 提供“检查更新”入口：显示当前版本、可用版本、更新日志。
- 进度反馈：`downloadAndInstall` 回调显示 Started/Progress/Finished。
- 成功后调用 `relaunch()`（或 Rust 侧 `app.restart()`）。

4) 配置与权限
- `tauri.conf.json`：`createUpdaterArtifacts`、`pubkey`、`endpoints`、Windows `installMode`（如需）。
- `capabilities/default.json`：加入 `"updater:default"`。

5) 更新源与产物
- 静态 JSON（`latest.json`）模板：
  - `version`、`notes`、`pub_date`（可选），`platforms[target].url` 与 `platforms[target].signature`（必填，signature 为 `.sig` 内容）。
- 动态 API：
  - 无更新返回 HTTP 204；有更新返回 200 + `{ version, url, signature, notes?, pub_date? }`。
- 产物托管：
  - 本地 HTTP 服务器（开发自测）或 GitHub Releases/CDN（准生产）。

6) 测试计划
- 基线用例：
  - 发现更新 → 下载 → 安装 → 重启 → 版本号提升。
  - 无更新（204）提示“已是最新”。
  - 签名不匹配拒绝更新（安全校验）。
  - 网络超时/失败的错误提示与恢复。
- 平台专项：
  - macOS：`~/Applications` 与 `/Applications` 两种放置；无苹果账号情况下的 Gatekeeper 行为提示。
  - Windows：安装器三种 `installMode`；便携版在用户可写目录的可行性验证与限制说明（文件锁/提权）。
- 自测步骤（本地静态 JSON）：
  - 用 v1.0.0 作为“已安装版本”，构建 v1.0.1 更新产物与 `.sig`。
  - 生成 `latest.json`，启动本地 HTTP（如 `npx http-server`）。
  - 旧版应用中点击“检查更新”并验证完整流程。

7) 发布与回滚
- 发布：
  - 通过 CI 生成更新产物与签名，上传到 Release/CDN。
  - 产物与 `latest.json` 上传至 Releases/CDN（或刷新动态接口数据）。
- 回滚：
  - 撤回最新产物；或将 `latest.json` 指向上一个稳定版本。
  - 如允许降级，Rust 侧定制 `version_comparator`。

8) 文档与移交
- 更新源格式说明、运维手册、常见问题排查（见下文附录）。

## 五、配置清单（示例）
- `src-tauri/tauri.conf.json` 关键片段：
```json
{
  "bundle": { "createUpdaterArtifacts": true },
  "plugins": {
    "updater": {
      "pubkey": "<PUBLICKEY.PEM 内容>",
      "endpoints": [
        "https://releases.example.com/{{target}}/{{arch}}/{{current_version}}",
        "https://github.com/org/repo/releases/latest/download/latest.json"
      ],
      "windows": { "installMode": "passive" }
    }
  }
}
```
- `src-tauri/capabilities/default.json`：
```json
{
  "permissions": [
    "updater:default"
  ]
}
```

## 六、前端最小用例（伪代码）
```ts
import { check } from '@tauri-apps/plugin-updater'
import { relaunch } from '@tauri-apps/plugin-process'

export async function runUpdateFlow() {
  const update = await check({ timeout: 30000 })
  if (!update) return { status: 'up-to-date' }

  let downloaded = 0
  let total = 0
  await update.downloadAndInstall((e) => {
    switch (e.event) {
      case 'Started': total = e.data.contentLength ?? 0; break
      case 'Progress': downloaded += e.data.chunkLength; break
    }
  })

  await relaunch()
}
```

## 七、更新源样例
- 静态 `latest.json`：
```json
{
  "version": "1.0.1",
  "notes": "Bug fixes and performance improvements",
  "pub_date": "2025-01-01T10:00:00Z",
  "platforms": {
    "darwin-aarch64": { "url": "https://cdn/app-1.0.1-darwin-aarch64.tar.gz", "signature": "<sig 内容>" },
    "windows-x86_64": { "url": "https://cdn/app-1.0.1-x86_64.zip", "signature": "<sig 内容>" }
  }
}
```
- 动态接口（有更新返回 200）：
```json
{ "version": "1.0.1", "url": "https://cdn/app-1.0.1.zip", "signature": "<sig>", "notes": "..." }
```
- 无更新返回：HTTP 204 No Content。

## 八、平台差异与限制
- macOS `.app`：
  - 支持直接替换更新；若位于 `/Applications` 且需要管理员权限可能失败（Updater 不主动提权）。建议用户安装到 `~/Applications`。
  - 无苹果开发者账号也可测试 Updater，但分发会触发 Gatekeeper 警告（建议正式版走代码签名+公证）。
- Windows：
  - 强烈建议安装器（NSIS/MSI），Updater 会下载并运行安装器，`installMode` 控制交互程度。
  - 便携版（绿色版）不稳定：运行中无法覆盖自身文件、缺乏提权与回滚；如必须使用，需将应用放到可写目录并设计辅助替换流程（本计划不默认实现）。

## 九、测试用例清单
- 功能流转：有更新/无更新/下载中断/重试/安装后重启成功。
- 安全校验：签名错误与端点被劫持时应拒绝更新。
- 网络异常：超时、代理、断网时的提示与恢复路径。
- 平台行为：
  - macOS：不同安装路径权限导致的成功/失败覆盖。
  - Windows：`passive|basicUi|quiet` 下安装器行为；便携版在用户可写目录的替换验证（若执行）。

## 十、发布与运维
- 发布流水线（建议 CI）：
  - 设置 `TAURI_SIGNING_PRIVATE_KEY`（机密变量）。
  - 构建生成各平台更新产物与签名。
  - 产物与 `latest.json` 上传至 Releases/CDN（或刷新动态接口数据）。
- 回滚策略：
  - 撤回最新产物；或将 `latest.json` 指向上一个稳定版本。
  - 如允许降级，Rust 侧定制 `version_comparator`。

## 十一、时间排期（参考）
- D1：密钥与基础集成（插件/配置/权限）。
- D2：前端入口与进度 UI、静态 JSON 本地自测通过。
- D3：GitHub Releases/CDN 端到端验证、平台专项测试。
- D4：文档完善、回滚与异常流程演练、准备上线。

## 十二、验收标准
- 基线流转：在两平台完成“发现→下载→安装→重启→版本提升”。
- 安全：签名校验生效，签名不匹配拒绝更新。
- 文档：更新源规范、操作手册、排障清单齐备。
- 稳定性：网络异常与常见权限问题有明确用户提示与可行恢复路径。

---

### 附录 A：常见问题排查
- “未发现更新”：确认 `version` 更大、端点可达、HTTP 返回码（204/200）。
- “签名校验失败”：`pubkey` 与私钥不匹配；`signature` 必须是 `.sig` 文件内容。
- “下载/超时失败”：增加 `timeout`、检查代理/证书、重试策略与提示。
- “macOS 更新失败”：检查安装路径是否需要管理员权限；建议 `~/Applications`。
- “Windows 便携版覆盖失败”：可写权限/进程占用/缺少提权，优先改为安装器分发。

### 附录 B：后续可选优化
- 渠道支持（stable/beta）与 UI 切换。
- 增量发布策略与 CDN 缓存优化。
- 远程开关与灰度比例控制（动态接口）。
- 统一 Telemetry：下载失败率、平均时延、更新成功率统计。