xisoul/nonebot-webui repository overview

⁠ ⁠
⁠ ⁠

⁠项目简介

这是一个基于 NoneBot WebUI 深度二改的项目，重点面向 NAS、Docker、WSL 和长期运行场景。

它更偏向“机器人实例运维面板”，而不只是原版 nb-cli 的简单图形封装，核心目标是：

• 同时管理多个 NoneBot 实例
• 直接接入 NAS / 宿主机上已经存在的机器人项目
• 尽量减少手动进容器、手动改配置、手动查日志的频率
• 让常用的运行、安装依赖、插件管理、文件修改、日志排查都能在 WebUI 里完成

⁠文档导航

• 使用文档⁠
• 部署文档⁠
• 更新文档⁠
• 发版草稿⁠

⁠主要功能

• 多实例管理：创建实例、接入已有实例、切换实例、启停与状态同步
• 配置与文件：在线编辑 pyproject.toml、.env、.env.prod 以及实例目录文件
• 扩展管理：安装、卸载、更新插件 / 驱动 / 适配器，并处理依赖安装流程
• 日志与通知：统一查看 WebUI 与实例日志，通知中心常驻留痕
• 备份恢复：支持本地备份、上传恢复，以及 WebDAV / S3 远端备份
• 容器场景支持：代理、镜像源、路径映射、随机 token、外部实例接入
• 主题系统：支持多套界面主题、主色配色切换，以及亮暗模式切换与持久化

⁠这次二改的重点

• 重点适配 NAS / Docker / WSL 的长期运行场景
• 优化已有实例导入，支持相对路径和容器内绝对路径识别
• 修复坏虚拟环境导致的依赖安装失败，自动备份并重建 .venv
• 补齐导入实例后的驱动 / 依赖初始化流程，减少第三步报错
• 修复添加实例失败后仍残留实例记录的问题，失败时自动回滚
• 修复实例列表重复污染问题，避免路径别名与自动扫描把测试实例反复塞回列表
• 将实例运行日志与维护终端拆分，实例操作页与独立终端页职责分离
• 调整概览、通知、日志、终端交互，让运维动作更集中
• 新增关于页，文档入口和项目信息集中展示
• 新增 WebUI 多主题与配色系统，支持 Classic / Frost / Paper / Midnight
• 修复主题抽屉被页面内容遮挡的问题，抽屉层级提升为真正的全局顶层
• 修复手动切换亮暗模式后刷新回退的问题
• 维护终端升级为多会话 PTY 工作台，支持会话标签、主题切换、快速命令和常驻交互
• 实例操作页聚焦运行日志与实例控制，不再混入旧的终端细节面板
• 永久 token 模式新增可复制的登录链接，登录页支持自动识别链接凭证

⁠适合谁用

• NAS 上已经有一批 NoneBot 项目，想统一接进一个面板管理的人
• 用 Docker 跑 WebUI，希望新建实例和外部已有实例分开挂载的人
• 需要经常安装依赖、排查插件问题、看日志、改配置的人
• 不想每次都手动进容器敲命令的人

⁠使用

⁠Docker 安装

如果你主要是部署到 NAS、Docker 或 WSL，直接使用 Docker Hub 镜像就行：

• docker.io/xisoul/nonebot-webui:latest
• docker.io/xisoul/nonebot-webui:master
• docker.io/xisoul/nonebot-webui:${version}

推荐优先使用显式版本号，例如 0.4.8，后面做升级、回滚、版本检测会更方便。

⁠非 Docker 安装

如果你明确是本机直接运行 nb-cli，也可以走插件安装方式：

nb self install nb-cli-plugin-webui-xisoul

⁠生产部署

推荐最少保留这几项挂载：

docker run -d \
  --name nonebot-webui \
  --restart=always \
  --network host \
  -e HOST=0.0.0.0 \
  -e PORT=18080 \
  -e WEBUI_DATA_DIR=/data \
  -e WEBUI_CONFIG_DIR=/data \
  -e WEBUI_CACHE_DIR=/data \
  -v /home/xisoul/nonebot-webui-data/projects:/projects \
  -v /home/xisoul/nonebot-webui-external-projects:/external-projects \
  # 挂载你本地的NoneBot项目目录到容器内，容器会自动扫描并添加所有项目
  -v /path/to/your/nonebot/projects:/opt/nonebot-projects \
  -v /home/xisoul/nonebot-webui-data:/data \
  xisoul/nonebot-webui:latest

