服务器基础配置

注意

先把 Velocity 代理与后端服的基础转发链路配置正确，再谈 HyperZoneLogin。
如果你对 Velocity、Paper、forwarding.secret、后端服 online-mode 这些概念还不熟悉，建议先补齐代理服基础知识。HyperZoneLogin 是建立在这些前置条件之上的登录框架，而不是替你跳过这些基础配置的“免配置插件”。

HyperZoneLogin 工作在代理层，需要可靠地识别玩家、控制认证阶段的转发行为，并把最终档案结果送到后端服务器。这要求你的代理链路至少满足以下条件：

• Velocity 与后端服之间的转发方式正确；
• 后端服只接受来自代理的连接；
• 代理与后端使用一致的密钥；
• 后端不会自行以在线模式再次接管登录流程。

只要这几个前提有一个没有满足，后续出现“UUID 不对”“玩家被踢”“认证状态丢失”“后端直接进服”等问题都很常见。

玩家信息转发配置

HyperZoneLogin 需要使用 Velocity 的modern转发方式才能正常运作。 以下简要介绍 Velocity 和 Paper 端的配置方法，其他后端服务器的配置方法请参考Velocity官方文档。

Velocity 配置

打开 Velocity 根目录中的 velocity.toml，确认如下配置：

player-info-forwarding-mode = "modern"

然后记录 Velocity 根目录下 forwarding.secret 文件中的内容。

Paper 后端服配置

1. 将server.properties文件中的online-mode一项设置为false，禁用服务器本身的身份验证机制。
2. 将spigot.yml中settings类别中的bungeecord一项设置为false，禁用Bungeecord的转发机制。
3. 打开config/paper-global.yml，按照以下代码块进行配置：

proxies:
  velocity:
    enabled: true
    online-mode: false
    secret: ********

其中 secret 必须替换为你自己 forwarding.secret 文件中的真实内容，online-mode必须和velocity.toml中的online-mode配置项保持一致。

配置完成后的预期状态

当代理与后端服配置正确后，应该达到如下状态：

1. 玩家连接的是 Velocity，而不是直接连接后端；
2. 后端服能接收到来自 Velocity 的转发信息；
3. Velocity 与后端服通过同一个 secret 建立可信关系；
4. 后端服不会绕过代理重新执行自己的在线验证流程。

这时，HyperZoneLogin 才有稳定的运行基础。

常见误区

误区 1：后端服能进就说明代理配置没问题

不对。后端能进，只能说明服务端在监听；不能说明代理转发、密钥、在线模式关系完全正确。

误区 2：忘记同步 secret 也没关系

不对。forwarding.secret 与后端 paper-global.yml 中的 secret 必须一致，否则后端无法正确接受 Velocity 转发信息。

误区 3：后端继续开 online-mode=true 更安全

在代理统一接管验证的部署模型里，这通常会造成流程冲突。对当前架构，应让代理层统一处理，后端按代理转发结果工作。

误区 4：不懂代理基础也可以先把插件装上再说

不建议这样做。登录框架本身依赖代理基础知识；如果连代理转发模式、后端在线模式、连接路径都没有梳理清楚，排障成本会非常高。

建议的自检清单

在进入下一章之前，请逐项确认：

• 已完成 Velocity 与后端服的基础联通；
• velocity.toml 使用 modern 转发；
• 后端的modern转发已正确配置，online-mode=false和bungeecord=false均已设置正确；
• 玩家无法绕过代理直连后端。