VelocityNavigator

插件

· 作者 demonzdevelopment

Velocity 网络的智能大厅路由与故障转移。提供九种负载均衡模式、断路器、会话保持、Java + Bedrock 服务器选择器、派对和队列功能。一个 JAR 文件即可用于代理和后端。

0 本站下载 0 关注 更新于 4 周前

最新 4.6.0 · 26.3 · Bukkit / Folia

一键开服(送7天)

VelocityNavigator

VelocityNavigator banner

面向现代 Velocity 网络的高性能大厅路由、原生可视化选择器、自愈熔断机制、零依赖 NPC 以及实用的代理运维功能。

VelocityNavigator 消除了代理负载均衡中的盲目猜测。它不再盲目地循环连接,而是在路由任何玩家之前,持续评估后端健康状态、服务器容量、维护窗口、排空状态、生命周期状态以及地理延迟。

无论是运行双大厅社区还是拥有数十个区域后端的分布式企业级网络,VelocityNavigator 都能提供弹性且可解释的路由方案,实现无缝扩展。

通用单 JAR 架构:将完全相同的 JAR 文件安装到你的 Velocity 代理上,以及任何你想要部署 NPC、YAML 菜单、Java 库存选择器、PlaceholderAPI 值或后端 Redis 注册的 Paper、Spigot 或 Folia 后端上。无需任何额外的桥接插件。


1. 智能大厅路由与负载均衡

Intelligent lobby routing

简单的轮询路由在生产环境中容易失效。断线、玩家分组以及异构的服务器硬件会导致严重的负载不平衡。VelocityNavigator 提供了 九种专为真实世界代理架构设计的专业路由策略:

  • 两选一算法 (power_of_two):分布式负载均衡的现代行业标准。随机选择两个候选大厅,并将玩家路由至负载较低的一个。在数学上消除了羊群效应和负载倾斜,且无需全局锁。
  • 最少玩家数 (least_players):将新连接直接路由到在线玩家最少的大厅。非常适合确保新玩家进入活跃且人口充实的环境。
  • 加权轮询 (weighted_round_robin):根据分配的服务器权重按比例分发流量。非常适合混合硬件部署(例如,将 3 倍于 8GB VPS 的玩家数量引导至 64GB 独立节点)。
  • 一致性哈希 (consistent_hash):使用带有虚拟节点的 Ketama 哈希环,将玩家 UUID 一致地映射到特定后端。提供确定性路由,同时在添加或移除服务器时仅平滑地重新分配部分键值。
  • 延迟感知 Ping 路由 (latency / ping):主动评估到每个后端的往返 Ping 值,并将传入玩家路由至延迟最低的响应节点。
  • 最少连接数 (least_connections):使用平滑处理的玩家数量和近期连接率对服务器进行评分,以分发突发流量。
  • 地理位置路由 (geo):根据玩家的国家代码和大洲代码,自动将国际玩家路由到区域后端集群。支持 MaxMind GeoLite2、IP-API 以及原生 GeoRestrict 集成。
  • 顺序轮询 (round_robin):在所有健康的候选后端之间进行严格的循环分发。
  • 均匀随机 (random):在所有可用的健康大厅中进行纯随机分发。

粘性会话与玩家亲和性

回归玩家讨厌每次切换世界时被扔进随机大厅。VelocityNavigator 提供了 可配置的玩家亲和性:

  • 在可配置的时间窗口内记住玩家之前所在的大厅。
  • 玩家在重新连接时会自动被路由回他们熟悉的大厅。
  • 通过原子磁盘存储实现跨代理重启的全局持久化。
  • 当首选大厅已满、处于排空状态或正在维护时,立即过期并绕过亲和性限制。

实时路由解释

需要诊断为何某位玩家被路由到特定大厅?运行 /vn debug player <username> 查看实时路由追踪:包括候选池发现、过滤规则(健康、容量、排空、维护、亲和性)、评分计算以及最终选定的目标。


2. 弹性自愈与熔断机制

Resilient routing and circuit breakers

