HBL - 全球封禁列表管理与警告

HBL - 全球封禁列表管理与警告

/hbl auth 激活您的服务器，即时阻止活跃封禁并提供申诉选项。/ban、/unban、/warning 和 /hbl import 带有本地队列 + 当达到 API 限制时自动同步本地备用。还包括员工登录，完整的封禁列表

生活质量

HBL - 全球封禁列表管理与警告预览查看大图

如有问题或建议，请在 HBL Nexus Discord 中提出，点击 此处

在 ko-fi.com 上请我喝杯咖啡

HBL - Hytale Ban List

针对 Hytale 服务器的全局集中式审核检查，可选共享封禁执行、本地警告，以及品牌的申诉通道和工作人员登录。

轻松阻止已知的黑客、破坏者和其他不良行为者。

✅ 激活插件

运行 /hbl auth 并使用提供的魔法链接即可。您的控制面板即上线，您的服务器也受到保护，免受已知不良行为者的侵害。

/hbl auth 注册流程

📜 （可选）配置封禁消息

  • 修改 config.json

🔨（可选）导入您当前的 bans.json

/hbl import

建议禁用其他已安装模组中重叠的原生审核功能。

✨ 核心功能

  • 针对 Hytale Ban List API 执行加入时封禁检查。
  • 内置白名单集成（Server/whitelist.json），可立即允许玩家并跳过 API 检查。
  • 对封禁玩家执行即时断开连接，并附带原因、到期时间和申诉 URL。
  • 由插件注册的顶级审核命令（/ban、/unban、/warning）。
  • 带有自动封禁的警告系统，达到可配置阈值后触发。
  • 速率限制回退模式，并每小时在控制台提醒在 hytalebanlist.org 提高限制。
  • 在速率限制期间加入队列的本地封禁（synced: false），在 UTC 时间 00:01 自动重试同步。
  • 更智能的 /hbl import 管道，尽可能从 UUID 解析用户名，并在完全成功后从内存缓存中清除已导入的封禁。
  • 已知审核模组的兼容性检测，带有红/绿状态输出和配置指导。
  • 通过可编辑的语言文件支持本地化。

⚙️ 配置指南

config.json 字段

字段 类型 默认值 功能说明
api.key 字符串 "YOUR_API_KEY_HERE" 来自 Hytale Ban List 控制面板的 API 密钥。
messages.kickMessage 字符串 包含 {reason}、{expires}、{appealUrl} 当玩家被拒绝连接时显示的消息。
moderation.warningThreshold 数字 3 达到此警告次数后自动封禁。
moderation.defaultBanDuration 字符串 "perm" 当 /ban 未指定时间时的默认时长。
general.locale 字符串 "en" 从 HytaleBanList/locales 加载的语言文件名。
general.replaceNativeBanCommands 布尔值 true 用插件版本替换原生的 /ban 和 /unban 命令。

支持的时长令牌

以下令牌可用于 /ban 和 defaultBanDuration：

  • s 秒
  • m 分钟
  • h 小时
  • d 天
  • w 周
  • mo 月（约30天）
  • y 年（约365天）
  • perm 永久

示例：30m、2h、7d、2w、1mo、1y、perm

🧩 命令

主命令

/hbl

子命令：

  • /hbl auth → 返回用于服务器设置的魔法链接
  • /hbl reload → 重新加载配置和语言文件
  • /hbl ban <玩家> [时长] [原因]
  • /hbl unban <玩家>
  • /hbl warn <玩家> [原因]
  • /hbl checkbans
  • /hbl import

由插件注册的顶级别名

  • /ban <玩家> [时长] [原因]
  • /unban <玩家>
  • /warn <玩家> [原因]
  • /checkbans

/hbl help 预览

HBL 帮助使用说明

[HytaleBanList] 帮助
/ban {玩家} {时间} {原因} | /hbl ban {玩家} {时间} {原因}
/unban {玩家} | /hbl unban {玩家}
/warning {玩家} {原因} | /hbl warn {玩家} {原因}
/hbl checkbans | /checkbans
/hbl import (从 Hytale bans.json 导入)
/hbl auth | /hbl reload
时间: 30m 2h 7d 2w 1mo 1y perm

