WebUI 管理面板

Gensokyo-NewQQ 提供内置 WebUI，用于查看实例状态和管理部分运行配置。WebUI 是管理入口，不代表 QQ 官方连接或 OneBot 下游连接已经正常建立。

启用与登录配置

WebUI 相关配置位于 config.yml 的 settings 下：

settings:
  port: "15630"
  disable_webui: false
  server_user_name: "admin"
  server_user_password: "change_me_now"

字段	说明
port	Gensokyo HTTP 服务与 WebUI 使用的端口
disable_webui	是否禁用 WebUI
server_user_name	WebUI 登录用户名
server_user_password	WebUI 登录密码

修改 WebUI 开关、端口或登录信息后，建议完整重启 Gensokyo。

访问地址

访问路径可能随运行版本变化。使用默认路由的版本通常可通过以下形式访问：

http://<主机地址>:<端口>/webui/

应优先查看启动日志中输出的监听地址和路由。若本机可访问但其他设备无法访问，还需检查监听网卡、防火墙、反向代理和容器端口映射。

账户安全

部分配置模板可能使用 admin / admin 作为初始凭据。这只适合首次在本机启动，不能直接用于局域网或公网部署。

部署前至少完成以下处理：

1. 修改默认用户名和密码，密码不要与 QQ、GitHub 或服务器账户复用。
2. 不直接把 WebUI 端口暴露到公网。
3. 通过反向代理启用 HTTPS，并限制来源 IP 或增加额外身份验证。
4. 不在截图、Issue、群聊或网页中展示完整 config.yml。
5. 定期检查日志和配置变更，发现异常登录后立即更换凭据。

页面能力

不同版本的 WebUI 页面和功能可能不同，常见能力包括：

• 查看实例与连接状态。
• 查看运行日志。
• 编辑或检查配置。
• 管理机器人实例。
• 执行版本提供的调试或消息测试功能。

实际可用功能应以当前版本页面和源码为准。涉及配置写入、进程启停或消息发送时，先确认操作目标，避免在生产实例上误改配置。

故障排查

页面无法打开

• 确认 disable_webui 没有设为 true。
• 确认端口没有被其他进程占用。
• 查看启动日志中的监听地址和错误信息。
• 检查防火墙、容器端口映射和反向代理配置。

可以登录但机器人不可用

WebUI 登录成功只说明 HTTP 管理入口可访问。还需要分别确认：

• QQ 官方 WebSocket 连接是否建立。
• Intent 与开放平台权限是否匹配。
• OneBot 正向或反向 WebSocket 是否连接。
• 下游机器人框架是否正常加载适配器和插件。

修改配置后没有生效

部分关键字段需要重启，包括机器人凭证、Intent、WebSocket 地址、服务端口和 WebUI 登录信息。保存配置后，检查 YAML 格式并重启实例。