中文

游戏服务器

如何使用 Geyser 和 Floodgate 接纳基岩版玩家

借助 Paper 上的 Geyser 和 Floodgate,向基岩版玩家开放您的 Minecraft Java 服务器:安装、TCP 和 UDP 端口、防火墙、连接和故障排除。

阅读约 6 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

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。请修改现有的行,不要重复添加:

YAML
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 基岩版中:

  1. 打开开始游戏,然后进入服务器选项卡
  2. 选择添加服务器
  3. 输入名称、地址 服务器IP 和端口 19132
  4. 保存,然后加入服务器

首次连接时,游戏会询问是否信任该服务器。通过 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.yml
YAML
allow-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” 或找不到服务器

  1. 使用 sudo ufw status、sudo iptables -L INPUT -n 或 sudo nft list ruleset 确认 TCP 和 UDP 端口均已开放
  2. 使用 sudo ss -tulpn | grep 19132 检查监听情况
  3. 在控制台中运行 geyser connectiontest 服务器IP 19132
  4. 查看日志中是否有连接尝试。如果没有任何记录,说明阻断发生在网络层面

如果服务器防火墙配置正确,但端口仍无法从外部访问,请通过您的客户中心联系技术支持,确认没有应用网络过滤。

“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 为单位逐步减小数据包大小,每次更改后重启并测试:

YAML
advanced:
  bedrock:
    mtu: 1300

服务器通告的地址不正确

Geyser 通常会自动检测公网地址。如果服务器有多个地址,或检测失败,请指定玩家应使用的地址:

YAML
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 官方文档。