---
title: 使用 Velocity 进行代理
description: 使用 Velocity 进行代理搭建跨服端
lastUpdated: 2026-01-12
---

Velocity 代理可以让玩家通过此代理连接到后端服务器，从而隐藏后端服务器的真实IP，同时 Velocity 还可以用来搭建跨服端，因为从 Velocity 连接的玩家可以通过输入命令随意在 Velocity 连接的后端服务器中切换。

## 安装 Java
Velocity 是用 Java 编写的，所以如果你还没安装 Java，就需要安装 在你继续之前。velocity 至少需要 Java 17，但21或更高时效果最佳。

## 初始化 Velocity

前往 **[PaperMC 官网](https://papermc.io/software/velocity/)** 下载 Velocity

将其放入一个空文件夹，在终端运行以下命令来启动 Velocity

```bash
java -jar velocity-x.x.x.jar
```

:::tip
确保把 `velocity-x.x.x.jar` 改为了你下载的 Velocity JAR 文件的名称。
:::

这将首次启动 Velocity 并生成配置文件 `velocity.toml`

以下是启动 `velocity` 后您将看到的输出：

```bash
[05:41:13 INFO]: Booting up Velocity 3.4.0-SNAPSHOT (git-74c932e5-b363)...
[05:41:13 INFO]: Loading localizations...
[05:41:13 INFO]: Connections will use epoll channels, libdeflate (Linux aarch64) compression, OpenSSL (Linux aarch64) ciphers
[05:41:13 INFO]: Loading plugins...
[05:41:13 INFO]: Loaded 0 plugins
[05:41:13 INFO]: Listening on /[0:0:0:0:0:0:0:0%0]:25565
[05:41:13 INFO]: Done (0.36s)!
```

此时关闭它，修改配置文件，键入以下命令以关闭 Velocity ：

```bash
end
```
关闭会出现以下输出：

```bash
[05:42:10 INFO]: Shutting down the proxy...
[05:42:10 INFO]: Closing endpoint /0.0.0.0:25565
```

## 配置Velocity

现在我们需要配置每台服务器接受来自代理的连接。

Velocity 是一个高度可配置的代理。虽然大多数用户不需要更改所有内容 配置，配置参考页面上有大量选项，还有详细说明 每种选项的运作方式。

编辑 `velocity.toml` 文件，以下是每个选项的作用

### 常规模块

```toml

config-version = "2.7"
#配置文件版本，不要修改这个选项！

bind = "0.0.0.0:25565"
#绑定端口，默认25565，玩家将通过此端口连接Velocity并进行代理转发 

motd = A Velocity Server
#服务器副标题

online-mode = true
#是否启用在线模式。

force-key-authentication = true
#强制客户端使用 Minecraft 1.19+ 的公钥身份验证（增强安全性）

prevent-client-proxy-connections = false
#是否阻止通过 **VPN/代理** 连接的玩家（可能会误伤）

player-info-forwarding-mode = "NONE" 
#玩家远程信息转发模式， 有 `NONE` / `LEGASY` / `BUNGEEGUARD` / `MODERN` 四种，详见 **[配置玩家信息转发](#配置玩家信息转发)**

forwarding-secret-file = "forwarding.secret"
#远程密钥文件路径，默认位于 Velocity 根目录的 forwarding.secret

announce-forge = false
#支持Forge系，如 Neoforge/Forge，若后端服务器为 Forge 系，在保证此项打开的前提下应该在后端服务器安装 **[proxy-compatible-forge](https://modrinth.com/mod/proxy-compatible-forge)** 这个 Mod

kick-existing-players = false
#如果开启（默认是关闭），并且代理处于在线模式，Velocity 将会在重复连接尝试时踢出任何已在线的玩家。

ping-passthrough = "DISABLED"
#收到Ping请求时查询后端服务器的模式，有 `disabled`/`mods`/`description`/`all` 四种模式

sample-players-in-ping = false
#是否响应Ping请求时包含玩家列表

enable-player-address-logging = true
#是否记录玩家真实IP地址


```

### [servers] 模块

在此模块中配置你的**后端 Minecraft 服务器列表**。每个条目包含一个自定义名称和对应的 IP 地址及端口。

```toml
[servers]
# Configure your servers here. Each key represents the server's name, and the value
# represents the IP address of the server to connect to.
lobby = "127.0.0.1:30066"
factions = "127.0.0.1:30067"
minigames = "127.0.0.1:30068"
```

这是配置文件的默认示例，配置如此，就会以以上三个服务器为后端服务器，等号前为服务器名称，你可以自定义修改它，等号后为服务器地址。

在 `try = [ "" ]` 填写服务器名称作为登入服务器，玩家在使用 Velocity 连接时登入的默认服务器，可填写多个，在第前者连接失败后将尝试第后者，填写一个则在此服务器登入失败后断开连接。

```toml
# In what order we should try servers when a player logs in or is kicked from a server.
try = [
  "lobby" #进入服务器将尝试连接服务器列表中名为 lobby 的服务器
]
```

### [forced-hosts] 模块

在此处配置你的强制主机，当玩家使用域名连接时，不同的域名可以被分配至不同的服务器，默认示例：

```toml
[forced-hosts]
# Configure your forced hosts here.
"lobby.example.com" = [
  "lobby"
]
"factions.example.com" = [
  "factions"
]
"minigames.example.com" = [
  "minigames"
]
```

### [advanced] 模块

在此处配置高级设置

```toml

compression-threshold = 256
#数据包必须有多大，我们才会压缩它。将其设置为零将压缩所有数据包，将其设置为 -1 将完全禁用压缩

compression-level = -1
#应该进行多少压缩 (从 0-9)，默认是 -1。

login-ratelimit = 3000
#客户端在上次连接后允许多快连接 (以毫秒为单位)？默认是三秒。通过将其设置为 0 来禁用此功能。

connection-timeout = 5000
#在此处指定连接超时的自定义超时时间。默认是五秒。

read-timeout = 30000
#在此处指定连接的读取超时时间。默认是 30 秒。

haproxy-protocol = false
#我也不知道这是啥

tcp-fast-open = false
#在代理上启用 TCP 快速打开支持。需要代理在 Linux 上运行。

bungee-plugin-message-channel = true
#在 Velocity 上启用 BungeeCord 插件消息通道支持。

show-ping-requests = false
#显示来自客户端的 ping 请求到代理。

failover-on-unexpected-server-disconnect = true
#还是不知道（

announce-proxy-commands = true
#向 1.13+客户端声明代理命令。

log-command-executions = false
#启用命令的日志记录。

log-player-connections = true
#启用记录玩家连接到代理，切换服务器以及从代理断开连接的日志。

accepts-transfers = false
#允许通过 Transfer 数据包 (Minecraft 1.20.5) 从其他主机传输的玩家被接收。

enable-reuse-port = false

command-rate-limit = 50
#命令速率限制，默认为0.05s

forward-commands-if-rate-limited = true

kick-after-rate-limited-commands = 0

tab-complete-rate-limit = 10

kick-after-rate-limited-tab-completes = 0

```

### [query] 模块

```toml

enabled = false
#是否启用对 GameSpy 4 查询响应的响应。

port = 25577
#如果查询已启用，查询协议应该在哪个端口上监听？

map = "Velocity-CTD"
#这是向查询服务报告的名称。

show-plugins = false
#默认情况下是否应该在查询响应中显示插件。

```

## 配置玩家信息转发（可选）

|选项|详解|
|---|---|
|NONE|不进行转发|
|LEGASYBungeeCord|转发|
|BUNGEEGUARD|和BungeeCord（LEGASY）转发一样，但包含一个密钥。|
|MODERN|Velocity 原生格式，它高效地转发所有玩家信息。|

MODERN 转发更高效，安全，以在 Velocity 配置 MODERN 转发为例

在 `velocity.toml` 文件中的 `player-info-forwarding-mode` 处配置玩家信息转发。

设置为 `player-info-forwarding-mode = "MODERN"`

在 Velocity 根目录，即 velocity jar 文件所在的文件夹存在一个 `forwarding.secret` 文件，其中存放着远程密钥，以对后端服务器进行验证，可以修改此文件来修改密钥。

例如此处修改为 `REoxygen` 

接下来配置后端服务器

### 配置 Paper/Folis/Leavea 的 MODREN 玩家信息转发模式

:::tip
保证根目录下 `spigot.yml` 文件中的 `bungeecord` 选项为 `false`，否则无法进行 MODERN 转发，如果你没有对此项进行修改，则不需要额外修改此项。
:::

在 Paper 服务端根目录中存在 config/paper-global.yml 文件，修改此文件，找到以下部分并修改。

```yml
proxies:
  bungee-cord:
    online-mode: true
  proxy-protocol: false
  velocity:
    enabled: true
    #是否启用 MODERN 转发。
    online-mode: true
    #是否启用在线模式，应与 `velocity.yoml` 文件内的选择保持一致。
    secret: 'REoxygen'
    #远程密钥，与 `forwarding.secret` 文件中内容保持一致。
```

**仅需修改 Velocity 以下的选项即可**

:::tip
使用 MODERN 转发模式时，如需开启在线模式请在 Velocity 中启用它，并关闭后端服务器中 `server.properties` 文件中的在线模式选项，让 Velocity 进行正版验证并转发玩家信息。
:::

### 配置 Forge/NeoForge 的 MODERN 玩家信息转发模式

在 Forge 服务端中安装 **[Proxy-Compatible-Forge](https://modrinth.com/mod/proxy-compatible-forge)** 模组，并运行服务端，生成配置文件，配置文件位于服务端根目录下 config/proxy-compatible-forge.toml 文件中找到以下内容并修改它。

```toml
#Player Info Forwarding Settings
[forwarding]
	#Enable or disable player info forwarding. Changing this setting requires a server restart.
	enabled = true  
  #是否启用 MODERN 玩家信息转发
	
  #The type of forwarding to use
	#Allowed Values: MODERN  
	mode = "MODERN"  #玩家信息转发类型
	
  #The forwarding secret shared with the proxy
	secret = ""  #密钥，与 `forwarding.secret` 内容保持一致。
	
  #A list of approved proxy hostnames or IP addresses. If the connecting proxy's hostname or IP isn't in this list, the player will be disconnected. Leave empty to allow all.
	approvedProxyHosts = []
```

- 修改 `player-info-forwarding-mode` 的选项为 `MODERN`。

- 修改 `secret` 选项与 `forwarding.secret` 内容保持一致。

:::tip
再次提醒，使用 MODERN 转发模式时，如需开启在线模式请在 Velocity 中启用它，并关闭后端服务器中 `server.properties` 文件中的在线模式选项，让 Velocity 进行正版验证并转发玩家信息。
:::

重启Fabric服务端即可

### 配置 Fabric 的 MODERN 玩家信息转发模式

在 Fabric 服务端中安装 **[FabricProxy-Lite](https://modrinth.com/mod/fabricproxy-lite)** 模组，并运行服务端，生成配置文件，配置文件位于服务端根目录下 `config/FabricProxy-Lite.toml` 找到并修改它。

```toml
hackOnlineMode = true
#在线模式，应与 `velocity.toml` 保持一致

hackEarlySend = false

hackMessageChain = false

disconnectMessage = "This server requires you to connect with Velocity."

secret = "REoxygen"
#密钥，应与 `forwarding.secret` 内容保持一致。
```

- 修改 `secret` 选项与 `forwarding.secret` 内容保持一致。

:::tip
再再次提醒，使用 MODERN 转发模式时，如需开启在线模式请在 Velocity 中启用它，并关闭后端服务器中 `server.properties` 文件中的在线模式选项，让 Velocity 进行正版验证并转发玩家信息。
:::

## 通过 Velocity 连接至后端服务器

配置完 Velocity 和后端服务器就可以运行前后端所有服务器了，如果配置了玩家信息转发，则只能通过 Velocity 代理连接到后端服务器，这提高了后端服务器的安全性，可以做到隐藏后端服务器的真实IP。

接下来通过 Velocity 连接到后端服务器

在多人游戏中输入 Velocity 的IP地址和端口：`IP地址:端口号`

Velocity 会将你连接到登入服务器中，你可以通过 `/server 服务器名称` 命令来直接连接到 Velocity 代理的其他后端服务器，`/server` 命令可以直接查看服务器列表。

此命令权限默认对所有玩家开放，你可以使用 [**LuckPerms**](https://luckperms.net/) 管理 Velocity 的命令权限。

:::tip
若管理 Velocity 命令的权限，则需要将 **LuckPerms** 插件的 Velocity 版本放入 Velocity 的插件文件夹中才能起到管理从 Velocity 代理连接的玩家使用 Velocity 相关命令的作用。
:::

关于 **LuckPerms** 详见 [**使用LuckPerms管理玩家权限**](../1-3)

<br/>
<br/>
<br/>

***<center>--- 由 柏茯灵_RsDline 编写 ---</center>***