ele-HeiXiu/test-server/README.md

HeiXiu 更新服务器 — 后端对接文档

本文档供后端程序员阅读和实现。

---

快速启动测试服务器

cd test-server
pip install fastapi uvicorn
python server.py --release-dir ../release --port 8000

启动后访问：

• API 文档（Swagger）：http://localhost:8000/docs
• 健康检查：http://localhost:8000/health

---

API 端点

所有请求为 GET，无鉴权。

1. GET /api/v1/update/check — 版本检查

客户端启动后调用，决定是否提示用户更新。

请求参数（Query String）：

参数	类型	必填	示例	说明
platform	string	是	win32	win32 / darwin / linux
version	string	是	0.0.3	客户端当前版本号（三段式 semver）
edition	string	否	personal	personal / enterprise，默认 personal

响应 — 有更新时：

{
  "code": 0,
  "data": {
    "hasUpdate": true,
    "latestVersion": "0.0.4",
    "downloadUrl": "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.0.4/xxx-Setup.exe",
    "fileSize": 113581841,
    "sha512": "Base64...",
    "blockMapUrl": "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.0.4/xxx-Setup.exe.blockmap",
    "blockMapSize": 120256,
    "changelog": "## 0.0.4\n\n- 日志记录\n- 增量更新",
    "releaseDate": "2026-06-04",
    "forceUpdate": false,
    "minimumVersion": "0.0.0"
  }
}

响应 — 无更新时：

{
  "code": 0,
  "data": {
    "hasUpdate": false
  }
}

字段说明：

字段	类型	必填	说明
downloadUrl	string	是	安装包 HTTPS 直链
fileSize	number	是	安装包字节数
sha512	string	是	安装包 SHA512 Base64
blockMapUrl	string	否	blockmap 文件 URL（缺失时客户端全量下载）
blockMapSize	number	否	blockmap 文件字节数（> 0 时客户端启用增量下载）
changelog	string	否	Markdown 格式更新日志
releaseDate	string	否	发布日期（YYYY-MM-DD）
forceUpdate	boolean	否	是否强制更新（true 时用户不可跳过）
minimumVersion	string	否	最低兼容版本（低于此版本的客户端必须更新）

增量更新说明：blockMapUrl + blockMapSize 为可选字段。客户端检测到 blockMapSize > 0 时自动启用增量下载（仅下载变更区块，节省 30%-70% 流量）。不传或为 null 时客户端全量下载。

---

2. POST /api/v1/releases — 发布新版本（需要鉴权）

POST /api/v1/releases
Authorization: Bearer <UPDATE_API_KEY>
Content-Type: application/json

请求体：

{
  "platform": "win32",
  "edition": "personal",
  "latestVersion": "0.1.0",
  "downloadUrl": "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.1.0/xxx.exe",
  "fileSize": 112910987,
  "sha512": "Base64...",
  "blockMapUrl": "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.1.0/xxx.exe.blockmap",
  "blockMapSize": 152340,
  "changelog": "## 0.1.0\n\n- 新功能 A\n- 修复 B",
  "releaseDate": "2026-06-04",
  "forceUpdate": false,
  "minimumVersion": "0.0.0"
}

---

数据库表结构

CREATE TABLE releases (
    id             BIGINT PRIMARY KEY AUTO_INCREMENT,
    platform       VARCHAR(10)  NOT NULL COMMENT 'win32 / darwin / linux',
    edition        VARCHAR(10)  NOT NULL COMMENT 'personal / enterprise',
    version        VARCHAR(20)  NOT NULL COMMENT '三段式 semver',
    file_url       VARCHAR(500) NOT NULL COMMENT '安装包 OSS HTTPS 地址',
    file_size      BIGINT       NOT NULL COMMENT '安装包字节数',
    sha512         VARCHAR(128) NOT NULL COMMENT '安装包 SHA512 Base64',
    blockmap_url   VARCHAR(500)          COMMENT 'blockmap OSS 地址（可为空）',
    blockmap_size  BIGINT                COMMENT 'blockmap 文件字节数',
    changelog      TEXT                  COMMENT 'Markdown 格式更新日志',
    force_update   TINYINT(1)   DEFAULT 0,
    min_version    VARCHAR(20)  DEFAULT '',
    release_date   DATE         NOT NULL,
    status         VARCHAR(10)  DEFAULT 'draft' COMMENT 'draft / published / deprecated',
    created_at     DATETIME     DEFAULT CURRENT_TIMESTAMP,
    updated_at     DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    UNIQUE KEY uk_platform_edition_version (platform, edition, version),
    INDEX idx_platform_edition_status (platform, edition, status)
);

---

更新检查逻辑（参考实现）

GET /api/v1/update/check?platform=win32&version=0.0.3&edition=personal

1. 查询最新 published 版本：
   SELECT * FROM releases
   WHERE platform = 'win32'
     AND edition = 'personal'
     AND status = 'published'
   ORDER BY version DESC
   LIMIT 1

2. 比较版本号：
   - 请求 version >= 最新 version → hasUpdate = false
   - 请求 version <  最新 version → hasUpdate = true

3. 版本比较建议用 semver 规则（major.minor.patch）

---

文件托管（OSS）

• 安装包和 .blockmap 文件托管在阿里云 OSS，允许公开读取
• 路径约定：releases/{version}/{filename}
• 客户端通过 downloadUrl 直接下载，不经过后端 API

---

后端实现清单

• 部署 GET /api/v1/update/check
• 部署 POST /api/v1/releases（Bearer Token 鉴权）
• 创建 releases 表
• 配置 OSS 公开读取 + HTTPS
• （可选）API Key 白名单 + 限流