新版 React 控制台

← 入门与部署 · 所有分区

新版控制台位于源码的 webui-preview/，采用 React、TypeScript 与 CDK 基础组件。目前玩家管理、网站详细设置连接真实 VexBot 后台；运行总览、服务器、指令中心及其余预览设置使用示例数据。它独立于正式 Bot 部署包，需要另外启动，尚未替代 5800 的内置管理面板。

三个地址分别做什么

以下为本机默认地址，已有 Bot 配置使用其实际端口：

地址	用途	启动方式
http://127.0.0.1:5800/	Bot 后台和内置完整管理面板，提供管理员与网站 API	运行 VexBot 主程序
http://127.0.0.1:5801/	本文介绍的新版 React 控制台	在 webui-preview/ 单独运行前端
http://127.0.0.1:8089/	面向玩家的独立社区官网本机预览	按官网部署另外启动

5801 用于管理员操作，8089 用于玩家查看社区和使用账号。启动 Bot 不会自动启动这两个独立前端；保存网站绑定也不会部署官网。127.0.0.1 始终指访问设备自身，供其他设备访问时需要配置实际可达的地址。

启动新版控制台

1. 准备源码和运行环境

需要包含 webui-preview/ 的项目源码，以及 Node.js 和 npm。本前端已在 Node.js 24 验证；首次执行 npm ci 需要联网。只有正式 Bot 部署 ZIP 时，需另外获取源码中的此前端目录及其上级目录的许可证文件，不能直接在部署目录执行前端命令。

先按Windows 安装或Linux 安装准备并运行 Bot。Windows 源码目录可执行：

.\VexBot.bat start quiet

该命令准备依赖、配置并后台启动 Bot，不打开脚本菜单或浏览器。已有本目录后台实例时会核验并复用。确认浏览器可访问实际 Bot 面板地址；Bot 已运行时不必再启动一个实例。

2. 单独启动前端

打开新终端，进入项目根目录，然后执行：

cd webui-preview
npm ci
npm run dev

保持前端终端运行，在浏览器打开 http://127.0.0.1:5801/。停止前端使用该终端的 Ctrl+C，不会停止 Bot；通过脚本启动的 Bot 可在项目根目录执行 .\VexBot.bat stop quiet 停止。

若要查看构建后的版本，在 webui-preview/ 中执行：

npm run build
npm run preview

build 包含 TypeScript 检查。开发服务和构建预览都固定使用 5801，请先停止其中一个再启动另一个。构建预览读取 dist/，更新源码后需重新构建；它仍需单独运行，复制静态文件不能自动获得 Vite 的后台代理。

3. 后台使用其他地址时

在 webui-preview/ 复制环境变量示例：

Copy-Item .env.example .env.local

编辑 .env.local：

VEXBOT_BACKEND_URL=http://127.0.0.1:5800

填写实际 Bot 的 HTTP(S) 来源，只包含协议、主机和端口，不追加 /api、/api/v1、用户名、密码、查询参数或片段。修改后重启 npm run dev 或 npm run preview。两种启动方式都会把前端同源 /api 请求代理到该后台，不需要 CDK 的 Go 服务、Redis 或 OAuth。

登录与权限

整个新版控制台使用现有 VexBot 管理员用户名和密码。没有默认账号或密码。首次没有服主账号时，先在实际 5800 内置面板点击「创建服主账号」，用 config.toml 的 app.admin_token 完成首次授权并设置自己的账号，再回到新版登录页点击「我已完成设置」。管理令牌用于首次授权及兼容 API，不是日常登录密码。

切页共享同一个会话，不需在玩家页再次登录。令牌只保存在当前页面内存，刷新页面需要重新登录。右上角「退出登录」可结束当前会话，登录过期或被后台撤销时，整个控制台返回登录页。后台改用了其他地址时，首次设置请直接打开该实际地址；登录页的「打开后台首次设置」链接指向默认本机 5800。

