企业官网建设流程全解析

Midscene.js 容器化部署完整指南：Docker 搭建与运行 AI 自动化服务

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

想把 Midscene.js 装进容器里跑起来，又不想在本机装一堆依赖？本文带你用 Docker 把它跑起来：克隆代码、准备模型密钥、在容器内装依赖、启动 Playground 服务，最后验证 AI 驱动浏览器的功能真的可用。全程不需要修改仓库里任何文件。

先看最终效果

部署完成后，你会得到两个服务：一个是运行在 3000 端口的 Playground 网页，你打开浏览器就能看到操作台界面；另一个是 5870 端口的 Playground Demo Server，它用 Puppeteer 驱动一个无头 Chrome 加载测试页面，并挂上一个PuppeteerAgent。你在网页里输入一句自然语言指令（比如"点击搜索框输入关键词"），AI 就会接管浏览器执行，执行过程有截图和步骤记录。

动手前：需要准备什么

• Docker：任意较新版本，确认docker version能正常输出
• Node 环境不用装：所有 Node 相关步骤都在容器内执行，宿主机只需 Docker
• 一个视觉语言模型 API Key：Midscene 通过多模态模型"看懂"屏幕再操作，需要类似 OpenAI 兼容接口的 Key 和 Base URL
• 约 2GB 磁盘空间：pnpm 依赖 + Chromium 浏览器，建议预留充足

从零到跑起来

步骤1：克隆仓库到本地

git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene

它把整个 monorepo 拉到当前目录并进入项目根目录。判断成功：ls能看到apps/、packages/、pnpm-workspace.yaml这些条目。Midscene 是 pnpm workspace 结构，packages/playground/ 是服务实现，apps/playground/ 是前端应用，后面都会用到。

步骤2：在仓库根目录准备好模型密钥

在midscene/.env文件中写入三行（文件名就叫.env，不带引号）：

MIDSCENE_MODEL_BASE_URL=你的模型服务地址 MIDSCENE_MODEL_API_KEY=你的API Key MIDSCENE_MODEL_NAME=模型名称

Demo server 启动时会自动加载仓库根目录的.env（见 apps/playground/demo/server.ts）。判断成功：cat .env能看到三行且 Key 没有笔误。完整的环境变量说明可参考 setup-env 文档。

步骤3：在容器内安装项目依赖

docker run -it --name midscene-work \ -v "$PWD":/app -w /app \ node:20-alpine sh -c "corepack pnpm install"

它启动一个 node:20-alpine 容器，把当前目录挂载到容器内的/app，用 corepack 激活 pnpm 后安装全部 workspace 依赖。判断成功：输出最后出现Done in ...且无红色报错，容器内生成node_modules/。仓库要求 Node^20.19，所以基础镜像选 node:20 系列。

步骤4：启动 Playground 服务

docker run -it --rm --name midscene \ -v "$PWD":/app -w /app -p 3000:3000 -p 5870:5870 \ -e MIDSCENE_MODEL_BASE_URL -e MIDSCENE_MODEL_API_KEY -e MIDSCENE_MODEL_NAME \ node:20-alpine sh -c "corepack pnpm run demo -w playground"

它在容器里同时启动两件事：demo:server（Puppeteer 无头浏览器 + Agent 服务，监听 5870）和 Playground 前端（监听 3000），并把两个端口映射到宿主机。-e参数把宿主机环境变量透传进容器，覆盖.env的值。判断成功：终端先后打印Playground Demo Server started on port 5870和 rsbuild 的 ready 信息。

步骤5：验证服务真的可用

docker ps curl -s http://localhost:5870/ | head -c 200

docker ps里应能看到midscene容器状态为 Up；curl 能返回内容说明 5870 端口已通。最后打开浏览器访问http://localhost:3000，看到 Playground 界面、页面提示已连接 demo server，就算整条链路跑通了：网页 → Agent 服务 → 无头 Chrome → 你的模型 API。

步骤6：用一句指令体验 AI 操作

在 Playground 页面输入类似"点击右上角菜单里的搜索按钮"这样的指令并执行。判断成功：页面出现逐步执行的进度条和截图，每一步都有对应的画面，最后给出执行结果。如果执行卡住不动，多半是模型 Key 或网络问题，跳到下一节排查。

常见故障与快速恢复

• Puppeteer 报找不到 Chrome /Failed to launch the browser process：alpine 镜像默认没有浏览器，原因是最小镜像没装 Chromium。解法：容器启动命令里加-e PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium，并在安装 Chromium 的镜像里运行。
• EADDRINUSE端口被占用：宿主机 3000 或 5870 已被其他进程占用。解法：ss -ltnp | grep 5870找到占用者，或把映射改成3001:3000后访问新端口。
• 执行指令时模型返回 401 / 404：API Key 或 Base URL 传错。解法：确认宿主机env | grep MIDSCENE有值且与.env一致，模型名和该服务实际支持的对得上。
• 第一次pnpm install极慢甚至超时：容器内走了国外 npm 源。解法：在容器启动命令里加-e PUPPETEER_SKIP_DOWNLOAD=true（浏览器另行安装），并为 npm 配置国内镜像，第二次起依赖已缓存会快很多。

要长期/生产使用时

• 限制容器资源：docker run加--cpus=2 --memory=4g，AI 服务主要吃内存和网络，避免占满宿主机
• 固定镜像版本：把node:20-alpine换成具体 tag（如node:20.19-alpine），避免基础镜像漂移导致行为变化
• 配置健康检查：用--health-cmd "curl -f http://localhost:5870/ || exit 1" --health-interval=30s，容器异常时能被编排系统自动拉起
• 收敛日志：给 daemon 设置max-size: 10m, max-file: 3（dockerd 的 log-driver 配置），防止无头浏览器频繁输出撑爆磁盘
• 密钥不要进镜像：始终用-e或编排平台的 Secret 注入模型 Key，.env加进.gitignore，绝不提交

下一步

到这里你已经完成了完整链路：克隆 → 密钥 → 容器内装依赖 → 启动 Playground → 验证 AI 执行。如果想继续深入，可以从三个方向走：

• 了解 CLI 批量跑 YAML 脚本的方式，看 packages/cli/ 与 yaml-script-runner 文档
• 研究 Agent 服务的实现细节，核心代码在 packages/playground/src/server.ts
• 需要控制真机时，Android Playground 的部署思路类似，参考 Android Playground 说明

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