VelocityToolbox ——插件管理、资源包托管、入口域名、多版本限制
本帖最后由 polang 于 2026-9-6 18:03 编辑VelocityToolbox
Velocity 运维工具箱：运行时插件管理、入口域名排查、子服客户端版本限制，以及可选的资源包 HTTP 托管。
https://raw.githubusercontent.com/polang233/VelocityToolbox/main/assets/logo-256.png
项目源码 | 下载插件 | 问题与建议
运行环境
[*]Velocity 4.0 及以上。
[*]Java 25 及以上。
[*]无硬前置。资源包分配可搭配 VelocityResourcepacks 1.9.0+。
能做什么
[*]运行时插件管理：加载、卸载或重载 plugins/ 里的 Velocity 插件。操作前可检查依赖与风险，操作后报告监听器、任务、命令等资源的清理结果。
[*]排查入口域名：/vtb vhosts 按玩家加入时使用的域名和端口分组。点击入口行展开玩家名与延迟，悬停查看详情。
[*]限制子服客户端版本：为不同子服设置最低/最高版本、允许列表和禁止列表。直接使用 Velocity 的客户端协议 API，无需 ViaVersion。默认关闭，支持配置重载。
[*]托管多个资源包：扫描本地 ZIP 文件，提供 HTTP 下载，计算 SHA-1，并生成支持多包叠加的 VelocityResourcepacks 配置片段。HTTP 服务默认关闭。
功能展示
按入口域名查看玩家人数和延迟：
https://raw.githubusercontent.com/polang233/VelocityToolbox/main/assets/screenshot-vhosts.jpg
热加载插件：
https://raw.githubusercontent.com/polang233/VelocityToolbox/main/assets/screenshot-plugin-load.png
热卸载插件并查看清理结果：
https://raw.githubusercontent.com/polang233/VelocityToolbox/main/assets/screenshot-plugin-unload.png
配置资源包托管并由 VelocityResourcepacks 分配后，玩家看到的下载提示：
https://raw.githubusercontent.com/polang233/VelocityToolbox/main/assets/screenshot-packs.png
安装
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，再授予对应子命令权限：
velocitytoolbox.command.info
velocitytoolbox.command.packs
velocitytoolbox.command.vhosts
velocitytoolbox.command.reload
插件管理还需要父权限 velocitytoolbox.command.plugin，以及对应操作权限：
velocitytoolbox.command.plugin.list
velocitytoolbox.command.plugin.inspect
velocitytoolbox.command.plugin.load
velocitytoolbox.command.plugin.unload
velocitytoolbox.command.plugin.reload
例如，只允许检查插件风险，需要同时授予 velocitytoolbox.command、velocitytoolbox.command.plugin 和 velocitytoolbox.command.plugin.inspect。帮助只显示执行者有权使用的命令。
子服客户端版本限制
https://raw.githubusercontent.com/polang233/VelocityToolbox/main/assets/screenshot-server-versions.png
在 config.yml 的 server-versions 段中配置。以下示例只允许指定版本进入 survival，并给 minigame 设置最低版本和禁止项：
server-versions:
enabled: true
servers:
survival:
allow: ["1.12.2", "1.20.1"]
minigame:
min: "1.18"
max: max
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。
pack-host:
enabled: false
bind: 0.0.0.0
port: 8765
public-url: ""
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🌟。
使用统计
https://bstats.org/signatures/velocity/VelocityToolbox.svg
页: [1]