现代进展画面

ModernAdvancements 公开了一个只读 JSON API，让你可以构建外部网站或仪表盘来展示服务器的进度数据。本指南涵盖从首次配置到使 API 可从互联网访问的所有内容。

如果你正在阅读本文，我会假设你一开始就知道自己在做什么。对于我无法控制的问题，我不承担任何责任。这个模组只是为你完成了收集游戏内信息的“困难”部分。

要求

• 一个正在运行的 Fabric Minecraft 服务器，运行 Minecraft 26.1 或更新版本
• Java 25 或更新版本（Minecraft 26.1+ 所需）
• 可以访问服务器的控制面板或控制台

模组安装

1. 从发布页面下载最新的模组 jar。文件名类似于 ModernAdvancementsScreen-1.3.0-1.26.1.jar。
2. 将 .jar 文件放入服务器的 mods/ 文件夹。
3. 如果尚未安装，也请在 mods/ 中安装匹配的 Fabric API 版本。
4. 启动或重启服务器。模组将在首次启动时生成其配置文件。

配置

首次启动服务器后，会在以下位置创建配置文件：

config/modern-advancements/modern-advancements_config.json

用任意文本编辑器打开它。相关字段如下：

{
  "httpApiEnabled": true,
  "httpApiHost": "0.0.0.0",
  "httpApiPort": 25580,
  "httpApiKey": ""
}

字段说明

启动 API

只要 httpApiEnabled 为 true，API 就会随 Minecraft 服务器自动启动。在服务器控制台中查找以下行以确认其成功启动：

[ModernAdvancements] Advancement API listening on 0.0.0.0:25580

如果你看到的是错误信息，请查看故障排除部分。

验证是否正常工作

如果你对服务器机器有控制台或 SSH 访问权限，请运行：

curl http://127.0.0.1:25580/api/advancements

配置了 API 密钥时：

curl -H "Authorization: Bearer your-api-key-here" http://127.0.0.1:25580/api/advancements

你应该会得到一份 JSON 响应，列出服务器已知的所有进度。如果你得到 connection refused，则 API 尚未启动或端口错误。

使 API 公开

使用 Minecraft 托管服务商（推荐）

大多数 Minecraft 托管服务商会在隔离环境中运行你的服务器，只有他们明确开放的端口才能从互联网访问。要暴露 API，你需要通过服务商的控制面板分配一个额外端口，然后在模组配置中设置该端口。

大多数服务商的流程相同：

1. 登录你的托管面板。
2. 找到 Ports 或 Network 部分。
3. 分配一个新端口。面板会分配给你一个数字——记下它。
4. 打开 config/modern-advancements/modern-advancements_config.json 并将 httpApiPort 设为该数字。
5. 将 httpApiHost 设为 0.0.0.0。
6. 重启你的 Minecraft 服务器。

之后即可通过 http://your-server-ip:that-port/api/advancements 访问 API。

以下是受支持服务商的确切步骤。

Kinetic Hosting

登录 Kinetic Panel 并导航到你的服务器。在左侧，点击 Network 标签并选择 Network & Ports。点击 Open Port 按钮——会生成并列出新端口。你可以为其添加备注（例如“ModernAdvancements API”），以便记住它的用途。

将配置中的 httpApiPort 设为该端口号并重启服务器。

Kinetic 还内置了反向代理，让你可以将域名映射到 API 端口，而无需暴露原始 IP。详情请参见使用域名代替 IP。

如果你需要特定的端口号而不是随机分配的端口，则需要一个专用 IP。向 Kinetic 提交支持工单，他们可以进行设置。

Shockbyte

在 Shockbyte 面板中导航到你的服务器，然后转到左侧菜单中的 Ports 标签，点击 Add Additional Port。给它起一个名称和描述（这些仅供你自己参考），然后点击按钮。新端口号将出现并立即可用。

将配置中的 httpApiPort 设为该端口号并重启服务器。

Bearded Hosting

Bearded Host 使用一个内置反向代理和协议选择器支持的自定义面板。登录 Bearded Panel 并导航到服务器的 Network 设置以分配一个额外端口。

如果你找不到端口分配选项，或需要帮助通过他们的反向代理暴露 API，请直接通过他们的 Discord 联系 Bearded Host 团队——他们的支持团队通常在 10–30 分钟内回复。

其他服务商

如果你的服务商未在此列出，请在其面板或知识库中查找以下任一项：