游戏内输出的颜色键：红色 = 封禁，绿色 = 解封，黄色 = 标题/警告/时间，青色 = 实用命令。

权限

  • hytalebanlist.auth
  • hytalebanlist.reload
  • hytalebanlist.ban
  • hytalebanlist.unban
  • hytalebanlist.warning
  • hytalebanlist.checkbans
  • hytalebanlist.import

🌍 本地化

本地化完全可选，但受到支持。

  1. 复制默认的 en.json 语言文件。
  2. 将值翻译成您的目标语言。
  3. 保存为插件语言文件夹内的 <您的语言文件>.json。
  4. 在 config.json 中设置 "locale": "<您的语言文件>"。
  5. 运行 /hbl reload。

如果自定义语言文件缺失或无效，插件将回退到内置的英文。

🛡️ 封禁和警告

封禁流程

  • 工作人员执行 /ban。
  • 插件提交到 Hytale Ban List API。
  • 成功后，玩家被断开连接，并显示您配置的踢出模板。
  • 当 API 提供申诉 URL 时，会包含在内。

当达到 API 限制时：

  • /ban 仍会在本地生效并立即断开连接。
  • 条目以 "synced": false 写入 bans.json。
  • 排队的条目会在 UTC 时间 00:01 自动重试。
  • 同步成功后，条目标记为 "synced": true。

警告流程

  • 工作人员执行 /warn。
  • 警告计数在本地跟踪。
  • 达到 warningThreshold 时，插件自动提交一个永久封禁。
  • 自动封禁成功后，该玩家的警告将被清除。

🌐 全局封禁行为（可配置）

全局/共享封禁行为由您的 Hytale Ban List 服务端设置（控制面板/API 策略）控制，而此插件则强制执行其收到的封禁检查响应。

实际上：

  • 此插件始终在玩家加入时执行配置的 API 检查。
  • 返回的封禁是全局共享、待定还是限于服务器范围，取决于您的 Hytale Ban List 配置。
  • 在您的 Hytale Ban List 控制面板中调整服务器的全局审核策略。

📉 API 速率限制行为

如果 API 用量耗尽（例如在 UTC 时间 00:00 重置之前）：

  • 插件进入临时回退模式，直到下一个 UTC 重置。
  • 加入检查使用白名单/封禁回退，并在该窗口内跳过 API 调用。
  • 控制台每小时打印一次提醒，表明 API 限制已达到，并提示访问 hytalebanlist.org 提高限制。
  • 在受限期间 /checkbans 被跳过，并显示速率限制消息。

重置后：

  • 排队的本地封禁（synced: false）会在 UTC 时间 00:01 自动重试。

🔗 通过 CNAME 实现的自定义域名（高级版）

HytaleBanList.org 支持在付费计划下，在您自己的子域名上使用自定义审核门户（封禁列表、查询、申诉）。

示例门户 URL：

DNS 设置

在您的 DNS 提供商处添加以下两条记录：

  1. CNAME 记录

    • 主机/名称：bans.yourserver.com（或您选择的子域名）
    • 目标：appeals.hytalebanlist.org

  2. TXT 记录

    • 主机/名称：_hytale-verify.bans.yourserver.com
    • 值：hbl_verify_<令牌>
    • 令牌来源：在您保存自定义域名时，由服务器设置控制面板生成。

然后，在记录传播后，在控制面板中验证 DNS。

备注

  • 自定义域名在高级计划中可用。
  • 建议使用子域名（根/顶级域名通常无法在标准 DNS 设置中使用 CNAME）。
  • 通常传播很快，但全局 DNS 可能需要更长时间。

✅ 建议的首次检查

设置完成后，请快速验证以下内容：

  • API 密钥已保存，并且日志中没有认证警告。
  • /hbl reload 执行成功。
  • 已为工作人员角色分配 /ban 和 /warn 权限。
  • 踢出消息中的占位符（{reason}、{expires}、{appealUrl}）能正确渲染。
  • 语言文件更改在重新加载后生效。

📚 有用链接