VelocityToolbox ——插件管理、资源包托管、入口域名、多版本限制

pol***

VelocityToolbox

Velocity 运维工具箱：运行时插件管理、入口域名排查、子服客户端版本限制，以及可选的资源包 HTTP 托管。



项目源码 | 下载插件 | 问题与建议

运行环境

• Velocity 4.0 及以上。
• Java 25 及以上。
• 无硬前置。资源包分配可搭配 VelocityResourcepacks 1.9.0+。
  

能做什么

• 运行时插件管理：加载、卸载或重载 plugins/ 里的 Velocity 插件。操作前可检查依赖与风险，操作后报告监听器、任务、命令等资源的清理结果。
• 排查入口域名：/vtb vhosts 按玩家加入时使用的域名和端口分组。点击入口行展开玩家名与延迟，悬停查看详情。
• 限制子服客户端版本：为不同子服设置最低/最高版本、允许列表和禁止列表。直接使用 Velocity 的客户端协议 API，无需 ViaVersion。默认关闭，支持配置重载。
• 托管多个资源包：扫描本地 ZIP 文件，提供 HTTP 下载，计算 SHA-1，并生成支持多包叠加的 VelocityResourcepacks 配置片段。HTTP 服务默认关闭。
  

功能展示

按入口域名查看玩家人数和延迟：


热加载插件：


热卸载插件并查看清理结果：


配置资源包托管并由 VelocityResourcepacks 分配后，玩家看到的下载提示：


安装

1. 从 Releases 下载 JAR，放入 Velocity 的 plugins/ 目录。
2. 完整启动代理一次，生成 plugins/VelocityToolbox/config.yml。
3. 给管理员授予 velocitytoolbox.admin，或按下方权限说明细分授权。
4. 使用 /vtoolbox help 或 /vtb help 查看命令。

更新 VelocityToolbox 自身时，替换 JAR 后完整重启代理。

命令

主命令为 /vtoolbox，别名为 /vtb。普通查询不会刷后台；插件加载、卸载、重载和配置重载只输出简短状态。

• /vtoolbox help：显示帮助。
• /vtoolbox info：查看插件、代理、Java、插件数量、子服版本限制和资源包托管概要。
• /vtoolbox packs：列出资源包 URL 和 SHA-1。
• /vtoolbox vhosts：按入口域名和端口显示人数，点击展开玩家信息。
• /vtoolbox reload：重载语言、配置、子服版本限制和资源包托管。
• /vtoolbox plugin list：列出插件名称、版本和作者，悬停查看完整信息。
• /vtoolbox plugin inspect 插件ID：检查基本信息、依赖、运行时资源和热卸载风险。
• /vtoolbox plugin load 文件.jar：从 plugins/ 目录加载插件。
• /vtoolbox plugin unload 插件ID：卸载插件。
• /vtoolbox plugin reload 插件ID：卸载后重新加载插件。
  

权限

velocitytoolbox.admin 可以使用全部命令。

细分授权时，先授予 velocitytoolbox.command，再授予对应子命令权限：

1. 
   
2. velocitytoolbox.command.info
   
3. velocitytoolbox.command.packs
   
4. velocitytoolbox.command.vhosts
   
5. velocitytoolbox.command.reload
   

复制代码

插件管理还需要父权限 velocitytoolbox.command.plugin，以及对应操作权限：

1. 
   
2. velocitytoolbox.command.plugin.list
   
3. velocitytoolbox.command.plugin.inspect
   
4. velocitytoolbox.command.plugin.load
   
5. velocitytoolbox.command.plugin.unload
   
6. velocitytoolbox.command.plugin.reload
   

复制代码

例如，只允许检查插件风险，需要同时授予 velocitytoolbox.command、velocitytoolbox.command.plugin 和 velocitytoolbox.command.plugin.inspect。帮助只显示执行者有权使用的命令。

子服客户端版本限制



在 config.yml 的 server-versions 段中配置。以下示例只允许指定版本进入 survival，并给 minigame 设置最低版本和禁止项：

1. 
   
2. server-versions:
   
3.   enabled: true
   
4.   servers:
   
5.     survival:
   
6.       allow: ["1.12.2", "1.20.1"]
   
7.     minigame:
   
8.       min: "1.18"
   
9.       max: max
   
10.       deny: ["1.20.2"]
    

复制代码

• 服务器名对应 velocity.toml 的服务器配置，未列出的子服不限制。
• min / max 包含边界；max: max 跟随当前 Velocity 支持的最高版本。
• allow 非空时只允许列表中的协议；deny 优先拒绝。范围与允许列表必须同时满足。
• 切服被拒时保留当前子服；首次进入被拒时断开并显示原因。
• /vtoolbox reload 或 /velocity reload 重载规则，/vtoolbox info 查看模块状态和各子服的版本范围、允许列表及禁止列表。
• 配置重载失败保留上次有效规则。首次加载失败时拒绝子服连接，修复后重载恢复。
  

模块默认关闭。版本名必须加引号；共用协议的版本会一起匹配，例如 1.20 和 1.20.1。模块只限制能否进入，跨版本协议转换仍需兼容插件。

完整说明：子服客户端版本限制

可选资源包托管

启用后，VTB 在代理机器上提供 HTTP 下载，扫描目录中的 ZIP，并生成 velocityresourcepacks-snippet.yml。每个 ZIP 都有独立的 URL、SHA-1 和 local-path。

1. 
   
2. pack-host:
   
3.   enabled: false
   
4.   bind: 0.0.0.0
   
5.   port: 8765
   
6.   public-url: ""
   
7.   packs-directory: packs
   

复制代码

1. 将 ZIP 放入 packs-directory，默认目录为 plugins/VelocityToolbox/packs。
2. 将 enabled 改为 true。外网使用时配置防火墙或反向代理，并把 public-url 填成玩家能访问的地址。
3. 执行 /vtoolbox reload，将生成的配置片段合并到 VelocityResourcepacks。

由 VelocityResourcepacks 决定把资源包发给哪些玩家，VTB 本身不直接发包。Minecraft 1.20.3+ 客户端可依次叠加多个包，旧客户端只使用生成列表的第一项；生成片段需要 VelocityResourcepacks 1.9.0+。

本插件不会自动配置端口映射、域名或 HTTPS。public-url 留空时会尝试使用第一块局域网 IPv4；不要把 0.0.0.0 当作玩家下载地址。

热管理说明

Velocity 4.0+ 没有公开的插件加载和卸载 API。VTB 会阻止卸载仍被其它插件硬依赖的目标，并尽量清理监听器、任务、命令、消息通道、线程池与类加载器，但不能保证任意第三方插件都能安全热卸载。

简单工具插件适合在测试后使用热重载。权限、协议或数据包、连接管理、大型缓存插件更新后，仍建议完整重启代理。

实现说明：架构文档

语言

language 留空时跟随服务器系统语言，没有对应语言文件时回退中文。也可固定为 zh_cn、en_us，或 lang/ 下的自定义文件名。玩家消息支持 MiniMessage，/vtoolbox reload 会重载语言。

可以在 GitHub Issues 提交问题与建议。如果插件对你有帮助，也欢迎给 项目 点个 Star🌟。

使用统计