Midscene.js 容器化部署指南：Docker 里十分钟跑通 Web 自动化服务

Midscene.js 容器化部署指南：Docker 里十分钟跑通 Web 自动化服务

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

Midscene.js 是基于视觉模型的 GUI 自动化引擎，本文用 Docker 做容器化部署，跑通它的 Web Playground 服务：在一台只装了 Docker 的干净机器上，十分钟完成装依赖、起服务，并拿到一个可以在浏览器里下自然语言指令的自动化环境。适合需要把可复现的自动化环境交给同事或 CI 机器的开发。

先跑起来

基础镜像的硬性要求是 node:22：仓库在 package.json 的 engines 里声明了 Node^20.19.0 || ^22.12.0 || >=24.0.0，用 node:18 或 alpine 标签会在安装阶段直接报错。Midscene.js 是 pnpm 单仓库，没有官方 Dockerfile，把源码目录挂进一个容器就能跑起 demo 服务：

git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene docker run --rm -it -v $(pwd):/app -w /app -p 3000:3000 -p 5870:5870 node:22 \ bash -c "corepack enable && pnpm install && pnpm --filter playground run demo"

demo命令一次起两个进程：5870 端口是 apps/playground/demo/server.ts 里的 Puppeteer 后端，负责驱动无头浏览器；3000 端口是 Playground 的 Web 界面。装完依赖大概三四分钟，打开 http://localhost:3000 输入一条自然语言任务，容器里能通模型服务的话，就能看到浏览器自己操作页面。

把关键配置讲透

整个服务唯一的外部依赖是视觉模型，用四个环境变量配置：MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY。前三个直白，最容易漏的是 FAMILY——它决定提示词模板和响应解析规则，调用的模型是 Qwen 却填成gpt的话，任务提交成功但模型输出的动作无法解析，表现为界面一直转圈、日志里报 parse 错误。demo 服务器从仓库根目录的.env读取这些变量，写好后重启容器即可；其他模型（Doubao、GLM、Gemini）的取值见 apps/site/docs/en/common/setup-env.mdx。

第二个关键点是镜像基底。Puppeteer 自带 Chromium，alpine 基底的 musl libc 和它不兼容，就算装依赖能过，运行到启动浏览器那一步也会失败。用 Debian 基底的 node:22，宿主机上执行docker run --rm node:22 node -v能确认版本满足 engines，这一步能提前排掉一半安装失败。

跑起来之后容易踩的坑

最高频的失败是容器缺 Chromium 运行库。现象是第一个任务抛出error while loading shared libraries: libnss3.so，原因是 node 官方镜像不带浏览器依赖库。处理：在容器里装系统 chromium，再让 Puppeteer 指过去：

apt-get update && apt-get install -y chromium fonts-liberation export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

第二个是模型服务不通。任务和界面都卡在执行中、日志里首次模型请求超时，多半不是 key 的问题，是网络问题：在容器里curl -I一下MIDSCENE_MODEL_BASE_URL，通不通一目了然；公司内网需要代理时，给容器加上http_proxy、https_proxy两个环境变量。

第三个是宿主机端口冲突。3000 或 5870 被占用时，Docker 启动不会报错，但页面里连接后端会一直失败，把-p映射里宿主机一侧的端口改掉即可。

上生产前再核对一遍

本地 demo 和生产之间只差这五条：

• 健康检查：docker compose healthcheck用curl -f http://localhost:5870/判定是否重启
• 内存上限：容器设 4G 左右，Chromium 吃内存，OOM 时浏览器进程会静默死掉
• API key 走 secret 或环境注入，不提交进仓库的 .env
• 日志轮转：json-file驱动加max-size: 10m，避免截图和日志撑爆磁盘
• 镜像写死版本号，不用 latest

Midscene.js 的容器化部署到这里就是这些。目标是可复现：任何一台装了 Docker 的机器执行同样的命令，得到的环境行为一致；CI 上跑 E2E、给同事交付环境，都能直接复用这套配置。后续接 Android 或桌面平台时，设备连接方式会变，但模型配置和容器结构可以原样保留。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene