根据新版配置格式重写文档

astro.config.ts

@@ -72,15 +72,10 @@ export default defineConfig({
                   collapsed: true,
                   items: [
                     "manual/zh/config/配置列表",
-                    "manual/zh/config/backend-server",
-                    "manual/zh/config/database",
-                    "manual/zh/config/messages",
-                    "manual/zh/config/modules",
-                    "manual/zh/config/misc",
-                    "manual/zh/config/remap",
-                    "manual/zh/config/offline-auth",
-                    "manual/zh/config/offlinematch",
+                    "manual/zh/config/start",
+                    "manual/zh/config/core",
                     "manual/zh/config/yggd-entry",
+                    "manual/zh/config/auth-offline",
                     "manual/zh/config/profile-skin",
                     "manual/zh/config/safe",
                     "manual/zh/config/merge-am",

src/content/docs/manual/zh/config/auth-offline.md

@@ -0,0 +1,134 @@
+---
+title: auth-offline.conf
+---
+
+离线登陆验证模块配置文件。在模块`auth-offline`激活时有效。
+
+```hocon
+# 离线认证主要设置
+main {
+    # 密码规则
+    password {
+        # 最短密码长度
+        min-length=6
+        # 最长密码长度
+        max-length=64
+        # 禁止密码含用户名
+        deny-name-in-password=true
+    }
+    # 登录保护
+    login {
+        # 输错多少次锁定登录
+        max-attempts=5
+        # 锁定冷却时间（秒）
+        block-seconds=300
+    }
+    # 邮箱与找回
+    email {
+        # 启用邮箱命令
+        enabled=true
+        # 恢复码投递模式：LOG 或 SMTP
+        delivery-mode=LOG
+        # 恢复码长度
+        recovery-code-length=6
+        # 恢复码有效期（分钟）
+        recovery-code-expire-minutes=15
+        # 请求恢复邮件冷却（秒）
+        recovery-cooldown-seconds=120
+        # 单个恢复码允许输错次数
+        max-code-verify-attempts=3
+        # 恢复码校验成功后，允许修改密码的时间窗口（分钟）
+        reset-password-window-minutes=10
+        # 恢复邮件模板与 SMTP 配置
+        smtp {
+            # 邮件显示的服务器名称
+            server-name=HyperZoneLogin
+            # ❇️SMTP 服务器地址
+            host="smtp.example.com"
+            # ❇️SMTP 端口
+            port=587
+            # 是否启用 SMTP 认证
+            auth=true
+            # ❇️SMTP 用户名
+            username="noreply@example.com"
+            # ❇️SMTP 密码或应用专用密码
+            password=change-me
+            # 是否启用 STARTTLS
+            start-tls=true
+            # ❇️是否直接使用 SSL
+            ssl=false
+            # 连接超时（毫秒）
+            connection-timeout-millis=10000
+            # 读取超时（毫秒）
+            read-timeout-millis=10000
+            # 写入超时（毫秒）
+            write-timeout-millis=10000
+            # ❇️发件人邮箱
+            from-address="noreply@example.com"
+            # ❇️发件人名称
+            from-name=HyperZoneLogin
+            # ❇️恢复邮件主题，支持占位符：%server%、%player%
+            recovery-subject="[%server%] 账号密码找回验证码"
+            # ❇️恢复邮件正文，支持占位符：%server%、%player%、%email%、%code%、%minutes%。使用 \n 表示换行
+            recovery-body="你好，%player%。\\n\\n你在 %server% 请求了离线账号密码找回。\\n验证码：%code%\\n有效期：%minutes% 分钟\\n\\n如果不是你本人操作，请忽略这封邮件。"
+        }
+    }
+    # 提示
+    prompt {
+        # 首次进入邮箱找回提示
+        show-recovery-hint=true
+    }
+    # 会话自动登录
+    session {
+        # 短期会话自动登录
+        enabled=false
+        # 会话有效期（分钟）
+        expire-minutes=30
+        # 会话与玩家 IP 绑定
+        bind-ip=true
+        # 注册成功后立刻签发会话
+        issue-on-register=true
+    }
+    # ⚠️透传离线 UUID
+    pass-offline-uuid-to-profile-resolve=true
+    # TOTP 二步验证
+    totp {
+        # 启用 TOTP（二步验证功能）
+        enabled=true
+        # 在验证器 App 中显示的名称
+        issuer=HyperZoneLogin
+        # 待确认 TOTP 密钥的有效期（分钟）
+        pending-expire-minutes=10
+        # 允许 短期会话 跳过二次验证
+        allow-session-bypass=false
+    }
+}
+# ⚠️玩家正离线形态匹配设置
+match {
+    # 是否允许进行匹配
+    enable=true
+    # UUID匹配设定
+    uuid-match {
+        # 是否允许全0的UUID(Zalith) 匹配为离线
+        zero=true
+        # 是否允许默认uuid生成方法 匹配为离线
+        offline=true
+        # 关于PCL2启动器匹配的细节设定
+        pcl2 {
+            # PCL2的UUID匹配
+            enable=true
+            # PCL2的UUID进行哈希计算匹配
+            hash=true
+            # PCL2的苗条模型UUID匹配
+            slim=true
+        }
+    }
+    # Host匹配设定
+    host-match {
+        start=[
+            offline,
+            o-
+        ]
+    }
+}
+```

src/content/docs/manual/zh/config/core.md

@@ -0,0 +1,161 @@
+---
+title: core.conf
+---
+
+插件核心配置文件，包括数据库、模块、等待区设置、调试输出等配置。
+
+```hocon
+# 数据库
+database {
+    # ❇️数据库类型
+    # 支持的值: SQLITE, MYSQL, MARIADB
+    type=SQLITE
+    # SQLite 数据库配置
+    sqlite {
+        # 数据库文件路径（相对于插件数据目录）
+        path="data/hyperzone_login.db"
+    }
+    # MySQL 数据库配置
+    mysql {
+        # ❇️地址
+        host=localhost
+        # ❇️端口
+        port=3306
+        # 库名
+        database="hyperzone_login"
+        # ❇️用户名
+        username=root
+        # ❇️密码
+        password=password
+        # ⚠️额外的连接参数
+        parameters="useSSL=false&serverTimezone=UTC&characterEncoding=utf8"
+        # ⚠️JDBC 驱动类（通常不需要修改）
+        driver-class-name="com.mysql.cj.jdbc.Driver"
+    }
+    # MariaDB 数据库配置
+    mariadb {
+        # ❇️地址
+        host=localhost
+        # ❇️端口
+        port=3306
+        # 库名
+        database="hyperzone_login"
+        # ❇️用户名
+        username=root
+        # ❇️密码
+        password=password
+        # ⚠️额外的连接参数
+        parameters="useSSL=false&characterEncoding=utf8"
+        # ⚠️JDBC 驱动类（通常不需要修改）
+        driver-class-name="org.mariadb.jdbc.Driver"
+    }
+    # ⚠️数据库表前缀（随意修改可能导致无法读取数据）
+    table-prefix="hz_"
+    # ⚠️连接池配置（影响数据库连接性能）
+    pool {
+        # ⚠️最大连接数
+        maximum-pool-size=10
+        # ⚠️最小空闲连接数
+        minimum-idle=2
+        # ⚠️连接超时时间（毫秒）
+        connection-timeout=30000
+        # ⚠️空闲连接超时时间（毫秒）
+        idle-timeout=600000
+        # ⚠️连接最大生命周期（毫秒）
+        max-lifetime=1800000
+    }
+}
+# UUID映射
+remap {
+    # ⚠️未开启对应渠道UUID透传时的生成前缀，如果填OfflinePlayer则为行业标准离线生成法
+    prefix=HyperZone
+}
+# 杂项
+misc {
+    # ⚠️不给服务器发送 CHAT_SESSION_UPDATE包
+    kill-chat-session=true
+}
+# Debug
+debug {
+    # 日志调试开关；建议统一放在此分支下配置
+    log {
+        # 通用 debug 日志
+        general=false
+        # Floodgate / OutPre 预登录链路追踪日志
+        out-pre-trace=false
+        # ProfileSkin 相关调试日志
+        profile-skin=false
+        # 后端等待区兼容链路调试日志
+        backend-compat=false
+        # Netty / GameProfile 重写链路调试日志
+        network-rewrite=false
+        # Yggdrasil 认证链路调试日志
+        yggdrasil-auth=false
+    }
+    # 慢测试模式相关配置
+    slow-test {
+        # 开启后，外部模块直接调用 overVerify 将被忽略，只有等待区 /over 才会真正完成 overVerify
+        enabled=false
+    }
+}
+# ❇️模块开关
+modules {
+    # Floodgate 认证；仅在已安装 floodgate 时生效
+    auth-floodgate=true
+    # 离线认证
+    auth-offline=true
+    # Yggdrasil 认证
+    auth-yggd=true
+    # 安全防护
+    safe=true
+    # 皮肤缓存
+    profile-skin=true
+    # 数据迁移
+    data-merge=false
+}
+# 等待区服务器
+v-server {
+    # 登录服实现模式：backend 或 outpre。推荐 outpre 模式，若有问题请使用backend模式。
+    mode=outpre
+    # ❇️认证完成后默认进入的服务器
+    post-auth-default-server=play
+    # 记住认证时收到的服务器跳转请求
+    remember-requested-server-during-auth=true
+    backend {
+        # 使用的真实认证等待服 Velocity 服务器名
+        fallback-auth-server=lobby
+        # 等待区 UpsertPlayerInfo/TabList 兼容过滤补偿
+        enable-player-info-compensation=true
+        # 档案补偿同步
+        enable-profile-compensation=true
+        # 在线热改 name（风险较低，默认开启）
+        enable-name-hot-change=true
+        # 在线热改 UUID（高风险，默认关闭）
+        enable-uuid-hot-change=false
+    }
+    outpre {
+        # 认证服的逻辑名，仅用于日志/状态标识；不需要在 Velocity 的 servers 中注册。
+        # 如果使用 ViaVersion，你需要在 Velocity 的 servers 中添加注册条目，如 outpre-auth = "127.0.0.1:30066"，但不需要将其配置到 try 队列。
+        auth-label=outpre-auth
+        # 认证服的直连 Host
+        auth-host="127.0.0.1"
+        # 认证服的直连 Port
+        auth-port=30066
+        # 转接给认证服时，在连接握手中对后端暴露的 Host；留空时使用 authHost
+        presented-host=""
+        # 转接给认证服时，在连接握手中对后端暴露的 Port；<=0 时使用 authPort
+        presented-port=-1
+        # 转接给认证服时，在连接握手中对后端暴露的玩家源 IP；留空时使用玩家真实 IP
+        presented-player-ip=""
+    }
+}
+# 消息
+messages {
+    # 默认语言；当未启用客户端语言检测，或客户端语言没有对应语言文件时使用
+    default-locale="zh_cn"
+    # 消息缺失时的回退语言；建议始终保留 en_us 或 zh_cn 之一
+    fallback-locale="en_us"
+    # 优先尝试读取客户端语言
+    use-client-locale=true
+}
+```

src/content/docs/manual/zh/config/legacy/配置列表.mdx

@@ -0,0 +1,43 @@
+---
+title: "配置列表（旧）"
+---
+
+import { FileTree } from "@astrojs/starlight/components";
+
+本页面介绍插件所涉及的各种配置文件。
+
+:::caution[配置格式已过时！]
+此页面所载的配置格式已经过时，仅适用于26.4.5-SNAPSHOT-8fcde1ec及以前版本。  
+关于目前正在使用的配置格式，请前往[新版配置列表](/manual/zh/config/配置列表/)页面。
+:::
+
+:::danger[危险]
+**部分配置项会直接影响本插件的关键行为，配置不得当的情况下很可能导致插件无法正常工作乃至崩溃。**  
+此类配置项已在对应的描述中添加了“⚠️”作为标识。除非你真的知道你在做什么，否则不要改动这些配置项目。
+:::
+
+<FileTree>
+  - plugins/hyperzonelogin/ HyperZoneLogin 插件数据目录
+    - data/ 数据库目录
+    - entry/ Yggdrasil 验证条目目录
+      - example/ 示例配置文件目录，不会被插件加载
+        - example.conf 示例配置文件
+      - elyby.conf Ely.by外置登录支持
+      - littleskin.conf Littleskin外置登录支持
+      - mojang.conf ⚠️正版登录支持
+      - [验证条目配置格式](/manual/zh/config/legacy/yggd-entry)
+    - libs/ 代码库目录
+    - merge/ 数据迁移目录
+      - [merge-am.conf](/manual/zh/config/legacy/merge-am) Authme 数据迁移配置
+      - [merge-ml.conf](/manual/zh/config/legacy/merge-ml) Multilogin 数据迁移配置
+    - [backend-server.conf](/manual/zh/config/legacy/backend-server) 后端服务器配置
+    - [database.conf](/manual/zh/config/legacy/database) 数据库配置
+    - [messages.conf](/manual/zh/config/legacy/messages) 语言选择配置
+    - [misc.conf](/manual/zh/config/legacy/misc) 杂项配置
+    - [modules.conf](/manual/zh/config/legacy/modules) 模块配置
+    - [offline-auth.conf](/manual/zh/config/legacy/offline-auth) 离线验证模块配置
+    - [offlinematch.conf](/manual/zh/config/legacy/oflinematch) 离线玩家匹配配置
+    - [profile-skin.conf](/manual/zh/config/legacy/profile-skin) 皮肤缓存与恢复模块配置
+    - [remap.conf](/manual/zh/config/legacy/remap) ⚠️UUID重映射配置
+    - [safe.conf](/manual/zh/config/legacy/safe) 安全防护模块配置
+</FileTree>