跳转至

Docker

所发布的图片展示了可重复使用 MCP 的推荐运行时。

如需为已运行的 HTTP 服务器配置 TLS 和身份验证的简短部署步骤,请参阅Docker Streamable HTTP 反向代理示例。

运行

docker run --rm -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

artefacts 会被写入容器中的 /data。挂载该路径以保存截图、快照、下载文件和网络输出。

镜像已将 Tini 作为 PID 1 和子进程收割器运行,因此常规命令不需要额外的 Docker init 进程。

相同的发布标签已发布到 Docker Hub,标签为 swimmwatch/cloakbrowser-mcp,并在 GHCR 上发布为 ghcr.io/swimmwatch/cloakbrowser-mcp。

有头会话与虚拟显示

镜像默认设置 PLAYWRIGHT_MCP_HEADLESS=true,无头会话不会启动 Xvfb。当会话请求 headless: false 时,启动器会按需启动一个容器私有的 Xvfb 显示,等待它可用,并保持运行直至容器退出。并发的有头 HTTP 会话共用该显示,但各自的 Playwright 浏览器上下文、页面、配置文件和产物仍保持隔离。

有头 stdio 会话使用标准 Playwright MCP 环境变量:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_HEADLESS=false \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

这不是可见桌面或图形界面流式传输服务:镜像不提供 VNC、noVNC、RDP、主机 X11 访问或显示捕获。不要将原生 X11 焦点、剪贴板或显示捕获视为租户隔离边界。启动器会在关闭期间停止显示;启动失败或 MCP CLI 退出会导致容器关闭,不会留下仍可使用的桥接器。

在此镜像之外,有头浏览器仍需要可用的显示环境。没有显示环境时,请设置 PLAYWRIGHT_MCP_HEADLESS=true。

容器健康检查与受限运行时

Docker HEALTHCHECK 通过私有 Unix 套接字主动确认 MCP CLI 事件循环能够响应。如果 Xvfb 已启动,也会检查 X11 显示;从未请求过显示的无头容器仍可处于健康状态。显示正在启动、正在关闭或发生故障时,健康检查失败。X11 响应探测最多等待 1 秒,CLI 响应最多等待 750 毫秒,私有健康请求最多等待 2.5 秒;Docker 会在 3 秒后终止一次健康检查命令。Docker 使用 2 秒的检查间隔和两次重试,因此状态转换取决于 Docker 的调度,不能作为可用性服务等级目标。此检查独立于公共 HTTP /healthz 和 /readyz 端点,绝不会通过 MCP stdio 发送流量。它不证明浏览器、MCP 会话或远程站点可用;重启和恢复由外部编排器负责。

启动器向每个子进程发送 SIGTERM 后最多等待 8 秒,再发送 SIGKILL 后最多等待 2 秒。Docker 停止超时必须允许 CLI 和 Xvfb 按顺序关闭。镜像以非 root 的 node 用户运行,并支持只读根文件系统。保留 /data 挂载以保存产物;如果可能运行有头会话,还需为 /tmp 和 /tmp/.X11-unix 提供可写的临时挂载。健康检查套接字仅允许所有者访问(0600)。容器内的 X11 套接字由 node 进程和 Xvfb 共用,因此不是租户隔离边界。不要从主机挂载这两个套接字,也不要在容器之间共享它们。

持久化配置文件

Docker 默认不会启用持久化浏览器配置文件。当你希望 cookie、本地存储、缓存或扩展状态在 容器重启后保留时,请使用现有的 /data 卷作为持久化根目录:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Docker 内部的环境变量必须使用容器路径,例如 /data/profiles/default, 而不是主机路径。桥接器会创建缺失的配置文件目录、检查写入权限、将容器路径写入生成的 Playwright MCP 配置,并锁定显式配置的持久配置文件。每个配置文件只能有一个活动服务器,包括在多个容器之间;恢复限制见持久登录配置文件。

CloakBrowser 许可证缓存

该镜像会将 CloakBrowser 二进制文件、许可证状态和验证缓存存储在 /home/node/.cloakbrowser 中。请在此处挂载命名卷,以便在更换容器时保留 GitHub 免费层或 Pro 登录状态:

