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

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

---

## 快速启动测试服务器

```bash
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` |

**响应 — 有更新时：**

```json
{
  "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"
  }
}
```

**响应 — 无更新时：**

```json
{
  "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` — 发布新版本（需要鉴权）

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

**请求体：**

```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"
}
```

---

## 数据库表结构

```sql
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 白名单 + 限流