rucky/nanami-web

Fork 0

Files

rucky fa7aedb8e7 feat: add localization and site settings

2026-05-12 09:58:25 +08:00

18 KiB

Raw Blame History

Nanami Web · Public API

Bilingual (zh / en) public REST API for the Nanami Turtle WoW platform.

标注：🆕 新增 · ✏️ 有变动 · 🌐 支持多语言

Base URL（生产环境）： https://nanami.rucky.cn
Base URL（直连 IP）： http://120.77.146.152:3000
Content-Type： application/json
认证： 公共读接口无需认证；POST/PUT/DELETE 写接口需要管理员 session（不属于公共 API 范围）

🎮 WoW 客户端版本（多版本支持）

平台为 Turtle WoW 1.18 与 1.17 两套客户端独立维护启动器、插件版本与发布渠道。每个 Release / SoftwareVersion 都打了 wowVersion 标签，且 isLatest 在 (addon|software, wowVersion) 维度内唯一 —— 同一插件可以同时存在「1.18 最新版」和「1.17 最新版」两条 latest。

如何选择 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 自己完全决定下载到的二进制。

为什么这样设计：

https://nanami.rucky.cn/download/launcher 这种第三方嵌入直链，必须永远稳定指向 1.18 版本，不能被访客之前在前台切换过的 cookie 污染。
启动器自更新（/api/software/check-update）的频道由启动器自身声明（?wow=1.17），避免 1.18 客户端因为 cookie 串台拿到 1.17 的更新。
不论中英文（lang）切换，下载到的二进制都是同一个，只跟 ?wow= 相关。

合法值：1.18、1.17。

响应字段

单条对象上含 wowVersion，标识该 release / version 所属的客户端版本
列表型响应顶层含 wowVersion 字段，回显本次过滤值（"all" 表示未过滤）

启动器自更新建议

启动器调用 /api/software/check-update 时务必带上 wow=1.18 或 wow=1.17，否则会按默认 1.18 返回 —— 1.17 客户端拿到 1.18 的更新就出问题了。

# 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'

🌐 国际化（i18n）

所有公共读接口都支持中英双语，通过查询参数选择语言。

语言协商

来源	示例	优先级
查询参数 `lang`	`?lang=en` 或 `?lang=zh`	1（最高）
查询参数 `locale`	`?locale=en`	2（`lang` 别名）
`Accept-Language` 请求头	`Accept-Language: en-US,en;q=0.9`	3
默认	—	`zh`

合法值：zh、en。其他值会被忽略，回退到默认。

响应字段约定

每条可翻译的文本字段，会同时返回三个键：

键名	含义
`name` / `summary` / `description` / `changelog` / `title` / `content`	「规范字段」，按当前 lang 解析后的值
`*Zh`（如 `nameZh`）	原始中文
`*En`（如 `nameEn`）	原始英文

响应顶层附带 lang 字段，回显本次实际响应使用的语言，便于客户端确认协商结果。

回退规则

请求 lang=en 时若 *En 字段为空，则规范字段回退到中文（保证客户端永远拿到非空内容）。*Zh / *En 始终是数据库存储的原始值（其中之一可能为空）。

兼容性

未传 lang 的旧客户端不受影响：name、summary、changelog 等字段仍是中文，行为与改造前一致
新增的 *Zh / *En 字段是增量字段，旧客户端可以安全忽略