docker volume create cloakbrowser-cache

docker run --rm -it \
  --entrypoint node \
  -v cloakbrowser-cache:/home/node/.cloakbrowser \
  swimmwatch/cloakbrowser-mcp:latest \
  /opt/cloakbrowser-mcp/node_modules/cloakbrowser/dist/cli.js login

docker run --rm -i \
  -v cloakbrowser-cache:/home/node/.cloakbrowser \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

使用同一个卷运行上游 info 或 logout 命令,即可检查或删除已保存的登录状态。 也可以通过容器的机密管理注入 CLOAKBROWSER_LICENSE_KEY。请勿将许可证密钥写入 镜像层、提交到版本控制的 Compose 文件,或作为构建证据捕获的命令输出中。

自定义 CloakBrowser 二进制文件

将兼容的浏览器可执行文件挂载到容器中,并通过 --binary-path(或 CLOAKBROWSER_BINARY_PATH)传递其容器内路径:

docker run --rm -i \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/custom-chrome:/browser/chrome:ro" \
  swimmwatch/cloakbrowser-mcp:latest \
  --binary-path /browser/chrome

该文件必须是与镜像 CPU 架构兼容的可读 Linux 可执行文件,且所需库必须在容器中 可用。该路径适用于容器中的所有 Streamable HTTP 会话;需要不同浏览器二进制文件 时,请运行单独的容器。

Chrome 扩展

Chrome 扩展需要持久化配置文件,并且必须单独挂载。请在环境变量中使用容器路径, 而不是主机路径。扩展挂载可以是只读的:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
  -e CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS=/extensions/my-extension \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/extensions/my-extension:/extensions/my-extension:ro" \
  swimmwatch/cloakbrowser-mcp:latest

当路径包含逗号或传入多个扩展目录时,请为 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS 使用 JSON 数组。更改扩展文件或扩展 路径后,请重启容器。

Playwright Extension 连接模式与上面的解压扩展挂载不同。它需要在 persistent Chrome/Edge profile 中安装官方扩展,并提供 PLAYWRIGHT_MCP_EXTENSION_TOKEN。请将每个 profile 挂载到独立的 writable path,通过 secret manager 注入 token,不要同时使用 PLAYWRIGHT_MCP_EXTENSION=true 和 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS。

可流式传输的 HTTP

若要在本地使用 Streamable HTTP,请将容器端口发布到回环地址:

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz

要运行有头 HTTP 会话,请在容器中设置 PLAYWRIGHT_MCP_HEADLESS=false。单个 initialize 请求仍可通过受支持的 MCP 元数据选择无头模式。

docker run --rm -p 127.0.0.1:3000:3000 \
  -e PLAYWRIGHT_MCP_HEADLESS=false \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

若要从容器直接访问 HTTPS,请挂载您的证书文件并选择 HTTPS:

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/certs:/certs:ro" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000 \
  --http-protocol https --https-cert /certs/cert.pem --https-key /certs/key.pem

主机端的 127.0.0.1:3000 绑定会将端点保留在本地。 若在非回环接口上发布 Streamable HTTP,请使用 HTTPS 并启用身份验证,或将服务器部署在具有身份验证和网络控制功能的可信 TLS 终止反向代理之后。 Streamable HTTP 公开了固定的 GET /healthz 和 GET /readyz 探测点,它们位于同一主机和端口上。 如果配置了 --http-auth-token 或 CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN 已配置,则这些探针需要与 MCP 请求相同的 Authorization: Bearer ... 标头。 有关所有 HTTP 传输标志和环境变量的详细信息,请参阅生成的 CLI 参考。

已管理 CDP

发布已配置的 managed-CDP 范围一对一。此 stdio 示例启用一个 会话并保持每个主机端口绑定到回环地址:

docker run --rm -i \
  -p 127.0.0.1:9222-9231:9222-9231 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --cdp-enabled \
  --cdp-port-range 9222-9231 \
  --cdp-host 0.0.0.0 \
  --cdp-allow-remote \
  --cdp-advertised-host 127.0.0.1

