Forge 1.20.1 游戏端

← 入门与部署 · 所有分区

当前版本：VexBot 0.6.30 · Forge 游戏端模组 0.1.2。 适用 Minecraft Java 版 1.20.1、Forge 47.x、Java 17；Forge 接入从 Bot 0.6.2 起提供。

这是服务端模组，文件放在 mods/。Paper / Spigot 使用原有插件，两种游戏端可以同时连接同一台 Bot。不要将 Bukkit 插件放入 Forge 的 mods/。

1. 准备游戏服务器

从 Forge 官方下载页 获取 1.20.1 安装器，创建 Forge 服务端。本模组使用推荐版本 47.4.10 构建。Forge 1.20.1 使用 Java 17，安装及开发环境要求见 Forge 官方文档。

先备份世界，停止游戏服务器，然后将 VexBot-Forge-1.20.1-0.1.2.jar 放入服务器根目录的 mods/。

这是 v0.6.28 Release、当前源码构建和面板下载的名称；部署 ZIP 内的兼容文件名为 StarBridge-Forge-1.20.1-0.1.2.jar，安装方式相同。历史 Release 的 StarBridge-Forge-1.20.1-0.1.0.jar 保留原名，安装旧版时使用该版附件。名称关系见 项目名称与兼容说明。

本模组没有客户端内容或自定义注册表，玩家不需要额外安装 VexBot；整合包里的其他模组仍按各自要求安装。仅支持专用服务端，不在单人世界或局域网共享世界中启动桥接。

2. 配置连接

Bot 面板打开 接入空间 → Minecraft 服务器，添加服务器并保存。准备该服务器的 ID、桥接令牌以及游戏服可访问的 Bot 地址。

第一次启动游戏服务器会生成 config/starbridge-common.toml。默认令牌没有配置时，VexBot 会停止游戏服务器，避免登录保护在配置错误时失效。修改后再启动：

endpoint = "http://127.0.0.1:5800"
server-id = "survival"
token = "替换为面板中该服务器的桥接令牌"
allowed-commands = ["list"]

也可直接在面板该服务器卡片选择 Forge 1.20.1，点击 下载模组连接配置，保存为 config/starbridge-common.toml。其他 Forge / NeoForge 版本见 多版本游戏端。

字段	填写方式
endpoint	游戏服能访问的 Bot 地址；两端不在同一机器时不能用 127.0.0.1，远程部署使用 HTTPS
server-id	与面板保存的服务器 ID 完全一致
token	该服务器桥接令牌，至少 24 字符；不能用面板管理员令牌
allowed-commands	初始完整命令列表；桥接连通后由面板命令白名单覆盖

连接参数修改后重启游戏服务器。聊天、登录方式、超时、群绑定及定时任务等业务设置仍在 Bot 面板调整。

3. 可用功能

功能	Forge 版行为
QQ 与游戏聊天	双向文本转发，进服与离服事件
在线状态	在线玩家、最大人数、Forge 版本、Java 版本与白名单状态
玩家管理	UUID、IP、到访记录、世界、模式、生命值和延迟；归属地仍手动填写
管理操作	踢出、封禁、解封、白名单增删；逐条回传执行结果
白名单申请	离线服按离线身份处理；正版服后台查询并校验官方 UUID
群与游戏绑定	登录后执行 /qbind 获取绑定码
游戏认证	网页或群注册密码登录，以及已绑定 QQ 的私聊确认
定时任务与跨服处罚	使用同一桥接任务协议；自动解封会核对原处罚标记，保留其他处罚

玩家历史档案保存在世界目录 starbridge-players.json，本地最多保留一万条，优先上报在线玩家和最近档案，每次最多 500 条。Bot 自身仍持久化历史玩家信息。复制世界时一并保存此文件；其中包含 IP，请勿公开。

4. 开启游戏登录

在 Bot 面板 游戏登录 中勾选该 Forge 服务器，选择 自动 或 VexBot 内置 引擎，开启需要的登录方式并保存。

命令	用途
/login <密码>、/l <密码>	使用游戏外注册时设置的密码；支持含空格的密码
/qqlogin、/ql	向绑定 QQ 发送私聊登录确认
/logout	退出本次认证并重新验证
/qbind	完成登录后获取群绑定验证码

AuthMe 是 Bukkit 插件，纯 Forge 不能使用 AuthMe 兼容引擎。显式选择 AuthMe 时，本模组会拒绝放行，并提示管理员更改引擎。混合核心不在此版验证范围内。

未登录时拦截移动、背包操作、交互、物品操作、聊天、其他命令和自定义模组数据包；仅保留连接维护与 VexBot 认证命令。玩家未认证时不能拾取物品，也不会受到伤害。登录超时断开连接。确认指令绑定本次连接，重连后旧确认失效。

桥接请求、密码验证和正版身份查询均在有容量限制的后台线程执行，不在游戏主线程等待 HTTP。模组不记录密码，登录命令在进入普通命令事件前由 VexBot 处理。

5. 升级与排查

1. 停服，备份世界与 config/starbridge-common.toml。
2. 替换 mods/ 中的 VexBot Forge JAR，只保留一份，然后重启。
3. 在面板确认桥接在线，再检查聊天、玩家信息、白名单和 /l、/ql。

现象	检查位置
启动后服务器停止	config/starbridge-common.toml 的地址、服务器 ID 和令牌是否有效
面板显示离线	防火墙、Bot 地址、桥接令牌，以及两个进程是否启动
无法登录	是否勾选该服务器、是否使用内置/自动引擎、注册账号是否设置密码
QQ 确认发不出	OneBot 是否连接、玩家是否已绑定 QQ、QQ 是否允许机器人私聊
白名单申请失败	正版名与 UUID 是否匹配、查询是否超时、玩家是否已被封禁
登录前其他模组界面不可用	登录保护会拦截其操作及自定义数据包，完成认证后再打开

6. 源码构建

维护者使用 JDK 17，构建脚本会运行测试和重映射，并复制最终 JAR 到 bridge/target/：

Windows：

.\bridge-forge\build.ps1 -JavaHome 'C:\Program Files\Java\jdk-17'

Linux：

cd bridge-forge
sh gradlew copyBridge --console=plain

不要发布开发环境的映射 JAR。使用 copyBridge 产出的 VexBot-Forge-1.20.1-0.1.2.jar。GitHub 版本发布流程会自动构建并附带 Forge 模组。

验证范围

已在 Forge 47.4.10 / Minecraft 1.20.1 / Java 17 专用测试服上，用未安装 VexBot 的真实协议客户端验证：心跳与玩家档案、未登录移动/聊天/命令限制、含空格密码的 /l 登录、/ql 私聊确认、退出与后端会话重建、绑定码、双向消息、踢出、封禁/解封来源保护、白名单增删与申请审核回执、关闭认证后的正常命令。另有网络响应大小和禁止令牌重定向测试。

此验证没有覆盖全部整合包或混合核心。其他模组的自定义交互在登录前会被限制；部署到自己的整合包后，再检查其登录后的交互流程。