203 lines
5.9 KiB
Markdown
203 lines
5.9 KiB
Markdown
# Nanami 启动器 API 文档
|
||
|
||
> Base URL: `https://nanami.rucky.cn`（或对应部署地址）
|
||
>
|
||
> 标注说明：🆕 新增 | ✏️ 有变动 | 无标注为原有不变
|
||
|
||
---
|
||
|
||
## 1. 检查更新 ✏️
|
||
|
||
检查指定软件是否有新版本。
|
||
|
||
```
|
||
GET /api/software/check-update?slug={slug}&versionCode={versionCode}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| slug | string | 是 | 软件标识，如 `nanami-launcher` 或 `nanami-launcher-patch` |
|
||
| versionCode | number | 否 | 当前客户端版本号（整数），不传默认为 0 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"hasUpdate": true,
|
||
"forceUpdate": false,
|
||
"latest": {
|
||
"version": "1.3.0",
|
||
"versionCode": 130,
|
||
"changelog": "- 修复xxx\n- 新增xxx",
|
||
"downloadUrl": "https://nanami.rucky.cn/api/software/download/clxxx?source=launcher",
|
||
"fileSize": 52428800,
|
||
"minVersion": "1.0.0",
|
||
"createdAt": "2026-03-25T10:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**✏️ 变动说明**：返回的 `downloadUrl` 现在自动附带 `?source=launcher` 参数，启动器直接使用该 URL 下载即可，下载量会被单独统计为「客户端更新下载」，与网页端下载区分。启动器无需做任何额外处理。
|
||
|
||
---
|
||
|
||
## 2. 下载文件 ✏️
|
||
|
||
根据版本 ID 下载文件。通常不需要手动拼接，直接使用 check-update 返回的 `downloadUrl` 即可。
|
||
|
||
```
|
||
GET /api/software/download/{versionId}?source={source}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| versionId | string | 是 | 路径参数，版本记录 ID |
|
||
| source | string | 否 | 下载来源标识，传 `launcher` 表示客户端更新下载 |
|
||
|
||
**响应**：
|
||
|
||
- 本地文件：直接返回二进制流（`Content-Type: application/octet-stream`）
|
||
- 外链文件：302 重定向到外部 URL
|
||
|
||
**✏️ 变动说明**：新增 `source` 查询参数。当 `source=launcher` 时，下载量会同时计入总下载量和启动器更新下载量两个计数器。check-update 返回的 URL 已自动包含此参数，启动器无需手动处理。
|
||
|
||
---
|
||
|
||
## 3. 获取最新版本信息（网页用）
|
||
|
||
获取 nanami-launcher 的最新版本信息或直接下载，主要给网页端使用。
|
||
|
||
```
|
||
GET /api/software/latest?info=1&track=1
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| info | string | 否 | 传 `1` 返回 JSON 元数据；不传则直接下载文件 |
|
||
| track | string | 否 | 仅在 `info=1` 时生效，传 `1` 同时计数下载量 |
|
||
|
||
**响应示例（info=1）：**
|
||
|
||
```json
|
||
{
|
||
"available": true,
|
||
"version": "1.3.0",
|
||
"versionCode": 130,
|
||
"changelog": "...",
|
||
"fileSize": 52428800,
|
||
"createdAt": "2026-03-25T10:00:00.000Z",
|
||
"downloadUrl": "/api/software/download/clxxx",
|
||
"downloadType": "local"
|
||
}
|
||
```
|
||
|
||
> 此接口固定查询 slug 为 `nanami-launcher` 的软件，启动器通常使用 check-update 接口而非此接口。
|
||
|
||
---
|
||
|
||
## 4. 上报心跳（在线状态） 🆕
|
||
|
||
启动器定期调用此接口上报在线状态，建议每 **60 秒** 调用一次。超过 3 分钟无心跳视为离线。
|
||
|
||
```
|
||
POST /api/launcher/heartbeat
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"deviceId": "unique-machine-id",
|
||
"os": "Windows",
|
||
"osVersion": "10.0.19045",
|
||
"appVersion": "1.3.0"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceId | string | **是** | 设备唯一标识，建议使用机器码或 UUID 持久化存储 |
|
||
| os | string | 否 | 操作系统名称，如 `Windows`、`macOS`、`Linux` |
|
||
| osVersion | string | 否 | 系统版本号，如 `10.0.19045`、`14.3` |
|
||
| appVersion | string | 否 | 启动器版本号，如 `1.3.0` |
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{ "ok": true }
|
||
```
|
||
|
||
**实现建议**：
|
||
- 启动器启动时立即发送一次心跳，之后每 60 秒发送一次
|
||
- `deviceId` 需要在客户端持久化保存，确保同一台机器始终使用相同 ID
|
||
- IP 地址由服务端自动获取，无需客户端上报
|
||
- 网络失败时静默忽略即可，不影响启动器正常功能
|
||
|
||
---
|
||
|
||
## 5. 历史更新日志 🆕
|
||
|
||
查询指定软件的所有版本历史和更新日志，按版本号倒序排列。
|
||
|
||
```
|
||
GET /api/software/changelog?slug={slug}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| slug | string | 是 | 软件标识，如 `nanami-launcher` 或 `nanami-launcher-patch` |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"name": "Nanami 启动器（全量包）",
|
||
"slug": "nanami-launcher",
|
||
"versions": [
|
||
{
|
||
"version": "1.3.0",
|
||
"versionCode": 130,
|
||
"changelog": "- 新增xxx\n- 修复xxx",
|
||
"fileSize": 52428800,
|
||
"isLatest": true,
|
||
"forceUpdate": false,
|
||
"createdAt": "2026-03-25T10:00:00.000Z"
|
||
},
|
||
{
|
||
"version": "1.2.0",
|
||
"versionCode": 120,
|
||
"changelog": "- 优化xxx",
|
||
"fileSize": 50331648,
|
||
"isLatest": false,
|
||
"forceUpdate": false,
|
||
"createdAt": "2026-03-10T08:00:00.000Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| versions[].version | string | 版本号 |
|
||
| versions[].versionCode | number | 版本号（整数），用于比较大小 |
|
||
| versions[].changelog | string | 更新日志内容 |
|
||
| versions[].fileSize | number | 文件大小（字节） |
|
||
| versions[].isLatest | boolean | 是否为当前最新版本 |
|
||
| versions[].forceUpdate | boolean | 是否为强制更新版本 |
|
||
| versions[].createdAt | string | 发布时间（ISO 8601） |
|
||
|
||
---
|
||
|
||
## 接口一览
|
||
|
||
| 方法 | 路径 | 状态 | 用途 |
|
||
|------|------|------|------|
|
||
| GET | `/api/software/check-update` | ✏️ 变动 | 检查更新，downloadUrl 已含 source 标记 |
|
||
| GET | `/api/software/download/{id}` | ✏️ 变动 | 下载文件，支持 source 参数区分来源 |
|
||
| GET | `/api/software/latest` | 无变动 | 获取最新版信息/下载（网页用） |
|
||
| GET | `/api/software/changelog` | 🆕 新增 | 查询历史更新日志 |
|
||
| POST | `/api/launcher/heartbeat` | 🆕 新增 | 上报在线状态 |
|