你的服务器,由你决定访客名单。
基于名称的访问控制 · Minecraft 与 Discord 管理 · 自定义本地文件
社区始于你所邀请的人。OrangeWhitelist 为你提供清晰的方式,通过 Minecraft 中的命令、可选的 Discord 管理员工具以及可自定义的设置,来管理谁可以加入。
OrangeWhitelist 4.0 · Minecraft 1.8.8–26.3 Spigot & Paper · 单个 JAR 文件 · 无需额外插件
01 / 通往你世界的邀请函
维护一个玩家名称列表,选择未列入名单的玩家会发生什么,并决定哪些人员豁免权限。你可以使用 Minecraft 或服务器控制台中的 /owl 命令进行管理。
-
门口检查。 默认设置在玩家加入世界之前检查未列入名单的名称。尊重来自其他插件的现有访问拒绝。
-
选择你的响应。 对于白名单拒绝,使用 KICK(踢出),或使用 BAN(封禁)配合插件内部封禁列表或可选的 LiteBans 钩子。自定义拒绝屏幕和封禁原因。
-
有意设置豁免。 权限绕过是可选的,默认禁用。仅拥有管理员权限并不会使玩家免除名单限制。
-
保持在线工作人员在名单中。 可选的 AntiRemove 功能可防止移除具有你指定权限的连接中玩家。离线名称仍可编辑。
-
使用熟悉的名称。 名称匹配不区分大小写。支持在 16 个字符限制内使用选定的前缀,例如
.Steve。
访问时机、名称与封禁
默认情况下,名称检查在异步预登录期间运行。启用权限绕过后,权限决策移至可用的玩家登录事件。加入安全检查会移除仍不符合资格的玩家;没有登录事件的服务器将使用该回退机制。
启用白名单并重新加载其文件会将所选的访问规则应用于已在线的玩家。如果启用了白名单强制执行且玩家没有有效的绕过权限,移除名称也会移除其连接的玩家。
该列表基于名称,而非经过身份验证的身份。接受的名称包含字母、数字和下划线,可选地以支持的前缀集中的最多三个字符开头。整个名称最多必须为 16 个字符;不接受带有空格的名称。
支持的前缀字符:. * ! ~ # $ % & + = ? @ ^ -
示例:Steve, Player_01, .Steve
内部 PLUGIN 封禁基于 Bans.yml 中的实际玩家 UUID 进行键控,并在白名单禁用时保持活动状态。在执行 /owl add <player> 保存新的列表条目后,它会解除匹配的內部封禁。已列出的名称会报告无新添加操作。现有内部封禁在绕过权限之前进行检查。
可选的 LiteBans 钩子使用控制台中的 litebans:ban <name> <reason>。如果 LiteBans 不可用,则使用内部封禁。添加玩家不会自动移除 LiteBans 或原版 Minecraft 封禁;请使用这些系统各自的赦免或解封工具。
OrangeWhitelist 维护自己的列表。如果服务器的原版白名单也启用,玩家还必须满足该列表的要求。
查看原始拒绝屏幕
截图来自早期版本。当前的拒绝消息完全可配置。
02 / 在你交谈的地方提供工作人员工具
启用集成的 Discord 机器人,让授权的工作人员从你的 Discord 服务器管理相同的 Minecraft 名单。机器人是可选的;所有 Minecraft 命令在没有它的情况下也能工作。
-
五种斜杠操作。 启用、禁用、添加、移除和列出
/whitelist。更改使用与 Minecraft 命令相同的白名单操作。 -
授权你的角色。 使用 Discord 角色 ID 来选择谁可以管理访问权限。应用程序所有者及其接受的团队成员也有资格。
-
有用的建议。 添加自动补全建议最近被拒绝的名称和尚未列入名单的在线玩家。移除自动补全建议当前列表条目。
-
选择语言。 英语、西班牙语、法语和中文可用于机器人的命令描述及其自身的反馈。
-
保持连接。 机器人处理心跳、可恢复会话和自动重连。无效凭据会在重新加载或重启之前停止重试。
Discord 命令 — 完整参考
/whitelist enable
启用白名单并将其规则应用于在线 Minecraft 玩家。
/whitelist disable
禁用白名单强制执行;现有封禁保持不变。
/whitelist add player:<name>
添加玩家名称;所需选项名为 player。它使用与 Minecraft 命令相同的添加操作。
/whitelist remove player:<name>
移除玩家名称,尊重受保护在线玩家的 AntiRemove。所需选项名为 player。
/whitelist list
在私人回复中显示计数和玩家名称。长列表会被缩短以适应回复。
这些命令在 Discord 服务器内工作,而不是直接消息。所需的 add/remove 选项名为 player。没有 Discord 重新加载命令。
白名单列表回复和权限被拒绝的回复是私人的。授权的更改命令在频道中回复。玩家名称会被转义,且回复不会生成 Discord 提及。
Discord 设置与角色访问
-
在 Discord 开发者门户中创建你的机器人应用。使用
bot和applications.commands作用域将其邀请至你的 Discord 服务器。此客户端不需要任何特权意图(privileged intents)。 -
将机器人的令牌复制到私有
Settings.yml中的Discord-Bot.Token,并设置Discord-Bot.Enabled: true。 -
开启 Discord 开发者模式,复制管理角色 ID 并将其作为带引号的值输入到
Discord-Bot.Authorized-Roles下。 -
选择机器人语言、在线状态和活动显示。运行
/owl reload,然后在你的 Discord 服务器中使用/whitelist。
Discord-Bot:
Enabled: true
Token: "YOUR_DISCORD_BOT_TOKEN_HERE"
Language: English
Status: "online"
Activity-Type: 0
Activity-Name: "Minecraft"
Authorized-Roles:
- "123456789012345678"
上述令牌和角色 ID 仅为示例。请使用你自己的值并保持令牌私密。无需手动配置 Application-ID。
Minecraft 权限节点不能用于授权 Discord 用户。Discord 成员需要拥有已配置的角色,或者是应用程序的所有者或其所属团队中被接受的成员。仅拥有 Discord 服务器所有权或管理员角色并不能授予访问权限。
当设置为 Authorized-Roles: [] 时,只有应用程序所有者/团队有资格访问。默认的命令可见性可能需要“管理服务器”权限,但可见性本身并不授予授权。
白名单操作回复使用你的 Messages 设置中的纯文本,不包含 Minecraft 颜色代码或命令前缀。Language 设置控制机器人自身的回复和斜杠命令描述。
如果凭据或致命的 Discord 网关错误导致机器人停止工作,请更正配置并运行 /owl reload 以重试。其他中断的会话会自动重新连接。
03 / 熟悉的设置。保留的列表。
版本 4 围绕独立本地文件重构了白名单管理,并将文本库打包在 JAR 文件中。你可以升级现有列表,或以同样简单的设置启动一个新社区。
-
Minecraft: Spigot 和 Paper 上的 1.8.8–26.3。在 Minecraft 服务器上安装
OrangeWhitelist-4.0.jar。 -
Java: 使用你的服务器软件所需的 Java 版本。该插件针对 Java 8 字节码;现代 Minecraft 服务器仍需其自身更新的 Java 运行时环境。
-
依赖项: 不需要额外的插件。LiteBans 是可选的,且包含 Discord 客户端。没有 PlaceholderAPI 集成。
-
文件:
Settings.yml保存配置,Whitelist.yml保存玩家名称,Bans.yml在使用时保存内部封禁记录。无需数据库设置。
04 / 一次设置。邀请你的玩家。
安装与配置
-
将
OrangeWhitelist-4.0.jar放入服务器的plugins文件夹并启动服务器。 -
全新安装会以空列表启用白名单。从控制台运行
owl add YourName然后再连接。添加其余玩家,或在准备访问期间使用owl disable。 -
打开
plugins/OrangeWhitelist/Settings.yml。选择 KICK 或 BAN 模式、消息、命令权限以及任何可选的绕过、AntiRemove 或 Discord 设置。 -
运行
/owl reload,然后运行/owl list。在邀请你的社区之前,测试一个已列入名单的玩家和一个未列入名单的玩家。
Minecraft 命令 — 完整参考
主命令:/orangewhitelist。别名:/owl、/orangewl、/orangewhl、/orangew、/dwl 和 /dragonwhl。所有六个操作对具有权限的玩家和控制台均开放。
/owl enable
默认权限: orangewhitelist.set OR orangewhitelist.admin
启用白名单,保存设置,并将访问规则应用于已在线的玩家。未列入名单且没有启用绕过的玩家将根据所选的 KICK 或 BAN 模式被移除。
/owl disable
默认权限: orangewhitelist.set OR orangewhitelist.admin
禁用白名单执行并保存设置。现有的 OrangeWhitelist 内部封禁和 LiteBans 封禁不会被移除。
/owl add <player>
默认权限: orangewhitelist.manage OR orangewhitelist.admin
验证并添加玩家名称。新条目保存后,匹配的 PLUGIN 内部封禁将被解除。这不会赦免原版 Minecraft 或 LiteBans 的封禁。如果名称已存在,则报告现状而不更改其记录。
/owl remove <player>
默认权限: orangewhitelist.manage OR orangewhitelist.admin
移除现有名称。AntiRemove 功能可以拒绝移除受保护的在线玩家。当白名单启用时,不再符合条件的在线玩家将按所选模式被移除。
/owl list
默认权限: orangewhitelist.manage OR orangewhitelist.admin
显示白名单计数和玩家名称,或显示配置的空白列表消息。
/owl reload
默认权限: orangewhitelist.reload OR orangewhitelist.admin
重新加载 Settings.yml、Whitelist.yml 和 Bans.yml,刷新 Discord 机器人并将访问规则应用于在线玩家。文件独立重载:无法读取的文件保留其之前的加载值,而其他有效文件可能会应用。
缺少或未知参数会显示用法。Tab 补全建议允许的子命令。add 建议包括最近被拒绝的玩家和列表中缺失的在线玩家;remove 建议使用现有列表条目。
权限 — 完整参考
orangewhitelist.admin — 默认为操作员(Operator)。允许所有六个 Minecraft 命令及更新通知。其声明的子权限为 set、manage 和 reload;它不授予 bypass 或 anti-remove 权限。
配置键: Permissions.ALL
orangewhitelist.set — 默认为操作员(Operator)。允许 /owl enable 和 /owl disable。配置的 admin 节点也允许这些命令。
配置键: Permissions.Enable-Disable
orangewhitelist.manage — 默认由操作员拥有。允许使用 /owl add、/owl remove 和 /owl list。配置的管理员节点也允许这些命令。
配置键: Permissions.Add-Remove
orangewhitelist.reload — 默认由操作员拥有。允许使用 /owl reload。配置的管理员节点也允许此命令。
配置键: Permissions.Reload
orangewhitelist.bypass — 默认不授予,包括操作员。仅在 Enable-Permission-Bypass 为 true 时,允许未列入名单的玩家加入。不会覆盖现有的内部封禁。
配置键: Bypass-Permission.Permission
orangewhitelist.antiremove — 默认不授予,包括操作员。仅在 Enable-AntiRemove 为 true 时,防止移除具有此节点且在线的玩家。离线条目不受保护。
配置键: AntiRemove.Permission
所有六个权限名称均可配置。如果您重命名它们,请通过您的权限管理器授予新名称。声明的操作员授予和子关系适用于默认名称。空白的权限名称将回退到其默认值。
绕过(Bypass)和防移除(AntiRemove)需要各自独立的启用开关。操作员和管理权限持有者不会自动获得这两项豁免。Discord 授权独立使用角色 ID。
配置 — 示例与所有设置
将以下部分合并到生成的 Settings.yml 中;保留其生成的版本字段和 Messages 部分。示例中禁用了 Discord、绕过功能和防移除功能,并使用 KICK 模式。
# 合并到 Settings.yml;保留生成的版本字段和 Messages。
Plugin-Config:
Enabled-Whitelist: true
Mode: KICK
Update-Checker: true
Kick-Ban-Hooks:
Hook: PLUGIN
Ban-Message: "<gray>You are not on this server's whitelist.</gray>"
Permissions:
Enable-Disable: "orangewhitelist.set"
Add-Remove: "orangewhitelist.manage"
Reload: "orangewhitelist.reload"
ALL: "orangewhitelist.admin"
Bypass-Permission:
Enable-Permission-Bypass: false
Permission: "orangewhitelist.bypass"
AntiRemove:
Enable-AntiRemove: false
Permission: "orangewhitelist.antiremove"
Discord-Bot:
Enabled: false
Token: "YOUR_DISCORD_BOT_TOKEN_HERE"
Language: English
Status: "online"
Activity-Type: 0
Activity-Name: "Minecraft"
Authorized-Roles: []
-
Plugin-Version / Config-Version. 受管理的版本字段。请勿更改其生成的值。支持的设置会被保留,修改过的配置文件会收到 old-configs/ 备份。 -
Plugin-Config.Enabled-Whitelist. 默认为 true。全新安装开始时白名单为空。在连接前从控制台添加您自己的名字,或者在您准备列表时故意禁用强制执行。 -
Plugin-Config.Mode. KICK 会在启用时拒绝未列入名单的玩家。BAN 会拒绝他们并使用选定的钩子记录封禁。无效的值会回退到 KICK 并在控制台发出警告。 -
Plugin-Config.Update-Checker. 默认为 true。检查 Spigot 上的更新并通知控制台和管理员;它不会安装更新。 -
Kick-Ban-Hooks.Hook. PLUGIN 使用 OrangeWhitelist 基于 UUID 的 Bans.yml。LiteBans 在该插件可用时会触发 litebans:ban。如果不可用,插件将回退到其自己的列表并记录回退信息。 -
Kick-Ban-Hooks.Ban-Message. 用于 BAN 模式和后续内部封禁拒绝的理由。LiteBans 接收纯文本理由。初始白名单拒绝使用 Messages.Kick-Message。 -
Permissions.Enable-Disable. 用于启用和禁用白名单的权限。默认为 orangewhitelist.set。 -
Permissions.Add-Remove. 用于添加、移除和列出玩家的权限。默认为 orangewhitelist.manage。 -
Permissions.Reload. 用于重新加载所有三个本地文件的权限。默认为 orangewhitelist.reload。 -
Permissions.ALL. 管理命令权限和更新通知。默认为 orangewhitelist.admin;它不包含绕过或防移除权限。 -
Bypass-Permission.Enable-Permission-Bypass. 默认为 false。当为 true 时,可以使用配置的权限授予访问权,而不是依赖名单成员身份。权限检查在可用时使用登录事件,并以加入安全检查作为回退。 -
Bypass-Permission.Permission. 默认为 orangewhitelist.bypass。仅授予那些应该在不列入名单的情况下加入的玩家;更早之前仍会检查现有的内部封禁。 -
AntiRemove.Enable-AntiRemove. 默认为 false。当为 true 时,受保护的在线玩家无法从插件列表中移除。这不是对离线名称的保护。 -
AntiRemove.Permission. 默认为 orangewhitelist.antiremove。仅在 AntiRemove 启用时对在线目标有效。 -
Discord-Bot.Enabled. 默认为 false。开启或关闭集成的 Discord 机器人。更改设置后需重新加载。 -
Discord-Bot.Token. 来自 Discord Developer Portal 的机器人令牌。请保持私密。示例仅为占位符,并非有效的凭据。无需 Application-ID 设置。 -
Discord-Bot.Language. English, Español, Français 或 中文。接受语言别名 en, es, fr 和 zh。未知语言将回退到 English。本地化命令描述和机器人反馈;白名单操作回复使用 Messages。 -
Discord-Bot.Status. online, idle, dnd 或 invisible。无效的值会回退到 online。 -
Discord-Bot.Activity-Type. 0 Playing, 1 Streaming, 2 Listening, 3 Watching, 4 custom text, 5 Competing。值会被限制在 0–5 之间。不提供流媒体 URL 设置。 -
Discord-Bot.Activity-Name. 活动文本。设置为空字符串以不显示任何活动。 -
Discord-Bot.Authorized-Roles. 允许在 Discord 服务器内使用 /whitelist 的引用 Discord 角色 ID。应用程序所有者及其所属团队的已接受成员也可以使用它。空表示仅限应用程序所有者/团队成员,而非每个服务器成员。
消息 — 格式与内置变量
Minecraft 消息支持 MiniMessage 颜色与样式、传统的 & 代码以及 HEX 颜色。完整的 RGB 颜色需要 Minecraft 1.16 或更高版本;旧版本将使用最接近的传统颜色。文本会被序列化为 Bukkit 字符串,因此交互式的悬停和点击组件不会包含在消息输出中。
将命令反馈消息设置为 "" 可使其静音。空的前缀会移除前缀;空的踢出消息仍会拒绝访问。插件内置的大括号变量不需要 PlaceholderAPI。
-
Messages.Prefix。 Minecraft 命令反馈的前缀。设置为空字符串以移除它。它不会添加到踢出屏幕或 Discord 回复中。 -
Messages.No-Perms。 Minecraft 命令因权限不足被拒绝。 -
Messages.No-Args。 缺失或未知命令参数的用法提示。 -
Messages.Reload。 成功重载的反馈。 -
Messages.W-ON。 白名单已启用。 -
Messages.W-OFF。 白名单已禁用。 -
Messages.Added。 添加操作成功;变量{player}。 -
Messages.Removed。 移除操作成功;变量{player}。 -
Messages.No-Whitelisted-Player。 请求的名称不在列表中。 -
Messages.Already-Whitelisted。 请求的名称已在列表中。 -
Messages.Invalid-Name。 请求的名称验证失败;变量{player}。 -
Messages.Cant-Remove。 由于 AntiRemove 保护了在线玩家,拒绝移除。 -
Messages.List。 列表输出;变量{count}和{players}。 -
Messages.List-Empty。 列表为空时的反馈。 -
Messages.Write-Failed。 文件无法读取或写入;变量{file}。请查看控制台以获取详细信息。重载时独立读取这三个文件。 -
Messages.Update-Available。 新版本通知;变量{version}和{current}。 -
Messages.Kick-Message。 初始白名单拒绝时显示的屏幕。使用 <newline> 换行;不添加命令前缀。
单独的 Kick-Ban-Hooks.Ban-Message 控制封禁理由及后续的内部封禁拒绝屏幕。
Messages:
Prefix: "<color:#BD987A><bold>OrangeWhitelist</bold></color> <dark_gray>» </dark_gray>"
Added: "<gray>{player} is now on the list.</gray>"
Removed: "<gray>{player} was removed from the list.</gray>"
List: "<gray>Whitelist ({count}): <white>{players}</white></gray>"
Kick-Message: "<color:#BD987A>OrangeWhitelist</color><newline><gray>You are not on this server’s whitelist.</gray>"
本地文件、升级与重载行为
Whitelist.yml 在 Players 下存储名称。名称比较时不区分大小写。添加和移除操作在保存后确认成功;临时文件替换降低了部分列表写入的风险。
Players:
- "YourName"
- ".Steve"
Bans.yml 由内部 PLUGIN 钩子使用,记录 UUID、名称和日期。如果文件不存在,则表示没有内部封禁记录。不要仅仅为了关闭白名单强制执行而删除它。
从版本 3 升级之前,请备份插件文件夹,停止服务器,替换旧的 JAR 文件并重新启动。现有的玩家名称会在配置更新之前从旧的 Settings.yml 白名单部分迁移到 Whitelist.yml。保留旧的示例条目而不是静默删除;请检查导入的列表。
支持的用户值会被保留,缺失的设置会被恢复,更改后的 Settings.yml 文件会备份到 old-configs/ 下。旧的 Discord-Bot.Autorized-Roles、Bypass-Permission.Bypasss-Whitelist-Permission 和 AntiRemove.Anti-Remove-Permission 会迁移到其当前名称。旧的 %player%、%count% 和 %players% 消息标记变为大括号变量。
在 Minecraft 自身封禁列表中创建的旧封禁记录仍保留在那里。如果你故意想解除其中一个,请使用 /pardon <name>。LiteBans 封禁记录保留在 LiteBans 中。/owl add <player> 处理新添加的名称以及匹配的内部版本 4 PLUGIN 封禁。
重载时独立读取三个本地文件。无法读取的文件保持原样并保留其之前的加载值;其他有效文件可能仍然适用。白名单读取失败也会阻止列表变更,直到文件修复并重新加载。
如果启动时无法读取 Settings.yml,则使用捆绑的默认值:白名单启用、KICK 模式、Discord 关闭且绕过关闭。无法读取的启动白名单初始没有加载的名称;无法读取的启动封禁文件初始没有加载的内部封禁。修复报告的文件并在依赖其记录之前重新加载。
文档与支持
需要关于访问规则或 Discord 机器人的帮助?请分享你的 Minecraft 和插件版本、相关的控制台错误日志以及移除了机器人令牌的配置片段。
合作伙伴
Teramont 是我们的托管合作伙伴。使用代码 Byte 可获得首月 85折 优惠。
© 2026 FruitForge Studios
你是这个资源的作者?登录后可认领此资源。
相似资源
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
ExyliaPlugins 的库。
通过对话框或铁砧界面帮助你的 Anthme
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