321 lines
9.0 KiB
Markdown
321 lines
9.0 KiB
Markdown
# 服务端升级功能逻辑说明
|
||
|
||
## 概述
|
||
|
||
本文档说明服务端需要实现的升级功能逻辑，配合客户端的自动升级功能。
|
||
|
||
## API 接口要求
|
||
|
||
### GET /version/check
|
||
|
||
**功能**：检查是否有新版本可用
|
||
|
||
**请求参数**（Query 参数）：
|
||
- `current_version`: 当前版本号（x.y.z 格式，如 "1.0.0"）
|
||
- `platform`: 平台类型（如 "win32", "darwin", "linux"）
|
||
- `arch`: 架构类型（如 "x64", "ia32", "arm64"）
|
||
- `sn_code`: 设备序列号（可选，用于权限控制）
|
||
|
||
**响应格式**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"version": "1.1.0",
|
||
"download_url": "http://work.light120.com/downloads/app-1.1.0.exe",
|
||
"release_notes": "修复了一些bug，新增了xxx功能",
|
||
"force_update": false,
|
||
"file_size": 52428800,
|
||
"file_hash": "abc123def456..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**：
|
||
- `version`: 最新版本号（x.y.z 格式）
|
||
- `download_url`: 更新包下载地址（完整的 HTTP/HTTPS URL）
|
||
- `release_notes`: 更新日志（可选，字符串）
|
||
- `force_update`: 是否强制更新（可选，布尔值，默认 false）
|
||
- `file_size`: 文件大小（字节，可选）
|
||
- `file_hash`: 文件 SHA256 哈希值（可选，用于校验文件完整性）
|
||
|
||
**业务逻辑**：
|
||
|
||
1. **版本比较**：
|
||
- 从数据库查询最新版本信息（根据 platform 和 arch）
|
||
- 比较请求中的 `current_version` 与数据库中的最新版本
|
||
- 如果最新版本 > 当前版本，返回更新信息
|
||
- 如果版本相同或更旧，返回 `code: 0, data: null` 或提示"已是最新版本"
|
||
|
||
2. **版本号格式**：
|
||
- 格式：x.y.z（如 1.0.0, 1.1.0, 2.0.0）
|
||
- 比较规则：主版本号 > 次版本号 > 修订号
|
||
- 示例：1.1.0 > 1.0.0, 2.0.0 > 1.9.9
|
||
|
||
3. **平台和架构过滤**：
|
||
- 只返回匹配 platform 和 arch 的版本信息
|
||
- 如果某个平台没有新版本，返回空结果
|
||
|
||
4. **序列号验证**（可选）：
|
||
- 可以根据 sn_code 验证设备权限
|
||
- 如果启用权限控制，未授权的设备返回错误
|
||
|
||
5. **错误处理**：
|
||
- 参数缺失：返回 `code: 400, message: "参数错误"`
|
||
- 服务器错误：返回 `code: 500, message: "服务器错误"`
|
||
- 无新版本：返回 `code: 0, data: null` 或 `has_update: false`
|
||
|
||
## 数据库设计建议
|
||
|
||
### 版本信息表（version_info）
|
||
|
||
| 字段名 | 类型 | 说明 | 约束 |
|
||
|--------|------|------|------|
|
||
| id | INT/BIGINT | 主键 | PRIMARY KEY, AUTO_INCREMENT |
|
||
| version | VARCHAR(20) | 版本号（x.y.z 格式） | NOT NULL, UNIQUE |
|
||
| platform | VARCHAR(20) | 平台类型（win32/darwin/linux） | NOT NULL |
|
||
| arch | VARCHAR(20) | 架构类型（x64/ia32/arm64） | NOT NULL |
|
||
| download_url | VARCHAR(500) | 下载地址 | NOT NULL |
|
||
| file_path | VARCHAR(500) | 服务器文件路径 | NOT NULL |
|
||
| file_size | BIGINT | 文件大小（字节） | DEFAULT 0 |
|
||
| file_hash | VARCHAR(64) | SHA256 哈希值 | |
|
||
| release_notes | TEXT | 更新日志 | |
|
||
| force_update | TINYINT(1) | 是否强制更新 | DEFAULT 0 |
|
||
| status | TINYINT(1) | 状态（1:启用 0:禁用） | DEFAULT 1 |
|
||
| create_time | DATETIME | 创建时间 | NOT NULL, DEFAULT CURRENT_TIMESTAMP |
|
||
| last_modify_time | DATETIME | 最后修改时间 | NOT NULL, DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
|
||
|
||
**索引建议**：
|
||
- PRIMARY KEY (id)
|
||
- UNIQUE KEY (version, platform, arch)
|
||
- INDEX (platform, arch, status)
|
||
|
||
### 版本发布历史表（version_history）（可选）
|
||
|
||
用于记录版本发布历史，便于管理：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | INT/BIGINT | 主键 |
|
||
| version_id | INT | 关联 version_info.id |
|
||
| release_type | VARCHAR(20) | 发布类型（stable/beta/alpha） |
|
||
| create_time | DATETIME | 发布时间 |
|
||
| last_modify_time | DATETIME | 最后修改时间 |
|
||
|
||
## 业务逻辑流程
|
||
|
||
### 1. 版本检查流程
|
||
|
||
```
|
||
客户端请求
|
||
↓
|
||
接收参数（current_version, platform, arch, sn_code）
|
||
↓
|
||
验证参数有效性
|
||
↓
|
||
查询数据库最新版本（按 platform + arch + status=1）
|
||
↓
|
||
版本号比较
|
||
↓
|
||
有更新？
|
||
├─ 是 → 构建返回数据（包含文件信息）
|
||
└─ 否 → 返回空结果或提示"已是最新版本"
|
||
↓
|
||
返回响应
|
||
```
|
||
|
||
### 2. 版本管理流程
|
||
|
||
**新增版本**：
|
||
1. 上传安装包文件到服务器指定目录
|
||
2. 计算文件 SHA256 哈希值
|
||
3. 获取文件大小
|
||
4. 插入数据库记录（status=1 表示启用）
|
||
|
||
**禁用版本**：
|
||
1. 更新 status=0（不删除记录，保留历史）
|
||
|
||
**删除版本**：
|
||
1. 删除数据库记录
|
||
2. 删除服务器上的文件
|
||
|
||
### 3. 文件存储建议
|
||
|
||
**目录结构**：
|
||
```
|
||
/uploads/
|
||
└── versions/
|
||
├── win32/
|
||
│ ├── x64/
|
||
│ │ ├── app-1.0.0.exe
|
||
│ │ └── app-1.1.0.exe
|
||
│ └── ia32/
|
||
└── darwin/
|
||
└── x64/
|
||
└── app-1.1.0.dmg
|
||
```
|
||
|
||
**文件命名规则**：
|
||
- 格式：`app-{version}.{ext}`
|
||
- 示例：`app-1.1.0.exe`, `app-1.1.0.dmg`
|
||
|
||
**下载 URL 生成**：
|
||
- 基础 URL：`http://work.light120.com/downloads/`
|
||
- 完整 URL：`http://work.light120.com/downloads/app-1.1.0.exe`
|
||
|
||
## 关键逻辑说明
|
||
|
||
### 1. 版本号比较逻辑
|
||
|
||
**字符串比较规则**：
|
||
- 将版本号按 "." 分割成数组：["1", "1", "0"]
|
||
- 逐位比较数字大小
|
||
- 主版本号优先级最高，依次递减
|
||
|
||
**示例**：
|
||
```javascript
|
||
// 伪代码
|
||
compareVersion("1.1.0", "1.0.0") → true // 1.1.0 > 1.0.0
|
||
compareVersion("2.0.0", "1.9.9") → true // 2.0.0 > 1.9.9
|
||
compareVersion("1.0.0", "1.0.0") → false // 相等
|
||
```
|
||
|
||
### 2. 文件哈希计算
|
||
|
||
**计算方法**：
|
||
- 使用 SHA256 算法
|
||
- 读取文件内容，计算哈希值
|
||
- 返回小写的十六进制字符串
|
||
|
||
**用途**：
|
||
- 客户端下载后校验文件完整性
|
||
- 防止文件被篡改
|
||
- 确保文件下载完整
|
||
|
||
### 3. 强制更新逻辑
|
||
|
||
**force_update 字段**：
|
||
- `true`: 强制更新，客户端必须更新才能使用
|
||
- `false`: 可选更新，客户端可以选择稍后更新
|
||
|
||
**业务场景**：
|
||
- 安全漏洞修复 → 强制更新
|
||
- 重大功能更新 → 强制更新
|
||
- 小版本更新 → 可选更新
|
||
|
||
### 4. 平台和架构支持
|
||
|
||
**支持列表**：
|
||
- Windows: `win32` + `x64` / `ia32`
|
||
- macOS: `darwin` + `x64` / `arm64`
|
||
- Linux: `linux` + `x64` / `arm64`
|
||
|
||
**查询逻辑**：
|
||
- 必须同时匹配 platform 和 arch
|
||
- 如果某个组合没有版本，返回空结果
|
||
|
||
## 安全考虑
|
||
|
||
### 1. 文件下载安全
|
||
|
||
- **HTTPS 下载**：优先使用 HTTPS 协议
|
||
- **文件校验**：提供 SHA256 哈希值供客户端校验
|
||
- **文件大小验证**：返回文件大小，客户端可以验证下载完整性
|
||
|
||
### 2. 权限控制
|
||
|
||
- **序列号验证**：可以根据 sn_code 控制哪些设备可以更新
|
||
- **版本状态**：使用 status 字段控制版本是否可用
|
||
- **IP 限制**：可以限制下载 IP 范围（可选）
|
||
|
||
### 3. 防止恶意更新
|
||
|
||
- **文件类型验证**：只允许上传 .exe、.dmg、.AppImage 等安装包
|
||
- **文件大小限制**：设置最大文件大小限制
|
||
- **版本号验证**：验证版本号格式是否正确
|
||
|
||
## 返回状态码说明
|
||
|
||
| code | 说明 | 处理方式 |
|
||
|------|------|----------|
|
||
| 0 | 成功 | 检查 data 是否为空判断是否有更新 |
|
||
| 400 | 参数错误 | 客户端提示参数错误 |
|
||
| 401 | 未授权 | 客户端提示未授权 |
|
||
| 404 | 未找到版本 | 客户端提示版本不存在 |
|
||
| 500 | 服务器错误 | 客户端提示服务器错误，稍后重试 |
|
||
|
||
## 示例场景
|
||
|
||
### 场景1：有新版本
|
||
|
||
**请求**：
|
||
```
|
||
GET /version/check?current_version=1.0.0&platform=win32&arch=x64&sn_code=GHJU
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"version": "1.1.0",
|
||
"download_url": "http://work.light120.com/downloads/app-1.1.0.exe",
|
||
"release_notes": "1. 修复了登录问题\n2. 新增自动升级功能",
|
||
"force_update": false,
|
||
"file_size": 52428800,
|
||
"file_hash": "a1b2c3d4e5f6..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 场景2：已是最新版本
|
||
|
||
**请求**：
|
||
```
|
||
GET /version/check?current_version=1.1.0&platform=win32&arch=x64&sn_code=GHJU
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "已是最新版本",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 场景3：参数错误
|
||
|
||
**请求**：
|
||
```
|
||
GET /version/check?current_version=1.0.0
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "缺少必要参数：platform, arch",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **日期字段命名**：统一使用 `create_time` 和 `last_modify_time`
|
||
2. **版本号格式**：严格按照 x.y.z 格式，便于版本比较
|
||
3. **文件存储**：建议使用 CDN 或静态文件服务器，提高下载速度
|
||
4. **日志记录**：记录版本检查请求，便于统计和分析
|
||
5. **缓存策略**：可以考虑缓存最新版本信息，减少数据库查询
|
||
6. **灰度发布**：可以通过 sn_code 控制部分设备先更新（可选）
|
||
|
||
## 实现优先级
|
||
|
||
1. **基础功能**：版本检查、版本比较、返回下载信息
|
||
2. **文件管理**：文件上传、文件存储、哈希计算
|
||
3. **安全功能**：文件校验、权限控制
|
||
4. **管理功能**：版本管理后台、历史记录
|
||
|