feat: refine instance UI and docker versioning

Author: XiSoul

.github/workflows/docker.yml

@@ -25,6 +25,7 @@ jobs:
     outputs:
       version: ${{ steps.meta.outputs.version }}
       image_tag: ${{ steps.image_tag.outputs.TAG }}
+      app_version: ${{ steps.app_version.outputs.VERSION }}
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -49,13 +50,19 @@ jobs:
           username: ${{ env.DOCKERHUB_USERNAME }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
+      - name: Read package version
+        id: app_version
+        run: |
+          VERSION="$(awk -F'\"' '/^version = \"/ {print $2; exit}' pyproject.toml)"
+          echo "VERSION=$VERSION" >> "$GITHUB_OUTPUT"
+
       - name: Generate image tag
         id: image_tag
         run: |
           if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
             TAG="${GITHUB_REF#refs/tags/v}"
           else
-            TAG="${GITHUB_SHA::7}"
+            TAG="${GITHUB_REF_NAME}"
           fi
           echo "TAG=$TAG" >> "$GITHUB_OUTPUT"
 
@@ -70,7 +77,6 @@ jobs:
             type=ref,event=branch
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
-            type=sha,prefix=
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Build and Push
@@ -80,7 +86,8 @@ jobs:
           platforms: linux/amd64
           push: true
           build-args: |
-            SOURCE_COMMIT=${{ steps.image_tag.outputs.TAG }}
+            APP_VERSION=${{ steps.app_version.outputs.VERSION }}
+            VCS_REF=${{ github.sha }}
             PYTHON_IMAGE=3.11
             VARIANT=-slim
           tags: ${{ steps.meta.outputs.tags }}

Dockerfile

@@ -1,4 +1,5 @@
-ARG SOURCE_COMMIT=
+ARG APP_VERSION=0.4.2
+ARG VCS_REF=
 ARG PYTHON_IMAGE=3.11
 ARG VARIANT=
 ARG APT_MIRROR=
@@ -21,6 +22,8 @@ RUN pnpm -C frontend run build-only
 
 FROM python:${PYTHON_IMAGE}${VARIANT:+-$VARIANT} AS build-stage
 
+ARG APP_VERSION=0.4.2
+ARG VCS_REF=unknown
 ARG PIP_INDEX_URL
 ARG PIP_EXTRA_INDEX_URL
 ARG PIP_TRUSTED_HOST
@@ -48,18 +51,29 @@ RUN pip install --no-deps .
 
 FROM python:${PYTHON_IMAGE}${VARIANT:+-$VARIANT}
 
+ARG APP_VERSION=0.4.2
+ARG VCS_REF=unknown
 ARG APT_MIRROR
 
 EXPOSE 18080
 
-ENV WEBUI_BUILD=${SOURCE_COMMIT}
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+LABEL org.opencontainers.image.revision="${VCS_REF}"
+
+ENV WEBUI_BUILD=1
+ENV WEBUI_VERSION=${APP_VERSION}
+ENV WEBUI_VCS_REF=${VCS_REF}
 ENV DEBIAN_FRONTEND=noninteractive
 
 COPY --from=build-stage /usr/local /usr/local
 COPY --from=build-stage /app /app
 
 WORKDIR /app
 
+RUN mkdir -p /usr/local/share/nb-cli-plugin-webui \
+    && printf '%s' "${APP_VERSION}" > /usr/local/share/nb-cli-plugin-webui/version \
+    && printf '%s' "${VCS_REF}" > /usr/local/share/nb-cli-plugin-webui/revision
+
 RUN if [ -n "$APT_MIRROR" ]; then \
       mirror="${APT_MIRROR%/}"; \
       for f in /etc/apt/sources.list /etc/apt/sources.list.d/debian.sources /etc/apt/sources.list.d/debian.list; do \
@@ -91,7 +105,27 @@ RUN if [ -n "$APT_MIRROR" ]; then \
         libxcursor1 \
         libgbm1 \
         libgtk-3-0 \
+        libgtk-4-1 \
+        libgstreamer1.0-0 \
+        libgstreamer-plugins-base1.0-0 \
+        libgstreamer-gl1.0-0 \
+        libgstreamer-plugins-bad1.0-0 \
+        libgraphene-1.0-0 \
+        libvulkan1 \
+        libwoff1 \
+        libvpx9 \
+        libopus0 \
+        libflite1 \
+        libjxl0.11 \
+        libavif16 \
+        libenchant-2-2 \
+        libsecret-1-0 \
+        libhyphen0 \
+        libmanette-0.2-0 \
+        libgles2 \
+        libx264-164 \
         libasound2t64 \
+    && ln -sf /usr/lib/x86_64-linux-gnu/libx264.so.164 /usr/lib/x86_64-linux-gnu/libx264.so \
     && rm -rf /var/lib/apt/lists/*
 
 CMD nb ui run

README.md

@@ -152,20 +152,23 @@ docker pull docker.io/xisoul/nonebot-webui:latest
 Docker 镜像可以选择以下版本:
 
 - `latest`: 默认分支最新可用镜像
-- `master`: 默认分支镜像
-- `${commit_sha7}`: 指定 commit 的短 SHA 镜像
-- `${version}` / `${major}.${minor}`: 当推送 `v*` tag 时自动生成的版本镜像
+- `master`: 默认分支镜像，适合持续跟进测试
+- `${version}` / `${major}.${minor}`: 当推送 `v*` tag 时自动生成的正式版本镜像，例如 `0.4.2`、`0.4`
+
+当前不再推荐使用 GitHub commit 短 SHA 作为公开版本标签。镜像版本统一以显式版本号为主，便于后续做镜像更新检测、版本对比和回滚。
 
 例如:
 
 ```shell
 docker pull ghcr.io/xisoul/nonebot-webui:latest
 docker pull ghcr.io/xisoul/nonebot-webui:master
-docker pull ghcr.io/xisoul/nonebot-webui:<commit_sha7>
+docker pull ghcr.io/xisoul/nonebot-webui:0.4.2
+docker pull ghcr.io/xisoul/nonebot-webui:0.4
 
 docker pull docker.io/xisoul/nonebot-webui:latest
 docker pull docker.io/xisoul/nonebot-webui:master
-docker pull docker.io/xisoul/nonebot-webui:<commit_sha7>
+docker pull docker.io/xisoul/nonebot-webui:0.4.2
+docker pull docker.io/xisoul/nonebot-webui:0.4
 ```
 
 ### 生产部署
@@ -208,6 +211,16 @@ Docker 运行模式下项目默认根目录为 `/projects`。
 ./deploy.sh
 ```
 
+默认情况下，这两个脚本都会自动读取 `pyproject.toml` 中的版本号作为 Docker tag。
+如果你想手动指定镜像版本，也可以直接传参：
+
+```shell
+./build-and-export.sh 0.4.2
+./deploy.sh 0.4.2
+```
+
+容器内显示的 WebUI 版本也会优先使用这个显式版本号，而不是 GitHub 随机 commit 字符串。
+
 本镜像当前不内置 Playwright Linux 系统依赖；若你管理的外部项目自身依赖 Playwright，请在对应项目运行环境中单独安装。
 
 ### 登录说明

build-and-export.sh

@@ -3,7 +3,9 @@
 set -euo pipefail
 
 IMAGE_NAME="nonebot-webui"
-TAG="${1:-$(git rev-parse --short HEAD 2>/dev/null || echo unknown)}"
+DEFAULT_TAG="$(awk -F'\"' '/^version = \"/ {print $2; exit}' pyproject.toml)"
+TAG="${1:-${DEFAULT_TAG:-latest}}"
+VCS_REF="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
 OUTPUT_DIR="${OUTPUT_DIR:-./dist-images}"
 ARCHIVE_NAME="${IMAGE_NAME}-${TAG}.tar"
 ARCHIVE_PATH="${OUTPUT_DIR}/${ARCHIVE_NAME}"
@@ -19,7 +21,8 @@ echo "[1/3] 构建 Docker 镜像..."
 docker build \
   -t "${IMAGE_NAME}:${TAG}" \
   -t "${IMAGE_NAME}:latest" \
-  --build-arg SOURCE_COMMIT="${TAG}" \
+  --build-arg APP_VERSION="${TAG}" \
+  --build-arg VCS_REF="${VCS_REF}" \
   --build-arg PYTHON_IMAGE=3.11 \
   --build-arg VARIANT=-slim \
   --build-arg APT_MIRROR="${APT_MIRROR:-${WEBUI_DEBIAN_MIRROR:-}}" \

deploy.sh

@@ -3,8 +3,8 @@
 # deploy.sh - 本地构建 Docker 镜像并部署到测试服务器
 #
 # 用法:
-#   ./deploy.sh              # 使用 git short hash 作为 tag
-#   ./deploy.sh v0.4.2       # 使用指定 tag
+#   ./deploy.sh              # 使用 pyproject.toml 里的版本号作为 tag
+#   ./deploy.sh 0.4.2        # 使用指定版本号
 #
 set -euo pipefail
 
@@ -18,8 +18,9 @@ CONTAINER_NAME="nonebot-webui"
 if [ -n "${1:-}" ]; then
   TAG="$1"
 else
-  TAG=$(git rev-parse --short HEAD)
+  TAG="$(awk -F'\"' '/^version = \"/ {print $2; exit}' pyproject.toml)"
 fi
+VCS_REF="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
 
 FULL_IMAGE="${IMAGE_NAME}:${TAG}"
 
@@ -33,7 +34,8 @@ echo "========================================"
 echo ""
 echo "[1/4] Building Docker image..."
 docker build \
-  --build-arg SOURCE_COMMIT="$TAG" \
+  --build-arg APP_VERSION="$TAG" \
+  --build-arg VCS_REF="$VCS_REF" \
   --build-arg PYTHON_IMAGE=3.11 \
   --build-arg VARIANT=-slim \
   --build-arg APT_MIRROR="${APT_MIRROR:-${WEBUI_DEBIAN_MIRROR:-}}" \

frontend/src/client/api/schemas.gen.ts

@@ -684,6 +684,13 @@ export const NoneBotProjectMetaSchema = {
         type: 'string'
       }
     },
+    discovered_plugin_dirs: {
+      title: 'Discovered Plugin Dirs',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
     builtin_plugins: {
       title: 'Builtin Plugins',
       type: 'array',
@@ -756,7 +763,14 @@ export const ProcessLogSchema = {
 
 export const ProjectTomlDetailSchema = {
   title: 'ProjectTomlDetail',
-  required: ['project_name', 'adapters', 'plugins', 'plugin_dirs', 'builtin_plugins'],
+  required: [
+    'project_name',
+    'adapters',
+    'plugins',
+    'plugin_dirs',
+    'discovered_plugin_dirs',
+    'builtin_plugins'
+  ],
   type: 'object',
   properties: {
     project_name: {
@@ -787,6 +801,13 @@ export const ProjectTomlDetailSchema = {
         type: 'string'
       }
     },
+    discovered_plugin_dirs: {
+      title: 'Discovered Plugin Dirs',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
     builtin_plugins: {
       title: 'Builtin Plugins',
       type: 'array',

frontend/src/client/api/types.gen.ts

@@ -184,6 +184,7 @@ export type NoneBotProjectMeta = {
   drivers: Array<nb_cli_plugin_webui__app__models__base__ModuleInfo>
   plugins: Array<nb_cli_plugin_webui__app__models__base__Plugin>
   plugin_dirs: Array<string>
+  discovered_plugin_dirs?: Array<string>
   builtin_plugins: Array<string>
   is_running?: boolean
   use_env?: string
@@ -210,6 +211,7 @@ export type ProjectTomlDetail = {
   }>
   plugins: Array<string>
   plugin_dirs: Array<string>
+  discovered_plugin_dirs: Array<string>
   builtin_plugins: Array<string>
 }
 

frontend/src/components/Modals/AddBot/GetBotBasicInfo.vue

@@ -1,11 +1,14 @@
 <script setup lang="ts">
 import { ProjectService } from '@/client/api'
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { useAddBotStore } from '.'
 
 const store = useAddBotStore()
 
 const inputValue = ref('')
+const discoveredOnlyPluginDirs = computed(() =>
+  store.discoveredPluginDirs.filter((dir) => !store.pluginDirs.includes(dir))
+)
 
 const search = async () => {
   if (!inputValue.value) {
@@ -28,6 +31,7 @@ const search = async () => {
     store.adapters = detail.adapters
     store.plugins = detail.plugins
     store.pluginDirs = detail.plugin_dirs
+    store.discoveredPluginDirs = detail.discovered_plugin_dirs ?? []
     store.builtinPlugins = detail.builtin_plugins
     store.projectPath = inputValue.value
 
@@ -96,7 +100,7 @@ const search = async () => {
         }"
       >
         <span class="font-semibold">
-          {{ store.plugins.length ? '已有插件:' : '未找到插件' }}
+          {{ store.plugins.length ? '已配置插件:' : '未配置插件' }}
         </span>
         <div class="flex items-center flex-wrap gap-2">
           <span
@@ -108,11 +112,16 @@ const search = async () => {
             {{ plugin }}
           </span>
         </div>
+        <span v-if="!store.plugins.length" class="text-sm opacity-70">
+          这里显示的是 <span class="font-mono">tool.nonebot.plugins</span> 里声明的插件；
+          大多数通过 pip 安装的插件本体都在项目的
+          <span class="font-mono">.venv/site-packages</span> 中，而不是本地插件目录。
+        </span>
       </div>
 
       <div class="flex flex-col gap-2 rounded-lg p-4 bg-base-200">
         <span class="font-semibold">
-          {{ store.pluginDirs.length ? '已有插件目录:' : '未配置插件目录' }}
+          {{ store.pluginDirs.length ? '已声明本地插件目录:' : '未声明本地插件目录' }}
         </span>
         <div v-if="store.pluginDirs.length" class="flex items-center flex-wrap gap-2">
           <span
@@ -125,8 +134,33 @@ const search = async () => {
           </span>
         </div>
         <span v-else class="text-sm opacity-70">
-          当前项目没有在配置里声明 <span class="font-mono">plugin_dirs</span>，这不影响继续导入；
-          已安装插件仍会按项目配置读取。
+          当前项目没有在 <span class="font-mono">tool.nonebot.plugin_dirs</span> 中声明本地插件目录。
+          这不影响继续导入，也不代表项目没有安装插件。
+        </span>
+      </div>
+
+      <div
+        :class="{
+          'flex flex-col gap-2 rounded-lg p-4 bg-base-200': true,
+          'opacity-50': !discoveredOnlyPluginDirs.length
+        }"
+      >
+        <span class="font-semibold">
+          {{ discoveredOnlyPluginDirs.length ? '扫描到的候选本地插件目录:' : '未扫描到额外候选目录' }}
+        </span>
+        <div v-if="discoveredOnlyPluginDirs.length" class="flex items-center flex-wrap gap-2">
+          <span
+            v-for="plugin_dir in discoveredOnlyPluginDirs"
+            :key="plugin_dir"
+            role="button"
+            class="badge badge-lg !bg-base-100"
+          >
+            {{ plugin_dir }}
+          </span>
+        </div>
+        <span v-if="discoveredOnlyPluginDirs.length" class="text-sm opacity-70">
+          这些目录是根据常见目录结构自动识别出来的，仅供你核对；
+          它们当前并不等于项目已经声明的 <span class="font-mono">plugin_dirs</span> 配置。
         </span>
       </div>
     </div>