页面或功能	当前行为	权限
运行总览	展示统计、活动和趋势的示例数据	登录后查看
服务器	示例服务器列表及编辑交互，不更改真实服务器配置	登录后体验
指令中心	示例指令与回复图片预览，不更改真实群指令	登录后体验
玩家管理	读取和修改后台真实玩家档案、绑定及游戏操作	服主或具备「玩家与绑定管理」权限（players.manage）
控制台设置	顶部「网站详细设置」真实保存；下方「界面预览」等选项只保存浏览器预览偏好	网站设置仅服主；其余预览选项登录后体验

创建或连接真实服务器、配置真实 QQ 接入、群指令、数据库及其他完整功能，继续使用5800 内置面板。新版示例服务器卡片的状态不能证明真实游戏端是否连接。

管理真实玩家

1. 打开「玩家管理」，使用玩家名或 QQ 身份、UUID、状态、服务器筛选，或切换「只看在线」。每页可选 10、25、50、100 位。
2. 点击玩家行「管理」，查看 UUID、IP、绑定身份和到访服务器；修改后点击「保存归属地与备注」。档案并发变动时保留草稿，按提示载入最新记录核对后再保存。
3. 手动建档使用「添加玩家」，填写真实玩家名和 UUID。这里只创建后台档案，不创建游戏账号或 Minecraft 存档。
4. 详情中的绑定区域选择真实服务器，填写「QQ / 官机用户身份」，点击「添加绑定」。QQ 号与官机场景身份不能仅凭显示名互换，需核实身份再绑定。
5. 在「到访服务器与游戏管理」中选择目标服执行踢出、永久封禁、解封或白名单操作。服务器必须连接，并由支持玩家管理的游戏端上报目标 UUID 与能力；手动建档或已有绑定不能代替游戏上报。

解绑和删除前会要求确认。删除的是后台档案与绑定，不删除游戏存档，也不封禁玩家。游戏操作提交后先等待插件确认，收到回执才显示执行结果；「结果未确认」时先刷新记录并检查游戏端，不要以新的请求重复提交。页面离开后停止轮询，网络中断不会自动重复执行。

档案默认保存在 SQLite，启用 MySQL 后使用所选数据库，详见数据存储。更多玩家行为及限制见玩家管理；其中内置面板的按钮与导航名称可能与新版不同。

网站详细设置

服主打开「控制台设置」，在顶部「网站详细设置」选择「网站绑定方式」。未授权的团队管理员只看到权限说明，不读取网站配置。

选择	显示和保存的内容
不接入官网（none）	默认模式，保留已保存地址、内容与外观，停止授权该绑定网站来源；公开 API 由下面开关独立控制
VexBot 官网（provided）	网站地址、Bot API 地址、公开权限，以及官网内容和外观
自定义网站（custom）	网站地址、Bot API 地址和公开权限；页面设计与文案由自己的项目管理

绑定网站与公开 API

1. 选择「VexBot 官网」或「自定义网站」，填写「网站地址」，例如 https://www.example.com/community/。保存后后台授权其准确来源，示例为 https://www.example.com。
2. 「Bot API 地址」推荐明确填写官网访客可访问的 https://bot.example.com/api/v1；本机测试可填 http://127.0.0.1:5800/api/v1。官网与 API 已由同一来源代理时可填 /api/v1，留空也表示官网使用同源 API。不要把 5801 当作对外 Bot API 地址。
3. 按需调整「开放玩家信息 API」「公开服务器状态」「开放网站密码登录 API」。公开玩家信息只包括玩家名、UUID 与在线状态，不公开 IP、邮箱、QQ 或管理备注。邮箱和 QQ 只供登录后的账号本人读取。
4. 点击「保存网站设置」，成功后检查「已保存的接入状态」与「授权来源」。设置会写入后台，与下方「保存预览设置」分开。

新版不会在留空时自动填入管理面板地址；需要下载 config.json 时，先明确填写并保存 Bot API 地址。地址只支持 HTTP(S)，不接受账号密码、查询参数或片段；API 地址路径为 /api/v1。注册与 SMTP 仍在内置面板配置，开放密码登录不等于开放新注册。

选择「不接入官网」不会关闭公共 API、停止外部网站服务或撤销已有用户令牌；已保存的地址、内容和外观会保留。三项公开 API 权限仍由各自开关控制。

官网内容与外观

