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 版本——请安装与你的服务器匹配的版本。
安装
- 从此页面或 GitHub Releases 下载最新的
mcrestapi-x.x.x.jar
- 将 JAR 文件放入 Fabric 服务器的
mods/ 文件夹中
- 启动服务器
- 首次启动时,模组会在
config/mcrestapi.json 生成配置文件,并在服务器控制台中打印主密钥和默认 API 密钥。请立即保存这两个密钥——之后无法再检索它们。
- API 默认在
http://localhost:8080 可用
- 管理仪表板位于
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 且受强制执行身份验证的可信反向代理后面时,才禁用身份验证
MCRestAPI
A Fabric mod that exposes a REST API and real-time event stream (SSE) for monitoring and controlling dedicated Minecraft servers. Built on top of the JDK's built-in HTTP server with zero external dependencies. Available for Minecraft 1.21.11 and 26.1+ — download the file that matches your version.
Features
- REST API for server monitoring (TPS, MSPT, memory, CPU, player count, server properties)
- Real-time Server-Sent Events (SSE) stream for chat, joins, leaves, deaths and game messages
- Complete player data: health, food, position, dimension, ping, gamemode, OP status, skin head URL
- World data: seed, time, weather, difficulty, entity count, loaded chunks, per-dimension stats
- Remote command execution via API
- Built-in admin dashboard (single-page web app) for monitoring and management
- Bundled Swagger UI with OpenAPI 3.1.0 specification
- Multi-key authentication with granular permissions
- Master key for administrative operations
- CORS configuration with per-origin allowlist
- API keys hashed with PBKDF2-SHA256 (never stored in plain text)
- Zero external dependencies (uses JDK built-in HTTP server)
- Virtual threads for lightweight concurrency
- Server-side only (does not run on clients)
Requirements
| Component |
1.21.11 line |
26.1 line |
| Minecraft |
1.21.11 |
26.1.x |
| Java |
>= 21 |
>= 25 |
| Fabric Loader |
>= 0.18.4 |
>= 0.19.3 |
| Fabric API |
any |
any |
Each release on Modrinth is tagged with its supported Minecraft version — install the one matching your server.
Installation
- Download the latest
mcrestapi-x.x.x.jar from this page or from GitHub Releases
- Place the JAR file in the
mods/ folder of your Fabric server
- Start the server
- On first launch, the mod generates a config file at
config/mcrestapi.json and prints the master key and default API key to the server console. Save both keys immediately -- they cannot be retrieved later.
- The API is available at
http://localhost:8080 by default
- The admin dashboard is at
http://localhost:8080/admin
Configuration
The configuration file is located at config/mcrestapi.json and is generated automatically on first launch.
| Field |
Type |
Default |
Description |
port |
integer |
8080 |
Port the HTTP server listens on |
bindAddress |
string |
127.0.0.1 |
Address to bind to. Use 0.0.0.0 for all interfaces |
maxConnections |
integer |
50 |
Maximum concurrent HTTP connections |
swagger |
boolean |
true |
Enable/disable Swagger UI and OpenAPI spec |
masterKeyHash |
string |
(generated) |
PBKDF2 hash of the master key |
auth |
object |
(enabled) |
Set auth.enabled to false to delegate auth to a reverse proxy |
keys |
array |
(generated) |
List of API keys with permissions |
cors |
object |
(disabled) |
CORS configuration |
API key hashes are stored using PBKDF2-SHA256. The raw key values are only shown once at creation time.
Authentication
All API endpoints (except public ones) require a Bearer token in the Authorization header:
Authorization: Bearer mcsapi_xxxxxxxxxxxxxxxx
The master key is generated on first launch and grants access to admin endpoints (/api/admin/*) and the dashboard (/admin). It also has wildcard permissions for all data endpoints.
Disabling authentication
If a reverse proxy already handles auth (basic auth, OIDC/forward-auth, etc.), set auth.enabled to false in the config:
{ "auth": { "enabled": false } }
This disables all authentication, including the admin endpoints — the reverse proxy becomes the only trust boundary. Only do this when bound to 127.0.0.1 behind a proxy that enforces access control. The mod logs a warning on startup (louder if the bind address is not loopback). You can also toggle it live from the dashboard (Settings → Require API Key), no restart required.
Permissions
| Permission |
Description |
Endpoints |
server.read |
Read server stats |
GET /api/server |
players.read |
Read player list |
GET /api/players |
world.read |
Read world data |
GET /api/world |
chat.read |
Read event history |
GET /api/chat |
chat.stream |
Connect to SSE event stream |
GET /api/events/stream |
command.execute |
Execute server commands |
POST /api/command |
* |
All permissions (wildcard) |
All endpoints |
API Endpoints
Base URL: http://<host>:<port> (default: http://localhost:8080)
For detailed request/response examples, see the built-in Swagger UI at /api/docs.
Public (no auth required)
| Method |
Path |
Description |
| GET |
/api/server/icon |
Server icon as PNG image |
| GET |
/api/docs |
Swagger UI |
| GET |
/api/openapi.json |
OpenAPI 3.1.0 spec |
Data Endpoints
| Method |
Path |
Permission |
Description |
| GET |
/api/server |
server.read |
Server stats (TPS, MSPT, memory, CPU). Supports ?fields= filtering |
| GET |
/api/players |
players.read |
Online player list with health, position, dimension, ping |
| GET |
/api/world |
world.read |
Global world data and per-dimension stats. Supports ?fields= filtering |
| GET |
/api/chat |
chat.read |
Event history. Supports ?limit= and ?type= filtering |
| GET |
/api/events/stream |
chat.stream |
Real-time SSE stream. Supports ?types= filtering |
| POST |
/api/command |
command.execute |
Execute a server command |
Admin Endpoints (master key required)
| Method |
Path |
Description |
| GET |
/api/admin/keys |
List all API keys |
| POST |
/api/admin/keys |
Create a new API key |
| PUT |
/api/admin/keys?id= |
Update an API key |
| DELETE |
/api/admin/keys?id= |
Revoke an API key |
| GET |
/api/admin/cors |
Get CORS configuration |
| POST |
/api/admin/cors |
Add an allowed origin |
| PUT |
/api/admin/cors |
Toggle CORS enabled/disabled |
| DELETE |
/api/admin/cors |
Remove an allowed origin |
| GET |
/api/admin/settings |
Get current settings |
| PUT |
/api/admin/settings |
Update settings |
SSE Event Stream
Connect to /api/events/stream for real-time server events. Events are sent in standard SSE format. A keepalive ping is sent every 30 seconds.
Event types: chat, command, join, leave, death, game
For browser-based SSE connections, pass the API key via ?auth= query parameter since EventSource does not support custom headers.
CORS
CORS is disabled by default. When enabled, only origins in the allowlist receive CORS headers. Configure via the admin dashboard or /api/admin/cors endpoints.
CORS only provides protection in the browser context. It does not replace API key authentication.
Admin Dashboard
Built-in web dashboard at /admin (requires master key).
Pages: Dashboard (server stats), Players, World, Chat (live SSE stream), Console (command execution), Keys, CORS, Settings.
Security
- Default bind address is
127.0.0.1 (localhost only)
- API keys hashed with PBKDF2-SHA256 with random salt
- Master key stored separately from API keys
- For remote access, use a reverse proxy (nginx, Caddy) with HTTPS/TLS
- Create API keys with minimal permissions needed for each use case
- Only disable authentication when bound to
127.0.0.1 behind a trusted reverse proxy that enforces auth
评论 0
登录后参与评分
还没有评论,来抢沙发吧