rucky/nanami-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

乌龟服官服

Browse Source
This commit is contained in:
rucky
2026-05-15 19:17:31 +08:00
parent fa7aedb8e7
commit 557ecebee6
33 changed files with 118 additions and 504 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
API.md
View File

@@ -11,57 +11,27 @@ Bilingual (zh / en) public REST API for the Nanami Turtle WoW platform.
---
## 🎮 WoW 客户端版本（多版本支持）
## 🎮 WoW 客户端版本
平台为 Turtle WoW **1.18** 与 **1.17** 两套客户端独立维护启动器、插件版本与发布渠道。每个 `Release` / `SoftwareVersion` 都打了 `wowVersion` 标签，且 `isLatest` 在 `(addon|software, wowVersion)` 维度内唯一 —— 同一插件可以同时存在「1.18 最新版」和「1.17 最新版」两条 latest。
平台当前只对外提供 Turtle WoW **1.18** 版本。每个 `Release` / `SoftwareVersion` 仍保留 `wowVersion` 字段用于标识历史数据和数据库约束，但公共网页、后台、下载和更新接口都会固定使用 `1.18`。
### 如何选择 wow 版本
### 版本解析
不同接口的解析策略略有差异：
#### 列表 / 浏览类接口（addons / releases / software / changelog）
| 来源 | 示例 | 优先级 |
|------|------|--------|
| 查询参数 `wow` | `?wow=1.18` 或 `?wow=1.17` | 1（最高） |
| 查询参数 `wowVersion` | `?wowVersion=1.17` | 2（别名） |
| Cookie `wow` | 浏览器侧由前台切换设置 | 3 |
| 默认 | — | `1.18` |
这些接口让浏览器在导航过程中保留用户选择的 wow 频道（cookie 持久化）。多数列表型接口还支持 `?wow=all` 表示不过滤、返回所有版本。
#### 下载 / 自更新类接口（latest / check-update / download/launcher）
| 来源 | 示例 | 优先级 |
|------|------|--------|
| 查询参数 `wow` | `?wow=1.18` | 1（最高） |
| 查询参数 `wowVersion` | `?wowVersion=1.17` | 2（别名） |
| 默认 | — | `1.18` |
⚠️ **下载类接口故意不读 Cookie**。这是一个强约定：**URL 自己完全决定下载到的二进制**。
为什么这样设计：
1. `https://nanami.rucky.cn/download/launcher` 这种第三方嵌入直链，必须永远稳定指向 1.18 版本，不能被访客之前在前台切换过的 cookie 污染。
2. 启动器自更新（`/api/software/check-update`）的频道由启动器自身声明（`?wow=1.17`），避免 1.18 客户端因为 cookie 串台拿到 1.17 的更新。
3. 不论中英文（`lang`）切换，下载到的二进制都是同一个，只跟 `?wow=` 相关。
合法值：`1.18`、`1.17`。
- `wow` / `wowVersion` 查询参数可以省略；即使传入其他历史值，也会回落到 `1.18`
- 浏览器 Cookie 不再参与 wow 版本选择
- 列表接口不再支持 `?wow=all` 返回所有历史版本
### 响应字段
- 单条对象上含 `wowVersion`，标识该 release / version 所属的客户端版本
- 列表型响应顶层含 `wowVersion` 字段，回显本次过滤值（`"all"` 表示未过滤）
- 单条对象上含 `wowVersion`，当前对外返回值为 `"1.18"`
- 列表型响应顶层含 `wowVersion` 字段，回显当前固定过滤值
### 启动器自更新建议
启动器调用 `/api/software/check-update` 时务必带上 `wow=1.18` 或 `wow=1.17`，否则会按默认 `1.18` 返回 —— 1.17 客户端拿到 1.18 的更新就出问题了。
启动器调用 `/api/software/check-update` 时无需传 wow 频道；服务端始终返回 1.18 通道。
```bash
# 1.17 启动器自检更新（已安装 versionCode=1010）
curl 'https://nanami.rucky.cn/api/software/check-update?slug=nanami-launcher&versionCode=1010&wow=1.17'
# 1.18 启动器
curl 'https://nanami.rucky.cn/api/software/check-update?slug=nanami-launcher&versionCode=1010&wow=1.18'
curl 'https://nanami.rucky.cn/api/software/check-update?slug=nanami-launcher&versionCode=1010'
```
---
@@ -114,7 +84,7 @@ GET /api/software/check-update?slug={slug}&versionCode={n}&wow={wow}&lang={lang}
|------|------|------|------|
| slug | string | ✅ | 软件标识，例如 `nanami-launcher`、`nanami-launcher-patch` |
| versionCode | number | ❌ | 当前客户端版本号（整数），缺省为 0 |
| wow | string | ❌ | `1.18` / `1.17`，缺省 `1.18` |
| wow | string | ❌ | 固定为 `1.18`；可省略 |
| lang | string | ❌ | `zh` / `en`，缺省 `zh` |
**响应示例（wow=1.18, lang=en）：**
@@ -140,7 +110,7 @@ GET /api/software/check-update?slug={slug}&versionCode={n}&wow={wow}&lang={lang}
}
```
`forceUpdate=true` 仅当存在更新且最新版被标记为强制更新。`isLatest` 是 `(software, wowVersion)` 维度的 —— 1.18 与 1.17 各自有独立的 latest，互不影响。下载 URL 自动带 `source=launcher`，启动器更新下载会单独计数。
`forceUpdate=true` 仅当存在更新且最新版被标记为强制更新。下载 URL 自动带 `source=launcher`，启动器更新下载会单独计数。
---
@@ -206,14 +176,13 @@ GET /download/launcher?wow={wow}
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| wow | string | ❌ | `1.18` / `1.17`，缺省 `1.18` |
| wow | string | ❌ | 固定为 `1.18`；可省略 |
⚠️ **第三方链接安全**：这条 URL 是公开嵌入用的，**只看显式 `?wow=` 参数**，**不读用户 cookie**。意思是：即使用户之前在前台切到 1.17，再点这条不带 `?wow=` 的链接仍然会下载到 1.18。这样可以让站外的「下载启动器」按钮稳定指向 1.18。
⚠️ **第三方链接安全**：这条 URL 是公开嵌入用的，不读用户 cookie，始终下载 1.18 通道。
```html
<a href="https://nanami.rucky.cn/download/launcher">下载 Nanami 启动器（默认 WoW 1.18）</a>
<a href="https://nanami.rucky.cn/download/launcher?wow=1.18">下载 Nanami 启动器（WoW 1.18）</a>
<a href="https://nanami.rucky.cn/download/launcher?wow=1.17">下载 Nanami 启动器（WoW 1.17）</a>
```
---
@@ -258,7 +227,7 @@ GET /api/software/changelog?slug={slug}&wow={wow}&lang={lang}
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| slug | string | ✅ | 软件标识 |
| wow | string | ❌ | `1.18` / `1.17`（缺省 `1.18`），传 `all` 不过滤 |
| wow | string | ❌ | 固定为 `1.18`；可省略 |
| lang | string | ❌ | `zh` / `en` |
**响应示例（wow=1.18, lang=en）：**
@@ -331,7 +300,7 @@ GET /api/software/changelog?slug={slug}&wow={wow}&lang={lang}
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| lang | string | ❌ | `zh` / `en` |
| wow | string | ❌ | `1.18` / `1.17` —— 仅返回此 WoW 版本下的 latest release；传 `all` 表示不过滤 |
| wow | string | ❌ | 固定为 `1.18`；可省略 |
| published | string | ❌ | 默认 `true`；传 `false` 包括草稿 |
| category | string | ❌ | 按分类过滤 |
| search | string | ❌ | 名称 / 简介模糊匹配，中英都搜 |
@@ -390,7 +359,7 @@ GET /api/software/changelog?slug={slug}&wow={wow}&lang={lang}
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| addonId | string | ❌ | 限定某个插件；缺省返回全平台所有插件的 release |
| wow | string | ❌ | `1.18` / `1.17`，缺省 `1.18`；传 `all` 不过滤 |
| wow | string | ❌ | 固定为 `1.18`；可省略 |
| lang | string | ❌ | `zh` / `en` |
**响应示例：**
@@ -538,7 +507,7 @@ GET /api/server-time
| GET | `/api/software/check-update` | ✏️ | ✅ | ✅ | 启动器自更新检查 |
| GET | `/api/software/download/{id}` | ✏️ | ❌ | ❌ | 下载启动器文件（按 versionId 精确） |
| GET | `/api/software/latest` | ✏️ | ✅ | ✅ | 最新启动器信息 / 下载（网页用） |
| GET | `/download/launcher` | 🆕 | ❌ | ✅ | 友好直链：按 wow 始终下载最新 |
| GET | `/download/launcher` | 🆕 | ❌ | ✅ | 友好直链：始终下载 1.18 最新 |
| POST | `/api/launcher/heartbeat` | — | ❌ | ❌ | 上报启动器在线状态 |
| GET | `/api/software/changelog` | ✏️ | ✅ | ✅ | 启动器历史 changelog |
| GET | `/api/software` | 🆕 | ✅ | ✅ | 软件列表 |
@@ -561,27 +530,15 @@ GET /api/server-time
# 1.18 启动器最新版（英文 changelog）
curl 'https://nanami.rucky.cn/api/software/latest?info=1&lang=en&wow=1.18'
# 1.17 启动器最新版
curl 'https://nanami.rucky.cn/api/software/latest?info=1&wow=1.17'
# 1.18 启动器全部历史 changelog（中文）
curl 'https://nanami.rucky.cn/api/software/changelog?slug=nanami-launcher&wow=1.18&lang=zh'
# 1.17 启动器自更新检查（已安装 versionCode=1010）
curl 'https://nanami.rucky.cn/api/software/check-update?slug=nanami-launcher&versionCode=1010&wow=1.17'
# 1.17 客户端的 UI 类插件（英文）
curl 'https://nanami.rucky.cn/api/addons?lang=en&category=ui&wow=1.17'
# 不限 WoW 版本，列出所有 release
curl 'https://nanami.rucky.cn/api/releases?wow=all'
# 1.18 客户端的 UI 类插件（英文）
curl 'https://nanami.rucky.cn/api/addons?lang=en&category=ui'
# 1.18 启动器友好直链
curl -L -o nanami-launcher-1.18.exe 'https://nanami.rucky.cn/download/launcher?wow=1.18'
# 1.17 启动器友好直链
curl -L -o nanami-launcher-1.17.exe 'https://nanami.rucky.cn/download/launcher?wow=1.17'
# 通过 Accept-Language 协商语言
curl -H 'Accept-Language: en-US,en;q=0.9' 'https://nanami.rucky.cn/api/articles'
```