中文

游戏服务器

如何使用 Velocity 连接多台 Minecraft 服务器

在 VPS 或专用 Linux 服务器上,通过 Velocity 代理连接多台 Paper 服务器:安全转发玩家信息、关闭内部端口以及回退方法。

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

本页内容

您的参数

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

Velocity 是一款 Minecraft 代理:玩家只需连接一个地址,即可在服务器之间切换而无需断开连接。本指南将您现有的服务器置于 Velocity 之后,并在同一台机器上为其添加一台 lobby 服务器。

本指南是创建 Minecraft 服务器和在 Paper 上安装和更新插件两篇指南的延续,沿用其中的 minecraft 用户、/opt/minecraft/server 文件夹、minecraft.service 服务和 mc-console 命令。

完成本指南后,您将拥有:

  • 监听公网端口 25565 的 Velocity,玩家使用的地址保持不变
  • 两台只能从本机访问的 Paper 服务器
  • 安全的玩家身份转发,玩家的 UUID 和物品栏都得以保留

前提条件

  • 一台运行 Paper 的服务器,已按照上述两篇指南安装,并具备 Java 25、curl 和 jq
  • 使用具有 sudo 权限的用户进行 SSH 访问
  • 在现有服务器之外,还需约 2 GB 可用内存:Velocity 占用 1 GB,lobby 服务器最多占用 1 GB
  • 足够的磁盘空间,可存放服务器文件夹的完整副本

Velocity、BungeeCord 还是 Waterfall?

Velocity BungeeCord Waterfall
项目 PaperMC,持续开发中 SpigotMC,老牌代理 PaperMC,已停止支持
安全的身份转发 是,通过密钥签名 否 否
插件 Velocity API BungeeCord API BungeeCord API

PaperMC 推荐使用 Velocity,而不是 BungeeCord 和 Waterfall,并且已不再维护 Waterfall。

只有一种情况仍值得选择 BungeeCord:您必需的某个代理插件没有 Velocity 版本,因为 Velocity 无法加载 BungeeCord 插件。由于 BungeeCord 的身份转发没有签名,下文介绍的关闭内部端口对它来说更加重要。

了解目标架构

服务 Velocity 中的名称 文件夹 监听地址 可访问范围
velocity.service /opt/minecraft/velocity 0.0.0.0:25565 互联网
minecraft.service survie /opt/minecraft/server 127.0.0.1:25566 仅本机
minecraft-lobby.service lobby /opt/minecraft/lobby 127.0.0.1:25567 仅本机

备份服务器

停止服务器,然后创建完整归档。在配置完成之前,服务器都保持停止状态,因为 Velocity 将接管 25565 端口:

终端
sudo systemctl stop minecraft.service
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backups

安装 Velocity

创建一个脚本,用于下载最新的稳定构建并校验其哈希值。之后更新时还会用到它:

终端
sudo nano /opt/minecraft/velocity-update.sh
终端
#!/bin/bash
# 下载 Velocity 的最新稳定构建并替换 velocity.jar
set -euo pipefail

VERSION="${1:?请指定 Velocity 版本,例如 4.3.1}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://fill.papermc.io/v3/projects/velocity/versions/$VERSION/builds"

mkdir -p /opt/minecraft/velocity
cd /opt/minecraft/velocity

BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
    echo "未找到稳定构建:Velocity $VERSION" >&2
    exit 1
fi

URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')

curl -fL -H "User-Agent: $UA" -o velocity.jar.new "$URL"
echo "$SHA256  velocity.jar.new" | sha256sum -c -

if [ -f velocity.jar ]; then
    mv velocity.jar velocity.jar.old
fi
mv velocity.jar.new velocity.jar
echo "Velocity $VERSION 构建 $(echo "$BUILD" | jq -r '.id') 已就绪。"

在 UA 这一行中,将 your-domain.com 替换为您的网站地址或联系方式。然后运行脚本:

终端
sudo chmod 755 /opt/minecraft/velocity-update.sh
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1

velocity.jar.new: OK 这一行表示文件完好无损。

创建服务:

