BedrockPassport

插件

· 作者 Onelsey

让基岩版玩家在通过 Geyser 和 Floodgate 加入服务器前,选择并保存真实的 Java 版服务器身份。

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

最新 1.4.0 · 26.3 · Folia / Paper

一键开服(送7天)

BedrockPassport-Banner

? BedrockPassport

为 Bedrock 玩家提供持久化的 Java 端身份标识 —— 在接入后端之前。

BedrockPassport 是 Geyser 服务器的预登录身份网关。一个 Bedrock/Xbox 账号可以拥有多个身份,并在后端登录开始前选择使用哪个 Java 端身份。

online-mode=false → LOCAL
online-mode=true  → JAVA_ACCOUNT
  • LOCAL — 已保存的服务端用户名、确定性的离线 UUID 以及 Floodgate 身份交接。
  • JAVA_ACCOUNT — 经过验证的 Microsoft/Minecraft Java 账号及其真实的 Java 用户名和 UUID。

这不是一个昵称插件。
BedrockPassport 在后端创建玩家之前就改变了后端身份。

? 实时演示服务器

想在安装 BedrockPassport 之前看看 LOCAL 流程吗?

地址: 194.164.217.187
端口: 10007

演示服务器特意使用了 online-mode=false,以便直接测试 LOCAL 身份流程,而无需要求 Java 账号。

通过 JAVA_ACCOUNT 提供程序,BedrockPassport 也支持在 online-mode=true 服务器上使用的经验证的 Java 账号。


⚡ 概览

? 身份 后端登录前选定的 Java 端用户名 + UUID
? UI 原生 Bedrock 表单
? 账号 每个 Xbox 账号可拥有多个身份
? 在线模式 经验证的真实 Java 账号
? 离线模式 通过 Floodgate 的 LOCAL 身份
? Bedrock 访问 按游戏名或 XUID 的可选白名单
? 语言 每位玩家的 en_US、ru_RU、uk_UA、de_DE、es_ES
? 保存的 Java 认证 AES-GCM 加密
? 存储 SQLite

✨ 工作原理

LOCAL

Bedrock / Xbox 账号
        ↓
Geyser 持有环境
        ↓
选择服务端身份
        ↓
Java 用户名 + 离线 UUID
        ↓
Floodgate 身份交接
        ↓
认证插件
        ↓
游戏进行

JAVA_ACCOUNT

Bedrock / Xbox 账号
        ↓
选择或添加 Java 账号
        ↓
Microsoft / Minecraft 认证
        ↓
经验证的 Java 用户名 + 真实 UUID
        ↓
在线模式后端登录
        ↓
游戏进行

回归玩家将获得原生的 Bedrock 选择器:

BedrockPassport-Passport

每个 Xbox 账号可以在加入 Java 后端之前保留多个已保存的身份,在它们之间切换,添加新身份并移除旧条目。

默认账号限制:

identity:
  max-accounts-per-xuid: 3

从 BedrockPassport 中移除条目 不会 删除 Java/Microsoft 账号或服务端玩家数据。


? 真实后端身份

所选账号不是显示名称、TAB 栏昵称、前缀或外观别名。

由于身份是在后端玩家创建之前解析的,绑定 UUID 的数据从会话开始就属于所选身份:

  • 玩家数据
  • 物品栏
  • 权限
  • 统计信息
  • 领地声明
  • 白名单条目
  • 其他绑定 UUID 的插件数据

LOCAL

所选用户名将接收与普通离线模式 Java 客户端相同的确定性离线 UUID。

因此,使用相同用户名的 Java 客户端和 Bedrock 客户端可以代表同一个服务端身份。

LOCAL 身份仍然只是一个身份快捷方式 —— 并非所有权的证明。

JAVA_ACCOUNT

BedrockPassport 通过 Microsoft/Minecraft 认证验证真实的 Java 账号,并使用其真实的:

  • Java 用户名
  • Java UUID
  • 已认证的 Java 会话

JAVA_ACCOUNT 不会生成离线 UUID。


? Bedrock/Xbox 白名单

BedrockPassport 可以将 Passport 流程限制为选定的 真实 Bedrock/Xbox 身份。

access:
  allowlist:
    enabled: false
    players: []
    xuids: []

启用后,如果连接的游戏名匹配 players 或其 XUID 匹配 xuids,则允许该连接。

此检查发生在 Passport 选择器和后端玩家创建之前,因此选择另一个已保存的 Java 身份无法绕过它。

  • Java 客户端不受影响。
  • 游戏名匹配不区分大小写。
  • XUID 可用作稳定标识符。
  • 启用白名单且两个列表均为空时,将拒绝所有 Bedrock 连接。

? 本地化

