警告:下载此插件前请知悉
在下载此插件之前,请注意,更改 UUID 可能导致现有在线玩家数据的丢失。
请从官方 Minecraft 网站 购买正版 Minecraft。该插件作者仅认可和支持正版的 Minecraft。
ahiropg-online
这是一个轻量级的 Velocity 代理插件,它能够在离线模式代理上为正版玩家提供其真实的 Mojang UUID,而未拥有 Mojang 会话的玩家则获得通常的离线 UUID。
每个连接仅在登录时执行一次任务。
它解决的问题
运行 online-mode=false 的代理是接受未拥有 Minecraft 账户玩家的唯一方式,但它有一个副作用:Velocity 会给所有人分配一个离线 UUID(基于 OfflinePlayer:<name> 计算的哈希值)。
对于确实拥有游戏的玩家来说,这会导致所有依赖其 Mojang UUID 的功能失效:排名、游戏时长、经济余额、领地所有权、白名单、跨服务器玩家数据等。将代理切换为 online-mode=true 可以解决这些问题,但会立即阻止所有未通过身份验证的玩家进入。
此插件保持了混合模式的设置。正版玩家保留其 Mojang UUID;其他玩家保留离线 UUID。
| 登录者 |
转发给后端的 UUID |
| 正版账户,正版客户端 |
真实的 Mojang UUID,例如 5c89121b-4e93-46bd-80c9-3022a01c5bbd |
| 正版账户,但本次以离线模式登录 |
离线 UUID,例如 0b5461e0-ea56-3019-8b05-6f4330752d8b |
| 无 Mojang 账户的玩家 |
离线 UUID |
| 第三方认证启动器(皮肤站) |
离线 UUID |
如何判定是否为正版
自 Minecraft 1.20.2 起,客户端在登录时总是发送自己的 UUID。Velocity 将其暴露为 PreLoginEvent#getUniqueId(),并揭示了客户端的意图:
| 客户端 |
声明内容 |
| 拥有有效会话的正版启动器 |
账户的真实 Mojang UUID |
| 离线启动器 |
自行计算的离线 UUID |
| 第三方认证启动器 |
该站点自己的 UUID |
因此,插件会将声明的 UUID 与该名称对应的离线 UUID 进行比较:
- 相等 → 客户端意图以离线模式加入 → 允许作为离线玩家进入
- 等于该名称的 Mojang UUID → 客户端声称自己是正版 → 即使代理处于离线状态,也会告诉 Velocity 验证此单个连接(调用
forceOnlineMode());真实的会话会产生正版 UUID,伪造的会话会在加密握手阶段失败并被 Velocity 断开连接
- 其他任何情况 → 可配置的后备处理;默认情况下,玩家会被允许以离线模式进入而非被踢出
会话验证本身由 Velocity 完成,而非此插件。该插件从不伪造登录;它仅决定某个连接应使用哪种登录模式。
由于准入取决于声明的 UUID 而非名称,因此即使某玩家的名称恰好与正版账户匹配,也不会被阻止,也不会意外地被当作正版玩家处理。他们发送离线 UUID,并像其他任何人一样走离线流程。
将 UUID 传递给你的后端
路径 1 — 登录握手,无需安装任何东西。 当 Velocity 连接到后端时,它会转发包含 UUID 的玩家 GameProfile,而插件已经将该 UUID 设置为其判定结果。你的后端从第一个 tick 开始就获得了正确的 UUID。如果你的后端已经读取 GameProfile UUID(BungeeGuard 风格的设置,bungeecord: true + 现代转发机制),你在此处已完成配置。
路径 2 — 插件消息,适用于希望双重检查或存储判定结果的后端插件。一旦玩家进入后端,插件会推送 ahiropg:online:
| 字段 |
类型 |
| 协议版本 |
byte,当前为 1 |
| 玩家名称 |
UTF |
| UUID |
UTF,带连字符格式 |
| premium |
boolean |
UTF 是 DataOutputStream#writeUTF(2 字节长度 + UTF-8 字节)。接收端代码:
public final class OnlineBridge extends JavaPlugin implements PluginMessageListener {
private static final String CHANNEL = "ahiropg:online";
@Override
public void onEnable() {
getServer().getMessenger().registerIncomingPluginChannel(this, CHANNEL, this);
}
@Override
public void onPluginMessageReceived(String channel, Player player, byte[] message) {
if (!CHANNEL.equals(channel)) {
return;
}
try (DataInputStream in = new DataInputStream(new ByteArrayInputStream(message))) {
byte version = in.readByte();
String name = in.readUTF();
UUID uuid = UUID.fromString(in.readUTF());
boolean premium = in.readBoolean();
getLogger().info(name + " uuid=" + uuid + " premium=" + premium);
} catch (IOException e) {
getLogger().warning("Failed to parse an ahiropg:online message: " + e);
}
}
}
通道名称是可配置的,因此需同时修改两端。
记录与会话掉线提示
每次登录都会被记录在 plugins/ahiropg-online/users.yml 中:包括名称、是否曾通过正版验证、其 Mojang UUID、其离线 UUID、实际转发的 UUID,以及首次/最后出现的时间戳。文件会通过定时器批量刷新并在关闭时刷新,通过临时文件加原子移动的方式写入。
如果一个账户此前曾以正版模式加入,但本次以离线模式加入,其所有者会收到一条可配置的聊天消息——常见原因是会话过期,或启动器静默切换到了离线登录。从未以正版模式加入过的玩家不会看到此提示。
配置
插件在首次启动时会创建 plugins/ahiropg-online/config.yml。每个键都在文件中有所文档说明;其中重要的包括:
| 键 |
默认值 |
含义 |
session-policy |
HYBRID |
HYBRID 按连接决定策略;PROXY 不执行任何操作,并遵循 velocity.toml 的设置 |
hybrid.allow-offline-connections |
true |
设置为 false 以拒绝离线连接,运行仅限正版(premium-only)的网络 |
hybrid.legacy-client-policy |
offline |
对 1.19.2 及更早版本客户端的处理方式,这些客户端声明没有 UUID |
hybrid.mojang-unavailable-policy |
offline |
当无法访问 Mojang API 时的回退策略 |
forward.channel |
ahiropg:online |
插件消息通道 |
forward.on-server-switch |
true |
在每次后端切换时再次推送身份标识 |
forward.override-uuid |
true |
强制将转发的 GameProfile UUID 应用于判定结果 |
offline-notice.enabled |
true |
启用“你的会话已掉线”提示消息 |
offline-notice.message |
— |
支持 %player%、%uuid%、& 颜色代码和 MiniMessage 格式 |
无命令,无权限——配置即整个接口。
此插件不做的事情
直白地说,以免有人产生误解:
- 它不会将你的代理切换到在线模式。 它仅要求 Velocity 验证那些声称是正版的单个连接。
- 除非你设置
allow-offline-connections: false,否则它不会阻止没有账号的玩家。 默认情况下,网络保持混合状态。
- 它不是认证插件。 它不为离线玩家添加密码或双重验证(2FA)。它也不会检查你的后端服务器上的任何东西。
- 它不能保护免受被盗的正版账号侵害。 如果有人拥有真实的会话,Velocity 会像原版在线模式一样验证他们。
- 它不能让盗版客户端变成正版。 没有任何东西可以做到这一点;伪造的 UUID 只会导致连接被强制进入一个无法完成的握手过程。
安装要求与步骤
- Velocity 3.x(基于
velocity-api 3.4.0 构建),Java 17+
- 将 jar 文件放入代理的
plugins/ 目录,启动一次,调整 config.yml,然后重启
- 后端服务器无需安装插件即可接收正确的 UUID;如果你需要额外数据,只需读取插件消息即可
兼容性说明
- 1.19.2 及更早版本的客户端 不发送 UUID,因此无法确定意图;它们会回退到
legacy-client-policy。
- 第三方认证启动器 被视为离线(它们发送自己的 UUID),因此如果你使用此类启动器,请确保你的后端接受离线 UUID。
- Mojang API 速率限制: 查找失败时会根据
hybrid.mojang-unavailable-policy 进行回退并记录警告。离线连接永远不会等待 API;查找操作异步运行并进行缓存。
- 大小写敏感性: 离线 UUID 源自客户端登录时使用的确切名称。对于此插件以及 Velocity 本身而言,
NapCatt_owo 和 Napcatt_owo 是不同的玩家。
源代码与许可证
源代码、问题追踪器和发行说明:
采用 MIT 许可证授权。
WARNING:before download this plugin
Before downloading this plugin, please be aware that changes to UUIDs may result in the loss of existing online player data.
Please purchase the legitimate version of Minecraft from the official Minecraft website. The plugin author endorses and recognizes only legitimate copies of Minecraft.
ahiropg-online
A small Velocity proxy plugin that gives premium players their real Mojang UUID
on an offline-mode proxy, while players without a Mojang session still get the
usual offline UUID.
One job, done at login, per connection.
The problem it solves
Running a proxy with online-mode=false is the only way to accept players who do not
own a Minecraft account, but it has a side effect: Velocity hands everyone an
offline UUID (a hash of OfflinePlayer:<name>).
For players who do own the game, that breaks everything keyed to their Mojang UUID:
ranks, playtime, economy balances, region ownership, whitelists, cross-server player
data. Switching the proxy to online-mode=true fixes that and immediately locks out
every unauthenticated player.
This plugin keeps the mixed-mode setup. Premium players keep their Mojang UUID;
everyone else keeps the offline UUID.
| Who logs in |
UUID forwarded to your backend |
| Premium account, premium client |
the real Mojang UUID, e.g. 5c89121b-4e93-46bd-80c9-3022a01c5bbd |
| Premium account, but logging in offline this time |
the offline UUID, e.g. 0b5461e0-ea56-3019-8b05-6f4330752d8b |
| Player with no Mojang account |
the offline UUID |
| Third-party auth launcher (skin sites) |
the offline UUID |
How it decides who is premium
Since Minecraft 1.20.2, a client always sends its own UUID during login. Velocity
exposes it as PreLoginEvent#getUniqueId(), and it reveals what the client intends:
| Client |
Declares |
| Premium launcher with a valid session |
the account's real Mojang UUID |
| Offline launcher |
the offline UUID it computed itself |
| Third-party auth launcher |
that site's own UUID |
So the plugin compares the declared UUID against the offline UUID for that name:
- equal → the client means to join offline → allowed in as an offline player
- equals the Mojang UUID of that name → the client claims to be premium → Velocity
is told to verify this one connection even though the proxy is offline
(
forceOnlineMode()); a real session yields the premium UUID, a forged one fails the
encryption handshake and Velocity disconnects it
- anything else → configurable fallback; by default the player is let in as offline
rather than kicked
Session verification itself is done by Velocity, not by this plugin. The plugin
never fakes a login; it only decides which login mode a connection gets.
Because admission depends on the declared UUID rather than on the name, a player whose
name happens to match a premium account is not blocked and not accidentally
treated as premium. They send the offline UUID and take the offline path like anyone
else.
Getting the UUID to your backend
Route 1 — the login handshake, nothing to install. When Velocity connects to a
backend it forwards the player's GameProfile including the UUID, and the plugin has
already set that UUID to its verdict. Your backend has the correct UUID from the first
tick. If your backend already reads the GameProfile UUID (BungeeGuard-style setups,
bungeecord: true + modern forwarding), you are done at this point.
Route 2 — a plugin message, for backend plugins that want to double-check or store
the verdict. Once the player is on a backend, the plugin pushes ahiropg:online:
| Field |
Type |
| protocol version |
byte, currently 1 |
| player name |
UTF |
| UUID |
UTF, dashed form |
| premium |
boolean |
UTF is DataOutputStream#writeUTF (2-byte length + UTF-8 bytes). Receiving side:
public final class OnlineBridge extends JavaPlugin implements PluginMessageListener {
private static final String CHANNEL = "ahiropg:online";
@Override
public void onEnable() {
getServer().getMessenger().registerIncomingPluginChannel(this, CHANNEL, this);
}
@Override
public void onPluginMessageReceived(String channel, Player player, byte[] message) {
if (!CHANNEL.equals(channel)) {
return;
}
try (DataInputStream in = new DataInputStream(new ByteArrayInputStream(message))) {
byte version = in.readByte();
String name = in.readUTF();
UUID uuid = UUID.fromString(in.readUTF());
boolean premium = in.readBoolean();
getLogger().info(name + " uuid=" + uuid + " premium=" + premium);
} catch (IOException e) {
getLogger().warning("Failed to parse an ahiropg:online message: " + e);
}
}
}
The channel name is configurable, so change both sides together.
Recording and the "session dropped" notice
Every login is recorded in plugins/ahiropg-online/users.yml: name, whether the account
has ever passed premium verification, its Mojang UUID, its offline UUID, the UUID
actually forwarded, and first/last seen timestamps. The file is flushed in batches on a
timer and on shutdown, written through a temp file plus an atomic move.
If an account has joined as premium before but is offline this time, its owner
receives a configurable chat message — the usual cause is an expired session, or a
launcher that silently switched to offline login. Players who have never joined as
premium never see it.
Configuration
The plugin creates plugins/ahiropg-online/config.yml on first start. Every key is
documented in the file; the important ones:
| Key |
Default |
Meaning |
session-policy |
HYBRID |
HYBRID decides per connection; PROXY does nothing and follows velocity.toml |
hybrid.allow-offline-connections |
true |
set false to reject offline connections and run a premium-only network |
hybrid.legacy-client-policy |
offline |
what to do with clients 1.19.2 and older, which declare no UUID |
hybrid.mojang-unavailable-policy |
offline |
fallback when the Mojang API cannot be reached |
forward.channel |
ahiropg:online |
plugin messaging channel |
forward.on-server-switch |
true |
push the identity again on every backend switch |
forward.override-uuid |
true |
force the forwarded GameProfile UUID to the verdict |
offline-notice.enabled |
true |
enable the "your session dropped" message |
offline-notice.message |
— |
supports %player%, %uuid%, & colour codes and MiniMessage |
No commands, no permissions — configuration is the whole interface.
What this plugin does not do
Stated plainly, so nobody buys into the wrong thing:
- It does not switch your proxy to online mode. It only asks Velocity to verify
individual connections that claim to be premium.
- It does not block players without an account unless you set
allow-offline-connections: false. Out of the box the network stays mixed.
- It is not an authentication plugin. It does not add passwords or 2FA for offline
players. It does not check anything on your backend servers.
- It does not protect against a compromised premium account. If someone has the
real session, Velocity verifies them — same as vanilla online mode.
- It does not make a cracked client premium. Nothing can; a forged UUID only gets
the connection forced into a handshake it cannot complete.
Requirements and installation
- Velocity 3.x (built against
velocity-api 3.4.0), Java 17+
- Drop the jar into the proxy's
plugins/, start once, adjust config.yml, restart
- Backend servers need no plugin to receive the correct UUID; only read the plugin
message if you want the extra data
Compatibility notes
- Clients 1.19.2 and older send no UUID, so intent cannot be determined; they fall
back to
legacy-client-policy.
- Third-party auth launchers count as offline (they send their own UUID), so make
sure your backend accepts offline UUIDs if you use one.
- Mojang API rate limits: a failed lookup falls back according to
hybrid.mojang-unavailable-policy and logs a warning. Offline connections never wait
on the API; lookups run asynchronously and are cached.
- Case sensitivity: offline UUIDs derive from the exact name the client logged in
with.
NapCatt_owo and Napcatt_owo are different players to this plugin, as they are
to Velocity itself.
Source and licence
Source code, issue tracker and release notes:
MIT licensed.
评论 0
登录后参与评分
还没有评论,来抢沙发吧