我的世界基岩版 allowlist 与 permissions.json 深度用法:XUID、权限分级与审计

基岩版的准入与管理权限全靠两个 JSON 文件,XUID 填错和 JSON 语法错误是最常见的两类事故。

先给结论

allowlist.json 决定谁能进,permissions.json 决定谁能管。两者都以玩家 XUID 为键、都必须保持 JSON 合法、都要重启服务端才生效。把这两个文件当成需要版本管理与审计的配置文件,而不是临时手改的清单,权限事故会减少大半。

一、先搞清 XUID 从哪里来

XUID 是基岩版账号的唯一标识,不是玩家昵称,也不是 Xbox 昵称。手填昵称或猜数字是最常见的失败原因,因为服务端只认 XUID,认不到就把玩家挡在门外。

正确获取方式是让目标玩家先尝试进入一次,然后在服务端日志或 allowlist.json 中读取服务端记录的 XUID。这样得到的是权威值,比让玩家自己报更可靠。若玩家一次都没尝试过连接,日志里就不会有记录,这时手工构造条目往往徒劳。

二、allow-list 开关与文件的关系

server.properties 中的 allow-list 是总开关,allowlist.json 是名单本体。开关打开而名单为空,结果是所有人都进不来;开关关闭而名单里有人,结果是谁都能进。两者必须一起看,只改一个都会得到与预期相反的效果。

另一个易错点是有多个服务端目录时改错了文件。改完重启后行为没变化,八成是因为服务端读取的不是你编辑的那一份。排查方式是看服务端日志中的加载路径,或临时清空名单验证开关是否真的生效。

三、permissions.json 的等级设计

基岩版权限通常分为访客、成员、操作员几个层级,决定玩家能否破坏方块、使用容器、执行命令。设计原则是最小必要:普通玩家只需要正常游玩的权限,管理权限只授予确实需要的人。

把所有人都设成操作员是最典型的错误,后果是出事后无法追责、无法收回权限,也无法区分是玩家误操作还是管理越权。正确做法是建立一份权限台账,记录谁在什么时间因为什么原因被授权,以及何时应当复核。

四、JSON 语法与生效验证

手工编辑 JSON 最常见的破坏是多余逗号、缺失引号和中英文标点混用。语法错误会导致整份文件被忽略,表现往往是权限全部失效或全部放开,而不是报出清晰的错误提示。

因此每次编辑后都应做一次语法校验,最省事的办法是用任意 JSON 解析器解析一遍,确认能通过再重启。重启后不要假设生效,而要用一个真实账号验证:该能进的能进,该被限制的确实被限制。

五、审计与回收

权限是会长大的。临时给某人开操作员做活动、临时把某人加入白名单测试,如果没有人回收,半年后名单里会堆满早已不活跃的账号,形成安全隐患。

建议固定周期导出两份清单核对,移除长期不上线的授权,并在移除前确认没有共享账号在使用。对于确实需要长期保留的授权,注明原因,避免下次复核时无法判断为什么要留着。

执行步骤

  1. 让目标玩家尝试连接一次,从日志或名单文件取得权威 XUID。
  2. 确认 server.properties 中 allow-list 开关与名单内容方向一致。
  3. 按最小必要原则设计 permissions.json 的权限分级。
  4. 每次编辑后用 JSON 解析器校验语法,通过后再重启服务端。
  5. 用真实账号验证准入与权限是否符合预期。
  6. 建立权限台账,记录授权时间、原因与授权人。
  7. 按固定周期导出清单复核并回收不活跃授权。
  8. 把两个 JSON 文件纳入备份范围,避免误删后无法恢复。

验收标准

  • 名单外账号无法进入,名单内账号可正常进入。
  • 普通玩家无法执行管理命令,管理员可以。
  • 两份 JSON 文件语法合法,重启后无解析错误。
  • 能导出完整的授权清单并说明每一项的原因。
  • 授权回收有记录,名单中没有长期不活跃账号。
  • 文件已被纳入常规备份。

常见误区

  • 用昵称代替 XUID 填名单,玩家始终进不来。
  • 允许多人共用同一个管理员账号,事故后无法追溯。
  • 手改 JSON 留下多余逗号,整份权限被忽略。
  • 只改名单不改开关,行为与预期完全相反。
  • 临时授权从不回收,权限持续累积。

权限体系的价值不在于设置得多严,而在于每次变化都可追溯、可回收、可验证。把两个 JSON 文件当配置文件管理,而不是当备忘录随手改。