Skip to content

webui-guide.md

Latest commit

 

History

History
181 lines (112 loc) · 6.17 KB

webui-guide.md

File metadata and controls

181 lines (112 loc) · 6.17 KB

WebUI 使用指南

WebUI 是 Undefined 的主要管理入口，提供配置编辑、日志查看、认知记忆管理、表情包库、AI 对话和系统监控等一站式功能。即使 config.toml 尚未创建，也可以通过 WebUI 补全配置并启动 Bot。

快速开始

启动

uv run Undefined-webui

默认监听 http://127.0.0.1:8787。相关配置位于 config.toml 的 [webui] 节：

[webui]
url = "127.0.0.1"      # 监听地址
port = 8787             # 端口
password = "changeme"   # 密码（必须在首次登录时修改）

如需远程访问，将 url 改为 0.0.0.0 或实际 IP。

首次登录

  1. 浏览器打开 http://127.0.0.1:8787
  2. 输入初始密码 changeme
  3. 系统强制要求修改默认密码后才能进入管理界面

修改后的密码会写入 config.toml。桌面端 / Android 客户端也使用同一密码连接。

功能概览

WebUI 共有 8 个主要页签（Tab），下面逐一介绍。

概览（Overview）

仪表盘页面，展示系统运行状态：

指标 说明
Bot 状态 运行中 / 已停止
系统运行时间 自启动以来的持续时间
CPU 使用率 实时百分比
内存占用 已用 / 总量 / 百分比
运行环境 CPU 型号、操作系统、Python 版本
资源趋势图 CPU / 内存随时间的变化曲线

页面会自动刷新，也可手动触发。

配置管理（Config）

提供两种编辑方式：

  • 表单模式：按分组展示所有配置项，带字段说明和类型校验，适合日常修改。
  • TOML 原始编辑器：直接编辑 config.toml 文本，带语法高亮，适合批量变更。

其他能力：

  • 验证：保存前自动进行 TOML 语法检查和严格配置校验，错误项会标红提示。
  • 配置历史：每次保存自动生成带时间戳的备份（最多 50 版本），可随时回滚到任意历史版本。
  • 模板同步：一键将 config.toml.example 中新增的配置项合并到当前配置，不覆盖已有值。

配置支持热更新——大多数配置项修改后即时生效，无需重启 Bot。需要重启的项（如 onebot_ws_url、webui_port）会在保存时提示。

日志查看（Logs）

  • 支持 Bot 日志 和 WebUI 日志 切换。
  • 实时流式推送（SSE）：日志实时滚动到最新。
  • 可暂停 / 恢复流式推送，调整显示行数（1–2000）。
  • 左侧文件列表展示所有日志文件（含归档），可选择查看历史日志。
  • 支持下载日志文件。

探针与诊断（Probes）

三类探针帮助排查问题：

  • 内部探针：版本号、Python 版本、平台、运行时间、OneBot 连接状态及 WebSocket 地址。
  • 外部探针：Runtime API 的可用端点和能力列表。
  • 引导探针：检查 config.toml 是否存在、TOML 语法是否合法、配置值是否有效，并给出修复建议。

认知记忆（Memory）

分为三个子面板，对应 认知记忆系统 的不同层次：

认知事件搜索

输入关键词进行语义搜索，查看 AI 提取并存储的用户 / 群聊事实记录。支持调整返回条数和排序方式。

认知侧写查看

  • 按关键词搜索侧写。
  • 按 QQ 号或群号精确查看对应的完整侧写内容。

长期记忆管理

AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：

  • 新建记忆条目
  • 编辑现有内容
  • 删除条目
  • 关键词搜索

表情包库（Memes）

管理 全局表情包库 的 Web 界面：

  • 浏览与搜索：分页列表展示，支持关键词搜索和语义搜索（以及混合模式）。输入时自动防抖搜索，Enter 立即触发。
  • 筛选与排序：按启用 / 禁用、静态 / 动态、置顶等条件筛选，按创建或更新时间排序。
  • 详情与操作：查看元数据（UID、描述、标签）和预览图；支持编辑描述 / 标签、启用 / 禁用、置顶 / 取消、删除。
  • 重分析 / 重索引：对单张表情包重新触发 AI 描述生成或搜索索引更新。
  • 统计概览：总数、启用 / 禁用数、静态 / 动态数等。

AI 对话（Chat）

WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：

  • 支持文本和图片消息。
  • AI 回复支持 Markdown 渲染。
  • 消息历史分页浏览。
  • 发出的消息会经过与 QQ 侧相同的处理流程（安全检查、工具调用等）。

关于（About）

显示当前版本号和 MIT 许可证文本。

Bot 控制

WebUI 首页（Landing Page）提供 Bot 的启停控制：

  • 启动 Bot：点击启动按钮，Bot 进程在后台运行。
  • 停止 Bot：安全停止当前 Bot 进程。
  • 状态指示：实时显示 Bot 运行状态。

首页还会检测是否有可用更新（基于 Git），并提供更新 + 重启功能。

键盘快捷键

快捷键 功能
Cmd/Ctrl + K 打开命令面板，可快速跳转到任意页签或执行操作

远程访问

WebUI 和桌面端 / Android 客户端共享同一 Management API：

  1. 将 [webui].url 设为 0.0.0.0（或你的 LAN/公网 IP）。
  2. 确保防火墙放行 [webui].port（默认 8787）。
  3. 桌面端 / Android 客户端输入 http://<IP>:8787 和密码即可连接。

如果启用了 Runtime API（[api].enabled = true），WebUI 会自动代理 Runtime API 的功能（探针、记忆查询、AI Chat 等），无需单独暴露 Runtime API 端口。

常见问题

Q: 忘记密码怎么办？

直接编辑 config.toml 中的 [webui].password 字段，重启 WebUI 即可。

Q: 配置保存后 Bot 没反应？

大多数配置项支持热更新。但少数关键配置（如 WebSocket 地址、WebUI 端口、API 端口）需要重启才能生效，保存时会有提示。

Q: 日志不滚动了？

检查是否意外暂停了日志流。点击日志页面的播放按钮恢复实时推送。

Q: 探针显示 Runtime API 不可达？

确认 [api].enabled = true 且 Bot 正在运行。Runtime API 由 Bot 主进程提供，Bot 未启动时自然不可达。