CloakBrowser 完整部署教程

根据仓库内容，CloakBrowser 是一个基于 Chromium 源码级修改的指纹伪装浏览器，能够通过各类反机器人检测。以下是详细的部署和使用指南。

一、快速开始

1. 环境要求

  • 操作系统：Linux (x86_64/ARM64)、macOS (Intel/Apple Silicon)、Windows (x86_64)
  • Python：Python 3.7+ 或 Node.js 14+
  • 磁盘空间：约 200MB (二进制文件)

2. 安装方式

Python 安装

1
2
3
4
5
# 基础安装
pip install cloakbrowser

# 安装 GeoIP 支持（推荐）
pip install 'cloakbrowser[geoip]'

Node.js 安装

1
2
3
4
5
# Playwright 版本（推荐）
npm install cloakbrowser playwright-core

# Puppeteer 版本
npm install cloakbrowser puppeteer-core

.NET 安装

1
dotnet add package CloakBrowser

3. 首次运行与登录

首次启动时会自动下载约200MB的Chromium二进制文件。

1
2
3
4
5
6
7
8
# 获取免费密钥（GitHub 登录）
python -m cloakbrowser login

# 或直接设置密钥
export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx

# 预下载二进制文件
python -m cloakbrowser install

二、基本使用

Python 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from cloakbrowser import launch

# 基本启动（无头模式）
browser = launch()

# 显示浏览器窗口
browser = launch(headless=False)

# 启用人类行为模拟
browser = launch(humanize=True)

page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

JavaScript/Node.js 示例

1
2
3
4
5
6
7
8
9
10
11
12
import { launch } from 'cloakbrowser';

// Playwright 版本
const browser = await launch({
    headless: false,
    humanize: true
});

const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

三、高级配置

1. 代理与指纹伪装（反检测核心配置）

1
2
3
4
5
6
7
8
9
10
11
browser = launch(
    proxy="http://user:pass@residential-proxy:port",  # 住宅代理
    geoip=True,        # 自动匹配时区和地区
    headless=False,    # 有头模式（反检测推荐）
    humanize=True,     # 人类行为模拟
    args=[
        "--fingerprint=12345",           # 固定指纹种子
        "--fingerprint-noise=false",     # 关闭噪声注入（避免指纹不一致）
        "--fingerprint-platform=windows" # 伪装为Windows平台
    ]
)

2. 持久化配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
from cloakbrowser import launch_persistent_context

# 创建/加载持久化配置
ctx = launch_persistent_context(
    "./my-profile",          # 配置目录
    headless=False,
    proxy="http://proxy:8080",
    extension_paths=["./my-extension"]  # 加载Chrome扩展
)

page = ctx.new_page()
page.goto("https://example.com")
ctx.close()  # 自动保存cookies和localStorage

3. 异步启动

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import asyncio
from cloakbrowser import launch_async

async def main():
    browser = await launch_async(
        headless=False,
        humanize=True,
        geoip=True
    )
    page = await browser.new_page()
    await page.goto("https://example.com")
    await browser.close()

asyncio.run(main())

四、部署场景

1. Docker 部署（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 快速测试
docker run --rm cloakhq/cloakbrowser cloaktest

# 交互式运行脚本
docker run --rm -v ./my_script.py:/app/my_script.py cloakhq/cloakbrowser python my_script.py

# CDP 服务模式（远程调试）
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser cloakserve

# 带代理和人类行为
docker run --rm cloakhq/cloakbrowser python -c "
from cloakbrowser import launch
browser = launch(proxy='http://user:pass@proxy:8080', humanize=True, headless=False)
page = browser.new_page()
page.goto('https://example.com')
print(page.title())
browser.close()
"

2. Docker Compose

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
services:
  cloakbrowser:
    image: cloakhq/cloakbrowser
    command: cloakserve
    restart: unless-stopped
    ports:
      - "127.0.0.1:9222:9222"
    environment:
      - CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx
      - CLOAKBROWSER_FETCH_WIDEVINE=1  # 启用Widevine DRM（可选）
    volumes:
      - ./profile:/profile  # 持久化配置
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9222/json/version"]
      interval: 30s
      timeout: 5s
      retries: 3

