1.1.1 官方原生管理接口与第三方方案对比#

MSMP 在安全性、实时性、功能完整性三个维度均实现了对传统协议的全面超越。特别是在双向通信和实时通知方面，MSMP 的 WebSocket 基础架构提供了原生支持，而 RCON 和 Query 作为早期设计的协议，其单向通信模式从根本上限制了实时管理能力。第三方 REST API 方案虽然可以通过 Webhook 或长轮询模拟实时效果，但实现复杂度高且可靠性差 。

1.1.2 基于 WebSocket + JSON-RPC 2.0 的双向通信架构#

MSMP 的通信架构由三个层次构成：传输层的 WebSocket 连接、消息格式的 JSON-RPC 2.0 封装，以及应用层的命名空间方法调度。WebSocket 连接建立后，客户端与服务端之间维持持久的全双工通道，所有管理操作与事件通知均在此通道上流转。相较于 HTTP 请求-响应模式，WebSocket 的长连接特性消除了频繁的 TCP 握手开销，将通信延迟降至最低；同时，服务端推送能力使得状态变更能够实时触达客户端，无需客户端主动轮询。

JSON-RPC 2.0 作为应用层协议，定义了两种消息类型：请求（Request）与通知（Notification）。请求消息包含唯一的 id 字段，服务端必须返回对应的响应（Response），形成完整的调用闭环；通知消息则无 id 字段，服务端不对其进行响应，适用于单向事件上报 。这一区分对于客户端实现至关重要：开发者需为方法调用维护请求-响应映射表（通常以 id 为键），而为通知注册独立的事件处理器。混合处理这两种消息类型是常见的初学者错误，会导致响应匹配失败或通知丢失。

命名空间（Namespace）是 MSMP 方法组织的核心机制。所有标准方法均归属于 minecraft 命名空间，格式为 minecraft:<group>/<action>，如 minecraft:players（获取玩家列表）、minecraft:allowlist/add（添加白名单）。通知事件则采用 minecraft:notification/<event> 格式，如 minecraft:notification/players/joined（玩家加入事件）。这种层级化的命名策略既保证了方法的可发现性，又为未来的功能扩展预留了清晰的路径。

1.1.3 实时状态同步与事件驱动模型#

MSMP 的事件驱动模型是其相较传统方案的核心竞争力。在 RCON 时代，获取玩家加入事件的唯一方式是定期执行 list 命令并比对输出差异——这种轮询模式不仅消耗服务器资源，还存在显著的延迟（取决于轮询间隔）。MSMP 通过 minecraft:notification/players/joined 和 minecraft:notification/players/left 通知，将事件延迟降至网络传输极限（通常 <10ms），且零服务器端轮询开销 。

事件驱动架构对插件开发范式产生了深远影响。以玩家管理插件为例，传统实现需维护定时任务扫描在线状态，而基于 MSMP 的实现则可完全事件化：注册通知处理器后，插件仅在事件触发时执行逻辑，资源占用与响应速度均获得数量级优化。更进一步，MSMP 的通知机制支持服务端状态的增量同步——当游戏规则（Gamerules）变更时，minecraft:notification/game-rules/updated 通知携带变更后的完整规则集，客户端无需重新查询即可更新本地缓存 。

1.2.1 引入版本：25w35a / 1.21.9+#

MSMP 于 2025 年 8 月 26 日随 25w35a 快照首次发布 ，随后在 1.21.9 正式版中稳定化。这一版本节点对于插件开发者具有重要参考价值：任何目标版本低于 1.21.9 的服务端均不支持 MSMP，需在文档中明确标注兼容性要求。值得注意的是，MSMP 的版本演进遵循独立于 Minecraft 主版本的语义化版本控制——rpc.discover 方法返回的 API 版本信息（如 2.0.0 (25w44a)）反映了协议本身的迭代状态，而非底层游戏版本。

开发者在实现客户端库时，应优先调用 rpc.discover 获取服务端支持的 API 版本与方法集合，而非硬编码假设。这一防御性编程策略能够适配未来可能的方法增删或行为变更。例如，mc-rpc Rust 库即基于运行时发现动态生成方法绑定，确保与任意支持 MSMP 的服务端版本兼容。

1.2.2 与 RCON、Query 等传统协议的功能对比#

MSMP、RCON 和 Query 三种协议在功能定位上形成明显的互补关系，而非简单的替代关系。理解它们的差异有助于在不同场景下选择最合适的工具 。

