ServerPlayerOnlineTracker/README_API.md

可用 API 接口

本 Mod 提供了一系列 RESTful API 接口，允许外部应用获取服务器的玩家在线数据和实时状态。所有 API 接口均通过 HTTP GET 请求访问。

基础 URL: http://您的服务器IP:配置的端口 (默认端口为 60048)

---

GET /api/stats

• 描述: 获取所有玩家的在线时长统计数据。

• 响应: JSON 数组，每个元素代表一个玩家的统计信息。

• 响应示例结构:

  [
    {
      "playerName": "玩家名称",
      "uuid": "114514-1919810",
      "totalTimeSeconds": 123456,
      "totalTimeFormatted": "34h 17m",
      "last30DaysSeconds": 54321,
      "last30DaysFormatted": "15h 05m",
      "last7DaysSeconds": 9876,
      "last7DaysFormatted": "02h 44m"
    }
    // ... 更多玩家
  ]
  

• 字段说明:

  • playerName (String): 玩家名称。
  • uuid (String): 玩家的 UUID。
  • totalTimeSeconds (long): 总在线时长（秒）。
  • totalTimeFormatted (String): 总在线时长（格式化字符串，例如 "34h 17m"）。
  • last30DaysSeconds (long): 最近 30 天在线时长（秒）。
  • last30DaysFormatted (String): 最近 30 天在线时长（格式化字符串）。
  • last7DaysSeconds (long): 最近 7 天在线时长（秒）。
  • last7DaysFormatted (String): 最近 7 天在线时长（格式化字符串）。

---

GET /api/lang

• 描述: 获取 Mod 当前加载的本地化语言字符串。

  • 注意: 此接口主要用于内部调试和网页前端加载语言，不建议公开暴露。

• 响应: JSON 对象，键为语言字符串的 key，值为对应的翻译文本。

• 响应示例结构:

  {
    "playertime.command.title": "§6===== 玩家在线时长 (第 {0}/{1} 页) =====",
    "playertime.web.title": "玩家在线及状态统计",
    // ... 更多语言键值对
  }
  

---

GET /api/online-players

• 描述: 获取当前在线玩家的列表，按白名单状态分类。

• 响应: JSON 对象，包含两个列表：whitelisted 和 non_whitelisted。

• 响应示例结构:

  {
    "whitelisted": [
      {
        "name": "WhitelistedPlayer1",
        "uuid": "114514-1919810"
      }
    ],
    "non_whitelisted": [
      {
        "name": "NonWhitelistedPlayer1",
        "uuid": "51121-55555121"
      }
    ]
  }
  

• 字段说明:

  • whitelisted (List<Map<String, String>>): 白名单在线玩家列表。每个 Map 包含 name (玩家名称) 和 uuid (玩家 UUID)。
  • non_whitelisted (List<Map<String, String>>): 非白名单在线玩家列表。每个 Map 包含 name (玩家名称) 和 uuid (玩家 UUID)。

---

GET /api/player-count

• 描述: 获取当前在线玩家的数量统计。

• 响应: JSON 对象，包含总数、白名单玩家数和非白名单玩家数。

• 响应示例结构:

  {
    "total": 10,
    "whitelisted": 8,
    "non_whitelisted": 2
  }
  

• 字段说明:

  • total (int): 在线玩家总数。
  • whitelisted (int): 在线白名单玩家数。
  • non_whitelisted (int): 在线非白名单玩家数（通常指假人或未在白名单的玩家）。

---

GET /api/whitelist

• 描述: 获取服务器的白名单列表。

• 响应: JSON 数组，每个元素代表一个白名单玩家的信息。

• 响应示例结构:

  [
    {
      "name": "BRanulf",
      "uuid": "114514-1919810",
      "online": true
    },
    {
      "name": "DarkSharkBee",
      "uuid": "51121-55555121",
      "online": false
    }
    // ... 更多白名单玩家
  ]
  

• 字段说明:

  • name (String): 白名单玩家名称。
  • uuid (String): 白名单玩家的 UUID。
  • online (boolean): 该玩家当前是否在线。

---

GET /api/server-status

• 描述: 获取服务器的详细运行状态信息。

• 响应: JSON 对象，包含内存、磁盘、处理器、运行时间及服务器自身信息。

• 响应示例结构:

  {
    "memory": {
      "max": 8589934592,
      "total": 8589934592,
      "used": 2147483648,
      "free": 6442450944,
      "usage_percentage": 25.0
    },
    "disk": {
      "total": 1073741824000,
      "free": 536870912000,
      "usable": 536870912000,
      "usage_percentage": 50.0
    },
    "available_processors": 8,
    "uptime": 3600,
    "uptime_formatted": "01小时 00分钟 00秒",
    "server": {
      "version": "1.21.4",
      "motd": "§aWelcome to My Server!",
      "player_count": 5,
      "max_players": 20,
      "average_tick_time_ms": 15.23,
      "recent_tick_samples_ms": [14.5, 16.1, 15.0, 15.8, ...]
    }
  }
  

• 字段说明:

  • memory (Object): 内存统计信息。
    • max (long): JVM 可用的最大内存（字节）。
    • total (long): JVM 当前分配的总内存（字节）。
    • used (long): JVM 已使用的内存（字节）。
    • free (long): JVM 可用的空闲内存（字节）。
    • usage_percentage (double): 内存使用率（已用 / 最大 * 100）。
  • disk (Object): 磁盘统计信息。
    • total (long): 磁盘总空间（字节）。
    • free (long): 磁盘空闲空间（字节）。
    • usable (long): 磁盘可用空间（字节）。
    • usage_percentage (double): 磁盘使用率（(总 - 空闲) / 总 * 100）。
  • available_processors (int): 服务器可用的处理器核心数。
  • uptime (long): 服务器运行时间（秒）。
  • uptime_formatted (String): 服务器运行时间（格式化字符串，例如 "01小时 00分钟 00秒"）。
  • server (Object): Minecraft 服务器自身信息。
    • version (String): Minecraft 服务器版本。
    • motd (String): 服务器 MOTD。
    • player_count (int): 当前在线玩家数。
    • max_players (int): 服务器最大玩家容量。
    • average_tick_time_ms (double): 服务器平均 Tick 时间（毫秒，即 MSPT）。
    • recent_tick_samples_ms (List): 最近的 Tick 时间样本（毫秒）。

---

GET /api/playerdata

• 描述: 获取原始的玩家在线时间数据文件内容。

  • 警告: 此接口直接暴露服务器的玩家数据文件内容，包含 UUID 和在线时间等敏感信息。强烈建议不要将此接口公开暴露给外部网络。

• 响应: JSON 对象，内容与 player_time_data.json 文件完全一致。

• 响应示例结构:

  {
    "114514-1919810": {
      "totalTime": 123456,
      "lastLogin": 0, // 0 表示离线，非 0 表示上次登录时间戳
      "rolling30Days": {
        "days": 30,
        "entries": [
          { "timestamp": 1678886400, "seconds": 3600 },
          // ...
        ]
      },
      "rolling7Days": {
        "days": 7,
        "entries": [
          { "timestamp": 1678886400, "seconds": 1800 },
          // ...
        ]
      }
    },
    "51121-55555121": {
      // ...
    }
  }