BedrockPassport 可以自动使用每位 Bedrock 玩家的客户端语言来面向玩家展示 Passport 流程。

language:
  config: en_US
  messages: en_US
  use-player-locale: true
  player-locale-fallback: en_US

面向玩家的语言环境:

  • en_US — English
  • ru_RU — Русский
  • uk_UA — Українська
  • de_DE — Deutsch
  • es_ES — Español

当 use-player-locale: true 时,BedrockPassport 会独立检测每个 Bedrock 连接的语言。因此,使用不同客户端语言的两位玩家可以同时收到不同的 Passport 表单。

区域变体按语言族进行匹配,例如:

en_GB → en_US
ru_KZ → ru_RU
es_MX → es_ES

如果客户端语言不受支持,则使用 player-locale-fallback。

当 use-player-locale: false 时,面向玩家的文本如常工作,并使用 language.messages。

language.messages 仍然是管理员和操作消息的默认语言。
language.config 控制写入 config.yml 中的解释性注释,目前支持 en_US 和 ru_RU。

仍可通过 messages.overrides 自定义单个消息。


? 认证与信任

LOCAL

BedrockPassport 选择 使用哪个服务端身份。它并不证明对该 LOCAL 身份的所有权。

单独的认证插件随后可以进行密码/注册验证。

在常规的 Bukkit 身份验证插件做出登录决定之前,Passport 身份信息以**不受信任(untrusted)**状态暴露,而真实的 Xbox 用户名、XUID 和 Bedrock 上下文信息仍然可用。

AuthMeReloaded 作为一个独立的本地身份验证层运行,无需特定的 BedrockPassport 适配器。

本地用户名在生成离线 UUID 之前会进行规范化处理:如果 AuthMe 已经拥有该账户,则使用其注册的大小写形式,因此 Steve 和 steve 永远不会变成两个不同的 UUID。

JAVA_ACCOUNT

JAVA_ACCOUNT 条目仅在 Microsoft/Minecraft 身份验证成功后创建。

保存的 Java 身份验证链在 passport.db 中使用 AES-GCM 进行加密。

每个账户一个设备代码,实现无缝登录。 Microsoft 刷新令牌会在后续加入时自动续期,并在后端连接建立前将轮换后的令牌写回数据库。

仅当 Microsoft 真正拒绝保存的登录信息时才会请求新的设备代码:例如刷新令牌过期或已撤销、密码更改、授权被撤销,或者该账户不再拥有 Minecraft。网络错误、超时以及 Microsoft/Xbox 的服务中断绝不会清除保存的登录信息。BedrockPassport 会进行重试,如果 Microsoft 仍然不可用,则会将玩家返回到选择器界面并显示一条消息。

Microsoft 刷新令牌在未使用的情况下大约会在 90 天后过期,因此超过这个时间未加入的账户需要再进行一次设备代码验证。

? 加密密钥位置

密钥按以下顺序查找:

  1. BEDROCKPASSPORT_KEY 环境变量(base64 编码,32 字节)
  2. config.yml 中的 security.credentials-key-path
  3. plugins/BedrockPassport/credentials.key(自动生成)
openssl rand -base64 32

插件永远不会生成、覆盖或轮换外部密钥。如果密钥缺失或无效,JAVA_ACCOUNT 会因安全原因失败,并在控制台输出清晰的错误信息,而不是创建一个会导致保存的登录信息无法读取的新密钥。/bp status 命令会显示密钥来源,但不会泄露密钥本身。

备份: 使用外部密钥时,请分别备份 passport.db 和密钥文件。泄露的数据库如果没有密钥是无法解密的。


?️ 会话保护与断开连接清理

启用 security.first-session-wins: true 后,已经拥有或预留了 LOCAL 身份的连接将保留该身份。

BedrockPassport 可防止常见的登录竞争问题:

  • Bedrock 无法夺取已在线的身份
  • Java 无法使用相同身份替换活跃的 Bedrock Passport 会话
  • 两个 Bedrock 连接不能预留相同的 LOCAL 身份
  • 同一个 XUID 不能同时打开两个 LOCAL Passport 流程

如果 Bedrock 客户端在未完成 Passport 流程期间断开连接,临时选择器、预留状态和交接状态将通过 Geyser 会话生命周期进行清理。

? 皮肤处理

皮肤处理属于 LOCAL / Floodgate 路径。

skins:
  policy: preserve
策略 行为
preserve 保留有意义的现有皮肤;否则允许正常的 Floodgate/SkinsRestorer 结果
refresh 允许最终的 Floodgate/SkinsRestorer 皮肤替换当前皮肤
off 禁用 BedrockPassport 的皮肤处理功能

