MCRestAPI

模组

· 作者 Natxo

用于 Minecraft 专用服务器的 REST API 和管理面板。监控 TPS、内存、玩家数量、世界数据,执行命令并通过 SSE 流式传输实时事件。零外部依赖。

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

需要前置:Fabric API

最新 2.0.0+26.1.2 · 26.1.2 · Fabric

一键开服(送7天)

MCRestAPI

一个 Fabric 模组,为监控和控制专用 Minecraft 服务器提供 REST API 和实时事件流(SSE)。基于 JDK 内置 HTTP 服务器构建,零外部依赖。适用于 Minecraft 1.21.11 和 26.1+ ——请下载与你的版本匹配的文件。


功能特性

  • 用于服务器监控的 REST API(TPS、MSPT、内存、CPU、玩家数量、服务器属性)
  • 用于聊天、加入、离开、死亡和游戏消息的实时服务器发送事件(SSE)流
  • 完整的玩家数据:生命值、饥饿值、位置、维度、延迟、游戏模式、OP 状态、皮肤头像 URL
  • 世界数据:种子、时间、天气、难度、实体数量、已加载区块、各维度统计信息
  • 通过 API 远程执行命令
  • 内置管理仪表板(单页 Web 应用),用于监控和管理
  • 捆绑带有 OpenAPI 3.1.0 规范的 Swagger UI
  • 支持多密钥认证及细粒度权限控制
  • 主密钥用于管理操作
  • CORS 配置,支持按来源白名单设置
  • API 密钥使用 PBKDF2-SHA256 进行哈希处理(绝不以明文存储)
  • 零外部依赖(使用 JDK 内置 HTTP 服务器)
  • 虚拟线程实现轻量级并发
  • 仅服务端运行(不在客户端上运行)

要求

组件 1.21.11 版本线 26.1 版本线
Minecraft 1.21.11 26.1.x
Java >= 21 >= 25
Fabric Loader >= 0.18.4 >= 0.19.3
Fabric API 任意 任意

Modrinth 上的每个发布版本都标记了其支持的 Minecraft 版本——请安装与你的服务器匹配的版本。


安装

  1. 从此页面或 GitHub Releases 下载最新的 mcrestapi-x.x.x.jar
  2. 将 JAR 文件放入 Fabric 服务器的 mods/ 文件夹中
  3. 启动服务器
  4. 首次启动时,模组会在 config/mcrestapi.json 生成配置文件,并在服务器控制台中打印主密钥和默认 API 密钥。请立即保存这两个密钥——之后无法再检索它们。
  5. API 默认在 http://localhost:8080 可用
  6. 管理仪表板位于 http://localhost:8080/admin

配置

配置文件位于 config/mcrestapi.json,并在首次启动时自动生成。

字段 类型 默认值 描述
port integer 8080 HTTP 服务器监听的端口
bindAddress string 127.0.0.1 绑定的地址。使用 0.0.0.0 绑定所有接口
maxConnections integer 50 最大并发 HTTP 连接数
swagger boolean true 启用/禁用 Swagger UI 和 OpenAPI 规范
masterKeyHash string (自动生成) 主密钥的 PBKDF2 哈希值
auth object (已启用) 将 auth.enabled 设置为 false 可将认证委托给反向代理
keys array (自动生成) 具有权限的 API 密钥列表
cors object (已禁用) CORS 配置

API 密钥哈希使用 PBKDF2-SHA256 存储。原始密钥值仅在创建时显示一次。


认证

所有 API 端点(除公开端点外)均需要在 Authorization 头中包含 Bearer 令牌:

Authorization: Bearer mcsapi_xxxxxxxxxxxxxxxx

主密钥在首次启动时生成,授予对管理端点(/api/admin/*)和仪表板(/admin)的访问权限。它还对所有数据端点拥有通配符权限。

禁用认证

如果反向代理已经处理认证(基本认证、OIDC/forward-auth 等),请在配置中将 auth.enabled 设置为 false:

{ "auth": { "enabled": false } }

这将禁用所有认证,包括管理端点——此时反向代理成为唯一的信任边界。仅当绑定到 127.0.0.1 且背后有强制执行访问控制的代理时才这样做。模组在启动时会记录警告(如果绑定地址不是回环地址,则警告更明显)。你也可以从仪表板实时切换此选项(设置 → 需要 API 密钥),无需重启。

权限

权限 描述 端点
server.read 读取服务器统计数据 GET /api/server
players.read 读取玩家列表 GET /api/players
world.read 读取世界数据 GET /api/world
chat.read 读取事件历史记录 GET /api/chat
chat.stream 连接到 SSE 事件流 GET /api/events/stream
command.execute 执行服务器命令 POST /api/command
* 所有权限(通配符) 所有端点

API 端点

基础 URL:http://<host>:<port>(默认:http://localhost:8080)

有关详细的请求/响应示例,请参阅内置 Swagger UI 中的 /api/docs。

公开(无需认证)

方法 路径 描述
GET /api/server/icon 作为 PNG 图像的服务器图标
GET /api/docs Swagger UI
GET /api/openapi.json OpenAPI 3.1.0 规范

数据端点

方法 路径 权限 描述
GET /api/server server.read 服务器统计信息(TPS、MSPT、内存、CPU)。支持 ?fields= 过滤
GET /api/players players.read 在线玩家列表,包含生命值、位置、维度、延迟
GET /api/world world.read 全局世界数据及各维度统计。支持 ?fields= 过滤
GET /api/chat chat.read 事件历史记录。支持 ?limit= 和 ?type= 过滤
GET /api/events/stream chat.stream 实时 SSE 流。支持 ?types= 过滤
POST /api/command command.execute 执行服务器命令

管理员端点(需要主密钥)

方法 路径 描述
GET /api/admin/keys 列出所有 API 密钥
POST /api/admin/keys 创建新的 API 密钥
PUT /api/admin/keys?id= 更新 API 密钥
DELETE /api/admin/keys?id= 撤销 API 密钥
GET /api/admin/cors 获取 CORS 配置
POST /api/admin/cors 添加允许的源
PUT /api/admin/cors 启用或禁用 CORS
DELETE /api/admin/cors 移除允许的源
GET /api/admin/settings 获取当前设置
PUT /api/admin/settings 更新设置

SSE 事件流

连接到 /api/events/stream 以获取实时服务器事件。事件以标准 SSE 格式发送。每 30 秒发送一次保活 ping。

事件类型: chat、command、join、leave、death、game

对于基于浏览器的 SSE 连接,请通过 ?auth= 查询参数传递 API 密钥,因为 EventSource 不支持自定义头部。


CORS

CORS 默认处于禁用状态。启用后,仅允许列表中的源会接收 CORS 头。可通过管理面板或 /api/admin/cors 端点进行配置。

CORS 仅在浏览器上下文中提供保护。它不能替代 API 密钥身份验证。


管理面板

内置 Web 管理面板位于 /admin(需要主密钥)。

页面: 仪表盘(服务器统计)、玩家、世界、聊天(实时 SSE 流)、控制台(命令执行)、密钥、CORS、设置。


安全性

  • 默认绑定地址为 127.0.0.1(仅限本地主机)
  • API 密钥使用带随机盐的 PBKDF2-SHA256 进行哈希处理
  • 主密钥与 API 密钥分开存储
  • 如需远程访问,请使用带有 HTTPS/TLS 的反向代理(nginx、Caddy)
  • 为每个用例创建具有所需最小权限的 API 密钥
  • 仅在绑定到 127.0.0.1 且受强制执行身份验证的可信反向代理后面时,才禁用身份验证

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源