1.2.3 未来扩展性：命名空间预留与自定义扩展机制#

MSMP 的命名空间设计体现了前瞻性的扩展规划。除 minecraft（标准方法）和 notification（标准通知）两个保留命名空间外，协议明确允许第三方通过自定义命名空间添加方法与事件 。这一机制为服务端软件（Fabric、Forge、Paper 等）以及插件框架提供了标准化的扩展通道：Fabric API 可通过 fabric:mods 命名空间暴露模组列表查询，Paper 可通过 paper:timings 命名空间集成性能分析数据，而无需破坏与标准客户端的兼容性。

对于插件开发者，自定义命名空间的采用需遵循以下最佳实践：命名空间应采用反向域名格式（如 com.example.myplugin）以避免冲突；自定义方法应复用标准模式中的类型定义（如 Player、Operator 对象）以保持接口一致性；文档中需明确标注扩展的最低服务端版本与依赖条件。

1.3.1 命名空间（Namespace）：minecraft 与 notification#

命名空间是 MSMP 方法标识符的前缀段，用于逻辑分组与避免命名冲突。标准协议定义了两个保留命名空间：

minecraft 命名空间下的方法路径通常遵循 group/action 或 group/subgroup/action 的层级模式，例如 minecraft:players（获取玩家列表）、minecraft:allowlist/add（添加白名单）、minecraft:server/save（保存服务器）。这种层级设计使方法组织清晰，便于文档化和代码生成 。

minecraft:notification/ 命名空间专用于服务端主动推送的事件通知。通知方法名同样采用层级结构，但语义侧重于状态变更而非操作指令，例如 minecraft:notification/players/joined（玩家加入）、minecraft:notification/players/left（玩家离开）、minecraft:notification/game-rules/updated（游戏规则更新）。通知与方法的命名空间分离，使客户端能够快速区分需要响应的请求和仅需处理的事件 。

1.3.2 方法（Method）与通知（Notification）的区别#

方法与通知的区分是 JSON-RPC 2.0 规范的核心语义，MSMP 严格遵循这一区分。开发者在实现客户端时，需为方法调用维护请求-响应映射表（通常以 id 为键），而为通知注册独立的事件处理器。

1.3.3 API 模式（Schema）与运行时发现机制#

MSMP 提供两种 API 模式获取方式，内容镜像一致但适用场景各异：

模式文件采用 JSON Schema 风格描述，包含方法参数、返回值、通知载荷的结构定义。以 operator 类型为例 ：

1
{
2
  "operator": {
3
    "properties": {
4
      "bypassesPlayerLimit": { "type": "boolean" },
5
      "permissionLevel": { "type": "integer" },
6
      "player": { "$ref": "#/components/schemas/player" }
7
    },
8
    "type": "object"
9
  }
10
}

运行时发现与静态生成的结合，使 MSMP 客户端能够在保证类型安全的同时，具备跨版本的适应能力。

2.1.1 management-server-enabled：启用开关#

此为 MSMP 的总开关。设置为 true 后，服务端在启动时将初始化 WebSocket 服务器，监听配置的地址与端口 。若保持默认 false，则 MSMP 相关代码完全不加载，零运行时开销。生产环境建议仅在需要管理功能时启用，以减少攻击面。

2.1.2 management-server-host：绑定地址（localhost/0.0.0.0）#

绑定地址决定了 WebSocket 服务器的网络可见范围。localhost 或 127.0.0.1 仅允许本机连接，适用于管理工具与服务器同机部署的场景；0.0.0.0 绑定所有网络接口，允许远程连接，但必须配合 TLS 与严格认证以确保安全 。云服务器部署时，建议显式指定内网 IP 而非 0.0.0.0，结合反向代理实现安全暴露。

2.1.3 management-server-port：端口设置（默认随机/静态指定）#

默认值为 0 时，服务端在启动时从操作系统获取可用临时端口，并将实际绑定端口写入日志 。这一设计简化了多实例部署（避免端口冲突），但增加了客户端配置的动态性。静态端口配置（如 25585）适用于需要防火墙规则预设或客户端硬编码的场景。端口选择应避开 Minecraft 游戏端口（默认 25565）及常用服务端口，减少扫描攻击风险。

2.1.4 management-server-secret：40 位字母数字认证密钥#

