二次开发 闭源 全新模组Xbox内置登录器 1.20.1

SYLogin —— 神月岛服务器移植版​

---

[MD] ## 0. 五分钟快速上手 如果你只想先把服务器跑起来，按下面四步做： 1. **服务端**：把 `sylogin-1.20.1-1.5.jar` 放进服务端 `mods/`，启动服务器。 2. **客户端**：把同一个 JAR 放进客户端 `mods/`，用 Forge 1.20.1 启动游戏。 3. **登录**：正版 Java 账户无需 Xbox 登录；离线账户进入“多人游戏”界面，点左上角的 **Xbox Login**，在游戏内界面用手机/另一台设备完成微软登录。 4. **进服**：正版玩家自动放行，保留原名字/UUID；离线玩家完成 Xbox 验证后以 `你的Gamertag` 和 Floodgate UUID 进入。 服务端：`config/xbridge/config.json` 客户端：`config/xbridge/client.json` 客户端令牌：`config/xbridge/tokens/msal_cache.json` 皮肤缓存：`config/xbridge/skins/` --- ## 1. 这个模组是做什么的 SYLogin 是一个“登录验证桥”： - 玩家在客户端用 **Xbox / 微软账号**登录； - 服务器在**登录阶段**（玩家还没进入世界时）向 Xbox Live 校验玩家身份； - 校验通过后，服务器用玩家的 **XUID** 生成 UUID：`UUID(0, XUID)`； - 这个 UUID 规则和 **Geyser / Floodgate** 给基岩版玩家的 UUID 完全一致，所以同一个 Xbox 账号在 Java 和基岩版会拥有同一个身份； - 服务器可以自动拉取该账号的基岩版皮肤。 适合： - 想让 Java 玩家用 Xbox 账号登录，并与基岩版身份互通的服务器； - 使用 Mohist 等 Forge + Bukkit 混合端，需要一套独立于 Mojang 正版验证的登录方案； - 已经有 Geyser/Floodgate，希望 Java 玩家也能共用同一套 XUID 身份。 不适合 / 注意： - 它不是“离线登录插件”的替代品：没有 Xbox 账号的玩家无法获得 XUID 身份（可以用 `bypassedUsernames` 放行，但那就没有身份同步了）； - 它不会替代 Geyser/Floodgate：基岩版玩家仍然需要 Geyser 才能进 Java 服； - 客户端和服务端都必须装，只有一边装无法完成验证。 --- ## 2. 准备工作 ### 2.1 版本清单 | 项目 | 要求 | |---|---| | Minecraft | 1.20.1 | | Forge | 47.x（构建使用 47.4.0） | | Java | 17（服务端和客户端都要） | | 模组文件 | `sylogin-1.20.1-1.5.jar` | | 账号 | 一个能登录 Xbox Live 的微软账号（Xbox 档案需已创建） | 检查 Java： ```bash java -version ``` 必须显示 `17.x`。Java 21 启动 1.20.1 Forge 可能直接崩溃，请不要用错版本。 ### 2.2 网络要求 服务器和客户端都需要能访问以下域名（HTTPS 443）： | 域名 | 用途 | |---|---| | `login.microsoftonline.com` | 微软账号 OAuth 登录 / 刷新令牌 | | `user.auth.xboxlive.com` | 用微软令牌换 Xbox Live 令牌 | | `xsts.auth.xboxlive.com` | 换 XSTS 令牌 | | `profile.xboxlive.com` | 服务端校验 XSTS、读取真实 XUID / Gamertag | | `api.geysermc.org` | 拉取基岩版皮肤 | | `api.mineskin.org` | `/syl skin <url>` 生成签名皮肤 | 如果服务器是国内机房或严格防火墙，至少要放行到 `*.xboxlive.com`、`login.microsoftonline.com` 的 443 出站，否则登录会超时或提示令牌无效。 ### 2.3 端口 - Minecraft 服务端默认 `25565/TCP`，需要放行； - 不需要为 SYLogin 额外开放端口； - 1.2 版使用游戏内登录界面（微软设备代码流程），**不会打开外部浏览器**，也不需要监听本机端口。 --- ## 3. 服务端安装 ### 3.1 Forge 服务端 1. 下载 Forge 1.20.1 安装器（例如 `forge-1.20.1-47.4.0-installer.jar`）。 2. 在空目录执行： ```bash java -jar forge-1.20.1-47.4.0-installer.jar --installServer ``` 3. 启动一次生成文件，同意 EULA： ```bash # Windows run.bat --nogui # Linux ./run.sh --nogui ``` 首次启动后编辑 `eula.txt`： ```properties eula=true ``` 4. 把 `sylogin-1.20.1-1.5.jar` 放进服务端 `mods/` 目录（没有就新建）。 5. 再启动服务器。 看到下面这些日志说明加载成功： ``` [SYLogin] SYLogin Forge mod loading (protocol v2) [SYLogin] Generated new 2048-bit RSA keypair for this session [SYLogin] Loaded 0 cached skins [SYLogin] SYLogin Server enabled! ``` ### 3.2 Mohist / 混合端 Mohist 同样使用 `mods/` 目录： 1. 正常安装并启动 Mohist 1.20.1（Forge 47.x 内核）； 2. 把 JAR 放进 `mods/`； 3. 重启服务器； 4. 在 `server.properties` 中建议保持： ```properties online-mode=true ``` 原因：SYLogin 客户端会在登录阶段跳过 Mojang 验证，但**没有装模组的原版客户端仍然走 Mojang 验证**。保持 `online-mode=true` 可以避免普通玩家用任意名字离线进服。 注意事项： - 不要同时用 AuthMe 等登录插件对同一批玩家做“二次密码登录”，否则玩家会先过 Xbox 验证、再被要求输密码。需要的话请在登录插件里豁免 SYLogin 玩家； - 如果使用 BungeeCord / Velocity 等代理，代理可能改写握手 hostname，导致 SYLogin 标记丢失；建议先直连后端测试，确认可用后再加代理； - Mohist 的 Bukkit 插件若取消登录事件，也可能影响进服，排查时先清空插件测试。 ### 3.3 首次启动与配置文件 第一次启动后生成： ``` config/xbridge/config.json config/xbridge/skins/ ``` 默认配置： ```json { "clientId": "98f7077a-f648-4861-8174-f86986364037", "usernamePrefix": "", "enableSkins": true, "autoFetchBedrockSkin": true, "authTimeoutSeconds": 60, "whitelistEnabled": false, "whitelist": [], "blacklist": [], "bypassedUsernames": [], "noModMessage": "§c§lSYLogin Required\\n\\n§7This server requires the SYLogin mod to join.\\n§7Download it at: §bhttps://shenyuedao.cn", "requireXboxForUnmarked": true, "debugLogging": false } ``` #### 字段说明 | 字段 | 说明 | 建议 | |---|---|---| | `clientId` | 微软 OAuth 公共客户端 ID。默认值与模组内置一致 | 一般不用改；默认应用失效时可填自己的 Azure 应用 ID | | `usernamePrefix` | Xbox 玩家名字前缀 | 默认空；旧配置的 `.` 会自动迁移为空，名字只保留字母和数字 | | `enableSkins` | 是否启用皮肤功能 | `true` | | `autoFetchBedrockSkin` | 登录时自动从 Geyser API 拉取基岩版皮肤 | `true` | | `authTimeoutSeconds` | 等待客户端完成 Xbox 验证的秒数 | 网络差可调大到 `120` | | `whitelistEnabled` | 是否只允许白名单中的 XUID 进入 | 公开服 `false`，亲友服 `true` | | `whitelist` | 允许进入的 XUID 列表（十进制字符串） | 配合 `whitelistEnabled` | | `blacklist` | 禁止进入的 XUID 列表 | 优先级高于白名单 | | `bypassedUsernames` | 跳过正版/Xbox 验证的玩家名（按离线 UUID 进入） | **仅限管理员/测试号，慎用** | | `noModMessage` | 未安装模组 / 未完成验证时显示的提示 | 可改成自己的下载地址 | | `requireXboxForUnmarked` | 离线模式服务器上是否拒绝未装 SYLogin 的客户端 | 默认 `true`；用 Geyser/Floodgate 时改 `false` | | `debugLogging` | 输出更多调试日志 | 排查时临时开 `true` | > `noModMessage` 里的 `\\n` 会被转换成换行。手动编辑 JSON 时保留 `\\n` 即可；直接写 `\n` 也可以。 #### 三种常用配置 **公开服（不限制 XUID）** ```json { "usernamePrefix": "", "enableSkins": true, "autoFetchBedrockSkin": true, "authTimeoutSeconds": 60, "whitelistEnabled": false, "whitelist": [], "blacklist": [], "bypassedUsernames": [], "debugLogging": false } ``` **白名单服** ```json { "usernamePrefix": "", "whitelistEnabled": true, "whitelist": [ "2535400000000000", "2535411111111111" ], "blacklist": [], "bypassedUsernames": [] } ``` **测试服（放行一个离线小号）** ```json { "bypassedUsernames": [ "TestAccount" ], "debugLogging": true } ``` `bypassedUsernames` 里的名字会跳过 Xbox 验证，按离线 UUID 进入；这相当于一个后门，公开服不要使用。 修改配置后，管理员可在游戏内执行： ``` /syl reload ``` ### 3.4 获取玩家 XUID 1. 玩家先用 SYLogin 正常进服； 2. 管理员执行： ``` /syl info <玩家名> ``` 输出示例： ``` Display Name: TestGamertag Gamertag: TestGamertag XUID: 2535400000000000 UUID: 00000000-0000-0000-0009-01eed05d1000 XUID Hex: 000901eed05d1000 Has Skin: true ``` 把 `XUID` 那一行填入白名单 / 黑名单，再 `/syl reload`。 ### 3.5 管理员命令 `/syl` 帮助和 `/syl skin` 玩家可用；`/syl reload`、`/syl list`、`/syl info` 需要 **OP / 权限等级 2**： | 命令 | 作用 | |---|---| | `/syl` | 查看帮助 | | `/syl reload` | 重新读取 `config/xbridge/config.json` | | `/syl list` | 列出当前通过 SYLogin 验证的在线玩家 | | `/syl info <player>` | 查看玩家的 XUID、UUID、皮肤状态 | 给管理员 OP（服务器控制台执行）： ``` op <玩家名> ``` 普通玩家只能使用 `/syl skin`。 --- ## 4. 客户端安装与登录 ### 4.1 安装 1. 安装 Forge 1.20.1（47.x），启动一次游戏； 2. 关闭游戏； 3. 把 `sylogin-1.20.1-1.5.jar` 放进客户端 `mods/`； 4. 用 **Forge 1.20.1 配置**启动游戏（不是原版配置）； 5. 进入主菜单 → Mods，确认列表里有 `SYLogin`。 ### 4.2 第一次 Xbox 登录（内置登录界面） > 1.2 版**不会打开任何外部浏览器窗口**。登录界面完全在游戏内，使用微软官方的“设备代码”流程。 1. 主菜单点击 **多人游戏**； 2. 在多人游戏界面**左上角**找到 **Xbox Login** 按钮（分辨率较小或界面按钮较多时可能与其他按钮靠得比较近）； 3. 点击后会打开游戏内的 **“Xbox 登录 · 内置登录器”** 界面； 4. 界面会显示： - 登录网址：`[URL]https://microsoft.com/link[/URL]` - 一个一次性登录代码（大号黄字） 5. 用**手机或另一台设备**打开这个网址，输入界面上的代码； 6. 登录你的微软账号（就是登录 Xbox 的那个账号）并授权； 7. 授权成功后，游戏内界面会自动检测到结果，显示 **登录成功！**，并返回多人游戏界面。 界面示例： ``` Xbox 登录 · 内置登录器 无需外部浏览器，全部在游戏内完成 1. 用手机或另一台设备打开： [URL]https://microsoft.com/link[/URL] 2. 输入下面的代码： ABCD-EFGH 代码有效期约 15 分钟，授权后会自动完成 等待授权中… ``` 右下角同时会弹出提示： ``` SYLogin Auth 登录成功！你的Gamertag ``` 此时令牌已保存，之后进服会自动静默刷新，不需要每次点按钮。 > 1.4 起：登录成功后回到多人游戏界面，左上角的 **Xbox Login** 按钮会变灰禁用，鼠标悬停显示 **“你已经完成了登录!无需再次登录!”**。 > 正版玩家（Mojang 会话有效）也会直接禁用该按钮。 > 需要切换账号时：离线账号删除 `config/xbridge/tokens/msal_cache.json` 后重启客户端；正版账号重新登录启动器。   ### 4.3 登录界面的按钮 | 按钮 | 作用 | |---|---| | 复制代码 | 把登录代码复制到剪贴板 | | 复制链接 | 把 `[URL]https://microsoft.com/link[/URL]` 复制到剪贴板 | | 重新获取 | 当前代码过期/失败时，重新向微软申请一个新代码 | | 取消 | 关闭登录界面，返回多人游戏界面 | 注意事项： - 登录代码有效期约 15 分钟，过期后点 **重新获取**； - 设备代码在微软页面输入时**不区分大小写**，但建议直接复制； - 模组不会接触你的微软密码；密码只输入在微软官方页面上； - 如果登录界面一直停在“正在申请登录代码…”，检查客户端能否访问 `login.microsoftonline.com`。 ### 4.4 检查是否登录成功 客户端目录下应出现： ``` config/xbridge/tokens/msal_cache.json ``` 日志（`logs/latest.log`）中可搜索： ``` [SYLogin] In-game login successful for 你的Gamertag ``` 如果登录失败，日志里会有： ``` [SYLogin] In-game device code login failed: ... ``` ### 4.5 进入服务器 直接连接服务器即可。服务器会根据你的会话类型自动选择验证方式： - **正版 Java 会话有效**：自动放行，名字保持你原来的 Java 名字，UUID 为 Mojang UUID； 不会触发 Xbox 验证，也不会被 `Gamertag` 或基岩皮肤覆盖； - **没有正版会话（离线/非正版）**：必须完成 Xbox 验证，进服后名字为 `你的Gamertag`， UUID 为 `UUID(0, XUID)`（与 Floodgate 一致）； - **未登录 Xbox 且无正版会话**：会被断开，提示： `请先在多人游戏界面点击 Xbox Login 完成内置登录。` 点击 **Xbox Login** 登录后重试； - **Xbox 令牌过期**：重新点 **Xbox Login**； - **未安装 SYLogin 的客户端**： - `online-mode=true`：按原版 Mojang 验证处理，正版可进； - `online-mode=false`：默认被拒绝（`requireXboxForUnmarked=true`），提示安装 SYLogin。 ### 4.6 正版 / 离线账户规则与数据隔离 | 客户端状态 | 服务端验证 | 最终身份 | |---|---|---| | 正版会话有效 + 装了 SYLogin | Mojang 会话服真实验证 | Mojang UUID、原名字、原皮肤 | | 无正版会话 + 装了 SYLogin | Xbox Live XSTS 验证 | `UUID(0, XUID)`、`Gamertag`、基岩皮肤 | | 未装 SYLogin + `online-mode=true` | 原版 Mojang 验证 | 正版放行；离线被 Mojang 拒绝 | | 未装 SYLogin + `online-mode=false` | 默认拒绝 | 需安装 SYLogin 后重新进服 | | `bypassedUsernames` | 跳过验证 | 离线 UUID（管理/测试） | 说明： - 客户端会调用 `api.minecraftservices.com/minecraft/profile` 检查自己的 Mojang 会话，并在握手时标记 `P`（正版）或 `O`（离线）； - **服务端不会只相信这个标记**：标记为 `P` 的客户端仍会强制走 Mojang 加密验证，验证失败会被断开； - 正版玩家的 UUID 是 Mojang UUID，Xbox 玩家是 `UUID(0, XUID)`，两者不同，因此背包、权限、经济、白名单等数据**天然隔离**； - Xbox 的名字前缀、皮肤只写入 Xbox 路径，不会覆盖正版玩家； - 正版会话失效时（例如启动器令牌过期），请重新登录启动器后再进服，或使用 Xbox 登录作为离线身份。 > 使用 Geyser/Floodgate 的离线模式服务器，请把 `requireXboxForUnmarked` 设为 `false`，否则没有 Java 模组的基岩版客户端会被拒绝。 > > **离线模式服务器（`online-mode=false`）注意**：服务端本身无法验明正版，必须依赖 SYLogin 客户端上报正版会话标记。因此正版玩家在这种服务器上**也要安装 SYLogin 客户端**，才能被自动识别放行；未安装的客户端会被默认拒绝。 > > **从 1.2 升级提示**：1.2 版所有客户端都走 Xbox 身份；1.3 后正版玩家会切换到 Mojang UUID。之前 `Gamertag` 身份下的背包/权限数据仍在 Floodgate UUID 下，不会自动迁移；需要继续使用那套数据时，请让该玩家以离线身份登录。 ### 4.7 强制重新登录 关闭游戏，删除： ``` config/xbridge/tokens/msal_cache.json ``` 重新启动客户端并点 **Xbox Login**。 --- ## 5. 皮肤 ### 5.1 自动皮肤 服务器默认会在玩家首次通过验证时，按 XUID 从 Geyser API 拉取该账号的基岩版皮肤，并缓存到： ``` config/xbridge/skins/<UUID>.json ``` - 有皮肤：进服显示基岩版皮肤； - 没有皮肤（API 404 或账号没有基岩版皮肤）：显示 Steve/Alex； - 想关闭：`enableSkins: false`，或 `autoFetchBedrockSkin: false`（只用已有缓存）。 ### 5.2 玩家命令 通过 SYLogin 验证的玩家可以使用： | 命令 | 作用 | |---|---| | `/syl skin <url>` | 用 PNG 直链设置皮肤（经 MineSkin 生成签名） | | `/syl skin reset` | 清除皮肤，恢复 Steve/Alex | | `/syl skin reload` | 重新拉取当前 URL 的皮肤 | 示例： ``` /syl skin [URL]https://example.com/my-skin.png[/URL] ``` 要求： - URL 必须以 `http://` 或 `https://` 开头； - 图片必须是合法的 64x64（或 64x32）Minecraft 皮肤； - MineSkin 有速率限制，失败时稍后再试。 --- ## 6. 与 Geyser / Floodgate 共存 SYLogin 的 UUID 规则与 Floodgate 一致： ``` UUID = UUID(0, XUID) ``` 因此： - 同一个 Xbox 账号： - 通过 Geyser 从基岩版进服 → Floodgate 分配 `UUID(0, XUID)`； - 通过 SYLogin 从 Java 版进服 → 同样得到 `UUID(0, XUID)`； - 两边是同一个玩家身份（背包、权限、经济等按 UUID 存储的数据互通）。 - 基岩版玩家仍然需要 Geyser + Floodgate； - 不需要给基岩版玩家装 SYLogin（他们走 Geyser 自己的验证）； - 如果服务器同时有 Floodgate，SYLogin 会识别 Floodgate UUID 并避免重复处理。 - **离线模式服务器必须设置** `requireXboxForUnmarked: false`，否则没有 Java 模组的 Geyser 客户端会被当作“未验证客户端”拒绝。 - 同一个人的正版 Java 身份和 Xbox 身份是**两套独立数据**（Mojang UUID 与 Floodgate UUID 不同），这是 1.3 的预期行为。 --- ## 7. 常见问题排查 先看日志： - 服务端：`logs/latest.log` - 客户端：`logs/latest.log` Windows 快速过滤： ```bat findstr /i xbridge logs\latest.log ``` Linux： ```bash grep -i xbridge logs/latest.log ``` ### 7.1 启动阶段 | 现象 | 可能原因 | 处理 | |---|---|---| | 启动崩溃，提示 `Mixin apply failed` / `NoSuchMethod` | MC 版本不对、装了旧版/重复 JAR | 确认 1.20.1 + Forge 47.x，`mods/` 只留一个 xbridge JAR | | 提示 `Mod xbridge requires forge [47,)` | Forge 版本太低 | 升级 Forge 到 47.x | | 提示 Java 版本不符 | 用了 Java 21/8 | 换 Java 17 | | 服务端没有 `[SYLogin] SYLogin Server enabled!` | 模组没放进服务端 `mods/`，或不是专用服务器 | 检查 `mods/` 与启动日志 | | 客户端 Mods 列表没有 SYLogin | JAR 没放对位置 / 启动的是原版配置 | 放入客户端 `mods/`，选 Forge 1.20.1 配置 | ### 7.2 登录阶段 | 现象 | 可能原因 | 处理 | |---|---|---| | 多人界面没有 Xbox Login 按钮 | 客户端模组未加载 | 检查 Mods 列表；确认没有装错版本 | | 点按钮没反应 / 登录界面没弹出 | 客户端模组未加载或界面异常 | 检查 Mods 列表和日志；重启客户端 | | 登录界面一直停在“正在申请登录代码…” | 客户端无法访问 `login.microsoftonline.com` | 检查网络/代理；稍后点“重新获取” | | 手机打开 `microsoft.com/link` 打不开 | 手机网络无法访问微软 | 换网络；或改用电脑访问该网址输入代码 | | 设备代码提示过期 | 超过有效期 | 点“重新获取” | | 提示 `请先在多人游戏界面点击 Xbox Login 完成内置登录。` | 客户端还没有登录令牌 | 先点 Xbox Login 完成登录，再进服 | | 提示 `Xbox authentication failed: Invalid or expired XSTS token` | 令牌失效 / 账号没有 Xbox 档案 / 服务器访问 Xbox API 失败 | 重新登录；确认账号能登录 xbox.com；检查服务器出站网络 | | 提示 `Xbox authentication failed: Validation request failed` | 服务器无法访问 `profile.xboxlive.com` | 检查服务器 DNS/防火墙/代理 | | 提示 `Authentication timed out` | 客户端和服务器网络慢，或服务器出站被墙 | 调大 `authTimeoutSeconds`；检查网络 | | 提示 `Invalid SYLogin auth nonce` | 加密应答与本次挑战不匹配 | 重试；确认没有代理/中间件改写登录包 | | 提示 `Failed to process SYLogin authentication` | 客户端应答格式异常 | 更新客户端/服务端到同一版本；查看完整日志 | | 提示 `You are not allowed on this server` / 未在白名单 | XUID 不在白名单或被拉黑 | 管理员 `/syl info` 查 XUID 后加入白名单 | | 提示 `This server requires the SYLogin mod to join` | 客户端没有装模组，或代理改写了握手 | 安装模组；检查代理；先直连测试 | | 离线模式服务器上未装模组的客户端被拒绝 | `requireXboxForUnmarked=true` | 安装 SYLogin；或用 Geyser 时设为 `false` | | 正版玩家进服却变成 `Gamertag` | 客户端没有识别到正版会话（令牌失效/网络） | 重新登录启动器；检查日志 `Premium session check`；确认能访问 `api.minecraftservices.com` | | 正版玩家提示 `Failed to verify username` | Mojang 会话已失效 | 重启启动器重新登录，再进服 | | 正版和 Xbox 数据不互通 | 设计如此：两套 UUID | 需要同一身份时统一使用 Xbox 或统一使用正版 | | 进服后名字不对 | `usernamePrefix` 配置 | 修改配置并 `/syl reload`，玩家重新进服 | | 和基岩版 UUID 对不上 | 不是同一个 Xbox 账号，或没有装 Floodgate | 确认同一账号；确认 Floodgate 正常 | ### 7.3 皮肤问题 | 现象 | 处理 | |---|---| | 进服是 Steve/Alex | 账号没有基岩版皮肤，或 Geyser API 无数据；可用 `/syl skin <url>` | | `/syl skin` 提示失败 | URL 不是直链 PNG、图片格式不对、MineSkin 限流；换图/稍后再试 | | 改了皮肤别人看不到 | 让玩家重新进服；或执行 `/syl skin reload` | | 想彻底清皮肤 | `/syl skin reset`，或删除 `config/xbridge/skins/<UUID>.json` | ### 7.4 Mohist / 插件环境 | 现象 | 处理 | |---|---| | 玩家卡在登录 / 被其他插件踢 | 先停用登录类插件（AuthMe 等）测试 | | 代理后无法验证 | 代理改写 hostname；先直连后端确认；必要时调整代理转发 | | Bukkit 登录事件冲突 | 在插件中豁免 SYLogin 玩家，或调整事件优先级 | --- ## 8. 安全建议 1. **保持 `online-mode=true`**：SYLogin 只对自己的客户端跳过 Mojang 验证，原版客户端仍走正版验证。 2. **不要公开 `bypassedUsernames`**：它等于“免验证后门”，只给管理员/测试号使用。 3. **`/syl` 管理子命令仅 OP 可用**：`reload`、`list`、`info` 限制权限等级 2，普通玩家只能用 `/syl skin`。 4. **保护令牌缓存**：`config/xbridge/tokens/msal_cache.json` 内含刷新令牌，不要发给别人。 5. **白名单服建议开启 `whitelistEnabled`**，按 XUID 管理，而不是按玩家名。 6. **定期备份** `config/xbridge/`（配置、皮肤缓存、令牌不需要备份）。 7. **不要把 `clientId` 改成别人的私有应用**；默认是公共客户端，不包含密钥。 --- ## 9. 卸载与重置 ### 9.1 重置某个玩家的登录 让玩家关闭游戏，删除： ``` config/xbridge/tokens/msal_cache.json ``` 重新启动并点 **Xbox Login**。 ### 9.2 清除某个玩家的皮肤 ``` /syl skin reset ``` 或删除 `config/xbridge/skins/<UUID>.json`。 ### 9.3 完全卸载 1. 服务端和客户端都删除 `mods/syl-1.20.1-1.3.jar`； 2. 可选：删除 `config/xbridge/`（会丢失配置、皮肤缓存）； 3. 重启服务器/客户端。 --- ## 10. 从源码构建（可选） 需要 JDK 17： ```bash cd XBridge-Forge ./gradlew build ``` Windows： ```bat gradlew.bat build ``` 产物： ``` build/libs/syl-1.3.jar ``` 首次构建需要联网下载 ForgeGradle / Minecraft 依赖，时间较长。 --- ## 11. 速查表 ### 命令 | 命令 | 权限 | 说明 | |---|---|---| | `/syl` | OP（等级 2） | 帮助 | | `/syl reload` | OP | 重载配置 | | `/syl list` | OP | 在线已验证玩家 | | `/syl info <player>` | OP | 玩家 XUID/UUID/皮肤 | | `/syl skin <url>` | 已验证玩家 | 设置皮肤 | | `/syl skin reset` | 已验证玩家 | 清除皮肤 | | `/syl skin reload` | 已验证玩家 | 重新拉取皮肤 | ### 路径 | 路径 | 内容 | |---|---| | `config/xbridge/config.json` | 服务端配置 | | `config/xbridge/client.json` | 客户端配置 | | `config/xbridge/tokens/msal_cache.json` | 客户端 Xbox 令牌缓存 | | `config/xbridge/skins/` | 服务端皮肤缓存 | | `logs/latest.log` | 日志 | ### 关键日志 ``` [SYLogin] SYLogin Server enabled! [SYLogin] Login Phase Auth Success for ... [SYLogin] Sent login auth challenge to ... [SYLogin] Manual authentication successful for ... ``` --- ## 12. 常见问题（FAQ） **Q：客户端必须用正版启动器吗？** A：不需要。只要能启动 Forge 1.20.1 即可；但 SYLogin 登录需要真实的微软/Xbox 账号，和 Mojang 正版会话是两套东西。 **Q：一个 Xbox 账号能两个人同时用吗？** A：不行。UUID 由 XUID 决定，两个人用同一账号会得到同一个 UUID，后进的人会把前一个人顶掉/被判定重复登录。 **Q：需要给基岩版玩家装这个模组吗？** A：不需要。基岩版走 Geyser/Floodgate；SYLogin 只负责 Java 端用 Xbox 账号登录。 **Q：服务器可以只装服务端、不要求客户端装吗？** A：可以，但没装模组的客户端不会走 Xbox 验证，也就没有 XUID 身份同步；它们会按原版方式登录。 **Q：为什么名字前面有个点？** A：`usernamePrefix` 默认是 `.`，用于区分 Xbox 身份和普通离线/正版名字。可以改成空字符串 `""` 或其他前缀。 **Q：支持离线模式服务器吗？** A：支持。SYLogin 自己完成 Xbox 验证；`online-mode=false` 时普通客户端仍可离线进服，安全性由白名单/黑名单和 `bypassedUsernames` 控制。 **Q：登录界面是内嵌浏览器吗？** A：1.2 版没有内嵌 Chromium/WebView，而是使用微软官方的**设备代码流程**，登录界面由模组自己在游戏内绘制。这样模组体积小、全平台可用，也不依赖 JavaFX/JCEF 等上百 MB 的原生库。它同样满足“不打开外部浏览器、登录全部在游戏内完成”。 **Q：为什么不用内嵌 Chromium/WebView？** A：真正的内嵌浏览器需要为 Windows/Linux/macOS 分别打包 100MB 以上的原生库，并且与 Forge/Mohist 的类加载、OpenGL 上下文容易冲突。设备代码是微软官方为“无浏览器设备”提供的标准登录方式，更稳定。 **Q：会和其他登录模组/插件冲突吗？** A：会。不要同时让同一个玩家走两套登录验证；AuthMe、其他登录模组请对 SYLogin 玩家豁免或停用。 --- ## 13. 获取帮助时请提供 - 服务端 `logs/latest.log` 中 `[SYLogin]` 相关行； - 客户端 `logs/latest.log` 中 `[SYLogin]` 相关行； - 服务端/客户端 Forge 版本、Java 版本； - 是否使用 Mohist/Geyser/Floodgate/代理； - `/syl info <player>` 的输出（如果已进服）。 --- ## 14. 版权与移植声明 ``` SYLogin Forge 1.20.1 —— 神月岛服务器移植版 Copyright (c) 2026 神月岛服务器 (Shenyuedao Server) 官方网站：[URL]https://shenyuedao.cn[/URL] 移植作者联系方式：3079271443 本移植版基于 areed 的 XBridge 1.1.0（Fabric 版）重新实现。 原版协议设计、配置格式、命令与身份规则版权归 areed 所有，依据 MIT License 授权。 本移植版的 Forge 1.20.1 实现、Mohist 兼容处理及相关文档版权归 神月岛服务器 所有。 ``` - 完整版权声明：模组 JAR 内 `COPYRIGHT.txt`； - 许可证：模组 JAR 内 `LICENSE.txt`（MIT License）； - 再分发或修改时，请保留上述版权信息与来源标识。 --- *本教程对应 SYLogin Forge 1.5（协议 v2）· 神月岛服务器移植版。* [/MD]