为 Minecraft Java 玩家选择 Velocity 入口。
插件把目标入口的域名和端口发送给客户端。客户端再连接目标入口。
这不是后端传送插件。 插件不保存跨代理的游戏会话。背包、坐标和其他游戏数据需要后端提供同步。
- 为不同运营商的玩家提供不同入口。
- 按域名、地理位置或玩家标识（UUID）选择入口。
- 记住玩家选择，并在持续高延迟时提供其他入口建议。
你必须先准备可用的代理入口。插件不创建代理，不提供网络加速，也不提供防 DDoS 服务。
| 名称 | 含义 |
|---|---|
| 入口 | 客户端能访问的代理域名和端口。 |
| 线路 | 插件内的一条入口配置。例如 dx。 |
| 后端 | 代理连接的 Minecraft 游戏服务器。 |
| Transfer | 让客户端连接另一个入口的协议。 |
| 历史偏好 | 插件按 UUID 保存的线路选择。不是到达确认。 |
矩形表示操作。菱形表示判断。动画沿连线显示处理顺序。
运行 /st list 查看有权限的线路。运行 /dx 等线路命令选择入口。插件检查条件后发送 Transfer。
插件按顺序检查登录规则。首条匹配规则决定动作。动作可以是转移、拒绝或跳过。
让玩家连接公开代理。配置防火墙，只允许可信代理访问后端。为后端配置安全转发。
隔离由部署配置实现，不是插件内置功能。 插件不创建防火墙规则。它不隐藏玩家 IP，也不隐藏 Transfer 目标代理的地址。
插件采样玩家到当前代理的延迟。持续高延迟时，插件提示可尝试的入口。玩家决定是否切换。
建议参考运营商信息。插件不测量所有候选入口，也不自动选择最快入口。
插件把玩家提交的线路选择写入本机 H2 数据库。下次普通登录时，插件可以读取偏好。读取后仍需检查版本、权限和转移状态。
规则优先于历史偏好。不同代理的本地数据库不会自动同步。
插件检查客户端版本、线路权限和当前转移状态。自动转移还检查 Transfer 握手、冷却和近期失败记录。
客户端已经使用目标入口时，插件不再发送请求。客户端使用 Transfer 握手进入时，插件不再自动转移它。
- 默认构建使用 Java 21 和 Velocity 3.5.1 API。
- Velocity 4.2.0 API 构建已验证。运行 Velocity 4.2.0 需要 Java 25。
- 线路切换需要 Minecraft Java 版 1.20.5 或更高版本。最低协议为 766。
- 旧客户端可进入默认后端。插件不会向它们发送 Transfer。
- Floodgate 玩家不使用本插件的登录路由和延迟采样。
GeoIP（IP 地理位置查询）使用 ip2region 2.7.0 的 IPv4 数据库。IPv6 地址不提供地理条件。数据库不可用时，域名、UUID 和历史规则仍可工作。插件不会把未知位置当作海外。
- 把
simpletransfer-1.7.jar放入 Velocity 的plugins/目录。 - 启动 Velocity。
- 编辑
plugins/simpletransfer/config.conf。 - 编辑
plugins/simpletransfer/rules.conf。 - 将示例域名替换为实际入口。
- 运行
/st reload all。
如果目标入口也是 Velocity，在目标代理的 velocity.toml 中启用 Transfer：
[advanced]
accepts-transfers = true为各入口配置正确的认证方式和转发密钥。需要保留跨代理的游戏数据时，配置后端数据同步。
config.conf 使用 HOCON。下面的配置提供 BGP、电信和 VIP 入口。
settings {
ping_threshold = 150
check_interval = 30
ping_monitor_enabled = true
rules_enabled = true
rules_file = "rules.conf"
transfer_timeout_protection {
enabled = true
fallback_server = "default.bgp"
timeout = 4000
failure_memory_duration = 300
}
}
permission_groups {
default {
permission = ""
servers {
bgp {
host = "bgp.example.com"
port = 25565
display_name = "BGP"
description = "默认入口"
}
dx {
host = "dx.example.com"
port = 25565
display_name = "电信"
description = "电信入口"
}
}
}
vip {
permission = "simpletransfer.group.vip"
servers {
vip {
host = "vip.example.com"
port = 25565
display_name = "VIP"
description = "VIP 入口"
}
}
}
}线路名称必须全局唯一。只使用小写字母、数字、下划线或连字符。不要使用保留名称 st、transfer 或 simpletransfer。
空的 permission 允许所有玩家使用该组线路。VIP 组需要 simpletransfer.group.vip 权限。
插件对手动转移、自动规则、历史偏好和管理员在线转移使用相同的线路权限。管理员权限不会自动赋予目标玩家 VIP 权限。
其他插件占用线路命令时，插件不会覆盖该命令。管理员仍可使用 /st transfer。
rules.conf 的根节点必须包含 rules 数组。不要使用裸数组。
下面的规则先拒绝错误域名，再为没有历史偏好的电信玩家选择 dx。
rules = [
{
enabled = true
name = "拒绝错误域名"
conditions {
hostname = "!play.example.com|bgp.example.com|dx.example.com|vip.example.com"
}
action { reject = "请使用正确的服务器域名" }
},
{
enabled = true
name = "电信用户首选入口"
conditions {
isp = "电信"
has_history = false
}
action { transfer = "dx" }
}
]支持 country、province、isp、hostname、uuid 和 has_history。
同一规则中的所有条件必须满足。字符串中的 | 表示任一值匹配。字符串开头的 ! 表示对整组值取反。
未知地理位置不满足地理条件。此限制也适用于否定条件。
hostname 不区分大小写。未写端口时，插件按 25565 匹配。插件读取客户端的虚拟主机地址。该地址不一定等于 DNS 或 SRV 解析结果。
uuid 可以使用字符串、| 分隔的字符串或字符串数组。has_history 必须使用布尔值。
每条规则只能配置一个动作：
| 动作 | 结果 |
|---|---|
transfer = "dx" |
检查转移条件，然后请求客户端连接该线路。 |
reject = "拒绝理由" |
拒绝本次登录。理由使用纯文本。 |
skip = true |
停止本轮规则和历史自动转移。 |
首条匹配规则生效。它的转移检查失败时，插件也不会继续检查后续规则。
没有匹配规则时，插件可以使用历史偏好。历史线路已删除时，插件可以使用 fallback_server。备用线路仍需通过转移检查。
启用 rules_enabled 才会执行规则。域名拒绝规则不需要地理查询结果。Transfer 入站不再自动转移，但仍会检查适用的拒绝规则。
| 命令 | 用途 |
|---|---|
/st help |
查看帮助。 |
/st list 或 /transfer |
查看有权限的线路。 |
/<线路名> |
选择该线路。例如 /dx。 |
/st ping |
查看当前延迟和采样统计。 |
/st enable、/st disable |
开关个人延迟提醒和欢迎消息。 |
以下命令需要 simpletransfer.admin。控制台可以使用它们。
| 命令 | 用途 |
|---|---|
/st reload [all|config|rules] |
重载配置或规则。默认重载全部。 |
/st rules |
查看规则。 |
/st check [玩家] |
预览登录路由。不发送 Transfer。 |
/st status <玩家> |
查看在线玩家状态。 |
/st transfer <玩家名或UUID> <线路> |
转移在线玩家，或修改离线玩家偏好。 |
离线修改可以直接使用 UUID。按名称修改时，数据库必须已有该名称记录。
默认 check_interval 是 30 秒。默认 ping_threshold 是 100 毫秒。快速配置示例将阈值改为 150 毫秒。
插件在登录 10 秒后开始采样。它保留最近 20 个有效样本。至少积累 15 个样本后才判断警告。警告冷却是 120 秒。默认间隔通常需要数分钟积累样本。
插件不向海外玩家或 hy 线路自动发送延迟警告。建议最多显示三条有权限的线路。建议不等于候选入口的实测延迟。
warning_message 支持 {ping} 替换。该消息使用纯文本。插件不解析 MiniMessage 或传统颜色代码。
欢迎消息提供线路、延迟和关闭提醒按钮。设置 welcome_message_enabled = false 可关闭全局欢迎消息。设置 ping_monitor_enabled = false 可暂停全局采样。
Velocity 启动时保留像素名称日志。设置 startup_banner_enabled = false 可关闭它。
使用 /st check [玩家] 预览首条匹配规则、历史候选和转移检查。该命令不切换玩家，也不写入线路偏好。
插件先解析完整配置，再发布配置快照。语法错误、重复线路、无效端口和错误规则会保留旧配置。启用的转移规则和备用线路必须指向已配置线路。
配置重载成功后，插件更新线路命令和监控间隔。重载失败时，检查控制台错误。修正文件后再次重载。
插件在配置快照中建立入口地址索引。采样不逐条遍历线路。重载会替换索引，并淘汰旧监控任务代次。冷却期仍保存延迟样本，但跳过警告分析。
登录处理异常或后台队列满时，插件拒绝本次登录，并提示玩家重试。插件不会绕过拒绝规则。
本机 playerdata.mv.db 保存 UUID、历史线路和最近用户名。数据库记录提交的选择，不记录目标代理确认到达。
各代理的数据库、消息和个人监控开关不会自动同步。个人开关使用有界缓存。最长闲置 30 天后会过期。进程重启或缓存淘汰后，个人开关恢复默认。历史线路保留在 H2 中。
首次启动会下载兼容 ip2region 2.7.0 的 IPv4 数据库。下载使用超时、大小限制和临时文件验证。已有数据库不兼容时，先备份，再替换。插件不会静默覆盖它。
transfer_timeout_protection.timeout 使用毫秒。它控制源代理等待客户端离开的请求锁时间。超时后，插件释放请求锁。启用失败保护时，插件暂时记住该玩家的失败线路。
源代理无法确认玩家是否到达另一台代理。客户端离开后，插件无法把它拉回。不要把请求提交当作切换成功。
每个转移请求具有独立身份。取消、失败、断线或关闭后，插件清理该请求及其超时任务。旧超时不会解锁替代请求。重复允许事件不会重复写入历史偏好。
fallback_server 用于历史线路失效时的备用选择。它不是目标代理故障后的自动返回机制。
后端踢出由 Velocity 处理。在 velocity.toml 中配置后端连接超时和尝试顺序。插件不会通过虚拟后端或立即断开连接来模拟跨代理故障切换。
使用 Java 21 和 Maven 3.9 或更高版本：
mvn -B -ntp clean verify产物是 target/simpletransfer-1.7.jar。部署此文件，不要部署 original- 开头的 JAR。
产物包含重定位后的 H2 和 ip2region。Velocity 提供 API、Adventure 和 Configurate。插件不重复打包这些依赖。
使用 Java 25 检查 Velocity 4.2.0 API 构建：
mvn -B -ntp -Dvelocity.version=4.2.0 clean verify仓库没有持久化测试用例。Maven 构建成功不代表真实客户端转移成功。
上线前检查旧客户端、线路权限、取消请求、重复请求和错误配置重载。再用真实客户端测试两台代理之间的重连。
动画维护与写作约定
动画只展示六个核心流程。不展示启动名称、热重载或诊断命令。
每个流程使用相同的矩形、菱形和细线。每个主题使用三种基色：背景、文字和连线。文字边缘使用抗锯齿过渡色。动画不使用网格、阴影、装饰编号或进度条。
每个流程提供浅色和深色 GIF。每个主题也提供完整静态 PNG。图片声明根据系统主题选择版本，并为减少动态效果设置提供静态图。若查看器不支持这些声明，直接打开同名 PNG。
需要 Python 3.10 或更高版本、Pillow 和中文字体。Windows 默认使用微软雅黑。Linux 优先使用 Noto Sans CJK。
python -m pip install Pillow
python scripts/render_readme_animations.py
python scripts/render_readme_animations.py --only rule-matching
python scripts/render_readme_animations.py --theme dark使用 --font 和 --font-bold 指定字体。生成文件保存在 docs/assets/。渲染脚本不是插件运行依赖。
本文使用短句、主动语态和一致术语。操作步骤使用明确动词。限制条件紧邻对应功能。
ASD-STE100 是英文受控语言标准。本文是中文说明，只借鉴其写作原则，不声明符合该标准。
开发说明与后续方向
Java 21 / Velocity 3.5.1 是默认构建基线。Java 25 / Velocity 4.2.0 是已验证的另一构建组合。
SimpleTransfer 管理生命周期。PlayerConnectionListener 处理事件。TransferService 统一转移检查。PlayerLoginMiddleware 决定登录动作。ConfigManager 与 RulesLoader 分别处理配置快照和规则。
插件使用 EventTask 等待登录路由。它使用 HandshakeIntent.TRANSFER 识别 Transfer 入站。它使用 PreTransferEvent 观察其他插件取消或改写请求。它把目标域名留给客户端解析。
参考：PaperMC 发布信息、Velocity 事件说明、ip2region 2.7.0 数据。
- 跨代理共享偏好。此功能需要共享存储或可信的数据交换机制。
- 真实候选入口测速。此功能需要测量玩家到各入口的网络路径。
- IPv6 GeoIP。此功能需要兼容 IPv6 的查询引擎和数据库。
这些是后续方向，不是当前功能。