nanami-web/API.md

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

响应示例：

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

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

请求体：

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

响应：

{ "ok": true }

实现建议：

• 启动器启动时立即发送一次心跳，之后每 60 秒发送一次
• deviceId 需要在客户端持久化保存，确保同一台机器始终使用相同 ID
• IP 地址由服务端自动获取，无需客户端上报
• 网络失败时静默忽略即可，不影响启动器正常功能

---

5. 历史更新日志 🆕

查询指定软件的所有版本历史和更新日志，按版本号倒序排列。

GET /api/software/changelog?slug={slug}

参数	类型	必填	说明
slug	string	是	软件标识，如 nanami-launcher 或 nanami-launcher-patch

响应示例：

{
  "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	🆕 新增	上报在线状态