278 lines
7.3 KiB
Markdown
278 lines
7.3 KiB
Markdown
# 升级提示功能使用指南
|
||
|
||
## 功能概述
|
||
|
||
新增的升级提示系统会在应用启动时自动检查更新，并在发现新版本时优雅地提示用户。整个体验流畅、专业，不打扰用户工作流。
|
||
|
||
## 主要特性
|
||
|
||
✅ **自动检测** - 应用启动后 5 秒自动检查更新
|
||
✅ **优雅提示** - 精美的弹窗设计，清晰的版本信息
|
||
✅ **实时进度** - 下载进度实时显示，包含速度和文件大小
|
||
✅ **灵活跳过** - 支持跳过非强制更新，下次不再提示
|
||
✅ **强制更新** - 重要安全更新强制安装，无法跳过
|
||
✅ **断点续传** - 下载支持断点续传，节省流量
|
||
✅ **安全安装** - 自动备份原程序，失败自动回滚
|
||
|
||
## 使用流程
|
||
|
||
### 1. 应用启动自动检查
|
||
|
||
```
|
||
应用启动
|
||
↓
|
||
等待 3 秒（避免阻塞启动）
|
||
↓
|
||
后台检查更新
|
||
↓
|
||
发现新版本？
|
||
├─ 是 → 延迟 2 秒显示升级提示弹窗
|
||
└─ 否 → 不显示，正常使用应用
|
||
```
|
||
|
||
### 2. 升级提示弹窗
|
||
|
||
当检测到新版本时，会显示精美的升级提示弹窗：
|
||
|
||
**弹窗包含：**
|
||
- 📌 当前版本 → 最新版本对比
|
||
- 📅 发布日期
|
||
- 📁 文件大小
|
||
- 📖 更新日志（版本更新内容）
|
||
- 🎯 操作按钮（跳过/立即更新）
|
||
- ⏰ 稍后提醒选项
|
||
|
||
**三种状态：**
|
||
1. **初始状态** - 显示版本信息和更新日志
|
||
2. **下载状态** - 显示下载进度和速度
|
||
3. **完成状态** - 下载完成，提示点击安装
|
||
|
||
### 3. 用户选择
|
||
|
||
#### 选择 A：立即更新
|
||
```
|
||
点击"立即更新"
|
||
↓
|
||
开始下载（显示进度条）
|
||
↓
|
||
下载完成
|
||
↓
|
||
点击"安装"
|
||
↓
|
||
确认对话框
|
||
↓
|
||
自动重启应用
|
||
```
|
||
|
||
#### 选择 B：跳过此版本
|
||
```
|
||
点击"跳过此版本"
|
||
↓
|
||
勾选"提醒我稍后更新"？
|
||
├─ 是 → 下次启动继续提示
|
||
└─ 否 → 记住选择，不再提示此版本
|
||
↓
|
||
关闭弹窗
|
||
```
|
||
|
||
### 4. 强制更新
|
||
|
||
对于重要的安全更新，弹窗会：
|
||
- 🔴 显示红色"重要更新"徽章
|
||
- ⚠️ 显示强制更新警告信息
|
||
- 🚫 禁用关闭按钮（无法跳过）
|
||
- ✅ 只提供"立即更新"按钮
|
||
|
||
## 配置选项
|
||
|
||
### 在"设置 → 版本更新"中配置：
|
||
|
||
#### 自动检查更新
|
||
- **开启** - 应用启动时自动检查（推荐）
|
||
- **关闭** - 不自动检查，需要手动检查
|
||
|
||
#### 检查间隔
|
||
- 范围：1-1440 分钟（1 分钟 - 24 小时）
|
||
- 推荐设置：60 分钟（1 小时）
|
||
- 说明：两次自动检查的最小间隔时间
|
||
|
||
#### 更新检查地址
|
||
- 系统配置，不可修改
|
||
- 当前地址：`https://img.1216.top/u-desk/last-version.json`
|
||
|
||
## 手动检查更新
|
||
|
||
如果关闭了自动检查，或者想立即检查：
|
||
|
||
1. 打开"设置"面板
|
||
2. 切换到"版本更新"标签
|
||
3. 点击"检查更新"按钮
|
||
4. 查看更新结果
|
||
|
||
## 版本信息文件
|
||
|
||
升级系统会读取远程的版本信息文件：
|
||
|
||
**文件地址：** `https://img.1216.top/u-desk/last-version.json`
|
||
|
||
**文件格式：**
|
||
```json
|
||
{
|
||
"version": "0.1.1",
|
||
"download_url": "https://img.1216.top/u-desk/go-desk-0.1.1-windows-amd64.exe",
|
||
"changelog": "• 修复文件列表刷新问题\n• 优化启动性能\n• 新增暗色模式支持",
|
||
"force_update": false,
|
||
"release_date": "2026-01-28",
|
||
"file_size": 45234567
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `version` - 最新版本号（格式：x.y.z）
|
||
- `download_url` - 安装包下载地址
|
||
- `changelog` - 更新日志（支持换行符 `\n`）
|
||
- `force_update` - 是否强制更新（true/false）
|
||
- `release_date` - 发布日期（格式：YYYY-MM-DD）
|
||
- `file_size` - 文件大小（字节，可选）
|
||
|
||
## 下载和安装
|
||
|
||
### 下载特性
|
||
- ✅ 支持断点续传（中断后可继续）
|
||
- ✅ 实时显示下载进度
|
||
- ✅ 显示下载速度和剩余时间
|
||
- ✅ 下载完成后自动计算 MD5 和 SHA256 哈希
|
||
|
||
### 安装特性
|
||
- ✅ 自动备份当前版本
|
||
- ✅ 安装失败自动回滚
|
||
- ✅ 安装成功自动重启
|
||
- ✅ 支持 .exe 和 .zip 格式
|
||
|
||
### 文件存储位置
|
||
- **配置文件**：`~/.u-desk/update_config.json`
|
||
- **下载目录**：`~/.u-desk/downloads/`
|
||
- **备份目录**：`~/.u-desk/backups/`
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 为什么自动检查更新后没有弹窗？
|
||
**A:** 可能原因：
|
||
1. 已是最新版本（无更新）
|
||
2. 此版本已选择"跳过"且未勾选"稍后提醒"
|
||
3. 自动检查功能已关闭
|
||
|
||
**解决方法：**
|
||
- 手动点击"检查更新"按钮
|
||
- 检查配置中的"自动检查更新"开关
|
||
|
||
### Q2: 下载失败了怎么办？
|
||
**A:**
|
||
- 下载支持断点续传，可以点击重试
|
||
- 系统会自动从断点继续下载
|
||
- 如果多次失败，检查网络连接和下载地址
|
||
|
||
### Q3: 安装失败会怎样？
|
||
**A:**
|
||
- 系统会自动回滚到备份版本
|
||
- 不会影响当前使用
|
||
- 可以查看错误日志了解失败原因
|
||
|
||
### Q4: 如何恢复跳过的版本提示？
|
||
**A:**
|
||
方法 1：手动点击"检查更新"
|
||
方法 2：清除浏览器 localStorage 中的 `skipped_version`
|
||
|
||
### Q5: 强制更新可以跳过吗？
|
||
**A:**
|
||
- 不可以。强制更新是为了修复严重的安全问题或数据损坏问题
|
||
- 不安装强制更新可能会影响应用正常使用
|
||
|
||
### Q6: 下载中断后下次如何继续？
|
||
**A:**
|
||
- 系统会自动检测已下载的部分
|
||
- 重新点击"立即更新"会从断点继续
|
||
- 不会重复下载已完成的文件
|
||
|
||
## 技术实现
|
||
|
||
### 前端组件
|
||
- **UpdateNotification.vue** - 升级提示弹窗组件
|
||
- **App.vue** - 集成自动检查逻辑
|
||
|
||
### 后端接口
|
||
- **CheckUpdate()** - 检查更新
|
||
- **DownloadUpdate()** - 下载更新包
|
||
- **InstallUpdate()** - 安装更新
|
||
- **GetUpdateConfig()** - 获取更新配置
|
||
- **SetUpdateConfig()** - 保存更新配置
|
||
|
||
### 事件系统
|
||
- **download-progress** - 下载进度事件
|
||
- **download-complete** - 下载完成事件
|
||
|
||
### 配置文件
|
||
**~/.u-desk/update_config.json**
|
||
```json
|
||
{
|
||
"current_version": "0.1.0",
|
||
"last_check_time": "2026-01-28T18:51:00+08:00",
|
||
"auto_check_enabled": true,
|
||
"check_interval_minutes": 60,
|
||
"check_url": "https://img.1216.top/u-desk/last-version.json"
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 对于用户
|
||
1. ✅ 保持自动检查开启，及时获取更新
|
||
2. ✅ 选择"稍后提醒"而非"跳过"，避免错过重要更新
|
||
3. ✅ 安装前保存当前工作，避免数据丢失
|
||
4. ✅ 遇到强制更新立即安装，确保安全性
|
||
|
||
### 对于开发者
|
||
1. ✅ 版本信息文件保持最新
|
||
2. ✅ 更新日志清晰详细
|
||
3. ✅ 重要更新标记为强制更新
|
||
4. ✅ 测试安装包的完整性
|
||
|
||
## 更新日志设计建议
|
||
|
||
### 好的更新日志
|
||
```
|
||
• 修复文件列表刷新后顺序错乱的问题
|
||
• 优化启动性能，加载时间减少 30%
|
||
• 新增暗色模式支持
|
||
• 修复 #123 问题：数据库连接失败
|
||
|
||
注意：此版本包含重要的安全修复，建议立即更新
|
||
```
|
||
|
||
### 不好的更新日志
|
||
```
|
||
bug fixes
|
||
performance improvements
|
||
new features
|
||
```
|
||
|
||
**建议：**
|
||
- ✅ 列出具体的改动
|
||
- ✅ 说明对用户的影响
|
||
- ✅ 标注重要性和紧急性
|
||
- ✅ 使用清晰的格式（项目符号）
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
新的升级提示系统提供了专业、流畅、友好的更新体验：
|
||
|
||
🎯 **自动化** - 后台检查，无需人工干预
|
||
💎 **精美设计** - 现代化的 UI，清晰的信息层次
|
||
⚡ **高效流畅** - 断点续传，实时进度
|
||
🔒 **安全可靠** - 备份回滚，哈希验证
|
||
👍 **用户友好** - 灵活跳过，稍后提醒
|
||
|
||
享受无缝的更新体验！
|