Floodgate入门指南：如何让你的基岩版玩家一键加入Java在线服务器？
【免费下载链接】FloodgateHybrid mode plugin to allow for connections from Geyser to join online mode servers.项目地址: https://gitcode.com/gh_mirrors/fl/Floodgate
Floodgate是 GeyserMC 团队开发的免费开源混合模式插件，配合 Geyser 使用，能让《我的世界》基岩版（手机、主机、Win10 版）玩家直接连接 Java 版在线模式服务器，无需关闭正版验证。本文是一份面向新手的完整入门教程，带你 10 分钟完成安装、配置与账号绑定，让两端玩家同服畅玩。
Floodgate 是什么？为什么需要它？
很多服主都会遇到这个痛点：
- Geyser 可以让基岩版玩家进入非在线模式的 Java 服务器；
- 但只要服务器开启了正版验证（
online-mode=true），基岩版玩家就会被拒之门外。
Floodgate 就是专门解决这个问题的"钥匙"：
| 能力 | 说明 |
|---|---|
| 🔐 绕过正版验证 | 用密钥加密的握手协议，在线模式下放行基岩版玩家 |
| 🔗 账号绑定 | 玩家把基岩版身份与 Java 正版账号关联，数据互通 |
| 🎨 皮肤同步 | 自动将 Java 账号的皮肤应用到基岩版玩家身上 |
| 🖥️ 多平台支持 | 兼容 Spigot/Paper、BungeeCord、Velocity 等主流服务端 |
一句话理解：Geyser 负责"翻译"协议，Floodgate 负责"开门"验证。两者搭配才是完整的混合玩法方案。
一键安装步骤：3 步搞定 Floodgate 插件
第 1 步：下载并安装插件
从 Floodgate 官方发布渠道下载与你服务端版本匹配的插件包（分别对应 Spigot、BungeeCord、Velocity），将插件文件放入服务端的plugins目录后重启，首次启动会自动生成配置文件与密钥文件。
核心配置结构定义在 FloodgateConfig.java 中，插件启动时会检查密钥文件是否存在，缺失时自动生成，无需手动创建。
第 2 步：把密钥文件同步给 Geyser
Floodgate 使用一个.key密钥文件（默认名为floodgate.key）来识别"合法"的 Geyser 玩家。你需要把这个文件复制到Geyser 所在的目录（Geyser 服务端或客户端加载器目录下），Geyser 才能携带正确签名。
小贴士：配置文件中的keyFileName选项可以修改密钥文件名，usernamePrefix可以设置基岩版玩家的 ID 前缀（如G_），方便在玩家列表中一眼区分两端玩家。
第 3 步：开启玩家账号绑定
打开plugins/Floodgate下的config配置文件，找到playerLink区块，常见选项含义如下：
enabled: true—— 开启账号绑定功能；enableOwnLinking: true—— 允许玩家自己在聊天框输入命令完成绑定（推荐新手开启）；requireLink—— 是否要求所有玩家必须绑定后才能进入；linkCodeTimeout—— 绑定验证码的有效期（毫秒）。
绑定命令的实现见 LinkAccountCommand.java。
玩家如何加入：绑定与进服流程
安装完成后，基岩版玩家的体验是这样的：
- 在基岩版中输入 Java 正版账号名，执行
/floodgate linkaccount <JavaID>； - 在 Java 版端登录同一个正版账号，收到验证码后输入
/floodgate linkaccount <验证码>； - 绑定成功后，基岩版玩家即可随时加入服务器，并且能同步显示你的Java 正版皮肤（皮肤同步逻辑见 SkinApplier.java）。
玩家端和后台常用命令都集中在/floodgate主命令下（见 MainCommand.java）：
/floodgate firewall check # 检查防火墙/端口连通性，排查连不上的问题 /floodgate version # 查看 Floodgate 版本信息 /floodgate whitelist # 管理允许绑定的白名单 /floodgate unlinkaccount # 解除账号绑定进阶配置：代理服务器与数据库
多后端？给代理服务器也装一个
如果你的架构是「Velocity / BungeeCord 代理 + 多个后端服务器」，需要在代理端和每个后端都安装 Floodgate，并启用代理专用配置——其中包含代理转发所需的额外字段，定义在 ProxyFloodgateConfig.java。
各平台的注入实现分别位于：
- Spigot/Paper：
spigot/模块（SpigotInjector.java） - BungeeCord：
bungee/模块（BungeeInjector.java） - Velocity：
velocity/模块（VelocityInjector.java）
账号数据存在哪里？
Floodgate 默认使用内置数据库，也支持扩展外部数据库来存储绑定关系，项目提供了三种实现：
| 模块 | 说明 |
|---|---|
| SQLite | 轻量内置，零配置（SqliteDatabase.java） |
| MySQL | 适合多人服（MysqlDatabase.java） |
| MongoDB | 文档型存储（MongoDbDatabase.java） |
选择外部数据库后，记得在配置中填写连接信息，重启前后可用/floodgate firewall check验证连通性。
常见问题快速排查
❓ 基岩版玩家连不上服务器？
先执行/floodgate firewall check，再检查：密钥文件是否已放到 Geyser 目录、Geyser 与 Floodgate 版本是否匹配、端口是否对外开放。
❓ 玩家进服后名字前面多了一串字符？
这是usernamePrefix配置生效的结果，属于正常现象；也可以在配置中设为空字符串关闭。
❓ 皮肤不显示？
确认玩家已完成账号绑定——皮肤同步依赖绑定后的 Java 账号信息，未绑定玩家无法同步正版皮肤。
❓ 服务器语言显示不对？
在配置文件的defaultLocale中设置语言代码即可。
从源码构建 Floodgate（选做）
如果你需要修改源码或构建最新开发版本，可以克隆仓库并构建：
git clone https://gitcode.com/gh_mirrors/fl/Floodgate cd Floodgate ./gradlew build构建完成后，各模块的产物位于对应模块的build/libs目录中，可直接部署到服务端使用。更多项目背景信息可参阅 README.md。
🎉总结：安装 Floodgate 只需"装插件 → 传密钥 → 开绑定"三步，配合 Geyser 即可让基岩版与 Java 版玩家同服游玩。现在就去试试吧，你的服务器即将迎来一波新玩家！
【免费下载链接】FloodgateHybrid mode plugin to allow for connections from Geyser to join online mode servers.项目地址: https://gitcode.com/gh_mirrors/fl/Floodgate
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
