ServerTap - 服务器 JSON API

ServerTap 是一个面向 Bukkit、Spigot 和 PaperMC Minecraft 服务器的 REST API 插件，可让服务器管理员通过简洁的 REST 语义查询并操作服务器。

💡获取插件

• 最新版本下载：

https://github.com/phybros/servertap/releases/latest

• Discord：

https://discord.gg/fefHbTFAkj

🎮简介

ServerTap 提供了一个可自托管的 HTTP API，支持通过 curl、Postman 或任何支持 HTTP 的工具与 Minecraft 服务器交互。

它还支持

• Swagger API 文档
• TLS
• Authentication
• CORS
• Webhooks
• Websockets

🔧使用方法

安装

• 将插件的 jar 文件放入服务器的 plugins/ 目录中。

调用 API

• 安装完成后，你可以使用 curl、Postman 或任何支持 HTTP 的工具请求服务器。

示例：查询服务器信息

$ curl 
http://localhost:4567/v1/server 
{
"name": "Paper",
"motd": "This is my MOTD",
"version": "git-Paper-89 (MC: 1.15.2)",
"bukkitVersion": "1.15.2-R0.1-SNAPSHOT",
"health": {
"cpus": 4,
"uptime": 744,
"totalMemory": 2010644480,
"maxMemory": 2010644480,
"freeMemory": 1332389360
},
"bannedIps": [],
"bannedPlayers": [
{
"target": "phybros",
"source": "Server"
}
]
}

示例：获取当前在线玩家列表

$ curl 
http://localhost:4567/v1/players 
[
{
"uuid": "55f584e4-f095-48e0-bb8a-eb5c87ffe494",
"displayName": "phybros",
"address": "localhost",
"port": 58529,
"exhaustion": 3.5640976,
"exp": 0.45454547,
"whitelisted": false,
"banned": false,
"op": true
}
]

⭐当前可用端点

ServerTap 会自托管 Swagger API 文档。你可以在以下地址查看完整文档：

• http://your-server.net:4567/swagger

你还可以直接在 Swagger UI 中探索并测试 API。

部分功能示例

• Ping
• Server
• Get/Add/Remove Ops
• Get/Add Whitelist
• Get/Save/List Worlds
• List/Read Scoreboard(s)
• Broadcast
• List/Find Players
• Get/Pay/Debt Economy (W/ Plugin)
• List Plugins

✨TLS

ServerTap 通过 Java 的 keystore 文件支持 TLS（也叫 SSL）。

强烈建议启用 TLS，因为它可以对与你服务器之间传输的请求和响应进行加密。

生成 keystore 示例

keytool -genkey -keyalg RSA -alias servertap -keystore selfsigned.jks -validity 365 -keysize 2048
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]:
...
<you can mostly answer whatever you want to all these questions>

配置步骤

• 将输出文件 selfsigned.jks 保存到 plugins/ServerTap 目录中。
• 然后在 config.yml 中添加：

tls:
enabled: true
keystore: selfsigned.jks
keystorePassword: testing

• 配置完成后，请使用 https:// 与 API 通信。

SNI

自 v0.5.0 起，TLS 可选支持 Server Name Indication（SNI）。

• 在配置中将 tls.sni 设为 true 即可启用（高级用法）。
• 99.9% 的用户无需关注这个选项，保持为 false 即可。

🎮Authentication

目前的认证机制还比较基础。

配置方法

将以下内容添加到 plugins/ServerTap/config.yml 中：

useKeyAuth: true
key: some-long-super-random-string

请求方式

• 在每个请求中添加名为 key 的 Header。
• Header 的值应为你在配置中设置的密钥。

说明

• 官方表示仍需帮助改进该功能。
• 更多信息请参见：

#5

⭐CORS

默认情况下，ServerTap 允许来自任意来源（*）的跨域请求。

如果你想修改此行为，请在配置文件中调整 corsOrigins。

示例

corsOrigins:
- 
https://mysite.com 

说明

• 该设置支持多个来源。
• 只需将更多来源添加到数组中即可。

🔧Webhooks

ServerTap 可以在服务器发生事件时发送 webhook 消息。

配置示例

在 plugins/ServerTap/config.yml 中这样定义：

webhooks:
default:
listener: "
https://your-webhook-target.com/whatever "
events:
- PlayerJoin
- PlayerQuit

Webhook 请求格式

Webhook 会发送 POST 请求，内容为简单的 JSON payload：

{
"player": {
"uuid": "55f584e4-f095-48e0-bb8a-eb5c87ffe494",
"displayName": "phybros",
"address": "localhost",
"port": 52809,
"exhaustion": 0,
"exp": 0.5714286,
"whitelisted": true,
"banned": false,
"op": true
},
"joinMessage": "§ephybros joined the game",
"eventType": "PlayerJoin"
}

当前可用事件

• PlayerJoin
• PlayerDeath
• PlayerChat
• PlayerKick
• PlayerQuit

🔧Websockets

ServerTap 提供双向 websockets 接口，可让你实时接收服务器日志行，无需轮询。

连接建立后，任何经过服务器正常日志过滤器的日志行都会通过 websocket 以 JSON 对象形式发送，例如：

{
"message": "§6/version: §fGets the version of this server including any plugins in use",
"timestampMillis": 1631834015918,
"loggerName": "",
"level": "INFO"
}

说明

• 你可以使用类似 ansicolors 的库在浏览器中解析颜色代码。

连接地址

• ws://<host>:4567/v1/ws/console
• 如果已启用 TLS，请使用 wss://

行为说明

• 连接客户端后，会收到最近的 1000 条服务器日志消息。
• 你可以通过修改 config.yml 中的 websocketConsoleBuffer 来配置日志缓冲区大小。
• 你也可以通过 WS 连接发送命令，这些命令会在服务器上执行。

❓Websockets 认证

由于 websocket 连接无法像普通 API 路由那样设置 Header，因此不能使用 Header key 进行认证。

你必须在承载 websocket 连接的页面上设置一个名为 x-servertap-key 的 cookie。

示例

// set cookie to authenticate the connection
document.cookie = "x-servertap-key=change_me";
this.ws = new WebSocket("ws://localhost:4567/v1/ws/console");
this.ws.onopen = function() {
console.log("Opened connection");
};

注意事项

• 如果你没有启用认证，相当于把一个远程管理控制台直接暴露到互联网上。
• 这是个坏主意。

✨开发

如果你想参与 ServerTap 的开发，需要准备以下环境：

• An IDE (e.g. IntelliJ)
• JDK 19
• Maven

构建方式

• 使用 mvn package 命令构建插件 jar。

我目前无法直接打开或读取 https://servertap.io 的网页内容。

请把该插件文档的原文粘贴过来，我就可以按照你的要求将其整理并翻译为适合插件目录网站发布的简体中文版本，格式会包括：

💡简短介绍

⭐功能

• ...

🎮命令

• ...

✨安装

• ...

❓常见问题

• ...

如果文档内容较长，也可以分多次发送，我会继续帮你整理。