286 lines
7.4 KiB
Markdown
286 lines
7.4 KiB
Markdown
# 版本更新功能设计文档
|
||
|
||
## 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
|
||
```
|
||
|
||
#### 接口返回格式
|
||
```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 秒）
|
||
- **数据格式**：
|
||
```json
|
||
{
|
||
"progress": 50.5,
|
||
"speed": 1024000,
|
||
"downloaded": 5242880,
|
||
"total": 10485760
|
||
}
|
||
```
|
||
|
||
#### download-complete
|
||
- **触发时机**：下载完成或失败
|
||
- **数据格式**（成功）：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"file_path": "C:\\Users\\...\\ssq-desk-0.1.1.exe",
|
||
"file_size": 10485760
|
||
}
|
||
```
|
||
- **数据格式**（失败）：
|
||
```json
|
||
{
|
||
"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
|