1. 检查更新 ✏️ 🌐 🎮

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`
lang	string	❌	`zh` / `en`，缺省 `zh`

响应示例（wow=1.18, lang=en）：

{
  "hasUpdate": true,
  "forceUpdate": false,
  "lang": "en",
  "wowVersion": "1.18",
  "latest": {
    "version": "1.0.15",
    "versionCode": 1015,
    "changelog": "Added Memorial Box feature\n…",
    "changelogZh": "添加骨灰盒功能\n…",
    "changelogEn": "Added Memorial Box feature\n…",
    "downloadUrl": "https://nanami.rucky.cn/api/software/download/abc123?source=launcher",
    "fileSize": 0,
    "minVersion": null,
    "wowVersion": "1.18",
    "createdAt": "2026-04-28T14:40:30.844Z"
  }
}

forceUpdate=true 仅当存在更新且最新版被标记为强制更新。isLatest 是 (software, wowVersion) 维度的 —— 1.18 与 1.17 各自有独立的 latest，互不影响。下载 URL 自动带 source=launcher，启动器更新下载会单独计数。

2. 下载文件 ✏️

GET /api/software/download/{versionId}?source={source}

参数	类型	必填	说明
versionId	string	✅	路径参数，版本记录 ID
source	string	❌	下载来源标记，`launcher` 表示客户端自更新

响应：

本地文件：Content-Type: application/octet-stream，二进制流
外链文件：HTTP 302 跳转

source=launcher 时，下载量计入「启动器更新下载」单独计数器。该参数已由 check-update 自动附加，启动器无需关心。

3. 获取最新启动器（网页用） 🌐

GET /api/software/latest?info=1&track=1&lang={lang}

参数	类型	必填	说明
info	string	❌	传 `1` 返回 JSON 元数据；不传则直接返回二进制文件
track	string	❌	仅 `info=1` 时生效，传 `1` 同时累加下载计数
lang	string	❌	`zh` / `en`，仅 `info=1` 时影响 changelog 字段

响应示例（info=1, lang=en）：

{
  "available": true,
  "version": "1.0.15",
  "versionCode": 1015,
  "changelog": "Added Memorial Box feature\n…",
  "changelogZh": "添加骨灰盒功能\n…",
  "changelogEn": "Added Memorial Box feature\n…",
  "fileSize": 0,
  "createdAt": "2026-04-28T14:40:30.844Z",
  "downloadUrl": "/api/software/download/abc123",
  "downloadType": "url",
  "lang": "en"
}

4. 启动器友好直链 🆕 🎮

GET /download/launcher?wow={wow}

外部网页可直接 <a href> 引用这个地址下载最新版启动器，等价于 GET /api/software/latest（无 info=1）：本地文件直返，外链 302 跳转。

参数	类型	必填	说明
wow	string	❌	`1.18` / `1.17`，缺省 `1.18`

⚠️ 第三方链接安全：这条 URL 是公开嵌入用的，只看显式 ?wow= 参数，不读用户 cookie。意思是：即使用户之前在前台切到 1.17，再点这条不带 ?wow= 的链接仍然会下载到 1.18。这样可以让站外的「下载启动器」按钮稳定指向 1.18。

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

5. 上报心跳（在线状态） 🆕

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`
osVersion	string	❌	系统版本号
appVersion	string	❌	启动器版本

响应： { "ok": true }

实现建议：启动时发送一次心跳，之后每 60 秒一次；超过 3 分钟未心跳视为离线。

6. 历史更新日志 ✏️ 🌐 🎮

GET /api/software/changelog?slug={slug}&wow={wow}&lang={lang}

参数	类型	必填	说明
slug	string	✅	软件标识
wow	string	❌	`1.18` / `1.17`（缺省 `1.18`），传 `all` 不过滤
lang	string	❌	`zh` / `en`

响应示例（wow=1.18, lang=en）：

{
  "name": "Nanami Launcher",
  "nameZh": "Nanami 启动器",
  "nameEn": "Nanami Launcher",
  "slug": "nanami-launcher",
  "lang": "en",
  "wowVersion": "1.18",
  "versions": [
    {
      "version": "1.0.15",
      "versionCode": 1015,
      "changelog": "Added Memorial Box feature\n…",
      "changelogZh": "添加骨灰盒功能\n…",
      "changelogEn": "Added Memorial Box feature\n…",
      "fileSize": 0,
      "isLatest": true,
      "forceUpdate": false,
      "wowVersion": "1.18",
      "createdAt": "2026-04-28T14:40:30.844Z"
    }
  ]
}

7. 软件列表 / 详情 🆕 🌐

`GET /api/software?lang={lang}`

返回全部软件包及其当前最新版本。

响应示例：

[
  {
    "id": "...",
    "slug": "nanami-launcher",
    "name": "Nanami Launcher",
    "nameZh": "Nanami 启动器",
    "nameEn": "Nanami Launcher",
    "description": "Nanami addon launcher…",
    "descriptionZh": "Nanami 插件启动器…",
    "descriptionEn": "Nanami addon launcher…",
    "createdAt": "...",
    "updatedAt": "...",
    "versions": [{ "version": "1.0.15", "isLatest": true, "...": "..." }],
    "_count": { "versions": 48 },
    "lang": "en"
  }
]

