如何使用 Velocity 连接多台 Minecraft 服务器
在 VPS 或专用 Linux 服务器上,通过 Velocity 代理连接多台 Paper 服务器:安全转发玩家信息、关闭内部端口以及回退方法。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
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.1velocity.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检查或修改文件开头的这几行:
bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"然后替换 [servers] 和 [forced-hosts] 两节的全部内容:
[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.servicevelocity 和 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 官方文档,特别是关于玩家信息转发和安全的页面。