u-desk/docs/04-功能迭代/GO-DESK-1.尝试/更新升级功能设计.md

Go Desk 更新升级功能设计

文档版本：v0.1.0 创建时间：2026-01-20 维护者：JueChen 状态：设计阶段

1. 功能概述

实现应用的自动更新升级功能，包括版本检查、下载更新包、自动替换和重启应用。

2. 功能需求

2.1 核心功能

• 版本检查：启动时或手动检查最新版本
• 版本对比：比较当前版本与最新版本
• 更新提示：发现新版本时提示用户
• 下载更新：后台下载更新包（支持进度显示）
• 自动替换：下载完成后自动替换旧版本
• 自动重启：替换完成后自动重启应用

2.2 版本管理

• 当前版本：从代码中定义（如 const Version = "1.0.0"）
• 版本格式：语义化版本（如 1.0.0, 1.0.1）
• 版本检查：从服务器获取最新版本信息（JSON 格式）

2.3 更新流程

应用启动
  ↓
检查更新（可选，后台进行）
  ↓
发现新版本？
  ↓ 是
显示更新提示
  ↓
用户确认更新
  ↓
下载更新包（显示进度）
  ↓
下载完成
  ↓
关闭当前应用
  ↓
替换旧版本文件
  ↓
启动新版本
  ↓
完成

3. 技术实现

3.1 版本信息结构

type VersionInfo struct {
    Version     string `json:"version"`      // 版本号，如 "1.0.1"
    DownloadURL string `json:"download_url"` // 下载地址
    ReleaseNotes string `json:"release_notes"` // 更新说明
    Size        int64  `json:"size"`        // 文件大小（字节）
    MD5         string `json:"md5"`         // 文件 MD5 校验
}

3.2 版本检查接口

接口地址：https://your-server.com/api/version/check

请求：

{
  "current_version": "1.0.0",
  "platform": "windows"
}

响应：

{
  "has_update": true,
  "latest_version": "1.0.1",
  "download_url": "https://your-server.com/releases/go-desk-1.0.1.exe",
  "release_notes": "修复了若干问题",
  "size": 13765632,
  "md5": "abc123..."
}

3.3 Go 后端实现

3.3.1 版本定义

// app.go 或 version.go
const AppVersion = "1.0.0"

3.3.2 更新检查方法

// CheckUpdate 检查更新
func (a *App) CheckUpdate() (map[string]interface{}, error)

3.3.3 下载更新方法

// DownloadUpdate 下载更新包
func (a *App) DownloadUpdate(downloadURL string, progressCallback func(int)) error

3.3.4 应用更新方法

// ApplyUpdate 应用更新（替换文件并重启）
func (a *App) ApplyUpdate(updateFilePath string) error

3.4 前端实现

3.4.1 更新检查组件

• 启动时自动检查（可选）
• 手动检查按钮
• 更新提示对话框
• 下载进度显示

3.4.2 界面元素

• 版本号显示
• 更新提示对话框（Arco Modal）
• 下载进度条（Arco Progress）
• 更新说明展示

4. 实现细节

4.1 版本比较

使用语义化版本比较：

• 格式：主版本号.次版本号.修订号（如 1.0.0）
• 比较逻辑：逐级比较版本号

4.2 文件下载

• 使用 Go 标准库 net/http 下载
• 支持进度回调
• 支持断点续传（可选）
• 下载到临时目录（如 %TEMP%/go-desk-update.exe）

4.3 文件替换（Windows）

方案1：使用批处理脚本

1. 下载完成后，生成批处理脚本
2. 脚本内容：等待进程结束 → 替换文件 → 启动新版本 → 删除脚本
3. 启动脚本后退出当前应用

方案2：使用 Go 实现

1. 创建更新助手程序
2. 主程序退出前启动助手程序
3. 助手程序等待主程序退出后替换文件并重启

4.4 错误处理

• 网络错误：提示检查网络连接
• 下载失败：支持重试
• 文件校验失败：重新下载
• 替换失败：提示手动更新

5. 文件结构

go-desk/
├── internal/
│   └── update/
│       ├── update.go      # 更新核心逻辑
│       ├── version.go    # 版本管理
│       └── download.go   # 下载功能
├── app.go                # 添加更新相关方法
└── version.go            # 版本常量定义

6. 配置项

6.1 更新服务器配置

const (
    UpdateCheckURL = "https://your-server.com/api/version/check"
    UpdateInterval = 24 * time.Hour // 检查间隔
)

6.2 可选配置

• 是否自动检查更新
• 检查更新间隔
• 更新服务器地址

7. 安全考虑

1. HTTPS 连接：版本检查和下载使用 HTTPS
2. 文件校验：下载后验证 MD5/SHA256
3. 权限检查：确保有写入权限
4. 回滚机制：更新失败时保留旧版本

8. 用户体验

1. 非阻塞：更新检查在后台进行，不阻塞应用启动
2. 可取消：用户可以选择稍后更新
3. 进度显示：下载时显示进度条
4. 友好提示：清晰的更新说明和操作指引

9. 开发优先级

阶段一：基础功能

• 版本定义和比较
• 版本检查接口
• 简单的更新提示

阶段二：下载功能

• 文件下载实现
• 进度显示
• 错误处理

阶段三：自动更新

• 文件替换逻辑
• 自动重启
• 完整测试

10. 注意事项

1. Windows 文件锁定：需要先关闭应用才能替换
2. 权限问题：确保有写入应用目录的权限
3. 网络超时：设置合理的超时时间
4. 更新失败处理：保留旧版本，不破坏现有功能

11. 参考实现

• Electron 的 auto-updater 机制
• Wails 社区更新方案
• Go 应用更新最佳实践

---

下一步：根据此设计文档开始实现更新功能。