`GET /api/software/{idOrSlug}?lang={lang}`

返回单个软件包及其全部历史版本（versions 按 versionCode 倒序）。

8. 插件列表 / 详情 🆕 🌐 🎮

`GET /api/addons`

参数	类型	必填	说明
lang	string	❌	`zh` / `en`
wow	string	❌	`1.18` / `1.17` —— 仅返回此 WoW 版本下的 latest release；传 `all` 表示不过滤
published	string	❌	默认 `true`；传 `false` 包括草稿
category	string	❌	按分类过滤
search	string	❌	名称 / 简介模糊匹配，中英都搜

响应示例：

[
  {
    "id": "...",
    "slug": "nanami-ui",
    "name": "Nanami-UI",
    "nameZh": "Nanami-UI",
    "nameEn": "Nanami-UI",
    "summary": "All-in-one UI replacement…",
    "summaryZh": "一款为乌龟服精心打造的全功能界面…",
    "summaryEn": "All-in-one UI replacement…",
    "description": "# Nanami-UI\n…",
    "descriptionZh": "# Nanami-UI\n…",
    "descriptionEn": "# Nanami-UI\n…",
    "iconUrl": "/uploads/...",
    "category": "ui",
    "published": true,
    "totalDownloads": 1234,
    "releases": [
      {
        "id": "...",
        "version": "0.9.14",
        "changelog": "See the launcher changelog for details.",
        "changelogZh": "详见启动器更新日志",
        "changelogEn": "See the launcher changelog for details.",
        "downloadType": "local",
        "filePath": "/uploads/...",
        "isLatest": true
      }
    ],
    "screenshots": [],
    "_count": { "releases": 5 },
    "lang": "en"
  }
]

`GET /api/addons/{idOrSlug}?lang={lang}`

返回单个插件及其所有 releases（按 createdAt 倒序）。

9. 插件版本（Releases） 🆕 🌐 🎮

`GET /api/releases?addonId={id}&wow={wow}&lang={lang}`

列出 release。

参数	类型	必填	说明
addonId	string	❌	限定某个插件；缺省返回全平台所有插件的 release
wow	string	❌	`1.18` / `1.17`，缺省 `1.18`；传 `all` 不过滤
lang	string	❌	`zh` / `en`

响应示例：

[
  {
    "id": "...",
    "version": "1.2.5",
    "changelog": "2026.04.03 update:\n…",
    "changelogZh": "2026.04.03更新：\n…",
    "changelogEn": "2026.04.03 update:\n…",
    "downloadType": "local",
    "filePath": "/uploads/...",
    "externalUrl": null,
    "gameVersion": "1.18.1",
    "downloadCount": 0,
    "isLatest": true,
    "createdAt": "...",
    "addon": {
      "id": "...",
      "slug": "instancejournal",
      "name": "InstanceJournal",
      "nameZh": "InstanceJournal",
      "nameEn": "InstanceJournal"
    },
    "lang": "en"
  }
]

`GET /api/download/{releaseId}`

直接下载 release 文件（本地文件返二进制，外链 302 跳转），同时累加 release 下载量。

10. 公告文章 🆕 🌐

`GET /api/articles`

参数	类型	必填	说明
lang	string	❌	`zh` / `en`
published	string	❌	默认 `true`
limit	number	❌	限制条数

响应：

[
  {
    "id": "...",
    "slug": "shutdown-announcement",
    "title": "Server shutdown",
    "titleZh": "关服公告",
    "titleEn": "Server shutdown",
    "summary": "...",
    "summaryZh": "...",
    "summaryEn": "...",
    "content": "Markdown content…",
    "contentZh": "Markdown 内容…",
    "contentEn": "Markdown content…",
    "coverImage": "/uploads/…",
    "published": true,
    "createdAt": "...",
    "updatedAt": "...",
    "lang": "en"
  }
]

`GET /api/articles/{idOrSlug}?lang={lang}`

返回单篇文章。字段同上。

11. 站点资源 🌐

`GET /api/banners?enabled=1`

首页 Hero Banner 图。无可翻译文本，lang 参数不影响响应。

[{ "id": "...", "imageUrl": "/uploads/...", "sortOrder": 0, "enabled": true }]

