autoAiWorkSys/_doc/服务端升级功能逻辑说明.md

服务端升级功能逻辑说明

概述

本文档说明服务端需要实现的升级功能逻辑，配合客户端的自动升级功能。

API 接口要求

GET /version/check

功能：检查是否有新版本可用

请求参数（Query 参数）：

• current_version: 当前版本号（x.y.z 格式，如 "1.0.0"）
• platform: 平台类型（如 "win32", "darwin", "linux"）
• arch: 架构类型（如 "x64", "ia32", "arm64"）
• sn_code: 设备序列号（可选，用于权限控制）

响应格式：

{
  "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"]
• 逐位比较数字大小
• 主版本号优先级最高，依次递减

示例：

// 伪代码
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

响应：

{
  "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

响应：

{
  "code": 0,
  "message": "已是最新版本",
  "data": null
}

场景3：参数错误

请求：

GET /version/check?current_version=1.0.0

响应：

{
  "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. 管理功能：版本管理后台、历史记录