530 lines
12 KiB
Markdown
530 lines
12 KiB
Markdown
# Nanami API 文档
|
||
|
||
所有公开接口均无需认证，供客户端软件直接调用。
|
||
|
||
基础 URL: `https://nui.rucky.cn`
|
||
|
||
---
|
||
|
||
# 一、插件市场 API
|
||
|
||
供启动器拉取插件列表、详情、版本和下载。
|
||
|
||
---
|
||
|
||
## 1.1 获取插件列表
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/addons
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| category | string | 否 | 按分类筛选（如 `ui`, `quest`, `combat`, `general`） |
|
||
| search | string | 否 | 按名称或简介模糊搜索 |
|
||
| published | string | 否 | 默认 `true` 只返回已发布插件，传 `false` 返回全部 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "cxxx001",
|
||
"name": "Nanami",
|
||
"slug": "nanami",
|
||
"summary": "一站式乌龟服插件管理器",
|
||
"description": "详细描述...",
|
||
"iconUrl": "/uploads/nanami-icon.png",
|
||
"category": "general",
|
||
"published": true,
|
||
"totalDownloads": 1234,
|
||
"createdAt": "2026-01-01T00:00:00.000Z",
|
||
"updatedAt": "2026-03-18T10:00:00.000Z",
|
||
"releases": [
|
||
{
|
||
"id": "rel001",
|
||
"version": "1.0.0",
|
||
"isLatest": true
|
||
}
|
||
],
|
||
"_count": {
|
||
"releases": 3
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | string | 插件唯一 ID |
|
||
| name | string | 插件名称 |
|
||
| slug | string | 插件标识（URL 友好） |
|
||
| summary | string | 简短描述 |
|
||
| description | string | 详细描述（支持长文本） |
|
||
| iconUrl | string\|null | 图标地址 |
|
||
| category | string | 分类标签 |
|
||
| published | boolean | 是否已发布 |
|
||
| totalDownloads | int | 累计下载次数 |
|
||
| releases | array | 最新版本信息（仅包含 isLatest=true 的版本） |
|
||
| _count.releases | int | 版本总数 |
|
||
|
||
---
|
||
|
||
## 1.2 获取插件详情
|
||
|
||
通过 ID 或 slug 获取单个插件的完整信息，包含所有版本和截图。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/addons/{id_or_slug}
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| id_or_slug | 插件 ID 或 slug，如 `nanami` |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"id": "cxxx001",
|
||
"name": "Nanami",
|
||
"slug": "nanami",
|
||
"summary": "一站式乌龟服插件管理器",
|
||
"description": "详细的 Markdown 描述...",
|
||
"iconUrl": "/uploads/nanami-icon.png",
|
||
"category": "general",
|
||
"published": true,
|
||
"totalDownloads": 1234,
|
||
"createdAt": "2026-01-01T00:00:00.000Z",
|
||
"updatedAt": "2026-03-18T10:00:00.000Z",
|
||
"releases": [
|
||
{
|
||
"id": "rel003",
|
||
"addonId": "cxxx001",
|
||
"version": "1.2.0",
|
||
"changelog": "- 新增XX功能\n- 修复YY问题",
|
||
"downloadType": "local",
|
||
"filePath": "uploads/nanami-1.2.0.zip",
|
||
"externalUrl": null,
|
||
"gameVersion": "1.12.1",
|
||
"downloadCount": 500,
|
||
"isLatest": true,
|
||
"createdAt": "2026-03-18T10:00:00.000Z"
|
||
},
|
||
{
|
||
"id": "rel002",
|
||
"addonId": "cxxx001",
|
||
"version": "1.1.0",
|
||
"changelog": "- 修复界面问题",
|
||
"downloadType": "local",
|
||
"filePath": "uploads/nanami-1.1.0.zip",
|
||
"externalUrl": null,
|
||
"gameVersion": "1.12.1",
|
||
"downloadCount": 300,
|
||
"isLatest": false,
|
||
"createdAt": "2026-02-15T10:00:00.000Z"
|
||
}
|
||
],
|
||
"screenshots": [
|
||
{
|
||
"id": "ss001",
|
||
"addonId": "cxxx001",
|
||
"imageUrl": "/uploads/screenshot1.png",
|
||
"sortOrder": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|---|---|
|
||
| 404 | 插件不存在 |
|
||
|
||
---
|
||
|
||
## 1.3 获取版本列表
|
||
|
||
获取所有版本，可按插件 ID 筛选。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/releases?addonId={addonId}
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| addonId | string | 否 | 按插件 ID 筛选 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "rel003",
|
||
"addonId": "cxxx001",
|
||
"version": "1.2.0",
|
||
"changelog": "- 新增XX功能",
|
||
"downloadType": "local",
|
||
"filePath": "uploads/nanami-1.2.0.zip",
|
||
"externalUrl": null,
|
||
"gameVersion": "1.12.1",
|
||
"downloadCount": 500,
|
||
"isLatest": true,
|
||
"createdAt": "2026-03-18T10:00:00.000Z",
|
||
"addon": {
|
||
"id": "cxxx001",
|
||
"name": "Nanami",
|
||
"slug": "nanami"
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
### 版本字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | string | 版本唯一 ID |
|
||
| addonId | string | 所属插件 ID |
|
||
| version | string | 版本号（如 "1.2.0"） |
|
||
| changelog | string | 更新日志 |
|
||
| downloadType | string | `local` 本地文件 / `url` 外部链接 |
|
||
| gameVersion | string | 适配的游戏版本（如 "1.12.1"） |
|
||
| downloadCount | int | 下载次数 |
|
||
| isLatest | boolean | 是否为最新版本 |
|
||
| addon | object | 所属插件基本信息 |
|
||
|
||
---
|
||
|
||
## 1.4 下载插件
|
||
|
||
通过版本 ID 下载对应的插件压缩包。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/download/{releaseId}
|
||
```
|
||
|
||
### 行为
|
||
|
||
- **本地文件**：返回文件二进制流，`Content-Disposition` 设为 `attachment`
|
||
- **外部链接**：302 重定向到外部下载地址
|
||
- 每次调用自动递增版本下载计数和插件总下载计数
|
||
|
||
### 响应头（本地文件时）
|
||
|
||
```
|
||
Content-Type: application/octet-stream
|
||
Content-Disposition: attachment; filename="nanami-1.2.0.zip"
|
||
Content-Length: 1048576
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|---|---|
|
||
| 404 | 版本不存在或文件丢失 |
|
||
|
||
---
|
||
|
||
# 二、软件更新 API
|
||
|
||
供启动器检查自身版本更新和热更新。
|
||
|
||
---
|
||
|
||
## 软件标识（slug）
|
||
|
||
| slug | 用途 | 文件类型 |
|
||
|---|---|---|
|
||
| `nanami-launcher` | 启动器全量安装包 | Nanami-Launcher-x.x.x.exe |
|
||
| `nanami-launcher-patch` | 热更新补丁包 | app.asar |
|
||
|
||
---
|
||
|
||
## 2.1 检查更新
|
||
|
||
客户端启动时调用此接口，传入当前版本号以检测是否有新版本可用。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/software/check-update?slug={slug}&versionCode={versionCode}
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| slug | string | 是 | 软件标识 |
|
||
| versionCode | int | 否 | 当前客户端的版本代码（整数），不传默认为 0 |
|
||
|
||
### 响应示例
|
||
|
||
**有更新：**
|
||
|
||
```json
|
||
{
|
||
"hasUpdate": true,
|
||
"forceUpdate": false,
|
||
"latest": {
|
||
"version": "1.2.0",
|
||
"versionCode": 120,
|
||
"changelog": "- 新增XX功能\n- 修复YY问题",
|
||
"downloadUrl": "https://nui.rucky.cn/api/software/download/cxxx123",
|
||
"fileSize": 5242880,
|
||
"minVersion": "1.0.0",
|
||
"createdAt": "2026-03-18T10:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**无更新：**
|
||
|
||
```json
|
||
{
|
||
"hasUpdate": false,
|
||
"forceUpdate": false,
|
||
"latest": {
|
||
"version": "1.0.0",
|
||
"versionCode": 100,
|
||
"changelog": "...",
|
||
"downloadUrl": "https://nui.rucky.cn/api/software/download/cxxx123",
|
||
"fileSize": 5242880,
|
||
"minVersion": null,
|
||
"createdAt": "2026-03-01T10:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| hasUpdate | boolean | 是否有新版本 |
|
||
| forceUpdate | boolean | 是否强制更新（true 时客户端应阻止用户继续使用旧版） |
|
||
| latest.version | string | 最新版本号（如 "1.2.0"） |
|
||
| latest.versionCode | int | 最新版本代码（整数，用于比较大小） |
|
||
| latest.changelog | string | 更新日志 |
|
||
| latest.downloadUrl | string | 下载地址（直接用于下载） |
|
||
| latest.fileSize | int | 文件大小（字节） |
|
||
| latest.minVersion | string\|null | 最低兼容版本号 |
|
||
| latest.createdAt | string | 发布时间 (ISO 8601) |
|
||
|
||
### 错误响应
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|---|---|
|
||
| 400 | 缺少 slug 参数 |
|
||
| 404 | 软件不存在或暂无版本 |
|
||
|
||
---
|
||
|
||
## 2.2 下载软件包
|
||
|
||
通过版本 ID 下载对应的软件安装包。一般从"检查更新"接口返回的 `downloadUrl` 直接获取。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/software/download/{versionId}
|
||
```
|
||
|
||
### 行为
|
||
|
||
- **本地文件**：返回文件二进制流，`Content-Disposition` 设为 `attachment`
|
||
- **外部链接**：302 重定向到外部下载地址
|
||
- 每次调用自动递增下载计数
|
||
|
||
### 响应头（本地文件时）
|
||
|
||
```
|
||
Content-Type: application/octet-stream
|
||
Content-Disposition: attachment; filename="nanami-launcher-v1.2.0.exe"
|
||
Content-Length: 5242880
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|---|---|
|
||
| 404 | 版本不存在或文件丢失 |
|
||
|
||
---
|
||
|
||
## 2.3 首页启动器最新版本下载
|
||
|
||
直接下载 `nanami-launcher` 的最新版本，用于首页下载按钮。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /api/software/latest
|
||
```
|
||
|
||
下载最新全量包（自动递增下载计数）。
|
||
|
||
```
|
||
GET /api/software/latest?info=1
|
||
```
|
||
|
||
仅返回版本信息 JSON，不下载。
|
||
|
||
---
|
||
|
||
## 2.4 客户端更新检查流程
|
||
|
||
Nanami 启动器在启动后应按以下顺序检查更新：
|
||
|
||
```
|
||
客户端启动（当前 versionCode = 76）
|
||
│
|
||
├── 步骤 1: 检查全量更新
|
||
│ GET /api/software/check-update?slug=nanami-launcher&versionCode=76
|
||
│ │
|
||
│ ├── forceUpdate=true → 弹出强制更新对话框，下载完整安装包
|
||
│ │ 不再检查热更新
|
||
│ │
|
||
│ └── hasUpdate=true, forceUpdate=false → 显示"新版本"徽章（用户自行决定）
|
||
│ │
|
||
│ └── 继续步骤 2
|
||
│
|
||
├── 步骤 2: 检查热更新
|
||
│ GET /api/software/check-update?slug=nanami-launcher-patch&versionCode=76
|
||
│ │
|
||
│ ├── hasUpdate=true → 静默下载 app.asar，替换本地文件
|
||
│ │ 显示"就绪"徽章，提示重启生效
|
||
│ │
|
||
│ └── hasUpdate=false → 当前已是最新，无需操作
|
||
│
|
||
└── 正常运行
|
||
```
|
||
|
||
### 版本号对应关系示例
|
||
|
||
| 发布类型 | 版本号 | versionCode | slug |
|
||
|---|---|---|---|
|
||
| 全量安装包 | 0.7.6 | 76 | nanami-launcher |
|
||
| 热更新补丁 | 0.7.7 | 77 | nanami-launcher-patch |
|
||
| 全量大版本 | 0.8.0 | 80 | nanami-launcher |
|
||
|
||
### 后台操作
|
||
|
||
- **发布全量版本**：在「Nanami 启动器（全量包）」中上传 `.exe` 文件
|
||
- **发布热更新**：在「Nanami 热更新包」中上传 `app.asar` 文件
|
||
- 两者的 `versionCode` 应保持递增关系，以便客户端正确比较
|
||
|
||
---
|
||
|
||
---
|
||
|
||
# 三、客户端集成示例（Electron）
|
||
|
||
## 3.1 启动器自身更新
|
||
|
||
```javascript
|
||
const BASE_URL = "https://nui.rucky.cn/api/software/check-update";
|
||
const CURRENT_VERSION_CODE = 76;
|
||
|
||
async function checkUpdates() {
|
||
// 步骤 1: 检查全量更新
|
||
const fullResp = await fetch(
|
||
`${BASE_URL}?slug=nanami-launcher&versionCode=${CURRENT_VERSION_CODE}`
|
||
);
|
||
const fullData = await fullResp.json();
|
||
|
||
if (fullData.hasUpdate && fullData.forceUpdate) {
|
||
showForceUpdateDialog(fullData.latest);
|
||
return;
|
||
}
|
||
|
||
if (fullData.hasUpdate) {
|
||
showUpdateBadge(fullData.latest);
|
||
}
|
||
|
||
// 步骤 2: 检查热更新
|
||
const patchResp = await fetch(
|
||
`${BASE_URL}?slug=nanami-launcher-patch&versionCode=${CURRENT_VERSION_CODE}`
|
||
);
|
||
const patchData = await patchResp.json();
|
||
|
||
if (patchData.hasUpdate) {
|
||
const asarResp = await fetch(patchData.latest.downloadUrl);
|
||
const buffer = await asarResp.arrayBuffer();
|
||
// 写入本地 app.asar 路径...
|
||
showRestartBadge();
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3.2 插件市场拉取
|
||
|
||
```javascript
|
||
const API_BASE = "https://nui.rucky.cn";
|
||
|
||
// 获取全部已发布插件
|
||
async function fetchAddons(category?: string, search?: string) {
|
||
const params = new URLSearchParams();
|
||
if (category) params.set("category", category);
|
||
if (search) params.set("search", search);
|
||
|
||
const resp = await fetch(`${API_BASE}/api/addons?${params}`);
|
||
return resp.json();
|
||
}
|
||
|
||
// 获取单个插件详情（含所有版本和截图）
|
||
async function fetchAddonDetail(slug: string) {
|
||
const resp = await fetch(`${API_BASE}/api/addons/${slug}`);
|
||
return resp.json();
|
||
}
|
||
|
||
// 下载插件最新版本
|
||
async function downloadAddon(addon: any) {
|
||
const latestRelease = addon.releases?.find((r: any) => r.isLatest);
|
||
if (!latestRelease) return;
|
||
|
||
const downloadUrl = `${API_BASE}/api/download/${latestRelease.id}`;
|
||
const resp = await fetch(downloadUrl);
|
||
const buffer = await resp.arrayBuffer();
|
||
// 保存到 WoW 插件目录 Interface/AddOns/...
|
||
}
|
||
|
||
// 检查插件是否有更新（对比本地已安装版本）
|
||
async function checkAddonUpdates(installedAddons: { slug: string; version: string }[]) {
|
||
const addons = await fetchAddons();
|
||
const updates = [];
|
||
|
||
for (const installed of installedAddons) {
|
||
const remote = addons.find((a: any) => a.slug === installed.slug);
|
||
if (!remote) continue;
|
||
|
||
const latestRelease = remote.releases?.[0];
|
||
if (latestRelease && latestRelease.version !== installed.version) {
|
||
updates.push({
|
||
addon: remote,
|
||
currentVersion: installed.version,
|
||
newVersion: latestRelease.version,
|
||
});
|
||
}
|
||
}
|
||
|
||
return updates;
|
||
}
|
||
```
|