如何为 Midscene.js 搭建容器化服务：Docker 部署完整指南

如何为 Midscene.js 搭建容器化服务：Docker 部署完整指南

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

Midscene.js 是基于视觉语言模型的 GUI 自动化工具，可驱动 Web、Android、iOS 界面执行 E2E 测试与自动化操作。本文用 Docker 把 Midscene.js 打包成可部署的服务，覆盖环境检查、镜像构建、启动验证与排障全过程。

适用场景：什么时候该给 Midscene.js 做容器化

容器化不是为了炫技，而是针对几类具体问题的解法。下面三种情况，直接上容器收益最大。

多台机器环境不一致

Midscene.js 的仓库对运行时版本有明确要求：Node 需要 20.19+ / 22.12+ / 24+，包管理器要求 pnpm 9.3+。团队里有人用 Node 20、有人用 Node 24，本地装依赖时版本漂移导致的报错很常见。把整个工作区打进一个基于 alpine 的 Node 镜像，所有人的运行环境由同一个镜像决定，与宿主机解耦。

在 CI 中跑自动化测试

CI 机器是无状态环境，每次构建都从干净系统开始。如果每次都要现装 Node、现拉依赖，构建慢且不稳定。预先构建好 Midscene.js 的 Docker 镜像后，CI 只需要docker run，自动化测试服务的启动时间从分钟级降到秒级，也天然做到了环境隔离。

团队共享一个自动化服务

Midscene 的 Playground 服务监听固定端口（默认 5800）。把它部署在一台公共机器上并做成容器，团队成员通过浏览器访问同一地址做调试、回放和验证脚本，避免每人各起一套本地环境，也省去了"我这边能跑、你那边跑不起来"的扯皮。

上手部署：Docker 环境检查清单

开始前确认宿主机上有 Docker 与 docker compose 两个工具，并记录 Node 版本要求以便选对基础镜像。

docker --version docker compose version

如果版本正常，拉取代码：

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

仓库是多包工作区，核心逻辑在 packages/core/，Playground 服务在 packages/playground/。镜像只需要覆盖工作区根目录即可。

构建镜像并启动 Midscene.js 服务

Dockerfile 保持最小化，关键约束是基础镜像的 Node 版本必须落在仓库支持范围内：

FROM node:22-alpine WORKDIR /app COPY . . RUN corepack enable && pnpm install --frozen-lockfile EXPOSE 5800 CMD ["pnpm", "run", "dev"]

pnpm run dev会构建工作区各包并拉起服务，Playground 服务默认监听 5800 端口。模型相关参数不要写死在镜像里，交给 compose 注入：

services: midscene: build: . ports: - "5800:5800" env_file: .env restart: unless-stopped

.env里放置模型配置，常用的有MIDSCENE_MODEL_NAME与MIDSCENE_MODEL_BASE_URL，其余字段在官方文档的模型配置章节有完整说明。

构建并启动：

docker compose up -d --build

首次构建需要拉依赖和编译各包，耐心等待几分钟即可。

服务启动验证与常见排障

启动后先用 compose 视角确认容器状态：

docker compose ps docker compose logs -f midscene

容器状态为 running、日志里出现服务监听 5800 的记录后，在宿主机做连通性验证：

curl -I http://localhost:5800

返回 HTTP 响应头即说明服务正常。排障时优先检查三类问题：

• 端口冲突：宿主机 5800 被占用时，把映射改成8080:5800之类即可，容器内端口不变。
• 模型服务不通：任务执行时报模型超时，多半是容器网络出不去。用docker compose exec midscene curl -I <模型服务地址>在容器内验证出站连通性，再检查代理或网络策略。
• 镜像构建失败：优先看pnpm install阶段的报错，多为 Node 版本与 engines 字段不匹配，换回受支持的基础镜像版本。

面向生产环境的加固：资源限制、健康检查与日志

把服务放到长期运行的机器上之前，建议在 compose 里补四样东西：资源上限、健康检查、日志轮转，以及对外模型服务的连通性兜底。

healthcheck: test: ["CMD", "wget", "-qO-", "http://localhost:5800"] interval: 30s deploy: resources: limits: cpus: "2" memory: 2g

日志用轮转避免磁盘写满：

logging: driver: json-file options: max-size: "10m" max-file: "3"

再说明两点：一是把.env加入.dockerignore，避免模型密钥被打进镜像层；二是如果模型服务走内网地址，在 compose 里显式声明网络并把模型服务端加入可达白名单，比事后排查"偶发超时"省事得多。

收尾

到这里，Midscene.js 已经从一个本地工程变成了一个可复用、可扩容的容器化服务：环境由镜像锁定，验证靠 5800 端口的连通性，加固项集中在资源与日志上。后续升级只需重新构建镜像并滚动替换容器。更多配置细节，可查阅官方文档：apps/site/docs/zh/。

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