认证密钥是 MSMP 安全模型的核心。若配置为空，服务端在启动时自动生成 40 位随机字符串，并回写至 server.properties 文件 。自动生成的密钥强度足够，但会导致配置文件变更，需在版本控制中注意忽略或同步。生产环境建议显式配置密钥，便于多节点一致性与密钥轮换管理。

密钥的 40 位长度与字符集限制经过安全考量：总密钥空间为 62^40 ≈ 2.7×10^71，远超暴力破解可行性；字母数字排除易混淆字符（如 O/0、I/l），降低人工抄录错误。客户端提交密钥时，服务端进行严格格式验证，非 40 位字母数字的密钥立即拒绝，返回 401 错误。

2.2.1 management-server-tls-enabled：TLS 开关#

默认 true 体现了**默认安全（Secure by Default）**的设计原则。启用后，WebSocket 端点从 ws:// 升级为 wss://，所有通信内容经 TLS 1.2/1.3 加密，防止中间人攻击与窃听 。

2.2.2 management-server-tls-keystore：PKCS12 证书库路径#

Java 生态的标准 TLS 配置方式，指向 PKCS#12 格式的密钥库文件。密钥库包含服务器证书与私钥，可由 Let’s Encrypt 等 CA 签发，或自签名生成 。

2.2.3 management-server-tls-keystore-password：密钥库密码（多来源优先级）#

密钥库访问密码的配置需考虑安全性与便利性的平衡。Java 支持三层密码来源优先级，从高到低：

生产环境强烈建议采用环境变量注入，避免密码泄露于配置文件或版本控制 。

2.2.4 自签名证书生成与浏览器信任配置#

开发测试场景下，自签名证书是便捷选择。使用 OpenSSL 生成：

1
# 生成私钥与证书
2
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
3
  -sha256 -days 365 -nodes -subj "/CN=localhost" \
4
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
5

6
# 转换为 PKCS12
7
openssl pkcs12 -export -out minecraft.p12 -inkey key.pem -in cert.pem \
8
  -name minecraft -password pass:changeit

浏览器环境连接自签名 WSS 端点时，需先将证书导入系统信任库，或访问 https://localhost:<port> 手动确认例外（WebSocket 无法直接处理证书警告）。Node.js 等环境可通过 NODE_TLS_REJECT_UNAUTHORIZED=0 临时禁用验证（仅限开发使用）。

2.3.1 management-server-allowed-origins：浏览器 WebSocket 来源白名单#

allowed-origins 是 MSMP 针对浏览器环境的安全强化机制。WebSocket 连接建立时，浏览器自动附加 Origin HTTP 头，服务端验证该值是否在白名单内 。验证失败时，立即返回 HTTP 401 Unauthorized，终止连接。

这一机制有效防御了跨站 WebSocket 劫持（CSWSH）攻击：即使攻击者获取了有效密钥，若其网页来源不在白名单，浏览器将阻止 WebSocket 连接建立。配置时需注意：Origin 值包含协议与端口（如 https://admin.example.com:8443），白名单条目需精确匹配。

2.3.2 Origin 验证失败时的 401 响应行为#

来源验证失败与认证密钥失败的响应码均为 401，但日志中应区分具体原因以便排查。典型的错误响应结构：

1
HTTP/1.1 401 Unauthorized
2
Content-Type: text/plain
3

4
Origin not allowed: https://evil.com

或

1
HTTP/1.1 401 Unauthorized
2
Content-Type: text/plain
3

4
Invalid or missing authentication

生产环境建议启用详细日志记录，监控异常来源的访问尝试，作为安全态势感知的数据源。

2.4.1 成功启动标志：Starting json RPC server on ...#

服务端成功初始化 MSMP 时，日志输出关键信息：

1
[Server thread/INFO]: Starting json RPC server on localhost/127.0.0.1:25585
2
[Server thread/INFO]: Json-RPC Management connection listening on localhost/127.0.0.1:25585

首行确认绑定地址与端口，第二行确认服务器已进入监听状态。若端口配置为 0，此处显示实际分配的动态端口。两行日志的线程标识均为 Server thread，表明 MSMP 与主游戏服务器共享线程——MSMP 处理函数应避免阻塞操作，以免影响游戏 tick 。

2.4.2 绑定失败处理与端口冲突排查#

端口冲突排查命令（Linux）：

1
sudo ss -tlnp | grep :8080  # 查看占用端口的进程
2
sudo lsof -i :8080          # 替代命令

