DevelopmentAPI
一个 Paper 插件,提供小型 HTTP/JSON API,让你能够通过外部工具驱动 Minecraft 服务器:检查服务器状态、管理在线玩家、查看日志,以及在沙盒文件夹中读写配置文件。附带 / 路径下的 Web 控制台界面。
安装设置
-
将 DevelopmentAPI-1.0.0.jar 放入服务器的 plugins/ 文件夹并启动服务器。
-
打开 plugins/DevelopmentAPI/config.yml。首次启动时会生成一个随机 Bearer Token 并写入该文件——复制该值。
-
每个 HTTP 请求都必须包含以下标头:
Authorization: Bearer <token>
配置
plugins/DevelopmentAPI/config.yml:
server:
host: "127.0.0.1" # 绑定地址;设为 0.0.0.0 以暴露给外部网络
port: 8080
token: "" # 首次启动时留空 — 系统将自动生成一个令牌
security:
target-plugin-folder: "Development"
allowed-extensions:
- yml
- yaml
- json
- txt
commands:
reload: "develop reload"
在游戏中使用 /devapi reload 重新加载配置。
游戏内命令
| 命令 |
描述 |
/devapi status |
显示监听器状态 |
/devapi reload |
重新加载 config.yml 并重启监听器 |
/devapi token |
打印当前 Bearer Token(仅限 OP) |
HTTP 端点
所有端点均需要 Authorization: Bearer <token> 认证。
| 方法 |
路径 |
描述 |
| GET |
/api/health |
存活探针 |
| GET |
/api/info |
插件版本、目标文件夹、操作列表 |
| POST |
/api/action |
分发 JSON 动作(见下文) |
| GET |
/ |
Web 控制台界面 |
POST /api/action 接收一个带有 "action" 字段的 JSON 对象。所有响应均为 JSON 格式,包含 "ok": true|false 以及动作特定的有效载荷或 "error" 错误字符串。
文件操作
路径相对于配置的 target-plugin-folder(默认为 plugins/Development/)。拒绝路径遍历;可读/可写的文件必须匹配 allowed-extensions。
| 动作 |
请求体 |
read_file |
{ "path": "foo.yml" } |
write_file |
{ "path": "foo.yml", "content": "...", "reload": false } |
list_files |
{ "path": "subdir" }(路径可选) |
delete_file |
{ "path": "foo.yml" } |
mkdir |
{ "path": "new/subdir" } |
move_file |
{ "from": "a.yml", "to": "b.yml", "overwrite": false } |
stat_file |
{ "path": "foo.yml", "hash": true }(hash 可选) |
命令操作
| 动作 |
请求体 |
run_command |
{ "command": "say hello" } |
run_commands |
{ "commands": ["save-all", "tps"] } |
reload |
{} — 分发配置的重载命令 |
服务器信息探测
| 动作 |
返回内容 |
server_info |
版本、MOTD、TPS、视距/模拟距离、内存、端口/IP |
players |
在线玩家信息,包括 UUID、游戏模式、生命值、饥饿值、等级、延迟、世界、位置 |
plugins |
已安装的插件,包括版本、启用状态、作者 |
worlds |
各世界的游戏时间、天气、难度、PVP、种子、出生点、区块数量 |
玩家操作
| 动作 |
请求体 |
broadcast |
{ "message": "server restarting in 5m" } |
message |
{ "player": "Notch", "message": "hi" } |
kick |
{ "player": "Notch", "reason": "afk" }(原因可选) |
teleport |
{ "player": "Notch", "x": 0, "y": 100, "z": 0, "world": "world" }(世界/yaw/pitch 可选) |
日志
| 动作 |
请求体 |
tail_log |
{ "lines": 200 } — 读取 server/logs/latest.log(最多 2000 行) |
示例
TOKEN="paste-from-config.yml"
# 服务器元数据
curl -s http://127.0.0.1:8080/api/info \
-H "Authorization: Bearer $TOKEN" | jq
# 实时 TPS、内存、MOTD、视距…
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"server_info"}' | jq
# 广播消息
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"broadcast","message":"hello from curl"}'
# 传送玩家
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"teleport","player":"Notch","x":0,"y":100,"z":0}'
# 查看最后 50 行日志
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"tail_log","lines":50}' | jq
Web 控制台
在浏览器中访问 http://<host>:<port>/。粘贴 Bearer Token 即可解锁。控制台包含带有快速预设的命令面板,以及针对目标插件文件夹范围的文件浏览器/编辑器。
安全须知
- 除非你清楚自己在做什么,否则请绑定到
127.0.0.1。若需将监听端口暴露至外部网络,请将其置于带有 TLS 的反向代理之后。
- Bearer Token 是唯一的认证方式。请在
config.yml 中轮换该 Token,并运行 /devapi reload 命令使其生效。
- 文件操作被沙盒限制在配置的目标文件夹及扩展名白名单内。
tail_log 是唯一例外——它仅读取服务器的 logs/latest.log 文件。
- 命令以控制台发送者的身份执行,因此拥有全部权限。请将 Token 视为根凭据妥善保管。
DevelopmentAPI
A Paper plugin that exposes a small HTTP/JSON API so you can drive your
Minecraft server from external tooling: inspect the server, manage
online players, tail the log, and read/write config files in a
sandboxed folder. Ships with a web console at /.
Setup
-
Drop DevelopmentAPI-1.0.0.jar into your server's plugins/ folder
and start the server.
-
Open plugins/DevelopmentAPI/config.yml. On first launch a random
bearer token is generated and written into it — copy that value.
-
Every HTTP request must include the header:
Authorization: Bearer <token>
Configuration
plugins/DevelopmentAPI/config.yml:
server:
host: "127.0.0.1" # bind address; 0.0.0.0 to expose externally
port: 8080
token: "" # leave blank on first launch — one is generated
security:
target-plugin-folder: "Development"
allowed-extensions:
- yml
- yaml
- json
- txt
commands:
reload: "develop reload"
Reload the config from in-game with /devapi reload.
In-game commands
| Command |
Description |
/devapi status |
Show listener state |
/devapi reload |
Reload config.yml and restart listener |
/devapi token |
Print current bearer token (op-only) |
HTTP endpoints
All endpoints require Authorization: Bearer <token>.
| Method |
Path |
Description |
| GET |
/api/health |
Liveness probe |
| GET |
/api/info |
Plugin version, target folder, action list |
| POST |
/api/action |
Dispatch a JSON action (see below) |
| GET |
/ |
Web console UI |
POST /api/action takes a JSON object with an "action" field. All
responses are JSON with "ok": true|false and either the action-
specific payload or an "error" string.
File actions
Paths are relative to the configured target-plugin-folder (default
plugins/Development/). Path traversal is rejected; readable/writable
files must match allowed-extensions.
| Action |
Body |
read_file |
{ "path": "foo.yml" } |
write_file |
{ "path": "foo.yml", "content": "...", "reload": false } |
list_files |
{ "path": "subdir" } (path optional) |
delete_file |
{ "path": "foo.yml" } |
mkdir |
{ "path": "new/subdir" } |
move_file |
{ "from": "a.yml", "to": "b.yml", "overwrite": false } |
stat_file |
{ "path": "foo.yml", "hash": true } (hash optional) |
Command actions
| Action |
Body |
run_command |
{ "command": "say hello" } |
run_commands |
{ "commands": ["save-all", "tps"] } |
reload |
{} — dispatches the configured reload command |
Server introspection
| Action |
Returns |
server_info |
version, MOTD, TPS, view/sim distance, memory, port/ip |
players |
online players with UUID, gamemode, health, food, level, ping, world, location |
plugins |
installed plugins with version, enabled state, authors |
worlds |
per-world time, weather, difficulty, PVP, seed, spawn, chunks |
Player actions
| Action |
Body |
broadcast |
{ "message": "server restarting in 5m" } |
message |
{ "player": "Notch", "message": "hi" } |
kick |
{ "player": "Notch", "reason": "afk" } (reason optional) |
teleport |
{ "player": "Notch", "x": 0, "y": 100, "z": 0, "world": "world" } (world/yaw/pitch optional) |
Log
| Action |
Body |
tail_log |
{ "lines": 200 } — reads server/logs/latest.log (max 2000 lines) |
Examples
TOKEN="paste-from-config.yml"
# Server metadata
curl -s http://127.0.0.1:8080/api/info \
-H "Authorization: Bearer $TOKEN" | jq
# Live TPS, memory, MOTD, view distance…
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"server_info"}' | jq
# Broadcast a message
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"broadcast","message":"hello from curl"}'
# Teleport a player
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"teleport","player":"Notch","x":0,"y":100,"z":0}'
# Tail the last 50 log lines
curl -s -X POST http://127.0.0.1:8080/api/action \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"tail_log","lines":50}' | jq
Web console
Visit http://<host>:<port>/ in a browser. Paste the bearer token to
unlock. The console has a command panel with quick presets and a file
browser/editor scoped to the target plugin folder.
Security notes
- Bind to
127.0.0.1 unless you know what you're doing. If you expose
the listener externally, put it behind a reverse proxy with TLS.
- The bearer token is the only auth. Rotate it in
config.yml and
run /devapi reload.
- File operations are sandboxed to the configured target folder and an
extension allowlist.
tail_log is the one exception — it reads the
server's logs/latest.log and only that.
- Commands are dispatched as the console sender, so they run with full
permissions. Treat the token like a root credential.
评论 0
登录后参与评分
还没有评论,来抢沙发吧