ServerAPI

插件

· 作者 kevin28576

一个 REST API,允许网站、Discord 机器人和仪表板读取你 Minecraft 服务器的实时数据。

0 本站下载 0 关注 更新于 3 个月前

最新 1.0.0 · 26.2 · Paper

一键开服(送7天)

ServerAPI

繁體中文 · English

一个 REST API,允许网站、Discord 机器人和管理面板从你的 Minecraft 服务器读取实时数据。

ServerAPI

curl http://localhost:8080/api/v1/status
{
  "ok": true,
  "data": { "online": ["40094f2f-…", "8b1e…"], "minecraft": 2, "discord": 3400 },
  "meta": { "version": "v1", "server": "global", "updatedAt": 1784300000000, "cachedAt": 1784299700000 }
}

每个玩家字段均为 UUID。


亮点

  • 绝不阻塞主线程 — 仅在主线程上安全读取的数据会在定时器触发时进行快照;HTTP 请求仅读取缓存,因此流量不会拖慢 TPS
  • 按端点访问控制 — 决定哪些端点需要密钥,以及哪些字段即使在公共端点上也要隐藏
  • 惩罚记录永久保存 — 封禁、临时封禁、踢出、警告、静音和监禁在解除后仍保留在历史记录中
  • 内置速率限制 — 令牌桶算法,支持在 Cloudflare 或 Nginx 后的正确客户端 IP 解析
  • 无运行时依赖 — HTTP 层使用 JDK 内置服务器,JSON 由内部序列化
  • 完全双语支持 — 配置、控制台、命令和 API 输出均支持英文和繁体中文

安装

  1. 将 ServerAPI-1.0.0.jar 放入 plugins/ 目录
  2. 启动服务器以生成 plugins/ServerAPI/config.yml
  3. 检查 http.port — 默认的 8080 经常与其他服务冲突
  4. curl http://localhost:8080/api/v1

需要 Paper 26.1 和 Java 21 或更高版本。首次启动时,Paper 的 PluginLoader 会从 Maven 下载数据库驱动程序(HikariCP / JDBC / Jedis),因此首次启动需要网络连接。

端点

GET /api/v1 返回当前启用的所有端点的索引。

端点 返回内容 默认需要密钥
/status 在线玩家 UUID 及数量、DiscordSRV 成员数量
/status?history=true 增加在线和 Discord 数量的时间序列
/player/{uuid} 单个玩家:名称、等级、昵称、游戏时长、空闲状态、余额、Discord
/player/{uuid}?detailed=true 扩展每个方块/物品/实体的统计数据
/server 版本、MOTD、最大玩家数、游戏模式、视距 ✓
/performance TPS、平均刻时间、内存、JVM / OS ✓
/worlds, /worlds/{name} 世界列表及详情 ✓
/gamerules 各世界的游戏规则 ✓
/entities 按类型分的世界实体数量,排除玩家 ✓
/spawnlimits 各世界的生成限制和间隔 ✓
/punishments, /punishments/{uuid} 惩罚记录和统计 ✓
/bans 封禁列表、玩家 UUID 和 IP ✓
/operators 管理员列表 ✓
/whitelist 白名单状态和条目(默认关闭) ✓
/plugins 已安装的插件列表 ✓
/placeholders?uuid=&p= 解析 PlaceholderAPI 占位符 ✓
/network 跨服务器聚合(默认关闭,需要多服务器 + Redis) ✓
/constants 静态枚举参考(游戏模式、难度、环境) ✓

每个端点都在两个路径下提供服务。/api/v1/{endpoint} 是带版本的路径 — 用于集成请使用此路径。/api/{endpoint} 是一个别名,始终指向最新版本。

实体计数故意排除玩家,以防止泄露谁在线。

响应格式

{ "ok": true,  "data": { … }, "meta": { … } }
{ "ok": false, "error": { "status": 404, "message": "…", "path": "…" }, "meta": { … } }

根据 ok 分支;有效负载始终在 data 中。

meta 中的两个时间戳含义不同:

字段 出现在 含义
updatedAt 每个端点 生成此响应的时间
cachedAt 快照端点 实际捕获数据的时间

updatedAt - cachedAt 表示有效负载的陈旧程度。要获取数据的真实年龄,请使用 cachedAt。

认证

将密钥作为 X-API-Key 头发送,或在 auth.allow-query-key 开启时作为 ?key= 参数发送:

curl -H "X-API-Key: <key>" http://localhost:8080/api/v1/plugins
curl "http://localhost:8080/api/v1/plugins?key=<key>"

URL 会出现在浏览器历史和反向代理访问日志中。对于真正的集成,请使用头部。

三层控制机制:

按端点 — auth.require-key.<endpoint>。未列出的任何内容默认都需要密钥,因此新端点绝不会意外公开。

按字段 — auth.protected-fields.<endpoint> 即使端点是公开的,也会隐藏个别字段。默认情况下,/player 隐藏 op、banned 和 discord:前两者在 /operators 和 /bans 上是受密钥保护的,如果让它们暴露则构成后门 — 从公共 /status 读取在线 UUID,然后逐个查询 /player 来重建这两个列表。隐藏字段列在 meta.hiddenFields 中。

伪装响应 — 当 auth.hide-protected 开启时,未经授权的请求会收到 404 而不是 401。回答 401 会告诉攻击者那里有值得保护的东西并指引他们去那里。