SkinsRestorer 是可选的。当可用时,BedrockPassport 可以在选定的 LOCAL 身份达到 Bukkit 加入条件后重新应用存储的皮肤。

确认 Bedrock 皮肤后,最多等待约两分钟,因为 Geyser 的全局皮肤服务可能需要一段时间来处理自定义皮肤的签名。

? Bedrock 检测、Floodgate 和反作弊

更改 Java 端的身份不会使 Bedrock 连接变成 Java 客户端。

在 LOCAL 模式下,Floodgate 参与后端交接,且正常的 Bedrock 上下文仍然可用。选择器在 Geyser 的暂存环境中运行,在后端连接打开之前,因此玩家选择账户永远不会阻塞其他玩家的连接。

在 JAVA_ACCOUNT 模式下,后端登录是一个真正的已认证 Java 配置文件。Floodgate 可能仍然安装,但其后端登录处理程序会被排除在经过验证的 Java 账户交接过程之外。

支持 Bedrock 的集成应使用受支持的 Geyser/Floodgate API,而不是仅依赖用户名前缀或猜测的 UUID 格式。

? AuthMeReloaded 和 AlixSystem

AuthMeReloaded

作为 LOCAL 的独立身份验证层非常有用。

BedrockPassport 首先执行身份交接;然后 AuthMe 执行其正常的密码/注册验证。

AlixSystem

BedrockPassport 在 LOCAL 身份交接中排在 AlixSystem 之前。

Alix 的兼容性仍取决于安装的 Alix 版本是否与安装的 Geyser 版本兼容。

? 管理命令

权限:bedrockpassport.admin — 默认由 OP(管理员)拥有。

/bp status
/bp who <javaName>
/bp reload
/bp reset-login <javaName>
/bp reset-login --all confirm
  • /bp status — 运行时信息、提供程序、凭据密钥来源、白名单、语言和会话信息。
  • /bp who <javaName> — 检查活动或待处理的身份。
  • /bp reload — 迁移/重载配置并重建运行时环境。
  • /bp reset-login <javaName> — 移除单个保存的 JAVA_ACCOUNT 的可重用身份验证状态。
  • /bp reset-login --all confirm — 移除所有保存的 Java 身份验证状态并轮换 credentials.key(外部密钥留给管理员处理)。

重置命令会保留 Passport 身份记录和经过验证的 Java UUID。

? 配置与存储

BedrockPassport 使用版本化的配置迁移和 SQLite 模式迁移。

当前配置方案:v5。

自动迁移旧版受支持的配置,包括将受支持的用户界面文本本地化至 messages.overrides。

当 BedrockPassport 引入新的配置选项时,缺失的设置会被添加到现有的 config.yml 中,同时保留管理员自定义的值。配置文件注释会根据所选的 language.config 区域设置重新生成。

在更新过程中,通常无需删除或重建 config.yml 或 passport.db。

护照数据:

plugins/BedrockPassport/passport.db

JAVA_ACCOUNT 加密密钥(默认位置,环境变量或自定义路径请参阅上方的 Encryption key location):

plugins/BedrockPassport/credentials.key

? 安装

  1. 安装 Geyser-Spigot。
  2. 对于 LOCAL 模式,安装 Floodgate 并设置 online-mode=false。
  3. 对于 JAVA_ACCOUNT 模式,使用 online-mode=true;Floodgate 可保持安装状态。
  4. 将 BedrockPassport 放入 plugins/ 目录。
  5. 启动服务器。

BedrockPassport 会在启动时检查所需的 Geyser 集成能力,如果缺少必需的后端集成点,则会阻止启动。


? 兼容性

软件 支持情况
Paper ✅
Folia ✅
Purpur ✅
Leaf ✅
Geyser-Spigot ✅ 必需
Floodgate ✅ LOCAL / ? JAVA_ACCOUNT 下可选
SkinsRestorer ? 可选
AuthMeReloaded ✅ LOCAL 认证层
AlixSystem ? 需要兼容 Geyser 的版本

需要 Java 25 或更高版本。

BedrockPassport 不依赖 Minecraft NMS。

与 BedrockPassport 配合使用的其他插件必须自行提供对 Folia 的兼容性。


? 为什么选择 BedrockPassport?

Geyser 使基岩版客户端能够兼容 Java 版服务器。

BedrockPassport 在后端玩家实体存在之前,补充了缺失的身份选择机制。

  • 没有虚假显示名称。
  • 不会强制使用 Xbox 游戏昵称作为服务器账号。
  • 不会因为有人切换游戏版本就产生重复的玩家数据。
  • LOCAL 身份验证与所有权验证相互独立。
  • 开启在线模式的服务器可以使用真实且经过验证的 Java 版账号。

为 Geyser 服务器提供清晰的前后端身份交接流程。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源