CloakBrowser

环境要求

• Python 环境，可用 pip 安装 PyPI 包
• Node.js 环境（使用 JavaScript/Node.js 版本时需要）
• Linux 服务器或容器需额外安装 emoji/CJK 字体包
• 使用官方镜像时需要 Docker 与 Docker Compose
• 需要 Playwright 系统依赖（不要装 Playwright 自带 chromium）

安装与启动步骤

1. 1安装 Python 包

   通过 PyPI 安装 cloakbrowser，安装后即可用其 API 启动隐身 Chromium。

   pip install cloakbrowser

   复制

2. 2安装 Node.js 包

   如果项目是 JavaScript/Node.js 技术栈，改用 npm 安装同名包。

   npm install cloakbrowser

   复制

3. 3装 Playwright 系统依赖

   不要执行 playwright install chromium，CloakBrowser 自带浏览器二进制，只需系统依赖。

   playwright install-deps chromium

   复制

4. 4Linux 装基础字体

   Docker、云主机等精简 Linux 缺少 emoji/CJK 字体，会导致 canvas 指纹哈希异常。

   sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf

   复制

5. 5装 Windows 字体

   Linux 默认伪装 Windows，需从真实 Windows 机器复制字体，否则字体指纹会暴露。

   mkdir -p ~/.local/share/fonts/windows
   cp -r /path/to/windows/Fonts/. ~/.local/share/fonts/windows/
   fc-cache -f

   复制

6. 6预下载浏览器二进制

   提前下载可避免首次运行时等待，也适合在 Docker 构建阶段执行。

   ensure_binary()

   复制

7. 7Docker Compose 启动

   官方镜像已含免费二进制，写入 compose 文件后启动服务，默认监听 9222 端口。

   services:
     cloakbrowser:
       image: cloakhq/cloakbrowser
       command: cloakserve
       restart: unless-stopped
       ports:
         - "127.0.0.1:9222:9222"
       healthcheck:
         test: ["CMD", "curl", "-f", "http://localhost:9222/json/version"]
         interval: 30s
         timeout: 5s
         retries: 3
         start_period: 10s

   复制

关键配置

如何确认成功

执行 curl -f http://localhost:9222/json/version 返回版本信息；或调用 binary_info() 看到 installed 为 True。

常见问题

注意事项

• 官方 Docker 镜像 cloakhq/cloakbrowser 已预装基础 emoji/CJK 字体，但仍需自行提供 Windows 字体。
• 官方下载路径的签名校验是强制的，只有自定义 CLOAKBROWSER_DOWNLOAD_URL 时才可通过 CLOAKBROWSER_SKIP_CHECKSUM 跳过校验。
• --disable-http2 只对确实需要的站点使用，优先考虑 SOCKS5 代理；多数站点 HTTP/2 可正常工作。
• 该工具可能违反目标网站服务条款，请自行评估合规与法律风险。