「VexBot 官网」模式还可填写网站标题、副标题、社区介绍、社区规则、加入服务器地址、群聊链接，调整主色、辅助色、官网主题及网格背景。这些设置供配套的独立官网读取，不改变新版控制台背景；改成「自定义网站」不会替你修改自有网站页面。

网站绑定只保存接入设置。实际部署与玩家账号流程按社区官网部署完成。

检查和下载接入文件

未保存草稿时先保存，再使用下列按钮：

按钮	用途
检查 API	当前浏览器读取已保存的公开 API，不发送管理员凭据；留空或相对地址时通过当前控制台同源 /api/v1 检查
下载接入配置	下载已保存 API 地址的 config.json，需要该地址非空；下载后手动替换官网根目录的配置
接入指南	下载官网部署与 API 文档
下载 SDK	下载自有网站接入示例 JavaScript
下载官网项目	仅「VexBot 官网」模式提供，下载后台已有的独立项目包

「检查 API」只证明管理浏览器能访问公开接口，不代表官网已部署，也不代表玩家设备可访问。跨域、HTTPS 混合内容或网络限制可能导致失败。源码后台未准备官网项目 ZIP 时，「下载官网项目」会显示错误；按官网项目构建说明准备附件即可，无需填写额外 API 密钥。

草稿、冲突与保存结果

切换控制台页面会保留尚未保存的网站草稿，刷新或退出则清空当前页面状态。「撤销更改」恢复当前已读取版本；「重新载入」重新读取后台。丢弃已有草稿前会显示应用内确认。

如果后台版本已被其他操作修改，草稿会保留并停止提交。点击「载入最新版本，保留草稿」，仅将自己改过的字段合并到最新数据，检查同一字段的改动后再保存。请求超时或保存时切页也可能提示「保存结果尚未确认」；此时后台可能已经写入，先载入核对，避免重复提交。

动画、背景与主题

右上角「动画」切换页面、卡片与组件动效，关闭后「重播动画」停用。未手动选择时跟随系统减少动态效果设置，手动选择后保存在当前浏览器。

「背景」提供纯净、雾蓝、薄荷、暖砂和点阵，支持明暗主题；由本地 CSS 绘制，不加载外部图片。主题、背景、动画与下方「界面预览」中的偏好仅影响当前浏览器，不修改 Bot 或官网全站外观。登录前也可调整主题、背景与动画。

网站设置深色效果 · 浅色效果 · 更多预览与许可说明

常见问题

现象	检查与处理
5800 能打开，5801 打不开	新版需要另外运行；确认源码有 webui-preview/，并在该目录完成依赖安装、保持 npm run dev 或 npm run preview 运行
启动提示 5801 被占用	开发与构建预览不能并开；先检查已有前端终端，停止自己的旧实例再启动，不要关闭其他程序
登录页连接失败或请求返回 502	先打开实际 Bot 面板确认后台运行；核对 .env.local 的 VEXBOT_BACKEND_URL 只有来源，修改后重启前端
不知道账号密码	没有默认值；首次去实际 Bot 内置面板创建服主账号，已有账号使用自己设置的密码，管理令牌不作为密码
只有玩家管理或网站设置提示无权限	页面共用同一登录；玩家管理需对应权限，网站设置必须服主，获得授权后重新登录
选择了官网类型但字段不见	确认服主登录并查看顶部「网站详细设置」；「不接入官网」隐藏地址，「自定义网站」隐藏配套官网内容与外观
更新源码后界面还是旧的	构建预览读取旧 dist/，先执行 npm run build 再刷新；开发模式确认启动目录正确
保存预览设置后后台没有变化	下方按钮只存浏览器偏好；网站使用上方「保存网站设置」，其他真实配置仍去 5800 内置面板
下载接入配置不可点击	先处理未保存草稿，再填写并保存非空 Bot API 地址；配置文件依据已保存值生成
提示网站版本冲突或保存结果未知	使用「载入最新版本，保留草稿」核对后台实际值后保存，不盲目重试；需要放弃草稿时再选择「重新载入」
游戏操作一直等待或结果未确认	刷新最近操作并检查目标游戏端日志、权限和实际状态，提交成功不等于插件执行成功

相关文档：内置面板 · 玩家管理 · 社区官网 · 管理员权限