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

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 输出均支持英文和繁体中文
安装
- 将
ServerAPI-1.0.0.jar 放入 plugins/ 目录
- 启动服务器以生成
plugins/ServerAPI/config.yml
- 检查
http.port — 默认的 8080 经常与其他服务冲突
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
ServerAPI
繁體中文 · English
A REST API allowing websites, Discord bots and dashboards to read live data from your Minecraft server.

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 }
}
Every player field is a UUID.
Highlights
- Never blocks the main thread — data that is only safe to read on the main thread is snapshotted there on a timer; HTTP requests only ever read the cache, so traffic cannot drag down TPS
- Per-endpoint access control — decide which endpoints need a key, and which fields stay hidden even on public endpoints
- Punishments kept forever — bans, tempbans, kicks, warnings, mutes and jails remain in the history after they are lifted
- Built-in rate limiting — token bucket, with correct client-IP resolution behind Cloudflare or Nginx
- No runtime dependencies — the HTTP layer uses the JDK's built-in server and JSON is serialised in-house
- Fully bilingual — English and Traditional Chinese across the config, console, commands and API output
Installation
- Drop
ServerAPI-1.0.0.jar into plugins/
- Start the server to generate
plugins/ServerAPI/config.yml
- Check
http.port — the default 8080 often clashes with other services
curl http://localhost:8080/api/v1
Requires Paper 26.1 and Java 21 or newer. On first start Paper's PluginLoader downloads the
database drivers (HikariCP / JDBC / Jedis) from Maven, so the first launch needs network access.
Endpoints
GET /api/v1 returns an index of every endpoint currently enabled.
| Endpoint |
Returns |
Key by default |
/status |
Online player UUIDs and count, DiscordSRV member count |
|
/status?history=true |
Adds a time series of online and Discord counts |
|
/player/{uuid} |
One player: name, rank, nickname, playtime, AFK, balance, Discord |
|
/player/{uuid}?detailed=true |
Expands per-block / item / entity statistics |
|
/server |
Version, MOTD, max players, game mode, view distance |
✓ |
/performance |
TPS, mean tick time, memory, JVM / OS |
✓ |
/worlds, /worlds/{name} |
World list and detail |
✓ |
/gamerules |
Game rules per world |
✓ |
/entities |
Entity counts per world, by type, players excluded |
✓ |
/spawnlimits |
Spawn limits and intervals per world |
✓ |
/punishments, /punishments/{uuid} |
Punishment records and statistics |
✓ |
/bans |
Ban list, player UUIDs and IPs |
✓ |
/operators |
Operator list |
✓ |
/whitelist |
Whitelist state and entries (off by default) |
✓ |
/plugins |
Installed plugin list |
✓ |
/placeholders?uuid=&p= |
Resolve PlaceholderAPI placeholders |
✓ |
/network |
Cross-server aggregation (off by default, needs multi-server + Redis) |
✓ |
/constants |
Static enum reference (game mode, difficulty, environment) |
✓ |
Every endpoint is served at two paths. /api/v1/{endpoint} is the versioned path — use this for
integrations. /api/{endpoint} is an alias that always points at the latest version.
Entity counts deliberately exclude players so they cannot leak who is online.
Response format
{ "ok": true, "data": { … }, "meta": { … } }
{ "ok": false, "error": { "status": 404, "message": "…", "path": "…" }, "meta": { … } }
Branch on ok; the payload is always in data.
The two timestamps in meta differ:
| Field |
Present on |
Meaning |
updatedAt |
every endpoint |
when this response was produced |
cachedAt |
snapshot endpoints |
when the data was actually captured |
updatedAt - cachedAt is how stale the payload is. For the real age of the data, use cachedAt.
Authentication
Send the key as an X-API-Key header, or as ?key= when auth.allow-query-key is on:
curl -H "X-API-Key: <key>" http://localhost:8080/api/v1/plugins
curl "http://localhost:8080/api/v1/plugins?key=<key>"
URLs end up in browser history and in reverse-proxy access logs. Use the header for real integrations.
Three layers of control:
Per endpoint — auth.require-key.<endpoint>. Anything not listed defaults to requiring a key, so
a new endpoint is never public by accident.
Per field — auth.protected-fields.<endpoint> hides individual fields even when the endpoint is
public. By default /player hides op, banned and discord: the first two are key-protected on
/operators and /bans, and leaving them exposed is a back door — read online UUIDs from the public
/status, then query /player one by one to rebuild both lists. Hidden fields are listed in
meta.hiddenFields.
Disguised responses — with auth.hide-protected on, unauthorised requests get a 404 rather than a
401. Answering 401 tells an attacker that something worth protecting lives there and points them at it.
When auth.enabled is false the whole check is off and none of the above applies.
Starting in that state logs a warning.
Rate limiting and reverse proxies
Token bucket: credit refills at a fixed rate and short bursts are allowed, but sustained overuse
returns 429 with a Retry-After header. The default is 120 requests per minute per source IP with
a burst of 30.
Behind Cloudflare, Nginx or Apache every visitor appears to come from the proxy, which throws the
limiter off. Turn on real-ip.enabled to read the real address from proxy headers:
real-ip:
enabled: true
trusted-proxies:
- "cloudflare" # expands to every published Cloudflare range
- "127.0.0.1/32"
Proxy headers are trivially forged, so they are only trusted when the connection itself comes from
trusted-proxies. X-Forwarded-For is scanned right to left, skipping trusted proxies to reach the
first address that is not one.
Punishment records
/punishments merges bans, IP bans, tempbans, kicks, warnings, mutes and jails, with statistics
(total, players punished, currently active).
Records are kept permanently — lifted or expired entries stay listed with their status changed,
which suits a public punishment lookup page. Set punishment-log.retention-days: 0 to never purge.
Neither Minecraft nor CMI stores kick history, so this plugin listens for the events itself; that
means only kicks after it was enabled are covered.
Data comes from periodic reconciliation against the ban list and CMI rather than from intercepting
commands, so punishments are recorded no matter what issued them.
Web pages
Three HTML pages, all off by default:
web:
docs: false # /api/docs Interactive API docs and try-it
punishments: false # /punishments?view=html Punishment records demo page
placeholders: false # /placeholders?list=true PlaceholderAPI preview page
These lay the content out in full for anyone who can open them, so consider carefully before exposing
them publicly. When off, the path or parameter returns 404; the JSON endpoints are unaffected.
/api/docs lists every enabled endpoint and parameter, lets you fire real requests from the page, and
includes an API key field that never leaves your browser.
Storage
History, the player stat cache and the punishment log all go to a database, which is the single source
of truth.
storage:
type: sqlite # sqlite · mysql · mariadb
Redis is optional: reads prefer Redis, writes go to the database first and then overwrite Redis. If
Redis dies the plugin falls back to the database without interruption and backfills on reconnect.
On a single server with a remote Redis, the local database is usually faster. Redis mainly pays off
for cross-server aggregation.
Offline players require re-reading the stats file (~425ms measured, versus ~4ms for online players),
so only offline players are cached. Entries live in Redis or the database and use no server memory.
Multi-server
Several servers can share one Redis and database, separated by server-id. Servers on the same
cluster-id discover each other, and /network aggregates the whole network.
Key {namespace}:{cluster-id}:{server-id}:{type}[:{id}]
Single serverapi:::history
Network serverapi:main:survival:history
server-id defaults to global, meaning unset and treated as standalone. When several servers share
one Redis each must get a unique value, otherwise they overwrite each other's data — the plugin
warns about this at startup.
Languages
English and Traditional Chinese are built in, covering config comments, console messages, command
replies and API output. Player-supplied text such as ban reasons and nicknames is never translated.
language: auto detects from the host locale and writes the result back on first start. Switch with:
/serverapi lang en_US
Switching backs up the existing config, then rebuilds it from the new language's template with
every value preserved. Language files live in plugins/ServerAPI/lang/ and can be edited; keys
added in later versions are filled in automatically from the bundled copy.
Integrations
All optional soft dependencies. When a plugin is missing its fields are null and nothing else breaks.
| Plugin |
Provides |
| LuckPerms |
rank on /player |
| CMI |
nickname, colours, playtime and AFK on /player; warnings, mutes and jails on /punishments |
| Vault |
balance on /player |
| DiscordSRV |
discord on /player, member count on /status |
| PlaceholderAPI |
the /placeholders endpoint |
/placeholders is the only endpoint that dispatches to the main thread, since most expansions need
Bukkit API access. It is bounded by a timeout and answers 504 if it expires.
Commands and permissions
| Command |
Description |
/serverapi info |
Show current status |
/serverapi reload |
Reload the config and restart the HTTP server |
/serverapi lang <code> |
Switch language |
| Permission |
Default |
Description |
serverapi.admin |
op |
Use the commands above |
serverapi.notice |
op |
Receive request notifications while debug is on |
Snapshot intervals
Tuned per endpoint by how fast the data changes versus what it costs to read
(cache in config.yml, in ticks):
| Endpoint |
Default |
Why |
status |
5s |
Freshest and cheapest |
entities |
20s |
Walks every entity, the expensive one |
worlds / gamerules / spawnlimits |
10m |
Rarely change |
Licence
Free for non-commercial use; commercial servers need a separate licence. See LICENSE.
Issues: GitHub Issues
评论 0
登录后参与评分
还没有评论,来抢沙发吧