终端
sudo nano /etc/systemd/system/velocity.service
配置
[Unit]
Description=Minecraft Velocity 代理
After=network.target

[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/velocity
ExecStart=/usr/bin/java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar /opt/minecraft/velocity/velocity.jar
SuccessExitStatus=130 143
Restart=on-failure
RestartSec=20
StandardInput=null

[Install]
WantedBy=multi-user.target

这些 Java 选项是 Velocity 文档推荐的配置。首次启动代理以生成其配置:

终端
sudo systemctl daemon-reload
sudo systemctl start velocity.service
sudo journalctl -u velocity.service -n 30 --no-pager

等待出现 Done 这一行。此时出现 Player info forwarding is disabled! 警告属于正常现象。然后停止代理,并保护其文件夹,因为其中包含密钥:

终端
sudo systemctl stop velocity.service
sudo chmod 700 /opt/minecraft/velocity
sudo ls -l /opt/minecraft/velocity

您应该看到 velocity.toml 和 forwarding.secret。

配置 Velocity

终端
sudo -u minecraft nano /opt/minecraft/velocity/velocity.toml

检查或修改文件开头的这几行:

toml
bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

然后替换 [servers] 和 [forced-hosts] 两节的全部内容:

toml
[servers]
lobby = "127.0.0.1:25567"
survie = "127.0.0.1:25566"

try = [
    "lobby",
    "survie"
]

[forced-hosts]

try 指定玩家连接时或被某台服务器踢出时依次尝试的服务器顺序。[forced-hosts] 一节保持为空:自带的示例指向 factions 和 minigames 服务器,而您并没有这些服务器,Velocity 会因此拒绝启动。

接入现有服务器

让服务器在新端口上监听本地回环地址,并将玩家验证交给代理:

终端
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=127.0.0.1/' \
    -e 's/^server-port=.*/server-port=25566/' \
    -e 's/^online-mode=.*/online-mode=false/' \
    /opt/minecraft/server/server.properties
sudo grep -E '^(server-ip|server-port|online-mode)=' /opt/minecraft/server/server.properties

然后在 Paper 配置中启用现代转发,并填入 Velocity 生成的密钥:

终端
SECRET=$(sudo cat /opt/minecraft/velocity/forwarding.secret)
sudo -u minecraft sed -i "/^  velocity:/,/^ \{0,2\}[a-z]/{s/^    enabled: .*/    enabled: true/;s/^    online-mode: .*/    online-mode: true/;s/^    secret: .*/    secret: '$SECRET'/;}" /opt/minecraft/server/config/paper-global.yml
unset SECRET
sudo chmod 700 /opt/minecraft/server/config

在不显示密钥的情况下检查结果:

终端
sudo grep -A3 '^  velocity:' /opt/minecraft/server/config/paper-global.yml | sed 's/secret: .*/secret: (已隐藏)/'
sudo grep -qF "$(sudo cat /opt/minecraft/velocity/forwarding.secret)" /opt/minecraft/server/config/paper-global.yml && echo "密钥一致" || echo "密钥不一致"
sudo grep 'bungeecord:' /opt/minecraft/server/spigot.yml

您应该看到 enabled: true、online-mode: true、密钥一致 和 bungeecord: false。使用现代转发时,最后这项必须保持为 false。

创建 lobby 服务器

lobby 服务器沿用相同的 server.jar 和相同的 Paper 全局配置:

终端
sudo -u minecraft mkdir -p /opt/minecraft/lobby/config
sudo chmod 700 /opt/minecraft/lobby/config
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/
sudo -u minecraft cp /opt/minecraft/server/config/paper-global.yml /opt/minecraft/lobby/config/
echo "eula=true" | sudo -u minecraft tee /opt/minecraft/lobby/eula.txt

创建其设置,使用超平坦世界且没有怪物:

终端
sudo -u minecraft tee /opt/minecraft/lobby/server.properties > /dev/null <<'EOF'
server-ip=127.0.0.1
server-port=25567
online-mode=false
motd=Lobby
max-players=50
level-type=minecraft\:flat
generate-structures=false
gamemode=adventure
force-gamemode=true
difficulty=peaceful
allow-nether=false
view-distance=6
simulation-distance=4
EOF

创建其服务:

终端
sudo nano /etc/systemd/system/minecraft-lobby.service
配置
[Unit]
Description=Minecraft Lobby Server
After=network.target

[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/lobby
ExecStart=/usr/bin/java -Xms512M -Xmx1G -jar /opt/minecraft/lobby/server.jar nogui
ExecStop=/bin/kill -SIGINT $MAINPID
SuccessExitStatus=130 143
TimeoutStopSec=180
Restart=on-failure
RestartSec=20
StandardInput=null

[Install]
WantedBy=multi-user.target

全部启动

启动两台服务器,然后跟踪 lobby 服务器的首次启动,直到出现 Done 这一行:

终端
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo systemctl enable --now minecraft-lobby.service
sudo journalctl -u minecraft-lobby.service -f

按 Ctrl+C 退出日志跟踪,然后启动代理:

终端
sudo systemctl enable --now velocity.service
sudo journalctl -u velocity.service -n 30 --no-pager

确认内部端口已关闭

终端
sudo ss -ltnp | grep -E ':(25565|25566|25567)\b'

25565 端口应监听所有地址。25566 和 25567 端口应显示 127.0.0.1 或 [::ffff:127.0.0.1],绝不能是 0.0.0.0、* 或 [::]。

防火墙无需改动:只有 25565 端口保持开放。如果使用 UFW,以下命令不应有任何输出:

终端
sudo ufw status | grep -E '2556[67]'

然后从另一台电脑测试这些端口。第一个应有响应,第二个应失败:

终端
nc -zv -w 5 服务器IP 25565
nc -zv -w 5 服务器IP 25566

如果服务器位于另一台机器上

本地回环地址仅在同一台机器内有效。在第二台机器上,请让服务器监听私有地址(最好是 WireGuard 隧道的地址),在 velocity.toml 中填写该地址,然后只允许代理访问。在第二台机器上使用 UFW:

终端
sudo ufw allow from 代理IP to any port 25566 proto tcp

或使用 iptables:

终端
sudo iptables -A INPUT -p tcp -s 代理IP --dport 25566 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 25566 -j DROP

验证结果

先检查三个服务:

终端
systemctl is-active velocity.service minecraft.service minecraft-lobby.service

然后使用 Minecraft 客户端,以与之前相同的地址连接。您应该会进入 lobby 服务器。接着输入:

文本
/server
/server survie

第一条命令列出服务器,第二条命令将您转移过去而不断开连接。您的建筑和物品栏应该都还在。最后检查服务器收到的信息:

终端
sudo journalctl -u minecraft.service --since "10 minutes ago" --no-pager | grep -E 'UUID of player|logged in with entity id'

您应该看到自己的公网 IP 地址,而不是 127.0.0.1。UUID 的第三段应以 4 开头,这表示账户已通过验证。

插件与代理

Paper 插件仍放在各服务器的 plugins 文件夹中。Velocity 有自己的插件,需放入 /opt/minecraft/velocity/plugins,然后重启代理以加载。

如果您使用 Geyser 和 Floodgate,它们在代理之后的安装方式有所不同:请按照 Floodgate 文档中针对 Velocity 的说明操作。

备份代理和 lobby 服务器

基础指南的 backup.sh 脚本不包含这些文件夹。请先保护归档文件夹,因为归档中将包含密钥:

终端
sudo chmod 700 /opt/minecraft/backups

然后在 /opt/minecraft/backup.sh 中现有的 tar 行之后添加这一行。world_ 前缀可让脚本的自动清理将其纳入处理:

终端
tar -czf $BACKUP_DIR/world_proxy_$DATE.tar.gz -C /opt/minecraft velocity lobby

更新

Minecraft 发布新版本时,请先于各服务器更新 Velocity,使其能够接受新客户端。操作期间玩家会断开连接:

终端
sudo systemctl stop velocity.service
sudo tar -czf /opt/minecraft/backups/velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft velocity
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1
sudo systemctl start velocity.service

然后按照 Paper 指南中的说明更新 survie 服务器,再将其文件复制到 lobby 服务器:

终端
sudo systemctl stop minecraft-lobby.service
sudo tar -czf /opt/minecraft/backups/lobby-$(date +%F-%H%M).tar.gz -C /opt/minecraft lobby
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/server.jar
sudo systemctl start minecraft-lobby.service

回退

要恢复为在 25565 端口上运行的单台服务器,且不丢失此后的游戏进度:

终端
sudo systemctl disable --now velocity.service minecraft-lobby.service
sudo systemctl stop minecraft.service
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=/' \
    -e 's/^server-port=.*/server-port=25565/' \
    -e 's/^online-mode=.*/online-mode=true/' \
    /opt/minecraft/server/server.properties
sudo -u minecraft sed -i "/^  velocity:/,/^ \{0,2\}[a-z]/{s/^    enabled: .*/    enabled: false/;s/^    secret: .*/    secret: ''/;}" /opt/minecraft/server/config/paper-global.yml
sudo systemctl start minecraft.service

velocity 和 lobby 文件夹会保留。如果问题更严重,请按照 Paper 指南中恢复备份一节的说明恢复 avant-velocity-… 归档。

故障排除

先查看代理和相关服务器的日志:

终端
sudo journalctl -u velocity.service -n 100 --no-pager
sudo journalctl -u minecraft.service -n 100 --no-pager
sudo journalctl -u minecraft-lobby.service -n 100 --no-pager

“Unable to connect you to lobby. Please try again later.”

Velocity 无法连接到该服务器。请确认它已启动并完成加载,然后确认 velocity.toml 中的端口与 server-port 一致。上文的 ss 命令可显示实际开放的端口。

“There are no available servers to connect you to.”

try 列表中没有任何服务器接受该玩家。请检查此列表,并至少启动其中一台服务器。

“Your server did not send a forwarding request to the proxy”

Paper 服务器上未启用现代转发。请确认 config/paper-global.yml 中为 enabled: true,然后重启该服务器。如果其日志显示 Velocity is enabled, but no secret key was specified,说明密钥为空:请重新执行接入现有服务器一节。

“Unable to verify player details”

Paper 中的密钥与 forwarding.secret 不一致。请在相关服务器上重新运行复制密钥的命令,然后重启该服务器。对于 lobby 服务器,请使用路径 /opt/minecraft/lobby/config/paper-global.yml。

“This server requires you to connect with Velocity.”

玩家未经过代理直接连接到了 Paper 服务器,或者 Velocity 未使用 modern 模式。请检查 player-info-forwarding-mode 以及玩家使用的地址。如果玩家能从互联网访问 25566,请立即关闭此端口。

“This server is only compatible with Minecraft 1.13 and above.”

现代转发会拒绝低于 1.13 的客户端。这些玩家需要升级到更新的版本。

Velocity 无法启动

日志中的消息 原因 解决方法
Can't bind to …:25565 端口已被占用,通常是被某台 Minecraft 服务器占用 检查 server-port 并使用 sudo ss -ltnp
Server 'factions' for forced host '…' does not exist [forced-hosts] 中还留有示例 清空该节
Fallback server … is not registered in your configuration! try 中的某个名称不在 [servers] 中 更正该名称
You don't have a forwarding secret set 密钥文件为空或找不到 检查 forwarding.secret
UnsupportedClassVersionError Java 版本过旧 安装 Java 25

Paper 服务器上出现“FAILED TO BIND TO PORT”

有两个服务在使用同一端口。请检查各 server.properties 中的 server-port:survie 为 25566,lobby 为 25567。

玩家的物品栏丢失

服务器为他们分配了另一个 UUID,通常是因为转发未启用,或者 proxies.velocity.online-mode 与 Velocity 的 online-mode 不一致。请停止服务器,更正这些设置后重新启动:原始数据仍保留在世界中,对应旧的 UUID。

如需进一步了解,请查阅 Velocity 官方文档,特别是关于玩家信息转发和安全的页面。