`GET /api/gallery?enabled=1&lang={lang}`

截图画廊。title 字段双语。

[
  {
    "id": "...",
    "imageUrl": "/uploads/...",
    "title": "Nameplate showcase",
    "titleZh": "姓名版展示",
    "titleEn": "Nameplate showcase",
    "sortOrder": 0,
    "enabled": true
  }
]

12. 服务器时间

GET /api/server-time

{ "serverTime": "2026-04-29T08:00:00.000Z", "epochMs": 1798156800000 }

供客户端校时与首页倒计时使用。

错误处理

所有失败响应都返回统一结构：

{ "error": "Slug already exists" }

HTTP	含义
400	参数缺失或格式错误
401	未授权（写接口）
404	资源不存在
409	冲突（如 slug 重复）
500	服务端错误

接口一览

方法	路径	状态	多语言	WoW 过滤	用途
GET	`/api/software/check-update`	✏️	✅	✅	启动器自更新检查
GET	`/api/software/download/{id}`	✏️	❌	❌	下载启动器文件（按 versionId 精确）
GET	`/api/software/latest`	✏️	✅	✅	最新启动器信息 / 下载（网页用）
GET	`/download/launcher`	🆕	❌	✅	友好直链：按 wow 始终下载最新
POST	`/api/launcher/heartbeat`	—	❌	❌	上报启动器在线状态
GET	`/api/software/changelog`	✏️	✅	✅	启动器历史 changelog
GET	`/api/software`	🆕	✅	✅	软件列表
GET	`/api/software/{idOrSlug}`	🆕	✅	✅	单个软件 + 全部版本
GET	`/api/addons`	🆕	✅	✅	插件列表
GET	`/api/addons/{idOrSlug}`	🆕	✅	✅	单个插件 + 所有 release
GET	`/api/releases`	🆕	✅	✅	插件版本列表
GET	`/api/download/{id}`	—	❌	❌	下载插件 release 文件（按 releaseId）
GET	`/api/articles`	🆕	✅	❌	公告列表
GET	`/api/articles/{idOrSlug}`	🆕	✅	❌	单篇公告
GET	`/api/banners`	🆕	❌	❌	Hero Banner 图
GET	`/api/gallery`	🆕	✅	❌	截图画廊
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 启动器友好直链
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'

18 KiB Raw Blame History Unescape Escape

Nanami Web · Public API

🎮 WoW 客户端版本（多版本支持）

如何选择 wow 版本

列表 / 浏览类接口（addons / releases / software / changelog）

下载 / 自更新类接口（latest / check-update / download/launcher）

响应字段

启动器自更新建议

🌐 国际化（i18n）

语言协商

响应字段约定

回退规则

兼容性

1. 检查更新 ✏️ 🌐 🎮

2. 下载文件 ✏️

3. 获取最新启动器（网页用） 🌐

4. 启动器友好直链 🆕 🎮

5. 上报心跳（在线状态） 🆕

6. 历史更新日志 ✏️ 🌐 🎮

7. 软件列表 / 详情 🆕 🌐

GET /api/software?lang={lang}

GET /api/software/{idOrSlug}?lang={lang}

8. 插件列表 / 详情 🆕 🌐 🎮

GET /api/addons

GET /api/addons/{idOrSlug}?lang={lang}

9. 插件版本（Releases） 🆕 🌐 🎮

GET /api/releases?addonId={id}&wow={wow}&lang={lang}

GET /api/download/{releaseId}

10. 公告文章 🆕 🌐

GET /api/articles

GET /api/articles/{idOrSlug}?lang={lang}

11. 站点资源 🌐

GET /api/banners?enabled=1

GET /api/gallery?enabled=1&lang={lang}

12. 服务器时间

错误处理

接口一览

调用示例

18 KiB

Raw Blame History

`GET /api/software?lang={lang}`

`GET /api/software/{idOrSlug}?lang={lang}`

`GET /api/addons`

`GET /api/addons/{idOrSlug}?lang={lang}`

`GET /api/releases?addonId={id}&wow={wow}&lang={lang}`

`GET /api/download/{releaseId}`

`GET /api/articles`

`GET /api/articles/{idOrSlug}?lang={lang}`

`GET /api/banners?enabled=1`

`GET /api/gallery?enabled=1&lang={lang}`