当后端崩溃或出现严重 TPS 下降时,标准代理会让玩家停留在超时界面上等待。VelocityNavigator 充当一个具备企业级防御系统的自愈式流量管理器:

  • 三态断路器(CLOSED ➔ OPEN ➔ HALF-OPEN):每个已注册的后端服务器都维护一个独立的断路器。当连接失败或 ping 超时超过您配置的阈值时,断路器会跳闸至 OPEN 状态,在玩家遭遇连接冻结之前立即切断对该服务器的玩家路由。经过一段冷却窗口后,它进入 HALF-OPEN 状态,通过金丝雀连接测试服务器健康状况,然后再恢复全量流量。
  • 带抖动指数的退避算法:当断开的后端恢复时,重连尝试会以伪随机抖动的方式逐步退避。这防止了毁灭性的“惊群效应”,即数百名玩家同时涌入正在恢复的服务器。
  • 连续多向量健康检查:活动的 ping 检测、TCP 套接字验证、MOTD 查询检查以及后端桥接心跳,使代理状态能够与真实的服务器状况保持持续同步。
  • 零停机排空系统(/vn drain <server>):安全地将大厅下线而无需踢出活跃玩家。排空中的服务器立即停止接收新加入者和 /lobby 转移请求,同时让现有玩家完成他们的游戏。一旦玩家数量归零,即可安全进行维护操作。
  • 空大厅回退机制:如果池中的所有大厅都无法访问,VelocityNavigator 会优雅地将玩家引导至配置的回退服务器,或者提供一个友好且本地化的断开连接通知,而不是显示未格式化的网络异常。

3. 统一的视觉选择器

为所有 Minecraft 客户端平台提供一致导航体验:

Native Java dialog selector

Java inventory selector

Bedrock form selector

  • 原生 Java 对话框 (Minecraft 1.21.6+ & Paper 1.21.7+):
    • 用于大厅选择、派对管理、认证和后端 YAML 菜单的简洁现代原生客户端对话框界面。
    • 无箱子库存杂乱或物品闪烁:大厅作为带有分页和悬停提示的原生对话框按钮显示。
    • 可配置的 UI 模式(auto、dialog、inventory、sign、command、chat),并为旧版客户端和后端提供无缝自动回退。
    • 内置安全性,使用绑定到玩家会话的过期一次性操作令牌。
  • Java 箱子库存 GUI:
    • 支持自定义行数(1–6 行)的多页分页。
    • 感知状态的项目展示:为 Open(开放)、Full(满员)、Draining(排空中)、Maintenance(维护中)和 Offline(离线)大厅配置不同的材质、显示名称和描述文本。
    • 实时玩家计数、容量计数器和动态描述文本占位符。
    • 自动 GUI 刷新间隔,以便在菜单保持打开的同时保持玩家计数准确。
    • 加密令牌验证以防止槽位注入和点击伪造攻击。
  • 原生 Bedrock / Geyser 表单:
    • 专为触摸和控制器导航设计的简洁原生 Floodgate/Geyser 对话框表单。
    • 显示服务器显示名称、实时玩家计数、描述和自定义图标图片。
    • 按下按钮即可直接切换服务器,无需笨拙的 Java GUI 模拟。
  • 交互式 MiniMessage 聊天选择器:
    • 轻量级、零 GUI 文本选择器,可从任何客户端访问。
    • 使用丰富的 MiniMessage 样式格式化,悬停提示显示服务器详情,并支持单击连接命令。
  • 所有选择器的单一服务器配置:
    • 在配置中定义一次服务器元数据:display_name、description、menu_order 和 show_in_menu。更改将立即同步到原生对话框、Java 库存、Bedrock 表单和聊天选择器。

4. 零依赖后端桥接与 NPC

Universal JAR architecture

Interactive NPCs in-game

