关键问题说明与命令文档

astro.config.ts

@@ -82,6 +82,7 @@ export default defineConfig({
                     "manual/zh/config/merge-ml",
                   ],
                 },
+                "manual/zh/命令列表",
                 "manual/zh/迁移数据",
                 "manual/zh/常见问题",
                 "manual/zh/问题反馈",

src/content/docs/manual/zh/命令列表.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 <TOTP验证码>` | 在验证器 App 中添加密钥后，输入当前验证码完成激活 | 玩家 |
+| `/totp remove <密码> <TOTP验证码>` | 验证当前密码与 TOTP 验证码后关闭二步验证 | 玩家 |
+
+## 数据迁移
+
+| 命令 | 说明 | 所需身份 |
+| --- | --- | --- |
+| `/hzl-merge ml` | 从 Multilogin 迁移数据 | 控制台 |
+| `/hzl-merge am` | 从 Authme 迁移数据 | 控制台 |

src/content/docs/manual/zh/常见问题.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` 模式。这样既能保证其他插件正确识别玩家，又不会影响登录流程的安全性。
+:::

src/content/docs/manual/zh/迁移数据.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/)** 。