API 开发文档

MC Server Hub 提供了一个标准化的 RESTful 接口层，旨在抹平不同上游（PaperMC, Fabric, Jenkins CI, GitHub Releases）之间的差异。

为什么使用此 API？

无需分别解析 Paper 的 v2 API 和 Fabric 的 Meta 接口，也无需编写复杂的 Jenkins XML 解析逻辑。本接口统一返回包含 download_url 和 sha256 的标准 JSON。

基础 URL & 规范

Base URL HTTP

http://localhost:3000/api

格式

统一返回 JSON 格式数据
方法

所有接口仅支持 GET 请求
状态

成功时包含 success: true

GET

/projects

获取当前系统配置的所有服务端核心类型列表。

字段	类型	说明
id	String	唯一标识符 (例如 `paper`, `fabric`)
type	String	适配器类型 (`paper_v2`, `jenkins`, `github`)
name	String	人类可读的显示名称

Example Response

{
  "success": true,
  "data": [
    { "id": "paper", "type": "paper_v2", "name": "Paper" },
    { "id": "fabric", "type": "fabric", "name": "Fabric" },
    { "id": "catserver", "type": "jenkins", "name": "Catserver" }
  ]
}

GET

/versions/:project

获取指定核心所支持的游戏版本列表。

路径参数 (Path Params)

project Required 核心 ID (通过 /projects 获取)

{
  "success": true,
  "from_cache": true,
  "data": [ "1.20.4", "1.20.2", "1.20.1", "1.19.4" ]
}

GET

/dl/:project/:version/:build?

最核心的接口。获取最终的文件下载地址、文件名和校验哈希。

参数	示例	说明
project	paper	项目 ID
version	1.20.4	游戏版本
build	latest	可选默认为 latest

Success Response

{
  "success": true,
  "data": {
    "project": "paper",
    "mc_version": "1.20.4",
    "build_id": "496",
    "file_name": "paper-1.20.4-496.jar",
    "download_url": "https://api.papermc.io/.../paper-1.20.4-496.jar",
    "hashes": {
      "sha256": "3a0b1c2d4e5f..."
    },
    "source_type": "PaperMC API"
  }
}

🐧 Linux 命令行一键下载

对于服务器运维人员，可以使用 curl 和 jq 组合命令，直接在 Linux 终端下载最新核心，非常适合编写 Dockerfile 或自动更新脚本。

# 设置变量
PROJECT="paper"
VERSION="1.20.4"
API="http://localhost:3000/api/dl"

# 方式 1: 直接下载并重命名为 server.jar
curl -s "$API/$PROJECT/$VERSION/latest" | jq -r '.data.download_url' | xargs wget -O server.jar

# 方式 2: 仅获取下载直链
LINK=$(curl -s "$API/$PROJECT/$VERSION/latest" | jq -r '.data.download_url')
echo "下载地址: $LINK"

需要预先安装 jq 工具 (apt install jq / yum install jq)

⚙️ 添加自定义源 (config.js)

通过修改后端的 config.js，您可以轻松扩展支持的服务端类型。

添加 Jenkins 源

'bungeecord': { 
    type: 'jenkins', 
    url: 'https://ci.md-5.net/job/BungeeCord', 
    artifactMatch: 'BungeeCord.jar' // 文件名匹配规则
}

添加 GitHub 源

'my-plugin': {
    type: 'github',
    repo: 'User/RepoName', 
    assetMatch: '.jar$' // 正则匹配 Asset
}

❌ 错误代码对照

HTTP Code	Message 关键词	可能原因
404	Project not supported	请求了 config.js 中未定义的 project ID
404	Version not found	上游源中不存在该版本
500	Fetch failed	服务器网络问题，无法连接到 GitHub/Jenkins/Paper 接口
500	Artifact not found	虽然构建成功，但在构建产物中未找到匹配 .jar 的文件