与其他需要单独 Spigot 插件、协议黑客或像 Citizens 这样重型依赖项的代理导航器不同,VelocityNavigator 完全自包含:

  • 单个通用 JAR:放置在 Velocity 上的完全相同的 JAR 文件可在 Paper、Spigot 和 Folia 后端上运行。
  • 零 NMS 数据包 NPC:
    • 在后端服务器上生成轻量级、高性能的 NPC,无需版本锁定的 NMS 代码。
    • 开箱即用兼容从 Paper 1.16.5 到 26.3 以及 Folia 的所有版本。
    • 通过用户名或 Mojang 纹理属性获取自定义玩家皮肤。
    • 配置灵活的点击动作:连接到服务器、打开自定义菜单或执行代理/后端命令。
    • 在游戏中管理 NPC,使用 /vn npc create <id> <name>、/vn npc skin <id> <player> 和 /vn npc delete <id>。
  • 后端 YAML 菜单 (plugins/VelocityNavigator/menus/*.yml):
    • 在后端构建完整的自定义库存菜单,无需第三方 GUI 插件。
    • 可配置的槽位网格、材质、自定义模型数据、头颅拥有者和声音。
    • 多动作执行:服务器转移、命令、广播消息、子菜单、分页和关闭。
  • PlaceholderAPI 桥接:
    • 在任何后端访问实时代理值:%velocitynavigator_lobby%、%velocitynavigator_party_leader%、%velocitynavigator_party_size%、%velocitynavigator_server_status_<server>% 和 %velocitynavigator_queue_position%。

5. 内置代理系统与社交功能

Built-in proxy systems

VelocityNavigator 包括生产就绪的网络工具,消除了对臃肿第三方附加组件的需求:

  • 容量排队系统:
    • 在玩家激增时绝不拒绝玩家。当所有路由的大厅达到容量上限时,玩家将进入指定保留服务器的优雅排队队列。
    • 显示动态动作栏和标题倒计时,提供实时排队位置和预计等待时间。
    • 为 VIP 和管理员提供优先级绕过权限(velocitynavigator.queue.priority)。
  • 跨服务器组队系统:
    • 完整的队伍管理功能:/party create、/party invite <player>、/party join、/party leave、/party kick 以及 /party disband。
    • 队长跟随:当队伍队长切换到大厅或小游戏时,所有在线的队伍成员会自动一起转移。
    • 私有的跨代理队伍聊天(/party chat <message>)以及开放/仅邀请的队伍模式切换。
  • 网络与单服务器维护:
    • 切换全网维护或锁定单个后端服务器(/vn maintenance set <server> true)。
    • 支持丰富 MiniMessage 和颜色格式化的自定义踢出理由。
    • 基于权限的绕过功能(velocitynavigator.bypass.maintenance),便于管理员进行测试。
    • 动态 MOTD 集成,显示维护徽章和倒计时。

6. 多代理集群与 Redis 同步

在 BGP Anycast IP 或 DNS 轮询背后运行多个 Velocity 代理?VelocityNavigator 通过 Redis 提供内置的分布式集群功能:

  • 跨代理健康与电路同步:断路器跳闸状态和后端健康快照在每个代理节点间以毫秒级速度同步。
  • 集群级玩家亲和性:粘性会话在代理之间持久化,确保返回的玩家无论连接到哪个代理,都能正确连接到大厅。
  • 动态服务器注册:后端可以通过 Redis Pub/Sub 动态宣布自身存在,在启动时向代理池注册,在关闭时注销,无需编辑代理配置文件。
  • 经过身份验证且通道隔离:使用可配置的通道和键前缀的安全 Redis 身份验证,适用于多网络环境。

7. 安全与认证引擎

Defensive design and security

利用现代防御性安全性保护您的代理网络:

  • Argon2id 密码哈希:使用固定的 64 MiB 内存成本、三次迭代和四个并行度。验证传统的加盐 SHA-256 凭据,并在配置了 Argon2id 且登录成功后将其升级。
  • 暴力破解速率限制:按账户跟踪失败次数,实施临时账户锁定和全局尝试次数限制,从而限制密码猜测。重新连接到同一代理时会保留账户锁定状态。
  • 等候大厅隔离:未认证的玩家被隔离在一个轻量级的等候大厅中。在认证成功之前,完全禁止玩家移动、方块交互、物品栏访问以及聊天命令(除 /login 和 /register 外)。
  • 原生 Bedrock 认证表单:通过 Floodgate 连接的 Bedrock 玩家将收到原生的模态对话框用于注册和密码输入,而不是在开放的聊天中输入密码。
  • 过期的会话令牌:代理本地的会话会在短时间内记住已认证的玩家,以便他们快速重新连接到同一代理,TTL 可在配置中设定。

8. 实时运维与可观测性

Operations dashboard and metrics

HTML dashboard preview

  • 嵌入式 HTML 运维仪表板:
    • 内置轻量级 Web 仪表板,运行在其专用的端口上。
    • 实时大厅状态表,显示活跃玩家数量、最大容量、延迟和电路健康状况。
    • 可视化路由分布图表、粘性会话计数器和加入/离开指标。
    • 通过 HTTP Bearer Token 身份验证进行安全保护。
  • Prometheus 与 Grafana 指标:
    • 原生 /metrics 端点开箱即用地导出 Prometheus 指标:路由计数、电路跳闸、健康检查延迟、队伍数量和队列深度。
    • 直接导入 Grafana 以实现 24/7 网络监控。
  • 动态 MiniMessage MOTD 轮换:
    • 动态 MOTD 管理器支持随机、顺序或按计划时间窗口的轮换。
    • 嵌入动态玩家数量、自定义十六进制颜色、渐变和维护状态行。
  • 自文档化配置与验证:
    • /vn config validate 执行深层语法和语义检查,并提供基于莱文斯坦距离的拼写错误建议。
    • /vn menu validate 在玩家遇到损坏的菜单之前,审计 GUI 项目槽位、材质、重复键和占位符。

9. 全球本地化

Localization and languages

开箱即用部署 15 种捆绑语言翻译:

语言 代码 语言 代码 语言 代码
English en Spanish es German de
French fr Russian ru Portuguese (BR) pt_br
Chinese (Simp.) zh_cn Japanese ja Korean ko
Italian it Dutch nl Polish pl
Turkish tr Arabic ar Hindi hi
  • 可以添加自定义 .properties 文件到 plugins/velocitynavigator/languages/ 目录,无需重新编译。
  • 支持通过 /vn reload 实现完全热重载。

10. 多引擎存储架构

将玩家数据、粘性会话和认证凭据存储在与您基础设施相匹配的存储引擎中:

  • 纯 JSON 文件:简单、零配置的存储方案,适用于小型网络。
  • SQLite:嵌入式 SQL 数据库,无需配置或外部数据库服务器。
  • MySQL & MariaDB:高性能数据库存储,支持 HikariCP 连接池和自动架构迁移。
  • PostgreSQL:用于大型网络部署的稳健企业级数据库后端。

11. 快速入门指南

在五分钟之内即可上手运行:

  1. 下载 VelocityNavigator-4.6.0.jar 并将其放入 Velocity 代理的 plugins/ 目录中。
  2. 启动一次代理以生成默认配置文件,然后停止代理。
  3. 打开 plugins/velocitynavigator/navigator.toml 并列出你的大厅服务器(名称需与 velocity.toml 中的匹配):
[routing]
selection_mode = "power_of_two"
balance_initial_join = true
default_lobbies = ["lobby-1", "lobby-2", "lobby-3"]

[routing.fallback]
strategy = "disconnect"
message = "<red>所有大厅当前已满或正在维护。</red>"

[health]
check_interval_seconds = 5
timeout_millis = 2000
circuit_breaker_threshold = 3
circuit_breaker_reset_seconds = 30
  1. 从控制台运行 /vn config validate 以验证你的配置。
  2. 启动代理并在游戏中输入 /lobby 来测试路由功能!

想要添加后端功能? 将完全相同的 JAR 文件复制到每个 Paper、Spigot 或 Folia 后端的 plugins/ 文件夹中,以便在这些服务器上启用 NPC、YAML 菜单或 Java 物品栏选择器。


12. 命令与权限参考

管理命令

命令 权限 描述
/vn health velocitynavigator.admin 聚合代理诊断信息和电路健康状况概览
/vn servers velocitynavigator.admin 分页显示服务器健康状态、容量、排水状态和电路信息
/vn debug player <player> velocitynavigator.admin 实时追踪特定玩家的路由决策过程
/vn drain <server> velocitynavigator.admin 切换排水模式,安全疏散后端服务器而不踢出玩家
/vn maintenance [server] [on/off] velocitynavigator.admin 切换全网或单服务器的维护模式
/vn affinity clean velocitynavigator.admin 手动清除过期的粘性会话映射
/vn bridge status velocitynavigator.admin 显示检测到的 Paper/Folia 后端桥接连接状态
/vn config validate velocitynavigator.admin 审计配置文件是否存在语法或拼写错误
/vn menu validate velocitynavigator.admin 验证自定义菜单项、槽位和材质
/vn reload velocitynavigator.admin 热重载所有配置、菜单和语言包

玩家命令

命令 权限 描述
/lobby 或 /hub none (可配置) 将玩家路由到最佳可用且健康的大厅
/lobby menu none (可配置) 打开交互式服务器选择器
/party none (可配置) 访问跨服务器小队管理系统

13. 兼容性矩阵

Compatibility matrix

  • 代理平台:
    • Velocity 3.4.x (Java 17+)
    • Velocity 3.5.x (Java 21+)
    • Velocity 4.0.0 (Java 25)
  • 后端平台(可选桥接):
    • Paper 1.16.5 – 26.3+
    • Spigot 1.16.5 – 26.3+
    • Folia 1.20.x – 26.3+
  • 生态系统集成:
    • GeyserMC & Floodgate(原生 Bedrock 表单及 Floodgate UUID 转换)
    • PlaceholderAPI(丰富的后端占位符)
    • GeoRestrict & MaxMind GeoLite2(地理路由)
    • Prometheus & Grafana(指标监控)

14. 文档与社区支持

VelocityNavigator footer


由 Nexeu Hosting 赞助

Nexeu Hosting

高性能、经济实惠的 Minecraft 托管服务,配备高端 NVMe 硬件、DDoS 防护以及 24/7 技术支持。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源