2.4.3 防火墙与云服务器安全组配置#

云服务器（AWS、Azure、阿里云等）需在安全组/网络 ACL 中显式放行 MSMP 端口。建议限制源 IP 范围至管理节点，而非 0.0.0.0/0，形成纵深防御 。

3.1.1 非 TLS 端点：ws://<host>:<port>#

开发测试环境的默认连接方式。URL 格式示例：

1
ws://localhost:25585
2
ws://192.168.1.100:8080

非 TLS 连接的所有内容（包括认证密钥）以明文传输，仅适用于可信网络环境。生产环境公网暴露必须启用 TLS 。

3.1.2 TLS 端点：wss://<host>:<port>#

生产环境的标准连接方式。URL 格式示例：

1
wss://mc.example.com:8443
2
wss://10.0.0.5:25585

TLS 握手在 TCP 连接建立后立即开始，客户端验证服务端证书的可信性。证书验证失败（自签名、过期、主机名不匹配）会导致连接终止，错误信息因客户端而异 。

3.2.1 Authorization 请求头：Bearer <40位密钥>#

标准 HTTP 认证头格式，适用于非浏览器客户端（服务器端应用、命令行工具、桌面程序）：

1
// Node.js 示例
2
const ws = new WebSocket('ws://localhost:25585', {
3
  headers: {
4
    'Authorization': 'Bearer AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd'
5
  }
6
});

1
# Python websockets 示例
2
import websockets
3

4
async with websockets.connect(
5
    'ws://localhost:25585',
6
    extra_headers={'Authorization': 'Bearer ' + SECRET}
7
):
8
    ...

3.2.2 Sec-WebSocket-Protocol 请求头：minecraft-v1,<40位密钥>#

专门为浏览器 WebSocket API 设计的认证方式。浏览器 WebSocket 构造函数不支持自定义请求头，但原生支持 protocols 参数，该参数值会编码为 Sec-WebSocket-Protocol 头发送 ：

1
// 浏览器原生 WebSocket API
2
const ws = new WebSocket(
3
  'wss://mc.example.com:8443',
4
  ['minecraft-v1', 'AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd']
5
);

Sec-WebSocket-Protocol 头的标准格式为逗号分隔的子协议列表，MSMP 约定首项为固定字符串 minecraft-v1，第二项为认证密钥。服务端解析时验证这一结构，提取密钥进行认证。

3.2.3 浏览器环境强制使用 Sec-WebSocket-Protocol 的原因#

浏览器安全模型（CORS、CSP）严格限制 WebSocket 连接的可控性，禁止脚本设置任意 HTTP 头，以防止请求伪造攻击。Sec-WebSocket-Protocol 是少数可由 JavaScript 控制的头部之一，因其属于 WebSocket 标准协议的有机组成部分。MSMP 的这一设计妥协，确保了纯浏览器端管理面板（如基于 React/Vue 的 Web UI）的可行性，无需后端代理即可直接连接服务端 。

3.3.1 HTTP 401 Unauthorized 响应#

认证失败时，WebSocket 握手阶段即返回 HTTP 401，连接未升级即终止。客户端表现为 WebSocket 构造抛出错误或连接事件触发失败。错误响应体包含具体原因，但浏览器端因安全限制通常无法读取，需服务端日志配合排查 。

常见 401 原因：

• 完全缺失认证头
• Authorization 头格式错误（非 Bearer <token>）
• Sec-WebSocket-Protocol 头格式错误（缺少 minecraft-v1 或令牌）
• 令牌与 management-server-secret 不匹配
• 浏览器客户端的来源不在 allowed-origins 中

3.3.2 密钥格式验证：严格 40 位字母数字#

服务端对密钥进行两层验证：长度严格等于 40 字符，字符集限定于 [A-Za-z0-9]。任何偏离均立即 401 拒绝，不进入后续处理。这一严格验证防止了编码错误、截断密钥等常见配置问题的安全降级。

3.4.1 命令行工具：websocat 连接演示#

websocat 是功能强大的命令行 WebSocket 工具，适用于快速测试与脚本集成 ：

1
# 无认证尝试（预期失败）
2
$ websocat ws://localhost:40745
3
websocat: WebSocketError: Received unexpected status code (401 Unauthorized)
4

