Dev API

插件

· 作者 everett2323

一个轻量级的 Paper 插件,提供受令牌保护的 HTTP/JSON API,以便通过外部工具操控你的 Minecraft 服务器。可查看服务器状态(TPS、玩家、世界、插件)、管理玩家(广播、消息、踢出、传送)、追踪……

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

最新 1.0.0 · 1.21.11 · Paper

一键开服(送7天)

DevelopmentAPI

一个 Paper 插件,提供小型 HTTP/JSON API,让你能够通过外部工具驱动 Minecraft 服务器:检查服务器状态、管理在线玩家、查看日志,以及在沙盒文件夹中读写配置文件。附带 / 路径下的 Web 控制台界面。


安装设置

  1. 将 DevelopmentAPI-1.0.0.jar 放入服务器的 plugins/ 文件夹并启动服务器。

  2. 打开 plugins/DevelopmentAPI/config.yml。首次启动时会生成一个随机 Bearer Token 并写入该文件——复制该值。

  3. 每个 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 视为根凭据妥善保管。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源