⁠自定义项目挂载说明：

你可以把宿主机上任意目录下的所有NoneBot项目，通过挂载到容器的/opt/nonebot-projects目录来实现自动接入：

• 容器启动后会自动扫描该目录下的所有子目录
• 自动识别原版NoneBot项目（不需要做任何适配修改）
• 自动添加到WebUI的实例列表，支持启停、依赖管理、日志查看等全功能操作

也可以直接使用仓库里的 docker-compose.yml。

只需要记住：

• /projects 给 WebUI 新建实例使用
• /external-projects 给宿主机 / NAS 里已经存在的实例使用
• /data 给 WebUI 运行期状态使用，包括 config.json、project.json、缓存和日志等可变数据；生产环境只需要把宿主机数据目录挂载到 /data
• 旧版本如果已经把 /app/config.json 或 /app/project.json 挂出来，新版本启动时会在 /data 还没有对应文件时自动兼容复制一次，避免已有登录凭证和实例列表丢失
• 新版本镜像不再声明默认 Docker VOLUME，避免 NAS / Docker Desktop 自动带出误导性的默认挂载项
• 如果 NAS 面板自动带出其它旧默认卷，建议只保留 /data、/projects、/external-projects 以及你额外挂载的实例目录

仓库自带的 docker-compose.yml 现在也包含了 watchtower 自动更新方案：

• 自动检查 xisoul/nonebot-webui:latest
• 发现远端更新后自动拉取新镜像
• 自动重建 nonebot-webui 容器

如果你不想自动更新，可以删掉 compose 里的 watchtower 服务。

⁠路径映射说明

Docker / NAS 场景下请区分“宿主机路径”和“容器内路径”：

• 宿主机路径：例如群晖 NAS 上的 /vol1/1000/nonebot
• 容器内路径：例如 /projects、/external-projects

不要把容器内路径也写成宿主机路径，例如：

• 错误：/vol1/1000/nonebot -> /vol1/1000/nonebot

推荐映射方式：

• WebUI 自己新建的实例：宿主机目录 -> /projects
• 已有机器人项目：宿主机目录 -> /external-projects

群晖 / NAS 常见示例：

• 宿主机已有目录：/vol1/1000/nonebot
• 容器挂载方式：/vol1/1000/nonebot -> /external-projects

如果你还需要让 WebUI 自己创建新实例，再单独准备一块目录映射到 /projects 即可。

⁠添加已有实例时怎么填路径

添加已有实例时，实例路径支持以下几种写法：

• 3998382152
• external-projects/3998382152
• /external-projects/3998382152

WebUI 会自动把它解析并保存为容器内的真实绝对路径。

如果当前是 Docker / NAS 部署，不要填写宿主机自己的物理路径，例如：

• /vol1/...
• /volume1/...
• /home/...

这些路径对容器里的 WebUI 来说是不可见的，必须填写容器内路径。

另外，添加的目录本身需要是一个 NoneBot 项目根目录，至少应当能看到 pyproject.toml。如果 pyproject.toml 在子目录里，就填写那个子目录，不要填到父目录。

本镜像已内置 WebUI 预装 nonebot_plugin_htmlrender / Playwright Chromium 常见所需的 Linux 运行库。

另外，镜像也会安装常见中文字体包，用于修复 NAS / Docker 场景下 Playwright 截图网页时中文变方块的问题。

如果你之前已经拉取过旧镜像，更新代码后需要重新构建或重新拉取镜像，否则容器里的浏览器字体环境不会自动变化。

如果你的外部项目依赖 Playwright，WebUI 在启动实例前会优先尝试用该项目自己的 Python 环境执行：

python -m playwright install chromium

浏览器二进制仍然安装在实例运行时可见的目录里，不会直接打进项目仓库。 如果你的网络环境使用 SOCKS 代理，WebUI 会继续保留实例代理环境用于下载 Chromium，但系统库仍然依赖当前 WebUI 容器镜像提供。

⁠登录说明

首次启动容器后，请先去查看容器日志里的登录凭证（token），再用它登录 WebUI。

例如：

