ssq-desk/docs/04-功能迭代/版本更新/版本更新设计.md

版本更新功能设计文档

1. 功能概述

实现应用版本更新检查、下载、安装功能，支持自动和手动更新，提供更新日志展示。

1.1 核心功能

• 版本检查：自动/手动检查远程版本信息
• 更新下载：支持断点续传的更新包下载
• 更新安装：自动备份、安装、重启
• 进度展示：实时显示下载和安装进度

1.2 设计原则

• 安全性：文件哈希验证、HTTPS 传输
• 可靠性：断点续传、备份回滚机制
• 用户体验：实时进度反馈、错误提示
• 代码质量：遵循 DRY 原则，简洁易维护

---

2. 架构设计

2.1 模块划分

版本更新模块
├── 后端服务层
│   ├── update_service.go      # 版本检查服务
│   ├── update_download.go      # 下载服务
│   ├── update_install.go      # 安装服务
│   └── update_config.go        # 配置管理
├── API 层
│   └── update_api.go           # 更新 API 接口
└── 前端层
    └── useVersion.ts           # 版本管理 Composable

2.2 数据流

前端 (useVersion.ts)
    ↓ 调用 API
API 层 (update_api.go)
    ↓ 调用服务
服务层 (update_service.go / update_download.go / update_install.go)
    ↓ 事件推送
前端 (通过 Wails Events 接收进度)

2.3 关键组件

版本检查服务

• 职责：获取远程版本信息，比较版本号
• 输入：检查 URL
• 输出：更新信息（版本号、下载地址、更新日志等）

下载服务

• 职责：下载更新包，计算进度，验证文件
• 输入：下载 URL
• 输出：下载结果（文件路径、哈希值）
• 特性：断点续传、进度回调

安装服务

• 职责：备份、安装、重启应用
• 输入：安装包路径
• 输出：安装结果
• 特性：自动备份、失败回滚

---

3. 技术实现要点

3.1 版本号格式

• 格式：语义化版本 主版本号.次版本号.修订号（如 1.0.0）
• 比较逻辑：逐级比较主版本号、次版本号、修订号
• 解析支持：支持 v1.0.0 或 1.0.0 格式

3.2 远程版本信息接口

接口地址

https://img.1216.top/ssq/last-version.json

接口返回格式

{
  "version": "0.1.1",
  "download_url": "https://img.1216.top/ssq/releases/ssq-desk-0.1.1.exe",
  "changelog": "更新日志内容",
  "force_update": false,
  "release_date": "2026-01-07"
}

字段说明

• version: 最新版本号（语义化版本）
• download_url: 更新包下载地址
• changelog: 更新日志内容
• force_update: 是否强制更新
• release_date: 发布日期

3.3 更新包格式

• Windows：.exe 安装包或 .zip 压缩包
• 支持方式：全量更新（当前实现）

3.4 下载机制设计

断点续传

• 使用 HTTP Range 头实现断点续传
• 支持从已下载位置继续下载
• 自动检测已下载文件大小

进度计算

• 更新频率：每 0.3 秒更新一次
• 进度值保护：多层防护确保进度值在 0-100% 之间
  • 后端 normalizeProgress() 函数标准化
  • API 层最后一道防线检查
  • 前端 clampProgress() 函数确保显示值合法

文件大小获取

1. 优先从 Content-Range 头获取（最准确）
2. 从响应 ContentLength 获取
3. 通过 HEAD 请求获取（备用方案）

3.5 安装机制设计

安装流程

1. 备份：安装前自动备份当前版本到 ~/.ssq-desk/backups/
2. 验证：可选的文件哈希验证（MD5/SHA256）
3. 安装：
   • .exe 文件：直接替换可执行文件
   • .zip 文件：解压后替换文件
4. 重启：安装成功后自动重启应用
5. 回滚：安装失败时自动恢复备份

Windows 文件替换

• 使用重命名方式（.old 后缀）
• 如果文件正在使用，将在重启后替换

3.6 检查间隔设计

检查触发机制

• 启动时检查：应用启动时立即检查一次
• 自动检查：根据配置的检查间隔自动检查
• 手动检查：用户可随时手动触发检查

推荐配置

• 开发/测试：5-30分钟
• 生产环境：60分钟（1小时）推荐
• 省流模式：360分钟（6小时）
• 最小间隔：5分钟（防止过于频繁）
• 最大间隔：1440分钟（24小时）

---

4. 接口设计

4.1 后端 API 接口

CheckUpdate()

• 功能：检查是否有新版本
• 返回：更新信息（版本号、下载地址、更新日志等）

GetCurrentVersion()

• 功能：获取当前版本号
• 返回：当前版本号

DownloadUpdate(downloadURL)

• 功能：下载更新包（异步）
• 参数：下载地址
• 事件：通过 download-progress 和 download-complete 事件推送进度

InstallUpdate(filePath, autoRestart)

• 功能：安装更新包
• 参数：文件路径、是否自动重启
• 返回：安装结果

4.2 前端事件

download-progress

• 触发时机：下载过程中（每 0.3 秒）
• 数据格式：

{
  "progress": 50.5,
  "speed": 1024000,
  "downloaded": 5242880,
  "total": 10485760
}

download-complete

• 触发时机：下载完成或失败
• 数据格式（成功）：

{
  "success": true,
  "file_path": "C:\\Users\\...\\ssq-desk-0.1.1.exe",
  "file_size": 10485760
}

• 数据格式（失败）：

{
  "error": "下载失败：网络错误"
}

---

5. 安全设计

5.1 已实现的安全措施

• ✅ 文件哈希验证：支持 MD5/SHA256 哈希验证
• ✅ HTTPS 传输：使用 HTTPS 确保传输安全
• ✅ 进度值安全：多层防护确保进度值不会异常

5.2 待增强的安全措施

• ⚠️ 数字签名验证：未实现（建议增强）
  • Windows: 验证 .exe 文件的 Authenticode 签名
  • macOS: 验证 .app 的代码签名
• ⚠️ URL 白名单验证：未实现（建议增强）
  • 在配置中维护允许的下载域名列表
  • 下载前验证 URL 是否在白名单中

---

6. 错误处理

6.1 网络错误

• 处理方式：提示用户检查网络连接
• 重试机制：支持手动重试

6.2 下载失败

• 处理方式：显示错误信息，支持重新下载
• 断点续传：支持从断点继续下载

6.3 安装失败

• 处理方式：自动回滚到备份版本
• 备份机制：安装前自动创建备份

6.4 进度值异常

• 处理方式：多层防护确保进度值在 0-100% 之间
• 保护机制：
  • 后端标准化函数
  • API 层检查
  • 前端标准化函数

---

7. 性能优化

7.1 代码优化（2026-01-08）

• 后端代码量减少：40-50%
• 前端代码量减少：约 40%（485行 → 300行）
• 优化措施：
  • 提取重复逻辑为函数
  • 精简日志输出
  • 优化事件处理

7.2 下载优化

• 进度更新频率：0.3 秒（平衡性能和用户体验）
• 缓冲区大小：32KB
• 超时时间：30 分钟

---

8. 扩展性设计

8.1 可扩展功能

• 增量更新支持
• 更新包压缩
• 多通道更新（稳定版/测试版）
• 数字签名验证

8.2 配置化设计

• 检查间隔可配置
• 检查地址可配置
• 自动检查开关可配置

---

文档维护者：JueChen
创建时间：2026-01-08