Docker¶
所发布的图片展示了可重复使用 MCP 的推荐运行时。
如需为已运行的 HTTP 服务器配置 TLS 和身份验证的简短部署步骤,请参阅Docker Streamable HTTP 反向代理示例。
运行¶
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"
]
}
}
}
本地构建¶
该 Dockerfile 使用已锁定的官方 Playwright MCP 镜像作为运行时基础镜像,在构建过程中应用可用的 Debian 安全更新,从运行时镜像中移除未使用的全局 npm 有效载荷,并在 /opt/cloakbrowser-mcp下安装桥接服务。
CI 会在合并更改前使用 Trivy 扫描 Docker 镜像。发布工作流会发布 SBOM 和溯源证明,并包含源代码、修订版、版本、许可证、基础镜像名称及其摘要的 OCI 标签。
更多实用路径¶
要在 upstream Playwright MCP 和本包之间选择,请查看对比。快速任务请使用操作示例:持久配置文件、扩展、reverse proxy、区域 QA、Claude Desktop、Codex CLI 和 CI 冒烟测试。