先给结论
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 解析器解析一遍,确认能通过再重启。重启后不要假设生效,而要用一个真实账号验证:该能进的能进,该被限制的确实被限制。
五、审计与回收
权限是会长大的。临时给某人开操作员做活动、临时把某人加入白名单测试,如果没有人回收,半年后名单里会堆满早已不活跃的账号,形成安全隐患。
建议固定周期导出两份清单核对,移除长期不上线的授权,并在移除前确认没有共享账号在使用。对于确实需要长期保留的授权,注明原因,避免下次复核时无法判断为什么要留着。
执行步骤
- 让目标玩家尝试连接一次,从日志或名单文件取得权威 XUID。
- 确认 server.properties 中 allow-list 开关与名单内容方向一致。
- 按最小必要原则设计 permissions.json 的权限分级。
- 每次编辑后用 JSON 解析器校验语法,通过后再重启服务端。
- 用真实账号验证准入与权限是否符合预期。
- 建立权限台账,记录授权时间、原因与授权人。
- 按固定周期导出清单复核并回收不活跃授权。
- 把两个 JSON 文件纳入备份范围,避免误删后无法恢复。
验收标准
- 名单外账号无法进入,名单内账号可正常进入。
- 普通玩家无法执行管理命令,管理员可以。
- 两份 JSON 文件语法合法,重启后无解析错误。
- 能导出完整的授权清单并说明每一项的原因。
- 授权回收有记录,名单中没有长期不活跃账号。
- 文件已被纳入常规备份。
常见误区
- 用昵称代替 XUID 填名单,玩家始终进不来。
- 允许多人共用同一个管理员账号,事故后无法追溯。
- 手改 JSON 留下多余逗号,整份权限被忽略。
- 只改名单不改开关,行为与预期完全相反。
- 临时授权从不回收,权限持续累积。
权限体系的价值不在于设置得多严,而在于每次变化都可追溯、可回收、可验证。把两个 JSON 文件当配置文件管理,而不是当备忘录随手改。