3. 自定义Docker镜像

1
2
3
FROM cloakhq/cloakbrowser
COPY your_script.py /app/
CMD ["python", "your_script.py"]

4. AWS Lambda 部署

参考仓库中的 aws_lambda/ 目录，使用容器镜像部署。

五、环境变量配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 许可证密钥
export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx

# 二进制文件缓存目录（默认 ~/.cloakbrowser）
export CLOAKBROWSER_CACHE_DIR=/path/to/cache

# 使用本地二进制（跳过下载）
export CLOAKBROWSER_BINARY_PATH=/path/to/chrome

# 固定Chromium版本
export CLOAKBROWSER_VERSION=146.0.7680.177.5

# 预览通道
export CLOAKBROWSER_RELEASE_CHANNEL=preview

# 禁用自动更新
export CLOAKBROWSER_AUTO_UPDATE=false

# GeoIP超时时间（秒）
export CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS=10

六、命令行工具

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 登录获取免费密钥
python -m cloakbrowser login

# 退出（移除密钥）
python -m cloakbrowser logout

# 下载二进制文件
python -m cloakbrowser install

# 诊断信息
python -m cloakbrowser info
python -m cloakbrowser info --quick  # 快速模式
python -m cloakbrowser info --json   # JSON输出

# 检查更新
python -m cloakbrowser update

# 清除缓存
python -m cloakbrowser clear-cache

七、测试验证

运行内置测试

1
2
3
4
5
6
7
8
9
# Python
python -c "
from cloakbrowser import launch
browser = launch(headless=False, humanize=True)
page = browser.new_page()
page.goto('https://fingerprintjs.com/demo/')
print('FingerprintJS 测试完成')
browser.close()
"

测试反检测能力

1
2
3
# 使用示例脚本
python examples/stealth_test.py
python examples/recaptcha_score.py

八、常见问题解决

1. macOS 首次运行被阻止

1
xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app

2. Linux 缺少系统依赖

1
2
3
4
5
6
7
8
# 安装字体（反检测必需）
sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf

# Windows字体（强烈推荐，需从真实Windows复制）
mkdir -p ~/.local/share/fonts/windows
cp -r /path/to/windows/Fonts/. ~/.local/share/fonts/windows/
fc-cache -f

3. 虚拟显示（无头服务器）

1
2
3
4
5
6
# 安装Xvfb
sudo apt install xvfb

# 启动虚拟显示
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

4. 检测到 WebDriver 标志

  • 使用 Playwright 而非 Puppeteer（Puppeteer 易被检测）
  • 确保 headless=False（有头模式）
  • 使用 humanize=True 和 geoip=True

5. reCAPTCHA v3 分数低

1
2
3
4
5
6
7
8
9
10
11
# 避免使用 CDP 命令
import time
# 错误：page.wait_for_timeout(3000)
# 正确：使用原生sleep
time.sleep(3)

# 使用真实键盘输入
page.type("#email", "user@example.com", delay=50)  # 而非 fill()

# 固定指纹种子
browser = launch(args=["--fingerprint=12345"])

九、性能与资源

  • 空闲内存：约190MB
  • 3个标签页：约280MB
  • 每个额外标签页：约30MB
  • 二进制大小：约200MB

十、安全注意事项

  1. CDP端口（如9222）不要暴露到公网
  2. 密钥通过环境变量或配置文件管理，避免硬编码
  3. 遵守目标网站的使用条款和法律法规
  4. 商业用途请购买Pro许可证

参考链接

按照上述步骤，您应该能够在本地、Docker或服务器环境中成功部署和使用CloakBrowser。核心在于使用住宅代理 + geoip + 有头模式 + humanize的组合配置，以获得最佳的反检测效果。