fix: prepare 0.4.6 playwright docker release

Author: XiSoul

Dockerfile

@@ -1,32 +1,41 @@
-ARG APP_VERSION=0.4.5
+ARG APP_VERSION=0.4.6
 ARG VCS_REF=
 ARG PYTHON_IMAGE=3.11
 ARG VARIANT=
 ARG APT_MIRROR=
 ARG PIP_INDEX_URL=
 ARG PIP_EXTRA_INDEX_URL=
 ARG PIP_TRUSTED_HOST=
+ARG SKIP_FRONTEND_BUILD=0
 
 FROM node:20 AS frontend-build
 
+ARG SKIP_FRONTEND_BUILD=0
+
 WORKDIR /app
 
+COPY nb_cli_plugin_webui/dist/ nb_cli_plugin_webui/dist/
 COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml ./
 COPY frontend/package.json frontend/
 
-RUN corepack enable && pnpm install --frozen-lockfile
+RUN if [ "$SKIP_FRONTEND_BUILD" != "1" ]; then \
+      corepack enable && pnpm install --frozen-lockfile; \
+    fi
 
 COPY frontend/ frontend/
 
-RUN pnpm -C frontend run build-only
+RUN if [ "$SKIP_FRONTEND_BUILD" != "1" ]; then \
+      pnpm -C frontend run build-only; \
+    fi
 
 FROM python:${PYTHON_IMAGE}${VARIANT:+-$VARIANT} AS build-stage
 
-ARG APP_VERSION=0.4.5
+ARG APP_VERSION=0.4.6
 ARG VCS_REF=unknown
 ARG PIP_INDEX_URL
 ARG PIP_EXTRA_INDEX_URL
 ARG PIP_TRUSTED_HOST
+ARG SKIP_FRONTEND_BUILD=0
 
 RUN if [ -n "$PIP_INDEX_URL$PIP_EXTRA_INDEX_URL$PIP_TRUSTED_HOST" ]; then \
       printf '[global]\n' > /etc/pip.conf; \
@@ -51,9 +60,10 @@ RUN pip install --no-deps .
 
 FROM python:${PYTHON_IMAGE}${VARIANT:+-$VARIANT}
 
-ARG APP_VERSION=0.4.5
+ARG APP_VERSION=0.4.6
 ARG VCS_REF=unknown
 ARG APT_MIRROR
+ARG SKIP_FRONTEND_BUILD=0
 EXPOSE 18080
 
 # 创建挂载目录
@@ -92,12 +102,16 @@ RUN if [ -n "$APT_MIRROR" ]; then \
     fi \
     && apt-get -o Acquire::http::Proxy=false -o Acquire::https::Proxy=false update \
     && apt-get -o Acquire::http::Proxy=false -o Acquire::https::Proxy=false install -y --no-install-recommends \
+        libasound2t64 \
         libnspr4 \
         libnss3 \
         libdbus-1-3 \
         libatk1.0-0t64 \
         libatk-bridge2.0-0t64 \
         libcups2t64 \
+        libevent-2.1-7t64 \
+        libharfbuzz-icu0 \
+        libicu76 \
         libxkbcommon0 \
         libatspi2.0-0t64 \
         libxcomposite1 \
@@ -117,7 +131,10 @@ RUN if [ -n "$APT_MIRROR" ]; then \
         libwoff1 \
         libvpx9 \
         libopus0 \
+        libwebpdemux2 \
+        libwebpmux3 \
         libflite1 \
+        libxslt1.1 \
         libjxl0.11 \
         libavif16 \
         libenchant-2-2 \
@@ -126,11 +143,10 @@ RUN if [ -n "$APT_MIRROR" ]; then \
         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
+CMD ["nb", "ui", "run"]
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
     CMD python -c "import json,sys,urllib.request; from pathlib import Path; path=Path('/app/config.json'); port=str((json.loads(path.read_text(encoding='utf-8')).get('port') if path.exists() else None) or '18080'); urllib.request.urlopen(f'http://127.0.0.1:{port}', timeout=5); sys.exit(0)"

README.md

@@ -77,7 +77,7 @@ _✨ 面向 NoneBot 多实例运维的 WebUI ✨_
 - `docker.io/xisoul/nonebot-webui:master`
 - `docker.io/xisoul/nonebot-webui:${version}`
 
-推荐优先使用显式版本号，例如 `0.4.5`、`0.4`，后面做升级、回滚、版本检测会更方便。
+推荐优先使用显式版本号，例如 `0.4.6`、`0.4`，后面做升级、回滚、版本检测会更方便。
 
 ### 非 Docker 安装
 