5
# 正确认证连接
6
$ websocat ws://localhost:40745 -H 'Authorization: Bearer n2pQcIG1OQ92jot2xG1M0aw0ZWnrh4F3Z3jw8qRP'
7
{"jsonrpc":"2.0","method":"server/status","id":0}
8
{"jsonrpc":"2.0","id":0,"result":{"started":true,"version":{"name":"25w37a","protocol":1073742092}}}
9

10
# TLS 连接（自签名证书）
11
$ websocat wss://localhost:40745 -H 'Authorization: Bearer ...' --insecure
12
# 或指定 CA 证书
13
$ websocat wss://localhost:40745 -H 'Authorization: Bearer ...' --ca-file cert.pem

3.4.2 Node.js 客户端：mc-server-management 库用法#

Aternos 团队维护的 mc-server-management 是目前最成熟的 Node.js 客户端库，提供高层 API 封装 ：

1
const { Server } = require('mc-server-management');
2

3
const server = new Server('ws://localhost:25585', {
4
  secret: 'AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd'
5
});
6

7
// 获取操作员列表包装器
8
const ops = server.operatorList();
9

10
// 异步获取所有操作员（自动缓存，通过通知更新）
11
const operators = await ops.get();
12
console.log(operators);
13

14
// 添加操作员（多种参数形式）
15
await ops.add('Notch');                          // 名称，默认等级
16
await ops.add('jeb_', 4, true);                  // 名称、等级4、绕过限制
17
await ops.add(Player.withId('uuid-here'), 2);    // UUID 对象
18

19
// 批量操作
20
await ops.add(['player1', 'player2'], 3, true);
21
await ops.remove(['player1', 'player2']);
22

23
// 设置完整列表（原子替换）
24
await ops.set([
25
  new Operator('Notch', 4, true),
26
  'jeb_',  // 使用默认参数
27
  Player.withId('uuid')
28
], 3, true);
29

30
// 清空列表
31
await ops.clear();

该库的核心价值在于：自动处理连接管理、请求序列化、响应解析；基于通知实现本地缓存的增量更新；提供类型友好的批量操作接口。

3.4.3 浏览器原生 WebSocket API 连接#

1
<!DOCTYPE html>
2
<html>
3
<head>
4
  <title>MSMP 管理面板</title>
5
</head>
6
<body>
7
  <pre id="output"></pre>
8
  <script>
9
    const SECRET = 'AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd';
10
    const ws = new WebSocket(
11
      'ws://localhost:25585',
12
      ['minecraft-v1', SECRET]
13
    );
14

15
    ws.onopen = () => {
16
      log('Connected');
17
      // 获取玩家列表
18
      send({ jsonrpc: '2.0', method: 'minecraft:players', id: 1 });
19
    };
20

21
    ws.onmessage = (event) => {
22
      const msg = JSON.parse(event.data);
23
      log('Received: ' + JSON.stringify(msg, null, 2));
24
    };
25

26
    ws.onerror = (err) => log('Error: ' + err);
27
    ws.onclose = () => log('Disconnected');
28

29
    function send(msg) {
30
      ws.send(JSON.stringify(msg));
31
    }
32
    function log(text) {
33
      document.getElementById('output').textContent += text + '\n';
34
    }
35
  </script>
36
</body>
37
</html>

浏览器示例展示了 Sec-WebSocket-Protocol 认证、消息收发、事件处理的基础模式。生产环境应添加重连逻辑、错误提示、UI 状态管理等增强功能。

4.1.1 必需字段：jsonrpc、method、id#

id 字段的选型建议：数字递增简单高效；字符串 UUID 避免冲突；null 仅用于通知（但通知应省略 id 而非设为 null）。客户端应确保同一连接内 id 的唯一性，通常采用单调递增计数器。

4.1.2 参数传递：params 数组包裹约定#

MSMP 的方法参数统一采用数组包裹，即使单参数也置于数组内 ：

1
// ✅ 正确：单参数数组包裹
2
{"method":"minecraft:allowlist/add","id":1,"params":[[{"name":"jeb_"}]]}
3

4
// ❌ 错误：直接传递对象
5
{"method":"minecraft:allowlist/add","id":1,"params":{"name":"jeb_"}}

这一设计源于 JSON-RPC 2.0 的 params 可为数组或对象的灵活性，MSMP 统一为数组以简化服务端解析逻辑。双层数组 [[...]] 在批量操作场景中出现：外层数组为参数列表（本方法仅一个参数），内层数组为批量元素数组。

4.1.3 命名空间方法完整格式：minecraft:<group>/<action>#

