这份文档面向日常使用 nonebot-webui 的用户，重点说明首次登录、实例接入、常见页面用途，以及 Docker / NAS 场景下最容易填错的路径规则。
- 想统一管理多个 NoneBot 实例
- 已经有宿主机项目，希望接入 WebUI 统一运维
- 需要在页面里完成启停、依赖安装、日志查看、文件编辑和安全设置
首次启动容器后，需要先到容器日志中查看登录凭证（token）：
docker logs nonebot-webui登录流程如下：
- 使用日志中的登录凭证登录
- WebUI 为当前浏览器换取 JWT 会话
- 后续页面请求与 WebSocket 连接都使用 JWT
需要注意：
- 登录凭证不是直接当
Authorization: Bearer ...使用的 - 永久 token 模式下，只要
/data/config.json里的认证配置仍然完整，重启后不会自动换 token - 如果你在“安全设置”里改成随机 token 模式，新 token 会继续写到容器日志中
查看当前实例、运行状态和整体运维入口。
用于切换当前操作的 NoneBot 实例，也可以接入已有实例或创建新实例。
当前页面主要用于查看实例运行日志，以及执行与当前实例相关的常见操作。
独立的维护终端页面，适合执行排障、安装依赖、临时检查环境等维护动作。
当前终端页支持：
- 创建多个维护会话标签
- 在不同会话之间切换
- 发送常驻交互命令，而不是只执行一次性命令
- 切换终端主题
- 使用快捷命令和最近命令
可在线浏览和编辑实例目录文件，常见会用到：
pyproject.toml.env.env.prod- 插件配置文件
- 扩展商店：浏览、安装插件 / 驱动 / 适配器
- 拓展管理：管理当前环境中已安装的扩展
用于调整登录方式、会话时长及认证配置。
永久 token 更新成功后，页面会返回一个新的登录链接。
这个链接可以：
- 直接跳到登录页
- 自动带入新的永久凭证
- 适合在端口变更或凭证重置后快速重新登录
右上角的设置抽屉用于调整前端界面行为，当前支持：
- 切换界面主题：
Classic、Frost、Paper、Midnight - 切换主题配色：赤焰、海蓝、翠绿、紫曜、琥珀
- 切换亮色 / 暗色模式
- 主题跟随系统
如果你手动切换到亮色或暗色模式，刷新页面后会继续保留当前选择，不会自动退回旧模式。
添加已有实例时，路径支持这些写法：
3998382152external-projects/3998382152/external-projects/3998382152
程序会自动解析并保存为容器内可用的真实绝对路径。
如果当前是 Docker / NAS 部署，不要填写宿主机自己的物理路径，例如：
/vol1/.../volume1/.../home/...
这些路径对容器里的 WebUI 不可见，必须填写容器内路径。
另外，填写的目录本身需要是 NoneBot 项目根目录，至少要能看到 pyproject.toml。如果 pyproject.toml 在子目录里，就填写那个子目录，不要填父目录。
- WebUI 新建实例默认放在
/projects - 宿主机已有实例建议统一挂到
/external-projects - 先确认项目目录里存在
pyproject.toml再接入 - 遇到插件依赖问题，优先看实例日志和维护终端输出
- 需要重新找登录凭证时，优先回容器日志查看
大多数情况下是把宿主机路径填到了容器内路径输入框里。请改成容器内挂载路径，例如 /external-projects/你的项目目录。
这通常不是永久 token 丢失，而是当前浏览器的 JWT 会话过期。请检查“安全设置”中的会话时长配置。
如果实例依赖 Playwright 或 nonebot_plugin_htmlrender，WebUI 会尝试在实例启动前补齐浏览器依赖，这是正常行为。
Overview 是 Docker Hub 仓库说明页，不是镜像更新开关。
如果它是空白，通常说明：
- Docker Hub 仓库页面还没有手动填写介绍
- 当前镜像虽然是通过 GitHub Actions 自动推送的，但不会自动把 GitHub README 同步到 Docker Hub Overview
这不影响镜像正常发布，也不影响 Docker Desktop 检查新版本。