docker logs nonebot-webui

如果你在群晖 Docker 管理界面中部署，也同样需要到“容器日志”里查看首次生成的 token。

登录流程是：

1. 用日志里的登录凭证登录
2. WebUI 会换取当前浏览器会话用的 JWT
3. 后续页面请求和 WebSocket 连接都会使用 JWT

因此，登录凭证本身不是直接拿来当 Authorization: Bearer ... 用的。

如果后面你在”安全设置”里改成随机 token 模式，新 token 也会继续写到容器日志里。

永久 token 模式下，只要 /data/config.json 中的认证字段仍然完整，后续重启不会自动换 token。 如果配置文件损坏或字段缺失，程序现在会直接报错提示你修复配置，而不是静默重新生成一个新 token。

⁠重置登录密码

如果忘记了登录密码，可以在 Docker 容器内执行以下命令重置：

docker exec -it nonebot-webui python -m nb_cli_plugin_webui.scripts reset_token

执行后会直接在终端输出新密码，请注意保存：

============================================================
WebUI login token has been reset successfully.
============================================================

Your new token is:

    abc123

ATTENTION: Token is only shown once. Please save it securely.
============================================================

IMPORTANT: You must restart the container for changes to take effect:
    docker restart nonebot-webui
============================================================

重置后必须重启容器才能生效：

docker restart nonebot-webui

⁠常用环境变量

• HOST: 指定监听地址，默认为 0.0.0.0
• PORT: 指定监听端口，默认为 18080

⁠代理与镜像源

容器运行时代理、Debian 镜像源、pip 源都可以在 WebUI 里直接配置，不需要部署阶段先写一大堆复杂参数。

如果你的环境确实需要，也支持通过环境变量传入：

• WEBUI_HTTP_PROXY
• WEBUI_HTTPS_PROXY
• WEBUI_ALL_PROXY
• WEBUI_NO_PROXY
• WEBUI_DEBIAN_MIRROR
• WEBUI_PIP_INDEX_URL
• WEBUI_PIP_EXTRA_INDEX_URL
• WEBUI_PIP_TRUSTED_HOST

⁠常见提醒

• WebUI 新建实例默认放在 /projects
• 外部已有实例建议统一挂到 /external-projects
• 添加已有实例时，路径必须填写容器内路径，不要填写 NAS 宿主机路径
• 如果实例根目录里没有 pyproject.toml，说明你填错目录层级了
• 首次登录凭证请去容器日志里看
• 想回头找 token，直接看容器日志，不是在页面里反查
• 如果某些插件依赖 Playwright，优先让 WebUI 在实例启动前自动预装；若项目还有额外浏览器或系统库要求，再按该项目自身文档补充

⁠发布流程

这个仓库当前的 Docker 镜像发布依赖 GitHub Actions 自动完成。

需要注意：

• 只在本地 docker build 不会自动更新 Docker Hub
• 自动推送镜像依赖 GitHub 上的提交和 tag
• 版本号必须和 tag 对应，否则 release workflow 会失败

⁠自动发布触发规则

• 推送到 master 会触发 Docker 构建流程
• 推送 v* 格式的 tag 也会触发 Docker 构建流程

当前 Docker workflow 会自动生成这些常用标签：

• latest
• master
• ${version}

例如版本 0.4.8 会自动生成：

• xisoul/nonebot-webui:latest
• xisoul/nonebot-webui:master
• xisoul/nonebot-webui:0.4.8

⁠推荐发版步骤

1. 修改代码并在本地测试通过
2. 更新 pyproject.toml 中的版本号
3. 同步更新 Dockerfile 中的 APP_VERSION
4. 提交代码
5. 打版本 tag，例如 v0.4.8
6. 推送 master 和对应 tag

示例：

git add .
git commit -m "feat: your change"
git push origin master

git tag v0.4.8
git push origin v0.4.8

⁠重要说明

• tag 必须和 pyproject.toml 中的版本一致
• 如果 tag 已经打错位置，需要先修正 tag 指向再重新 push
• 当前 release workflow 已移除 PyPI 发布，只保留 GitHub Release 产物上传，避免因为 PyPI Trusted Publisher 配置导致整条流程报红
• 如果 Docker Hub 没更新，优先去 GitHub Actions 看 docker.yml 是否成功