From 5a42db8728fbc28d7dd2b90977c94903a71dbf0d Mon Sep 17 00:00:00 2001 From: JerryHan3 <13671233113@163.com> Date: Mon, 20 Apr 2026 20:14:39 +0800 Subject: [PATCH 1/4] docs(data-merge/faq): some key issues --- ...70\270\350\247\201\351\227\256\351\242\230.md" | 15 ++++++++++++++- ...77\201\347\247\273\346\225\260\346\215\256.md" | 8 ++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git "a/src/content/docs/manual/zh/\345\270\270\350\247\201\351\227\256\351\242\230.md" "b/src/content/docs/manual/zh/\345\270\270\350\247\201\351\227\256\351\242\230.md" index 5a9b49d..a546239 100644 --- "a/src/content/docs/manual/zh/\345\270\270\350\247\201\351\227\256\351\242\230.md" +++ "b/src/content/docs/manual/zh/\345\270\270\350\247\201\351\227\256\351\242\230.md" @@ -19,7 +19,7 @@ title: "常见问题" 如果玩家长时间未重新登录启动器，或游戏客户端保留了过期会话，进入服务器时就可能被上游验证链路判定为无效会话。 3. **离线玩家使用了非常规 UUID 或特殊启动器接入方式** - 当前离线识别会受到 `offlinematch.conf` 中匹配规则影响。若启动器使用了不常见的 UUID 生成方式，服务器可能无法按预期识别该玩家。 + 当前离线识别会受到 `auth-offline.conf` 中匹配规则影响。若启动器使用了不常见的 UUID 生成方式，服务器可能无法按预期识别该玩家。 ### 处理方法 @@ -56,3 +56,16 @@ java.lang.UnsupportedClassVersionError: icu/h2l/login/HyperZoneLoginBootstrap ha 表示 Java 版本不兼容。HyperZoneLogin 需要使用 Java 24 及以上版本才能运作。 鉴于 Minecraft 26.1 起要求 Java 25 运行，建议直接使用 Java 25 启动服务器。 + +## 为什么被封禁的玩家还能绕过封禁？ + +> *参见：[`core.conf`](/manual/zh/config/core/)* + +HyperZoneLogin 在玩家等待验证时，会临时把玩家名字改成类似 `HZLxxxxxx` 的随机名，防止未登录玩家获得过高权限。但不同登录服实现模式下，这个改名对其他插件的影响不一样： + +- **`outpre` 模式（推荐）**：只修改发送给登录服的玩家信息，Velocity 和其他封禁插件看到的还是玩家的真实名字，封禁能正常生效。 +- **`backend` 模式（备用）**：直接在 Velocity 上改名字，因此登陆期间 Velocity 和其他插件（比如封禁插件）看到的都是临时名 `HZLxxxxxx`。如果此时封禁插件检测到违规，或者会记忆玩家首次登陆时的信息，它封的会是这个临时名，而不是真正的玩家。再加上每次临时名都不一样，**玩家只需要再次进服就能绕过封禁。** + +:::caution[由于改名逻辑的不同，`backend`模式还可能会和其他 Velocity 插件出现不兼容的现象。] +**任何情况下都请优先使用 `outpre` 模式**，只在遇到严重兼容性问题时再考虑切到 `backend` 模式。这样既能保证其他插件正确识别玩家，又不会影响登录流程的安全性。 +::: diff --git "a/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" "b/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" index 5d63d68..6565040 100644 --- "a/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" +++ "b/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" @@ -6,6 +6,10 @@ title: 迁移数据 ## 迁移步骤 +:::caution[务必备份原有的数据库！] +迁移数据涉及对数据库的直接更改，**属于高危操作。** 请务必在迁移前将 HyperZoneLogin 的数据库和 Authme/Multilogin 的数据库都备份一次！ +::: + 首先，请在`core.conf`配置中激活`data-merge`模块。 ```hocon title=core.conf @@ -22,6 +26,10 @@ modules { ## Multilogin 迁移配置 +:::danger[目前迁移模块无法从 Multilogin 正常迁移基岩版玩家数据。] +这将导致迁移后出现玩家档案冲突。开发者[正在着手解决此问题](https://github.com/HyperZoneLogin/HyperzoneLogin/issues/16)，有使用 Multilogin 处理基岩版登录的服务器请暂时不要进行迁移操作。 +::: + Multilogin 数据迁移的配置文件为`/plugins/hyperzonelogin/data-merge`目录下的`multilogin.conf`文件。 在此之前，你需要先按照 Multilogin 中的原有配置，**为每个 Yggdrasil 登录服务创建好[条目配置文件](/manual/zh/config/yggd-entry/)** 。 From a5b7d84197b4ec7b822ef984e2fd20f1e136e681 Mon Sep 17 00:00:00 2001 From: JerryHan3 <13671233113@163.com> Date: Mon, 20 Apr 2026 20:55:32 +0800 Subject: [PATCH 2/4] docs(command): command reference --- astro.config.ts | 1 + ...75\344\273\244\345\210\227\350\241\250.md" | 48 +++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 "src/content/docs/manual/zh/\345\221\275\344\273\244\345\210\227\350\241\250.md" diff --git a/astro.config.ts b/astro.config.ts index cab0cc0..0254399 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -82,6 +82,7 @@ export default defineConfig({ "manual/zh/config/merge-ml", ], }, + "manual/zh/命令列表", "manual/zh/迁移数据", "manual/zh/常见问题", "manual/zh/问题反馈", diff --git "a/src/content/docs/manual/zh/\345\221\275\344\273\244\345\210\227\350\241\250.md" "b/src/content/docs/manual/zh/\345\221\275\344\273\244\345\210\227\350\241\250.md" new file mode 100644 index 0000000..3e864d5 --- /dev/null +++ "b/src/content/docs/manual/zh/\345\221\275\344\273\244\345\210\227\350\241\250.md" @@ -0,0 +1,48 @@ +--- +title: 命令列表 +--- + +以下是 HyperZoneLogin 及其各项模块所包含的所有命令。 + +:::note[HyperZoneLogin 不使用权限系统控制命令的权限。] +这种设计是为了避免出现意外提权。所有管理命令请**直接从服务器控制台执行。** +::: + +:::tip[参数说明] +`<参数名>` 表示必需参数，`[参数名]` 表示可选参数。 +填入参数时**不需要保留括号。** +::: + +## 核心插件 + +| 命令 | 说明 | 所需身份 | +| --- | --- | --- | +| `/hzl re` | 重新触发认证流程 | 玩家 | +| `/hzl reload` | 重载插件配置/状态 | 控制台 | +| `/hzl bindcode generate` | 为当前档案生成绑定码 | 玩家 | +| `/hzl bindcode use <绑定码>` | 使用绑定码绑定到现有档案 | 玩家 | + +## 离线验证 + +| 命令 | 说明 | 所需身份 | +| --- | --- | --- | +| `/login <密码> [TOTP验证码]` | 登录服务器，若启用TOTP需要附带验证码 | 已注册玩家 | +| `/register <密码>` | 为当前玩家注册离线账号并自动登录 | 未注册玩家 | +| `/changepassword <旧密码> <新密码>` | 修改当前玩家的离线账号密码 | 玩家 | +| `/logout` | 登出服务器 | 玩家 | +| `/email add <密码> <邮箱地址> <邮箱地址>` | 绑定邮箱到当前离线账号 | 玩家 | +| `/email change <密码> <旧邮箱地址> <新邮箱地址>` | 修改当前离线账号绑定邮箱 | 玩家 | +| `/email show <密码>` | 查看当前离线账号绑定邮箱 | 玩家 | +| `/email recovery <邮箱地址>` | 向已绑定邮箱发送找回验证码 | 玩家 | +| `/email code <验证码>` | 验证邮箱收到的恢复码 | 玩家 | +| `/email setpassword <新密码> <新密码>` | 在恢复码验证通过后重置密码，并自动完成本次认证 | 玩家 | +| `/totp add <密码>` | 生成待确认的 TOTP 密钥与 `otpauth://` 链接 | 玩家 | +| `/totp confirm ` | 在验证器 App 中添加密钥后，输入当前验证码完成激活 | 玩家 | +| `/totp remove <密码> ` | 验证当前密码与 TOTP 验证码后关闭二步验证 | 玩家 | + +## 数据迁移 + +| 命令 | 说明 | 所需身份 | +| --- | --- | --- | +| `/hzl-merge ml` | 从 Multilogin 迁移数据 | 控制台 | +| `/hzl-merge am` | 从 Authme 迁移数据 | 控制台 | From f24d538282ee123c5f488a32253a4e487f1a0f05 Mon Sep 17 00:00:00 2001 From: JerryHan3 <63506570+JerryHan3@users.noreply.github.com> Date: Sat, 25 Apr 2026 19:36:21 +0800 Subject: [PATCH 3/4] docs(migrate): floodgate id --- .../\350\277\201\347\247\273\346\225\260\346\215\256.md" | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git "a/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" "b/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" index 6565040..16955e8 100644 --- "a/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" +++ "b/src/content/docs/manual/zh/\350\277\201\347\247\273\346\225\260\346\215\256.md" @@ -26,10 +26,6 @@ modules { ## Multilogin 迁移配置 -:::danger[目前迁移模块无法从 Multilogin 正常迁移基岩版玩家数据。] -这将导致迁移后出现玩家档案冲突。开发者[正在着手解决此问题](https://github.com/HyperZoneLogin/HyperzoneLogin/issues/16)，有使用 Multilogin 处理基岩版登录的服务器请暂时不要进行迁移操作。 -::: - Multilogin 数据迁移的配置文件为`/plugins/hyperzonelogin/data-merge`目录下的`multilogin.conf`文件。 在此之前，你需要先按照 Multilogin 中的原有配置，**为每个 Yggdrasil 登录服务创建好[条目配置文件](/manual/zh/config/yggd-entry/)** 。 @@ -52,6 +48,9 @@ Multilogin 数据迁移的配置文件为`/plugins/hyperzonelogin/data-merge`目 - `source.mysql.username`：Multilogin MySQL 数据库用户名。 - `source.mysql.password`：Multilogin MySQL 数据库密码。 +如果你原先为 Multilogin 添加了 Floodgate 服务，你还需要调整以下配置： +- `flodgate-service-ids`：一个含所有 Floodgate 服务 ID 的数组。比如说 Multilogin 中 Floodgate 服务的 ID 是 1，那么此处应填`[1]`。 + **其余配置请勿擅自改动**，除非你修改过 Multilogin，使用了自定义的 JDBC 链接或参数。 ## Authme 迁移配置 From bb74e46b12114b436fe32fb166fa74a5c4940cd2 Mon Sep 17 00:00:00 2001 From: JerryHan3 <63506570+JerryHan3@users.noreply.github.com> Date: Sat, 25 Apr 2026 19:41:20 +0800 Subject: [PATCH 4/4] docs(config): floodgate service ids config --- src/content/docs/manual/zh/config/merge-ml.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/manual/zh/config/merge-ml.md b/src/content/docs/manual/zh/config/merge-ml.md index 9e8fbfd..88d5723 100644 --- a/src/content/docs/manual/zh/config/merge-ml.md +++ b/src/content/docs/manual/zh/config/merge-ml.md @@ -49,7 +49,8 @@ tables { service-id-mapping { "1"=mojang } - +# Floodgate 服务 ID。此服务中的用户数据将会被迁移至 HyperZoneLogin 的 Floodgate 数据表中。 +floodgate-service-ids=[] ``` ## 服务ID映射配置