@@ -166,7 +166,16 @@ WebUI 会自动把它解析并保存为容器内的真实绝对路径。
 
 另外，添加的目录本身需要是一个 NoneBot 项目根目录，至少应当能看到 `pyproject.toml`。如果 `pyproject.toml` 在子目录里，就填写那个子目录，不要填到父目录。
 
-本镜像当前不内置 Playwright Linux 系统依赖；若你管理的外部项目自身依赖 Playwright，请在对应项目运行环境中单独安装。
+本镜像已内置 WebUI 预装 `nonebot_plugin_htmlrender` / Playwright Chromium 常见所需的 Linux 运行库。
+
+如果你的外部项目依赖 Playwright，WebUI 在启动实例前会优先尝试用该项目自己的 Python 环境执行：
+
+```shell
+python -m playwright install chromium
+```
+
+浏览器二进制仍然安装在实例运行时可见的目录里，不会直接打进项目仓库。
+如果你的网络环境使用 SOCKS 代理，WebUI 会继续保留实例代理环境用于下载 Chromium，但系统库仍然依赖当前 WebUI 容器镜像提供。
 
 ### 登录说明
 
@@ -213,6 +222,15 @@ docker logs nonebot-webui
 - `WEBUI_PIP_EXTRA_INDEX_URL`
 - `WEBUI_PIP_TRUSTED_HOST`
 
+### 本地镜像排查
+
+如果你是在本机或 WSL 里排查 Docker 镜像问题，仓库额外提供了一个只用于调试的构建参数：
+
+- `SKIP_FRONTEND_BUILD=1`
+
+它会直接复用仓库内现成的 `nb_cli_plugin_webui/dist`，跳过 Node / pnpm 的前端重新构建步骤，方便先验证 Python、Playwright、Linux 运行库和实例启动链路。
+正式发布时默认不要开启这个参数，仍应走完整前端构建流程。
+
 ## 常见提醒
 
 - WebUI 新建实例默认放在 `/projects`
@@ -221,7 +239,7 @@ docker logs nonebot-webui
 - 如果实例根目录里没有 `pyproject.toml`，说明你填错目录层级了
 - 首次登录凭证请去容器日志里看
 - 想回头找 token，直接看容器日志，不是在页面里反查
-- 如果某些插件依赖 Playwright 或系统库，请在对应机器人项目自己的运行环境里安装，不是装在 WebUI 容器里
+- 如果某些插件依赖 Playwright，优先让 WebUI 在实例启动前自动预装；若项目还有额外浏览器或系统库要求，再按该项目自身文档补充
 
 ## 发布流程
 
@@ -245,20 +263,20 @@ docker logs nonebot-webui
 - `${major}.${minor}`
 - `${version}`
 
-例如版本 `0.4.5` 会自动生成：
+例如版本 `0.4.6` 会自动生成：
 
 - `xisoul/nonebot-webui:latest`
 - `xisoul/nonebot-webui:master`
 - `xisoul/nonebot-webui:0.4`
-- `xisoul/nonebot-webui:0.4.5`
+- `xisoul/nonebot-webui:0.4.6`
 
 ### 推荐发版步骤
 
 1. 修改代码并在本地测试通过
 2. 更新 `pyproject.toml` 中的版本号
 3. 同步更新 `Dockerfile` 中的 `APP_VERSION`
 4. 提交代码
-5. 打版本 tag，例如 `v0.4.5`
+5. 打版本 tag，例如 `v0.4.6`
 6. 推送 `master` 和对应 tag
 
 示例：
@@ -268,8 +286,8 @@ git add .
 git commit -m "feat: your change"
 git push origin master
 