• “Additional Ports”
• “Port Allocation”
• “Network”设置
• “Port Manager”

如果这些都不存在，请联系他们的支持团队并询问：“我需要为在 Minecraft 服务器上运行的 HTTP API 开放一个额外的 TCP 端口。我该如何设置？” 所有主要服务商都以某种形式支持这一点——这是 Dynmap 等插件的常见需求。

自托管 / VPS

如果你在 VPS 或专用机器上自行运行服务器，只需在防火墙中开放 API 端口。

# Ubuntu / Debian (ufw)
sudo ufw allow 25580/tcp

# CentOS / RHEL (firewalld)
sudo firewall-cmd --add-port=25580/tcp --permanent && sudo firewall-cmd --reload

还要检查你的 VPS 服务商的网络防火墙（在其 Web 仪表盘中有时称为“Security Groups”或“Inbound Rules”），并确保那里也允许 TCP 端口 25580。

将配置中的 httpApiHost 设为 0.0.0.0，即可通过 http://your-server-ip:25580 访问 API。

使用域名代替 IP

将域名或子域名指向 API 是分享它最简洁的方式——它隐藏了原始 IP 地址，并使 URL 更易于记忆和使用。例如，你的网站可以调用 https://api.yourserver.com/api/players，而不是 http://123.45.67.89:25580/api/players。

根据你的设置，有两种方法。

Kinetic Hosting 内置反向代理

如果你使用 Kinetic Hosting，他们的面板中直接内置了一个反向代理工具来为你处理此事。

1. 确保 API 端口已分配并正常工作（参见上面的 Kinetic 部分）。
2. 在 Kinetic Panel 中，转到 Advanced -> Reverse Proxy。
3. 点击 Add Proxy。
4. 将 Domain 字段设置为你想要的子域名，例如 api.yourserver.com。
5. 将 IP 设置为你的服务器 IP 地址（可在 Overview 页面找到）。
6. 将 Port 设置为你为 API 分配的端口。
7. 点击 Create。
8. 在你的 DNS 服务商（例如 Cloudflare）中，添加一条 A 记录，将 api.yourserver.com 指向你的服务器 IP。

一旦 DNS 传播完成（最多 24 小时，通常快得多），即可通过 http://api.yourserver.com/api/advancements 访问 API，URL 中没有端口号。你还可以在同一面板屏幕中粘贴证书和密钥来添加 SSL 证书——Cloudflare 的免费 SSL 是最简单的生成方式。

Cloudflare DNS + 代理（任意服务商）

这适用于任何托管服务商，并且还能为你提供 Cloudflare 的免费 DDoS 保护和 HTTPS。你的服务器 IP 将隐藏在 Cloudflare 网络之后。

前提条件： 在任何地方注册的域名，以及一个添加了你的域名的免费 Cloudflare 账户。

步骤：

1. 登录 Cloudflare 并选择你的域名。
2. 转到 DNS 标签，点击 Add record。
3. 设置以下内容：
   • Type: A
   • Name: 你想要的子域名，例如 api（这将创建 api.yourserver.com）
   • IPv4 address: 你的服务器 IP 地址
   • Proxy status: 设置为 Proxied（橙色云图标）——这会隐藏你的真实 IP
4. 点击 Save。
5. 转到 Rules 标签 -> Page Rules（或在较新的 Cloudflare 中为 Rules -> Origin Rules），创建一个重写端口的规则，或者如果你的 API 端口是非标准端口，也可以使用 Cloudflare Worker。

不使用 Worker 的更简单替代方案： 如果你有 VPS（而非共享托管面板），将 httpApiHost 设为 127.0.0.1，并将 Caddy 放在其前面。在 Cloudflare 中将 api.yourserver.com 指向你的服务器 IP（Proxied），并使用这两行的 Caddyfile：