--cdp-host 0.0.0.0 是 Docker 端口转发所必需的,因此明确 --cdp-allow-remote 选择加入和具体的 --cdp-advertised-host 也是必需的。 不要将范围重新映射到不同的主机端口号:发现 URL 包含 租用的端口和每个已发布的端口必须一对一地路由到其所属会话。

对于多会话 Streamable HTTP,请配置并发布池,但不要设置 如果客户应单独选择,则处理默认值:

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -p 127.0.0.1:9222-9231:9222-9231 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http \
  --http-host 0.0.0.0 \
  --http-port 3000 \
  --cdp-port-range 9222-9231 \
  --cdp-host 0.0.0.0 \
  --cdp-allow-remote \
  --cdp-advertised-host 127.0.0.1

一个经过身份验证的 initialize 请求使用 cdpEnabled: true 租约发布了一个 端口。省略的值继承进程默认值,而cdpEnabled: false 明确选择退出且不使用任何 CDP 端口。池耗尽仅拒绝新的 启用 CDP 的会话;它不会降低禁用会话的容量。

从 cloakbrowser_bridge_info 读取具有能力的 URL。不要放入其中 容器日志或健康检查。连接到像 CDP API 这样的 chromium.connectOverCDP();URL 与 Playwright 不兼容 chromium.connect() 或当前的 Open WebUI 流程。

--cdp-advertised-scheme https 将已发布的 URL 更改为 https/wss,但该 桥不为托管的 CDP 提供 TLS。请使用运营商拥有的 TLS 终端。 占用外部网络命名空间中相同的广告端口,保留 Host/Origin,并一对一转发到明文桥接监听器。该 bridge-to-Chromium 跳转也保持明文回环流量。

GeoIP 代理匹配

Docker 使用与 npm 相同的代理和 GeoIP 环境变量。当区域 QA 需要 CloakBrowser 的时区、语言和 区域设置指纹以遵循配置的代理位置时,请启用 GeoIP 代理匹配:

docker run --rm -i \
  -e PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
  -e CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

对于需要身份验证的代理,请将凭据嵌入代理 URL 中,并对用户名或密码中的特殊字符进行百分比编码。

受支持的 CloakBrowser 二进制文件使用原生 URL 内联代理身份验证;较旧的二进制 文件会回退到 Playwright 代理对象。

当容器运行 Streamable HTTP 时,客户端还可以通过 initialize 元数据,为每个 MCP 会话选择不同的 代理。请参阅 GeoIP 代理匹配,了解运行时代理元数据、 多区域用例及限制。

默认值

Variable Default
PLAYWRIGHT_MCP_BROWSER_ENGINE cloak
PLAYWRIGHT_MCP_HEADLESS true
PLAYWRIGHT_MCP_OUTPUT_DIR /data
PLAYWRIGHT_MCP_USER_DATA_DIR unset
CLOAK_PLAYWRIGHT_MCP_TRANSPORT stdio
CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL http
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST 127.0.0.1
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT 3000
CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT /mcp
CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN unset
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKEND memory
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS 3600000
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAX 32
CLOAK_PLAYWRIGHT_MCP_LOG_LEVEL info
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH false
CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS unset
CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS unset
CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK true
CLOAK_PLAYWRIGHT_MCP_STEALTH_ARGS true
CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX true

MCP 客户端配置

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/tmp/cloakbrowser-artifacts:/data",
        "swimmwatch/cloakbrowser-mcp:latest"
      ]
    }
  }
}

本地构建

npm run docker:build
npm run docker:smoke

该 Dockerfile 使用已锁定的官方 Playwright MCP 镜像作为运行时基础镜像,在构建过程中应用可用的 Debian 安全更新,从运行时镜像中移除未使用的全局 npm 有效载荷,并在 /opt/cloakbrowser-mcp下安装桥接服务。

CI 会在合并更改前使用 Trivy 扫描 Docker 镜像。发布工作流会发布 SBOM 和溯源证明,并包含源代码、修订版、版本、许可证、基础镜像名称及其摘要的 OCI 标签。

更多实用路径

要在 upstream Playwright MCP 和本包之间选择,请查看对比。快速任务请使用操作示例:持久配置文件、扩展、reverse proxy、区域 QA、Claude Desktop、Codex CLI 和 CI 冒烟测试。