-git tag v0.4.5
-git push origin v0.4.5
+git tag v0.4.6
+git push origin v0.4.6
 ```
 
 ### 重要说明

RELEASE_TODO_2026-05-01.md

@@ -1,8 +1,8 @@
 # Release Notes Draft 2026-05-01
 
-这份清单用于记录 `0.4.5` 计划带上的修复项。
+这份清单用于记录 `0.4.6` 计划带上的修复项。
 
-## 0.4.5 已纳入修复
+## 0.4.6 已纳入修复
 
 ### 1. Docker / NAS 创建容器体验修复
 
@@ -64,21 +64,27 @@
   - 改为统一走 `get_version()`
   - 修复改包名后镜像启动 `PackageNotFoundError`
 
-## 本次明确不纳入发版
-
-### htmlrender / Playwright 下载链路
+### 7. htmlrender / Playwright 启动前预装与 Linux 依赖补齐
 
 - 文件:
+  - `Dockerfile`
+  - `README.md`
   - `nb_cli_plugin_webui/app/process/service.py`
-- 原因:
-  - 当前不同平台行为差异大
-  - 你已经明确说明这条先不动，后面有时间再单独测试
-  - 不建议在这次发版里继续混入 htmlrender 下载策略调整
+- 内容:
+  - WebUI 启动实例前会先尝试用项目自己的 Python 环境执行 `python -m playwright install chromium`
+  - `nonebot_plugin_htmlrender` 场景下统一补齐 `PLAYWRIGHT_BROWSERS_PATH` 和下载超时等运行时环境
+  - Docker 镜像内补齐 Playwright Chromium 常见 Linux 运行库，覆盖 `libicu76`、`libxslt1.1`、`libevent-2.1-7t64`、`libwebpdemux2`、`libwebpmux3`、`libharfbuzz-icu0` 等缺失项
+  - 遇到 SOCKS 代理时，日志会明确说明系统库依赖镜像内提供，避免把插件内部 `--with-deps` 失败误判成浏览器未下载
+
+## 本次测试备注
+
+- WSL 侧 Docker `buildx` 插件曾出现段错误，已在本机补装系统包版 `docker-buildx`
+- 当前仓库额外加入了 `SKIP_FRONTEND_BUILD=1` 构建开关，仅用于本地/WSL 排查镜像问题时复用现成前端产物；默认发布流程仍走完整前端构建
 
 ## 发版前建议确认
 
-1. 确认 `pyproject.toml` 版本号与待打 tag `v0.4.5` 一致
-2. 确认 `Dockerfile` 中 `APP_VERSION` 已同步更新到 `0.4.5`
-3. 确认这次不包含 `htmlrender` 下载源策略调整
-4. 构建镜像后优先验证 NAS 容器创建页是否还会自动带出错误挂载
+1. 确认 `pyproject.toml` 版本号与待打 tag `v0.4.6` 一致
+2. 确认 `Dockerfile` 中 `APP_VERSION` 已同步更新到 `0.4.6`
+3. 构建镜像后优先验证 `nonebot_plugin_htmlrender` 项目的 Playwright Chromium 预装与启动
+4. 复测 NAS / Docker 场景下的路径映射与默认挂载说明
 5. 复测“添加实例失败”场景，确认不再留脏记录

nb_cli_plugin_webui/app/process/service.py

@@ -217,6 +217,13 @@ def _default_nonebot2_data_dir(env: dict) -> Path:
     return home_dir / ".local" / "share" / "nonebot2"
 
 
+def _is_socks_proxy_url(value: str) -> bool:
+    normalized = str(value or "").strip().lower()
+    return normalized.startswith(
+        ("socks4://", "socks4a://", "socks5://", "socks5h://")
+    )
+
+
 def _clear_stale_htmlrender_dirlock(env: dict, log_storage: Optional[LogStorage] = None) -> None:
     lock_path = (
         _default_nonebot2_data_dir(env)
@@ -629,6 +636,7 @@ async def _background_install() -> None:
         or str(env.get("HTTPS_PROXY") or env.get("https_proxy") or "").strip()
         or str(env.get("HTTP_PROXY") or env.get("http_proxy") or "").strip()
     )
+    socks_proxy_active = _is_socks_proxy_url(active_proxy)
 
     if log_storage is not None:
         await log_storage.add_log(
@@ -666,6 +674,16 @@ async def _background_install() -> None:
                     ),
                 )
             )
+            if socks_proxy_active:
+                await log_storage.add_log(
+                    CustomLog(
+                        level="INFO",
+                        message=(
+                            "当前代理为 SOCKS 协议，启动前预装只下载 Playwright Chromium，"
+                            "不依赖 apt 安装系统库；Linux 运行库需由 WebUI 容器镜像预先提供。"
+                        ),
+                    )
+                )
         else:
             await log_storage.add_log(
                 CustomLog(
@@ -976,6 +994,13 @@ async def run_nonebot_project(project: project_service.NoneBotProjectManager):
     if str(env_data.get("HOST", "")).strip() != host:
         project.write_to_env(project_meta.use_env, "HOST", host)
 
+    await _ensure_htmlrender_browser_ready(
+        project_meta,
+        env,
+        log_storage=log_storage,
+        block=True,
+    )
+
     process = ProcessManager.get_process(project_meta.project_id)
     if process:
         if process.refresh_runtime_state():

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "nb-cli-plugin-webui-xisoul"
-version = "0.4.5"
+version = "0.4.6"
 description = "web ui support for nb-cli"
 authors = ["Kyomotoi <kyomotoiowo@gmail.com>"]
 license = "MIT"