YoungestSongMo
95019316b2
- task: device_id 改为必填参数，API 层 Omit 封装 + getDeviceId() 自动注入 - pricing.ts: Python 后端 calculate_cost 完整移植，六种定价模式 + 6 个 Bug 修复 (浮点冗余/维度匹配不一致/null 守卫/matrix 数据提取/unit_scale 等) - ModelInputForm: 三层兜底预估消费展示 + React Hooks 顺序修复 - AccountInfo: VIP 等级列表匹配，套餐详情展示（说明/周期/席位/到期） - 模型列表加密缓存 (safe-storage, stale-while-revalidate) - VIP API 模块 (激活码/等级/订单/模拟支付) - device_id 统一使用 UUID v4 持久化 (与 login/register 对齐)
184 lines
5.8 KiB
Markdown
184 lines
5.8 KiB
Markdown
# 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 白名单 + 限流
|