方法字符串的解析规则：以冒号分隔命名空间与路径，路径中以斜杠分隔功能组与操作。当前版本的标准功能组包括：

4.2.1 成功响应：result 字段结构#

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": [
5
    {"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"}
6
  ]
7
}

成功响应保留请求的 id，result 字段内容为方法特定的返回值。数组、对象、标量均可能，具体以 rpc.discover 模式或本文档方法章节为准。

4.2.2 错误响应：error 对象（code、message、data）#

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "error": {
5
    "code": -32601,
6
    "message": "Method not found",
7
    "data": "Method not found: minecraft:foo/bar"
8
  }
9
}

4.3.1 -32601 Method not found：方法不存在#

-32601 是 JSON-RPC 2.0 标准错误码，表示请求的方法未被服务端识别 。MSMP 场景下的典型原因：

• 命名空间拼写错误（如 minecraft:player 而非 minecraft:players）
• 服务端版本不支持该方法（如旧版本无 server-settings 组）
• 方法尚未实现（自定义命名空间的预期行为）

客户端应将此错误视为致命或降级信号：致命意味着服务端版本不兼容，需升级或切换方法；降级意味着功能不可用，可提示用户或禁用相关 UI。

4.3.2 JSON-RPC 2.0 规范错误码全集#

MSMP 可能扩展 -32000 范围的错误码表示特定领域错误（如玩家不存在、权限不足），客户端应预留处理未知错误码的弹性。

4.4.1 服务端主动推送特征：无 id 字段#

1
{
2
  "jsonrpc": "2.0",
3
  "method": "minecraft:notification/players/joined",
4
  "params": [{"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"}]
5
}

通知消息的关键识别特征：id 字段完全缺失（非 null），method 字段以 notification: 开头。客户端解析时应优先检查 id 存在性，区分响应与通知的处理路径。

4.4.2 通知命名空间：notification:<event>#

通知的 params 载荷结构与对应查询方法的返回元素一致，便于客户端复用解析逻辑。

5.1.1 rpc.discover：动态获取服务端支持的方法与通知#

rpc.discover 是 MSMP 的元方法，无需认证即可调用（或作为首个验证连接的探针），返回当前服务端完整的 API 能力描述 ：

1
// 请求
2
{"jsonrpc":"2.0","method":"rpc.discover","id":1}
3

4
// 响应（结构示意）
5
{
6
  "jsonrpc": "2.0",
7
  "id": 1,
8
  "result": {
9
    "jsonrpc": "2.0",
10
    "info": {
11
      "title": "Minecraft Server JSON-RPC",
12
      "version": "2.0.0 (25w44a)"
13
    },
14
    "methods": [
15
      {
16
        "name": "minecraft:players",
17
        "params": [],
18
        "result": {"$ref": "#/components/schemas/PlayerArray"}
19
      }
20
      // ... 更多方法
21
    ],
22
    "notifications": [
23
      {
24
        "name": "notification:players/joined",
25
        "params": [{"$ref": "#/components/schemas/Player"}]
26
      }
27
      // ... 更多通知
28
    ],
29
    "components": {
30
      "schemas": {
31
        "Player": {
32
          "type": "object",
33
          "properties": {
34
            "id": {"type": "string", "format": "uuid"},
35
            "name": {"type": "string"}
36
          }
37
        }
38
        // ... 更多类型
39
      }
40
    }
41
  }
42
}

5.1.2 响应结构：方法列表、参数模式、通知事件#

5.1.3 与静态 json-rpc-api-schema.json 的关系#

mc-rpc Rust 库的构建流程展示了静态模式的典型用法：build.rs 在编译期解析 json-rpc-api-schema.json，为每个方法生成异步函数，为每个类型生成 Rust 结构体，实现零开销的类型安全 。

5.2.1 minecraft:players：获取在线玩家列表#

1
// 请求
2
{"jsonrpc":"2.0","method":"minecraft:players","id":1}
3