api.yourserver.com {
    reverse_proxy /api/* 127.0.0.1:25580
}

Caddy 会自动处理 HTTPS。你的 API 之后位于 https://api.yourserver.com，没有端口。

不隐藏端口的 DNS CNAME

如果你不需要隐藏端口，只是想要一个比原始 IP 地址更简洁的 URL，你可以用 CNAME 或 A 记录将子域名指向你的服务器，并在 URL 中仍然包含端口。例如 http://api.yourserver.com:25580/api/advancements。这不需要代理设置——只需将 DNS 记录指向你的服务器 IP。

身份验证

如果你的 API 可从互联网访问，请设置 API 密钥，以便只有你的网站可以查询它。

生成一个强随机密钥，你可以使用下面的命令，或者直接去问 AI：

# Windows (PowerShell)
[System.Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

将结果粘贴到 config/modern-advancements/modern-advancements_config.json 中的 httpApiKey，然后重启服务器。

在请求中使用密钥：

每个请求都必须在 Authorization 头中作为 Bearer 令牌包含密钥：

Authorization: Bearer your-api-key-here

使用 curl 的示例：

curl -H "Authorization: Bearer your-api-key-here" http://your-server-ip:25580/api/advancements

JavaScript 示例：

const response = await fetch('http://your-server-ip:25580/api/advancements', {
  headers: { 'Authorization': 'Bearer your-api-key-here' }
});

如果未配置密钥，则 API 对任何能访问它的人开放。

API 参考

所有端点都是只读 GET 请求。所有响应都是 application/json。

GET /api/players

返回服务器见过的所有玩家，按进度完成情况排序。

示例响应：

{
  "players": [
    {
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "ThighHugger",
      "completed": 42,
      "total": 95,
      "percentage": 44.2,
      "tabs": [
        {
          "id": "minecraft:story/root",
          "title": "Minecraft",
          "completed": 10,
          "total": 16,
          "completedIds": ["minecraft:story/mine_stone", "..."]
        }
      ]
    }
  ]
}

GET /api/player?name=PlayerName

返回单个玩家的详细进度数据。

错误响应： 如果缺少 name 则为 400，如果未找到玩家则为 404。

GET /api/advancements

返回服务器已知的每个进度及其元数据。

示例响应：

{
  "advancements": [
    {
      "id": "minecraft:story/mine_stone",
      "tab": "minecraft:story/root",
      "parent": "minecraft:story/root",
      "title": "Stone Age",
      "description": "Mine Stone, Granite, Diorite or Andesite",
      "type": "TASK"
    }
  ]
}

type 为 TASK、GOAL 或 CHALLENGE 之一。

GET /api/stats

返回服务器范围的统计数据，包括完成最多和最少的进度。

示例响应：

{
  "totalPlayers": 12,
  "totalAdvancements": 95,
  "averageCompletion": 38.4,
  "mostCompleted": [
    {
      "id": "minecraft:story/mine_stone",
      "title": "Stone Age",
      "count": 11,
      "percentage": 91.7
    }
  ],
  "leastCompleted": [...]
}

GET /api/feed

返回最近进度完成的时间顺序列表。

示例响应：

{
  "events": [
    {
      "playerName": "ThighHugger",
      "advancementId": "minecraft:nether/find_fortress",
      "advancementTitle": "A Terrible Fortress",
      "tabTitle": "Nether",
      "timestamp": 1714000000000
    }
  ],
  "total": 243
}

total 是应用任何 limit 之前的完整事件计数。timestamp 是 Unix 时间（毫秒）。

连接网站

以下是一个获取并显示进度列表的最小工作示例：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Server Advancements</title>
</head>
<body>
  <h1>Server Advancements</h1>
  <ul id="advancements">Loading...</ul>

</body>
</html>

关于 CORS 的说明： API 已在每个响应中包含 Access-Control-Allow-Origin: *，因此来自任何域的浏览器请求都可以正常工作，托管端无需任何额外配置。

故障排除

测试 API 时出现 connection refused API 要么启动失败，要么绑定到了错误的接口，要么端口错误。检查服务器控制台中的 Advancement API listening on ...。如果该行不存在，请重新检查你的配置并确保 httpApiEnabled 为 true。

address already in use 配置的端口已被另一个进程占用。将配置中的 httpApiPort 改为其他值并重启。如果在托管服务商上，请从其面板请求一个新端口。

401 Unauthorized 你请求中的 API 密钥与配置中的不匹配。密钥区分大小写。

API 在本地响应但从互联网无法访问 在托管服务商上，端口可能未在面板中正确分配。再次确认分配的端口与 httpApiPort 完全匹配。如果使用 VPS，请确保操作系统防火墙和服务商的网络防火墙都允许该端口。

503 Server not ready Minecraft 服务器仍在启动中。等待世界加载完成并重试。

空进度列表 进度树会在服务器完全启动且有玩家进入世界后填充。如果 /api/advancements 返回空列表，请在玩家加入后重试。

空玩家列表 API 只有自模组安装以来至少加入过服务器一次的玩家的数据。不会从离线玩家文件回填。