如何使用 Geyser 和 Floodgate 接纳基岩版玩家
借助 Paper 上的 Geyser 和 Floodgate,向基岩版玩家开放您的 Minecraft Java 服务器:安装、TCP 和 UDP 端口、防火墙、连接和故障排除。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
Minecraft Java 版和 Minecraft 基岩版(移动设备、Windows、主机)使用的网络协议不同。本指南介绍如何在您的 Paper 服务器上安装两个插件,让基岩版玩家也能加入:
- Geyser 负责在基岩版和 Java 版之间转换通信
- Floodgate 让基岩版玩家使用其 Microsoft 账户进入,无需拥有 Minecraft Java 版
前提条件
- 运行 Paper 的服务器,并已按照在 Paper 上安装和更新插件指南配置好
mc-console命令 server.properties中保持在线模式:online-mode=true- 可以访问服务器的防火墙
- 用于测试的最新版 Minecraft 基岩版客户端
了解端口
基岩版现在使用 NetherNet 连接协议,Geyser 默认启用该协议。它需要在两种协议上使用相同的端口号:
| 端口 | 协议 | 用途 |
|---|---|---|
| 19132 | TCP | 信令:客户端查找服务器并准备连接 |
| 19132 | UDP | 游戏数据交换 |
| 25565 | TCP | Java 版玩家,已开放 |
开放防火墙
只使用一种防火墙工具,即服务器上已启用的那一种。
使用 UFW
sudo ufw allow 19132/tcp
sudo ufw allow 19132/udp
sudo ufw reload使用 iptables
sudo iptables -A INPUT -p tcp --dport 19132 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 19132 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4重启后保留规则需要安装 iptables-persistent 软件包。
使用 nftables
这些命令使用 inet filter 表和 input 链,二者在 Debian 的 /etc/nftables.conf 中默认存在。
sudo nft add rule inet filter input tcp dport 19132 accept
sudo nft add rule inet filter input udp dport 19132 accept
(echo "flush ruleset"; sudo nft list ruleset) | sudo tee /etc/nftables.conf安装 Geyser 和 Floodgate
从官方服务下载适用于 Paper 和 Spigot 的版本:
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
curl -fL -o Geyser-Spigot.jar https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot
curl -fL -o floodgate-spigot.jar https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot
ls -l Geyser-Spigot.jar floodgate-spigot.jar
exit重启服务器以生成配置文件,然后等待出现 Done 这一行:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f按 Ctrl+C 退出日志跟踪。
配置 Geyser
打开配置文件:
sudo -u minecraft nano /opt/minecraft/server/plugins/Geyser-Spigot/config.yml检查 bedrock 部分,然后在 java 部分将 auth-type 改为 floodgate。请修改现有的行,不要重复添加:
bedrock:
address: 0.0.0.0
port: 19132
transport: nethernet
java:
auth-type: floodgate您还可以通过 gameplay 部分的 server-name 自定义向基岩版玩家显示的名称。
重启服务器以应用这些更改:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f验证结果
确认插件已加载,且服务器正在两种协议上监听:
sudo mc-console plugins
sudo mc-console 'geyser version'
sudo MC_CONSOLE_WAIT=5 mc-console 'geyser nethernet'
sudo ss -tulpn | grep 19132您应该看到:
- 插件列表中有
Geyser-Spigot和floodgate - 启动日志中有一行
Built-in signaling started on ss的输出中端口19132同时以tcp和udp出现
然后测试外部访问。以下命令让 Geyser 检查您的服务器是否可访问:
sudo MC_CONSOLE_WAIT=15 mc-console 'geyser connectiontest 服务器IP 19132'您也可以从另一台计算机检查 TCP 端口:
nc -vz 服务器IP 19132从基岩版连接
在 Minecraft 基岩版中:
- 打开开始游戏,然后进入服务器选项卡
- 选择添加服务器
- 输入名称、地址
服务器IP和端口19132 - 保存,然后加入服务器
首次连接时,游戏会询问是否信任该服务器。通过 IP 地址或未使用 HTTPS 连接时,这属于正常现象。要取消此提示,您可以使用域名和证书通过 HTTPS 提供信令服务。
进入游戏后,确认玩家已在线:
sudo mc-console 'geyser list'管理基岩版玩家
玩家名
Floodgate 会在基岩版玩家名前添加一个点号,以避免与 Java 账户冲突:Steve 变为 .Steve。空格会被替换为 _。这些设置对应 plugins/floodgate/config.yml 中的 username-prefix 和 replace-spaces。
白名单
如果已启用 white-list=true,请使用 Floodgate 的命令添加基岩版玩家,不带点号:
sudo mc-console 'fwhitelist add Steve'使用 LuckPerms 管理权限
LuckPerms 默认拒绝包含点号的玩家名。请在其配置文件中允许:
sudo -u minecraft nano /opt/minecraft/server/plugins/LuckPerms/config.ymlallow-invalid-usernames: true重启服务器。玩家连接后,您可以使用其完整玩家名将其分配到某个等级:
sudo mc-console 'lp user .Steve parent add vip'关联 Java 和基岩版账户
同时拥有两个版本的玩家可以分别使用两个账户加入 link.geysermc.org 服务器,并使用 /linkaccount 进行关联。此全局关联功能默认启用。
更新 Geyser 和 Floodgate
基岩版更新频繁,游戏的新版本可能导致玩家在 Geyser 更新前无法连接。请定期更新:
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
curl -fL -o Geyser-Spigot.jar https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot
curl -fL -o floodgate-spigot.jar https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot
exit
sudo systemctl restart minecraft.service故障排除
“Unable to connect to world” 或找不到服务器
- 使用
sudo ufw status、sudo iptables -L INPUT -n或sudo nft list ruleset确认 TCP 和 UDP 端口均已开放 - 使用
sudo ss -tulpn | grep 19132检查监听情况 - 在控制台中运行
geyser connectiontest 服务器IP 19132 - 查看日志中是否有连接尝试。如果没有任何记录,说明阻断发生在网络层面
如果服务器防火墙配置正确,但端口仍无法从外部访问,请通过您的客户中心联系技术支持,确认没有应用网络过滤。
“NetherNet will not start! Could not load its WebRTC native library”
Geyser 无法加载其网络库,该库会被解压到临时文件夹。请确认 /tmp 未使用 noexec 选项挂载,且仍有可用空间:
findmnt -no OPTIONS /tmp
df -h /tmp客户端一直停留在查找服务器阶段(“Locating Server”)
在 plugins/Geyser-Spigot/config.yml 中以 100 为单位逐步减小数据包大小,每次更改后重启并测试:
advanced:
bedrock:
mtu: 1300服务器通告的地址不正确
Geyser 通常会自动检测公网地址。如果服务器有多个地址,或检测失败,请指定玩家应使用的地址:
bedrock:
signaling:
advertise-addresses:
- 服务器IP“Address already in use”
另一个程序已占用端口 19132,通常是第二个 Geyser 实例。请使用 sudo ss -tulpn | grep 19132 找出该程序。
“Auth-type set to Floodgate but Floodgate is not installed!”
Floodgate 缺失或未能启动。请确认 plugins 中存在 floodgate-spigot.jar,然后在日志中查找其错误。
“Cannot reply to EncryptionRequestPacket without profile and access token”
Floodgate 未启用,或 auth-type 未设为 floodgate。请检查这两点。如果 Geyser 文件夹中有 key.pem 的副本,请将其删除。
“javax.crypto.AEADBadTagException: Tag mismatch!”
Floodgate 密钥不一致。请停止服务器,删除 plugins/floodgate 文件夹以及 plugins/Geyser-Spigot 中的所有密钥,然后重新启动:
sudo systemctl stop minecraft.service
sudo rm -rf /opt/minecraft/server/plugins/floodgate
sudo rm -f /opt/minecraft/server/plugins/Geyser-Spigot/key.pem
sudo systemctl start minecraft.service如果您曾修改过 Floodgate 的配置,则需要重新进行这些设置。
“Please connect through the official Geyser”
Geyser 和 Floodgate 互不兼容。请将两者都更新。
“Failed to verify username!”
在 config/paper-global.yml 的 unsupported-settings 部分,将 perform-username-validation 改为 false,然后重启服务器。
“Outdated client” 或 “Outdated server”
基岩版客户端与 Geyser 版本不再匹配。请先更新 Geyser,再更新游戏。如果您的 Java 服务器不是 26.3 版本,请安装 ViaVersion。
如需进一步了解,请查阅 Geyser 官方文档和 Floodgate 官方文档。