4
// 响应
5
{
6
  "jsonrpc": "2.0",
7
  "id": 1,
8
  "result": [
9
    {"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"},
10
    {"id": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Notch"}
11
  ]
12
}

返回当前在线玩家的完整列表。空服务器返回空数组 []。

5.2.2 玩家对象结构：UUID（id）、名称（name）#

玩家对象是 MSMP 的核心引用类型，广泛嵌套于管理员、白名单等结构中。UUID 的解析与验证需注意：离线服务器（online-mode=false）使用基于用户名的离线 UUID 生成算法，与正版 UUID 不同，但格式一致。

5.2.3 相关通知：minecraft:notification/players/joined、minecraft:notification/players/left#

1
// 玩家加入通知
2
{
3
  "jsonrpc": "2.0",
4
  "method": "minecraft:notification/players/joined",
5
  "params": [{"id": "...", "name": "NewPlayer"}]
6
}
7

8
// 玩家离开通知
9
{
10
  "jsonrpc": "2.0",
11
  "method": "minecraft:notification/players/left",
12
  "params": [{"id": "...", "name": "LeavingPlayer"}]
13
}

通知载荷为单个玩家对象，而非数组。客户端可通过维护本地在线玩家集合，响应通知进行增量更新，避免频繁全量查询。

5.3.2 minecraft:allowlist/add：添加白名单（支持 UUID/名称）#

1
// 请求：通过名称添加
2
{"method":"minecraft:allowlist/add","id":1,"params":[[{"name":"jeb_"}]]}
3

4
// 请求：通过 UUID 添加
5
{"method":"minecraft:allowlist/add","id":1,"params":[[{"id":"853c80ef-3c37-49fd-aa49-938b674adae6"}]]}
6

7
// 请求：批量添加
8
{"method":"minecraft:allowlist/add","id":1,"params":[[
9
  {"name":"player1"},
10
  {"id":"uuid-2"},
11
  {"name":"player3"}
12
]]}
13

14
// 响应：成功添加的玩家列表（含解析后的 UUID）
15
{
16
  "jsonrpc": "2.0",
17
  "id": 1,
18
  "result": [
19
    {"id": "...", "name": "jeb_"}
20
  ]
21
}

params 的双层数组结构：外层数组为方法参数列表（本方法仅一个参数），内层数组为批量操作条目。每个条目为对象，含 name 或 id 字段。

5.3.4 批量操作与单条操作的参数差异#

批量操作的设计体现了性能优化考量：单次网络往返处理多个条目，减少 WebSocket 帧传输开销。

5.4.2 minecraft:operators/add：添加管理员（支持等级与绕过限制）#

添加管理员时，可以指定两个额外参数：

• level：权限等级，1-4，控制可用命令范围
• bypass：布尔值，是否绕过玩家数量限制

mc-server-management 库提供了优雅的操作员对象抽象 ：

1
// 使用默认等级和绕过设置
2
await ops.add('Aternos');
3

4
// 显式指定等级4，绕过限制
5
await ops.add('Aternos', 4, true);
6

7
// 通过 UUID 添加
8
await ops.add(Player.withId('player-uuid'), 2, false);

封禁条目结构#

1
{
2
  "player": {"id": "uuid", "name": "playerName"},
3
  "reason": "封禁原因",
4
  "source": "操作者",
5
  "expires": "2026-01-01T00:00:00Z"
6
}

IP 封禁条目结构#

1
{
2
  "ip": "192.168.1.1",
3
  "reason": "封禁原因",
4
  "source": "操作者",
5
  "expires": "2026-01-01T00:00:00Z"
6
}

6.1.1 服务端状态变更的实时推送#

MSMP 的通知机制是其相对于传统管理协议的核心优势。与轮询模式相比，通知驱动架构具有显著的效率和实时性优势：

WebSocket 的全双工特性为通知机制提供了理想的传输基础。服务端可以在任意时刻向客户端推送消息，无需等待请求 。

6.1.2 通知与轮询的效率对比#

以玩家在线状态监控为例：

• RCON 轮询方案：每秒执行 list 命令，解析文本输出，对比前后差异。10 个监控客户端 = 服务端每秒处理 10 条命令。
• MSMP 通知方案：玩家加入/离开时，服务端推送一次通知。10 个监控客户端 = 服务端推送 10 条消息，但仅在事件发生时。

对于 100 人在线、日均 500 次加入/离开的服务器，RCON 方案日处理 864,000 条命令，MSMP 方案仅处理 5,000 条通知——效率提升 170 倍。

6.2.1 服务端状态通知#

6.2.2 玩家生命周期通知#

1
// 玩家加入通知示例
2
{
3
  "jsonrpc": "2.0",
4
  "method": "minecraft:notification/players/joined",
5
  "params": [{"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"}]
6
}

6.2.3 管理员列表变更通知#

6.2.4 白名单变更通知#

6.2.5 封禁列表变更通知#

6.2.6 游戏规则变更通知#

1
// 游戏规则更新通知示例
2
{
3
  "jsonrpc": "2.0",
4
  "method": "minecraft:notification/game-rules/updated",
5
  "params": [{"key": "doDaylightCycle", "type": "boolean", "value": false}]
6
}

6.2.7 服务端心跳通知#

7.1.1 数据生成器运行：--reports 参数#

数据生成器（Data Generator）是 Minecraft 内置的工具，用于导出游戏数据的各种结构化表示。运行数据生成器获取 API 模式：

1
java -jar server.jar --reports

7.1.2 json-rpc-api-schema.json 输出位置#

输出目录中将包含 reports/json-rpc-api-schema.json 文件，其内容与运行时 rpc.discover 响应一致 。

8.1.1 连接池与长连接维护#

MSMP 设计为长连接协议，客户端应保持单一连接而非频繁创建销毁。连接建立后，通过同一连接发送所有请求并接收通知。

8.1.2 断线重连与指数退避策略#

网络不稳定场景需要健壮的断线重连机制。推荐采用指数退避策略：

首次断线立即重试，后续间隔递增，避免对服务端造成重连风暴。

8.1.3 心跳检测与连接健康监控#

虽然 WebSocket 协议内置 Ping/Pong 帧，但应用层可以实现更语义化的心跳。定期发送 minecraft:server/status 请求，既可以检测连接健康，又可以同步服务端状态。

8.2.1 密钥安全存储：环境变量 vs 配置文件#

8.2.2 密钥轮换与最小权限原则#

• 密钥轮换：MSMP 当前版本不支持动态密钥轮换，需要重启服务端生效。规划中的改进包括热重载配置和密钥版本控制。
• 最小权限：为不同用途的客户端分配不同密钥（未来版本支持），或通过网络隔离限制访问范围。

8.2.3 生产环境强制 TLS 配置#

8.3.1 JSON-RPC 错误码分类处理#

8.3.2 网络超时与重试策略#

为每个请求设置合理的超时时间（建议 30s），避免无限等待。超时后应视为连接异常，触发重连。

8.3.3 服务端重启后的状态同步#

服务端重启后，客户端应：

1. 重新执行 rpc.discover 获取当前能力
2. 刷新所有缓存状态（玩家列表、白名单、游戏规则等）
3. 重新注册通知处理器（若服务端状态丢失）

8.4.1 批量操作优先于单条调用#

批量操作减少 90% 网络延迟。

8.4.2 通知订阅替代主动轮询#

8.4.3 本地缓存与增量更新策略#

• 缓存策略：合理设置 TTL，游戏规则等不频繁变化数据可长期缓存
• 增量更新：收到通知后，更新本地缓存而非重新查询
• 失效处理：连接断开后，标记缓存失效，重连后全量刷新

8.5.1 请求/响应日志记录#

8.5.2 性能指标采集#

9.1.1 公网暴露的 TLS 强制要求#

MSMP 提供的服务器控制能力使其成为高价值攻击目标。公网暴露必须满足：

9.1.2 反向代理部署模式#

推荐在生产环境使用反向代理（如 Nginx、Traefik）终止 TLS，提供额外的：

• 访问日志：集中审计
• 速率限制：防止暴力破解
• WAF 保护：过滤恶意请求

9.2.1 密钥泄露的潜在危害：完整服务器控制#

密钥泄露意味着攻击者获得：

• 修改白名单和管理员列表
• 执行服务器停止命令
• 更改游戏规则和服务器设置
• 潜在的权限提升路径

9.2.2 密钥生成与分发流程#

10.4.1 MSMP vs RCON：功能、安全、实时性#

10.4.2 MSMP vs Query：适用场景差异#

10.4.3 MSMP vs 第三方 REST API 插件#

12.1.1 401 Unauthorized：认证失败排查清单#

12.1.2 连接被拒绝：端口、防火墙、绑定地址#

12.2.1 Method not found：命名空间拼写、服务端版本#

排查清单：

• 检查命名空间拼写（minecraft 而非 minecrafts）
• 验证方法路径（allowlist/add 而非 allowlist.add）
• 确认服务端版本支持该方法
• 运行 rpc.discover 获取实际支持的方法列表

12.2.2 参数格式错误：数组包裹、对象字段#

12.3.1 高频率调用的限流与缓存#