当 auth.enabled 为 false 时,整个检查关闭,上述规则均不适用。 以该状态启动时会记录警告。

速率限制和反向代理

令牌桶:信用额度以固定速率补充,允许短时间突发,但持续过度使用会返回 429 并附带 Retry-After 头。默认为每源 IP 每分钟 120 次请求,突发容量为 30。

在 Cloudflare、Nginx 或 Apache 后面时,所有访客看起来都来自代理服务器,这会导致限速器失效。启用 real-ip.enabled 可从代理标头读取真实地址:

real-ip:
  enabled: true
  trusted-proxies:
    - "cloudflare"        # 扩展为所有已发布的 Cloudflare 范围
    - "127.0.0.1/32"

代理标头极易伪造,因此仅在连接本身来自 trusted-proxies 时才信任它们。X-Forwarded-For 从右向左扫描,跳过受信任的代理以找到第一个非受信任的地址。

处罚记录

/punishments 合并了封禁、IP 封禁、临时封禁、踢出、警告、静音和监禁,并提供统计数据(总数、被处罚玩家数、当前活跃数)。

记录永久保留——解除或过期的条目仍会列出,但状态已更改,这适合用于公共处罚查询页面。设置 punishment-log.retention-days: 0 可永不清理。

Minecraft 和 CMI 均不存储踢出历史,因此本插件自行监听相关事件;这意味着只有在本插件启用之后发生的踢出才会被记录。

数据来源于定期与封禁列表和 CMI 进行核对,而非通过拦截命令获取,因此无论由谁发出的处罚都会被记录。

Web 页面

三个 HTML 页面,默认全部关闭:

web:
  docs: false           # /api/docs                 交互式 API 文档及试用功能
  punishments: false    # /punishments?view=html    处罚记录演示页面
  placeholders: false   # /placeholders?list=true   PlaceholderAPI 预览页面

这些页面将内容完整呈现给任何能打开它们的人,因此在向公众暴露之前请慎重考虑。当关闭时,路径或参数将返回 404;JSON 端点不受影响。

/api/docs 列出每个启用的端点和参数,允许您直接从页面发起真实请求,并包含一个永远不会离开您浏览器的 API 密钥字段。

存储

历史记录、玩家统计缓存和处罚日志全部存入数据库,作为唯一事实来源。

storage:
  type: sqlite          # sqlite · mysql · mariadb

Redis 是可选的:读取优先使用 Redis,写入首先进入数据库,然后覆盖 Redis。如果 Redis 宕机,插件会无中断地回退到数据库,并在重新连接时回填数据。

在拥有远程 Redis 的单服务器环境中,本地数据库通常更快。Redis 主要在跨服务器聚合场景中体现价值。

离线玩家需要重新读取统计文件(实测约 425ms,而在线玩家约 4ms),因此仅缓存离线玩家的数据。条目存储在 Redis 或数据库中,不占用服务器内存。

多服务器

多台服务器可以共享同一个 Redis 和数据库,通过 server-id 进行区分。处于相同 cluster-id 的服务器会自动互相发现,且 /network 会聚合整个网络的数据。

Key       {namespace}:{cluster-id}:{server-id}:{type}[:{id}]
Single    serverapi:::history
Network   serverapi:main:survival:history

server-id 默认为 global,表示未设置并按独立服务器处理。当多台服务器共享一个 Redis 时,每台都必须获得唯一的值,否则它们会相互覆盖数据——插件会在启动时对此发出警告。

语言

内置英文和繁体中文,涵盖配置注释、控制台消息、命令回复和 API 输出。玩家提供的文本(如封禁原因和昵称)不会被翻译。

language: auto 会从主机区域设置中检测语言,并在首次启动时将结果写回。可通过以下命令切换:

/serverapi lang en_US

切换时会备份现有配置,然后基于新语言的模板重新构建配置,同时保留所有值。语言文件位于 plugins/ServerAPI/lang/ 并可编辑;后续版本中添加的键会自动从捆绑副本中填充。

集成

所有均为可选的软依赖。当缺少某个插件时,其对应字段为 null,且不会导致其他部分出错。

插件 提供内容
LuckPerms /player 上的 rank
CMI /player 上的昵称、颜色、游戏时间和 AFK 状态;/punishments 上的警告、静音和监禁
Vault /player 上的 balance
DiscordSRV /player 上的 discord 信息;/status 上的成员数量
PlaceholderAPI /placeholders 端点

/placeholders 是唯一分发到主线程的端点,因为大多数扩展需要 Bukkit API 访问权限。它设有超时限制,若超时则返回 504。

命令和权限

命令 描述
/serverapi info 显示当前状态
/serverapi reload 重载配置并重启 HTTP 服务器
/serverapi lang <code> 切换语言
权限 默认 描述
serverapi.admin op 使用上述命令
serverapi.notice op 当 debug 开启时接收请求通知

快照间隔

根据数据变化速度与读取成本之间的平衡,针对每个端点进行调优(config.yml 中的 cache,单位为刻):

端点 默认值 原因
status 5s 最新且开销最低
entities 20s 遍历所有实体,开销较大
worlds / gamerules / spawnlimits 10m 很少变更

许可证

免费用于非商业用途;商业服务器需单独获取许可证。请参阅 LICENSE。

问题反馈:GitHub Issues

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源