cloakhq--cloakbrowser
wehub-resource-sync
1419 行
65 KiB
Markdown
1419 行
65 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/CloakHQ/CloakBrowser) · [上游 README](https://github.com/CloakHQ/CloakBrowser/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/cqkp6fG.png" width="500" alt="CloakBrowser">
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://pypi.org/project/cloakbrowser/"><img src="https://img.shields.io/pypi/v/cloakbrowser" alt="PyPI"></a>
|
||
<a href="https://www.npmjs.com/package/cloakbrowser"><img src="https://img.shields.io/npm/v/cloakbrowser" alt="npm"></a>
|
||
<a href="LICENSE"><img src="https://img.shields.io/github/license/cloakhq/cloakbrowser?v=1" alt="License"></a>
|
||
<a href="https://github.com/CloakHQ/CloakBrowser"><img src="https://img.shields.io/github/last-commit/cloakhq/cloakbrowser" alt="Last Commit"></a>
|
||
<br>
|
||
<a href="https://github.com/CloakHQ/CloakBrowser"><img src="https://img.shields.io/github/stars/cloakhq/cloakbrowser" alt="Stars"></a>
|
||
<a href="https://pypi.org/project/cloakbrowser/"><img src="https://img.shields.io/pepy/dt/cloakbrowser?label=pypi&logo=pypi&logoColor=white" alt="PyPI Downloads"></a>
|
||
<a href="https://www.npmjs.com/package/cloakbrowser"><img src="https://img.shields.io/npm/dt/cloakbrowser?label=npm&logo=npm&logoColor=white" alt="npm Downloads"></a>
|
||
<a href="https://hub.docker.com/r/cloakhq/cloakbrowser"><img src="https://img.shields.io/docker/pulls/cloakhq/cloakbrowser?label=docker&logo=docker&logoColor=white" alt="Docker Pulls"></a>
|
||
</p>
|
||
|
||
<br>
|
||
|
||
<h3 align="center">可绕过各类机器人检测测试的隐身 Chromium。</h3>
|
||
|
||
<table><tr><td>
|
||
不是打过补丁的配置。也不是 JS 注入。而是在 C++ 源码层修改指纹的真实 Chromium 二进制。反机器人系统会把它判为普通浏览器——因为它<em>本来就是</em>普通浏览器。
|
||
</td></tr></table>
|
||
|
||
<br>
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/IvB0It7.gif" width="600" alt="Cloudflare Turnstile — 3 Tests Passing">
|
||
<br><em>Cloudflare Turnstile — 3 项线上测试通过（headed 模式，macOS）</em>
|
||
</p>
|
||
|
||
<br>
|
||
|
||
<p align="center">
|
||
适用于 Python 和 JavaScript 的即插即用 Playwright/Puppeteer 替代方案。<br>
|
||
相同 API、相同代码——只需替换 import。<strong>3 行代码，30 秒解除拦截。</strong>
|
||
</p>
|
||
|
||
- **66 项源码级 C++ 补丁** — canvas、WebGL、audio、fonts、GPU、screen、WebRTC、网络时序、自动化信号、CDP 输入行为
|
||
- **`humanize=True`** — 类人鼠标曲线、键盘时序与滚动模式。一个开关即可通过行为检测
|
||
- **Pro：reCAPTCHA v3 得分 0.9** — 人类水平，经服务端验证
|
||
- **通过 Cloudflare Turnstile**、FingerprintJS、BrowserScan — 已在 30+ 个检测站点上测试
|
||
- **自动下载正确二进制** — 按许可证自动选择免费版或 Pro
|
||
- **`pip install cloakbrowser`** 或 **`npm install cloakbrowser`** — 二进制自动下载，零配置
|
||
- **开源封装** — 免费 v146 二进制，Pro 提供最新构建
|
||
|
||
**立即试用** — 无需安装：
|
||
|
||
```bash
|
||
docker run --rm cloakhq/cloakbrowser cloaktest
|
||
```
|
||
|
||
**Python：**
|
||
|
||
```python
|
||
from cloakbrowser import launch
|
||
|
||
browser = launch()
|
||
page = browser.new_page()
|
||
page.goto("https://example.com")
|
||
browser.close()
|
||
```
|
||
|
||
**JavaScript（Playwright）：**
|
||
|
||
```javascript
|
||
import { launch } from 'cloakbrowser';
|
||
|
||
const browser = await launch();
|
||
const page = await browser.newPage();
|
||
await page.goto('https://example.com');
|
||
await browser.close();
|
||
```
|
||
|
||
也支持 Puppeteer：`import { launch } from 'cloakbrowser/puppeteer'`（[详情](#puppeteer)）
|
||
|
||
**对于带有反机器人保护的站点**，请添加住宅代理及以下标志：
|
||
|
||
```python
|
||
browser = launch(
|
||
proxy="http://user:pass@residential-proxy:port", # residential IP, not datacenter
|
||
geoip=True, # match timezone + locale to proxy IP
|
||
headless=False, # some sites detect headless even with C++ patches
|
||
humanize=True, # human-like mouse, keyboard, scroll
|
||
)
|
||
```
|
||
|
||
```javascript
|
||
const browser = await launch({
|
||
proxy: 'http://user:pass@residential-proxy:port',
|
||
geoip: true,
|
||
headless: false,
|
||
humanize: true,
|
||
});
|
||
```
|
||
|
||
特定站点问题（FingerprintJS、Kasada、reCAPTCHA）请参见 [故障排除](#troubleshooting)。
|
||
|
||
## 安装
|
||
|
||
**Python：**
|
||
|
||
```bash
|
||
pip install cloakbrowser
|
||
```
|
||
|
||
**JavaScript / Node.js：**
|
||
|
||
```bash
|
||
# With Playwright
|
||
npm install cloakbrowser playwright-core
|
||
|
||
# With Puppeteer
|
||
npm install cloakbrowser puppeteer-core
|
||
```
|
||
|
||
**.NET / C#：**
|
||
|
||
```bash
|
||
dotnet add package CloakBrowser
|
||
```
|
||
|
||
> 基于 Microsoft.Playwright 的社区维护 .NET 客户端。完整 API 见 [`dotnet/README.md`](dotnet/README.md)。
|
||
|
||
---
|
||
|
||
首次运行时，隐身 Chromium 二进制会自动下载（约 200MB，本地缓存）。
|
||
|
||
**可选：** 根据代理 IP 自动检测时区/语言区域：
|
||
|
||
```bash
|
||
pip install cloakbrowser[geoip]
|
||
```
|
||
|
||
**从 Playwright 迁移？** 只需改一行：
|
||
|
||
```diff
|
||
- from playwright.sync_api import sync_playwright
|
||
- pw = sync_playwright().start()
|
||
- browser = pw.chromium.launch()
|
||
+ from cloakbrowser import launch
|
||
+ browser = launch()
|
||
|
||
page = browser.new_page()
|
||
page.goto("https://example.com")
|
||
# ... rest of your code works unchanged
|
||
```
|
||
|
||
> ⭐ **Star** 以示支持 — **[关注 releases](https://github.com/CloakHQ/CloakBrowser/subscription)** 以便在有新构建时收到通知。
|
||
|
||
---
|
||
|
||
## 最新：v0.4.10 — 66 项源码级隐身补丁（Chromium 148.0.7778.215.5 — Windows + Linux；macOS 随后跟进）
|
||
|
||
- **CloakBrowser Pro** — 最新二进制（Chromium 148.0.7778.215.5，66 项源码级补丁）已面向 Pro 订阅用户在 **Windows 和 Linux** 上提供（macOS 为 148.0.7778.215.3，下一构建将跟进）。设置 `license_key`（JS 中为 `licenseKey`）或 `CLOAKBROWSER_LICENSE_KEY` 环境变量后，封装会自动拉取最新构建。参见 [CloakBrowser Pro](#cloakbrowser-pro)
|
||
- **.NET 8 / C# 客户端** — CloakBrowser 现已作为 NuGet 包发布（`CloakBrowser`），与 Python 和 JS 封装对齐。
|
||
- **66 项指纹补丁** — 改进 Linux 与 Windows 的渲染一致性，校正 GPU/显示/图形参数以匹配原版 Chrome 配置文件
|
||
- **Windows 原生 GPU 透传** — 真实硬件值直接透传而非伪造，行为与真实浏览器一致
|
||
- **HTTP 代理内联凭据** — 网络层新增对带内联认证代理的支持
|
||
- **`extension_paths`** — 在所有启动函数中加载 Chrome 扩展
|
||
- **Humanize 可操作性** — 在拟人化操作前自动等待元素可见、可用且稳定
|
||
- **按次调用的 `human_config`** — 可在单次方法调用上覆盖 humanize 设置
|
||
- **可组合 JS 辅助函数** — `buildLaunchOptions()` 与 `humanizeBrowser()`，用于自定义 Playwright 集成
|
||
- **原生 SOCKS5 代理** — `proxy="socks5://user:pass@host:port"` 可在所有启动函数中直接使用，Python + JS 均支持。QUIC/HTTP3 通过 SOCKS5 的 UDP ASSOCIATE 隧道传输
|
||
- **代理特征清除** — DNS/连接/SSL 时序归零，剥离代理缓存头，移除 Proxy-Connection 头泄露
|
||
- **升级至 Chromium 146** — 将全部补丁从 145.0.7632.x 变基至 146.0.7680.177
|
||
- **WebRTC IP 伪造** — `--fingerprint-webrtc-ip=auto` 解析代理出口 IP 并伪造 WebRTC ICE 候选。使用 `geoip=True` 时自动注入（无额外网络请求）
|
||
- **`humanize=True`** — 一个开关让所有鼠标、键盘与滚动交互表现得像真实用户。贝塞尔曲线、逐字符输入、逼真滚动模式
|
||
- **零标志即隐身** — 二进制启动时自动生成随机指纹种子。无需配置
|
||
- **根据代理 IP 设置时区与语言区域** — `launch(proxy="...", geoip=True)` 自动检测时区与语言区域
|
||
- **持久化配置文件** — `launch_persistent_context()` 可在会话间保留 cookies 与 localStorage，绕过无痕模式检测
|
||
|
||
详情见完整 [CHANGELOG.md](CHANGELOG.md)。
|
||
|
||
## 为什么选择 CloakBrowser？
|
||
|
||
- **配置级补丁会失效** — `playwright-stealth`、`undetected-chromedriver` 和 `puppeteer-extra` 通过注入 JavaScript 或调整标志实现。每次 Chrome 更新都会破坏它们。反机器人系统会直接检测这些补丁本身。
|
||
- **CloakBrowser 修改 Chromium 源码** — 指纹在 C++ 层被修改并编译进二进制。检测站点看到的是真实浏览器，因为它*本来就是*真实浏览器。
|
||
- **源码级隐身** — C++ 补丁在二进制层处理指纹（GPU、screen、UA、硬件上报）。无 JavaScript 注入，无配置级技巧。多数隐身工具仅在表层打补丁。
|
||
- **行为处处一致** — 在本地、Docker 与 VPS 上表现相同。无需针对环境的补丁或配置。
|
||
- **适用于 AI agent 与自动化框架** — 可为 browser-use、Crawl4AI、Scrapling、Stagehand、LangChain、Selenium 等提供即插即用隐身能力。参见 [集成](#framework-integrations)。
|
||
|
||
CloakBrowser 不会解决 CAPTCHA——它会阻止 CAPTCHA 出现。无需 CAPTCHA 求解服务，也不内置代理轮换——请自备代理，使用你已熟悉的 Playwright API。
|
||
|
||
## CloakBrowser Pro
|
||
|
||
封装层（Python + JS）采用 MIT 许可，永久免费。二进制文件采用延迟免费发布模式：
|
||
|
||
- **Free（v146）** — 上一版二进制文件，见 [GitHub Releases](https://github.com/CloakHQ/cloakbrowser/releases). 随着检测技术演进，数周内即会过时。
|
||
- **Pro（最新版，Chromium 148.0.7778.215.5）** — 优先获得最新补丁与 Chromium 升级，从而在反机器人系统变化时，让[下方测试结果](#test-results)保持绿色。支持 Linux、Windows 和 macOS（Apple Silicon + Intel）。
|
||
|
||
反机器人检测不断更新，旧版二进制文件会迅速退化。
|
||
Pro 让你始终使用针对最新检测积极维护的构建版本。
|
||
|
||
若 CloakBrowser 用于生产级抓取、QA、监控或自动化，而陈旧的浏览器指纹会浪费你的时间或导致运行被拦截，请使用 Pro。
|
||
|
||
**新功能：免费试用最新 Pro 二进制文件（Chromium 148）7 天** — 看看它在你目标站点上的表现。随时可取消。
|
||
|
||
使用许可证密钥激活（环境变量、`license_key=` 参数或 `~/.cloakbrowser/license.key`）：
|
||
|
||
```bash
|
||
export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx
|
||
```
|
||
|
||
Pro 方案与免费试用 → **[cloakbrowser.dev](https://cloakbrowser.dev)**
|
||
|
||
## 测试结果
|
||
|
||
所有测试均针对实时检测服务验证。除非另有说明，下方结果为最新 Pro/当前构建版本。最近测试：2026 年 7 月（Chromium 148）。
|
||
|
||
| 检测服务 | 原版 Playwright | CloakBrowser | 备注 |
|
||
|---|---|---|---|
|
||
| **reCAPTCHA v3** | 0.1（机器人） | **0.9**（人类） | Pro/当前构建；服务端已验证 |
|
||
| **Cloudflare Turnstile**（非交互式） | FAIL | **PASS** | 自动解决 |
|
||
| **Cloudflare Turnstile**（托管式） | FAIL | **PASS** | 单击一次 |
|
||
| **ShieldSquare** | BLOCKED | **PASS** | 生产站点 |
|
||
| **FingerprintJS** 机器人检测 | DETECTED | **PASS** | Pro/当前构建；demo.fingerprint.com |
|
||
| **BrowserScan** 机器人检测 | DETECTED | **NORMAL**（4/4） | browserscan.net |
|
||
| **bot.incolumitas.com** | 13 fails | **1 fail** | 仅 WEBDRIVER 规范 |
|
||
| **deviceandbrowserinfo.com** | 6 true flags | **0 true flags** | `isBot: false` |
|
||
| `navigator.webdriver` | `true` | **`false`** | 源码级补丁 |
|
||
| `navigator.plugins.length` | 0 | **5** | 真实插件列表 |
|
||
| `window.chrome` | `undefined` | **`object`** | 与真实 Chrome 一致 |
|
||
| UA string | `HeadlessChrome` | **`Chrome/146.0.0.0`** | 无 headless 泄露 |
|
||
| CDP detection | Detected | **Not detected** | `isAutomatedWithCDP: false` |
|
||
| TLS fingerprint | Mismatch | **Identical to Chrome** | ja3n/ja4/akamai 匹配 |
|
||
| | | **已在 30+ 检测站点上测试** | |
|
||
|
||
### 证明
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/hvIQyMv.png" width="600" alt="reCAPTCHA v3 — Score 0.9">
|
||
<br><em>Pro/最新构建：reCAPTCHA v3 得分 0.9 — 服务端已验证（人类级别）</em>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/qMIRfhq.png" width="600" alt="Cloudflare Turnstile — Success">
|
||
<br><em>Cloudflare Turnstile 非交互式挑战 — 自动解决</em>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/PRsw6rT.png" width="600" alt="BrowserScan — Normal">
|
||
<br><em>BrowserScan 机器人检测 — NORMAL（4/4 项检查通过）</em>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/9n2C7tu.png" width="600" alt="FingerprintJS — Passed">
|
||
<br><em>Pro/最新构建：FingerprintJS 网页抓取演示 — 数据正常返回，未被拦截</em>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://i.imgur.com/srCcFtK.png" width="600" alt="deviceandbrowserinfo.com — You are human!">
|
||
<br><em>deviceandbrowserinfo.com 行为机器人检测 — 在 humanize=True 下显示 "You are human!"（24/24 项信号通过）</em>
|
||
</p>
|
||
|
||
## 对比
|
||
|
||
| 功能 | Playwright | playwright-stealth | undetected-chromedriver | Camoufox | CloakBrowser |
|
||
|---|---|---|---|---|---|
|
||
| reCAPTCHA v3 得分（Pro/当前） | 0.1 | 0.3-0.5 | 0.3-0.7 | 0.7-0.9 | **0.9** |
|
||
| Cloudflare Turnstile | Fail | Sometimes | Sometimes | Pass | **Pass** |
|
||
| 补丁层级 | None | JS injection | Config patches | C++ (Firefox) | **C++ (Chromium)** |
|
||
| 能否经受 Chrome 更新 | N/A | Breaks often | Breaks often | Yes | **Yes** |
|
||
| 维护状态 | Yes | Stale | Stale | Unstable | **Active** |
|
||
| 浏览器引擎 | Chromium | Chromium | Chrome | Firefox | **Chromium** |
|
||
| Playwright API | Native | Native | No (Selenium) | No | **Native** |
|
||
|
||
## 工作原理
|
||
|
||
CloakBrowser 是围绕自定义构建的 Chromium 二进制文件的轻量封装层（Python + JavaScript）：
|
||
|
||
1. **你安装** → `pip install cloakbrowser` 或 `npm install cloakbrowser`
|
||
2. **首次启动** → 二进制文件自动为你的平台下载（Chromium 146）
|
||
3. **每次启动** → Playwright 或 Puppeteer 使用我们的二进制文件 + 隐身参数启动
|
||
4. **你编写代码** → 标准 Playwright/Puppeteer API，无需学习新接口
|
||
|
||
该二进制文件包含 66 项源码级补丁，覆盖 canvas、WebGL、audio、fonts、GPU、screen properties、WebRTC、network timing、hardware reporting、automation signal removal，以及模拟 CDP input behavior。
|
||
|
||
这些补丁编译进 Chromium 二进制文件——并非通过 JavaScript 注入，也不是通过启动参数设置。
|
||
|
||
二进制下载在解压前会针对已发布的校验和上的固定 Ed25519 签名进行验证，从而确认下载来源真实（确为我们发布）且未被篡改。被入侵的镜像无法提供被篡改或降级的二进制文件。
|
||
|
||
## API
|
||
|
||
### `launch()`
|
||
|
||
```python
|
||
from cloakbrowser import launch
|
||
|
||
# Basic — headless, default stealth config
|
||
browser = launch()
|
||
|
||
# Headed mode (see the browser window)
|
||
browser = launch(headless=False)
|
||
|
||
# Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
|
||
browser = launch(license_key="cb_xxxxxxxx")
|
||
|
||
# With proxy (HTTP or SOCKS5)
|
||
browser = launch(proxy="http://user:pass@proxy:8080")
|
||
browser = launch(proxy="socks5://user:pass@proxy:1080")
|
||
|
||
# With proxy dict (bypass, separate auth fields)
|
||
browser = launch(proxy={"server": "http://proxy:8080", "bypass": ".google.com", "username": "user", "password": "pass"})
|
||
|
||
# With extra Chrome args
|
||
browser = launch(args=["--disable-gpu"])
|
||
|
||
# With timezone and locale (sets binary flags — no detectable CDP emulation)
|
||
browser = launch(timezone="America/New_York", locale="en-US")
|
||
|
||
# Auto-detect timezone/locale from proxy IP (requires: pip install cloakbrowser[geoip])
|
||
# Also auto-injects --fingerprint-webrtc-ip to prevent WebRTC IP leaks (no extra cost)
|
||
# Note: makes HTTP calls through your proxy to resolve exit IP (ipify.org, checkip.amazonaws.com)
|
||
browser = launch(proxy="http://proxy:8080", geoip=True)
|
||
|
||
# Explicit timezone/locale always win over auto-detection
|
||
browser = launch(proxy="http://proxy:8080", geoip=True, timezone="Europe/London")
|
||
|
||
# WebRTC IP spoofing only (no geoip dep needed — resolves exit IP via HTTP call through proxy)
|
||
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=auto"])
|
||
|
||
# Explicit WebRTC IP (no network call)
|
||
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=1.2.3.4"])
|
||
|
||
# Human-like mouse, keyboard, and scroll behavior
|
||
browser = launch(humanize=True)
|
||
|
||
# With slower, more deliberate movements
|
||
browser = launch(humanize=True, human_preset="careful")
|
||
|
||
# Without default stealth args (bring your own fingerprint flags)
|
||
browser = launch(stealth_args=False, args=["--fingerprint=12345"])
|
||
```
|
||
|
||
返回标准 Playwright `Browser` 对象。所有 Playwright 方法均可使用：`new_page()`、`new_context()`、`close()` 等。
|
||
|
||
### `launch_async()`
|
||
|
||
```python
|
||
import asyncio
|
||
from cloakbrowser import launch_async
|
||
|
||
async def main():
|
||
browser = await launch_async()
|
||
page = await browser.new_page()
|
||
await page.goto("https://example.com")
|
||
print(await page.title())
|
||
await browser.close()
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
### `launch_context()`
|
||
|
||
便捷函数，一次调用即可创建 browser + context，并设置 user agent、viewport、locale 和 timezone：
|
||
|
||
```python
|
||
from cloakbrowser import launch_context
|
||
|
||
context = launch_context(
|
||
user_agent="Custom UA",
|
||
viewport={"width": 1920, "height": 1080},
|
||
locale="en-US",
|
||
timezone="America/New_York",
|
||
)
|
||
page = context.new_page()
|
||
page.goto("https://protected-site.com")
|
||
context.close()
|
||
```
|
||
|
||
额外的 kwargs 会转发给 Playwright 的 `browser.new_context()`——可用于 `storage_state`、`permissions`、`extra_http_headers` 等场景，且无需持久化 profile 文件夹：
|
||
|
||
```python
|
||
from cloakbrowser import launch_context
|
||
|
||
# Restore a saved session (cookies, localStorage) from a JSON file
|
||
context = launch_context(storage_state="state.json")
|
||
page = context.new_page()
|
||
page.goto("https://example.com")
|
||
# Save state back for next run
|
||
context.storage_state(path="state.json")
|
||
context.close()
|
||
```
|
||
|
||
### `launch_context_async()`
|
||
|
||
`launch_context()` 的异步版本。签名相同，并同样转发 kwargs：
|
||
|
||
```python
|
||
import asyncio
|
||
from cloakbrowser import launch_context_async
|
||
|
||
async def main():
|
||
ctx = await launch_context_async(storage_state="state.json")
|
||
page = await ctx.new_page()
|
||
await page.goto("https://example.com")
|
||
await ctx.storage_state(path="state.json")
|
||
await ctx.close()
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
### `launch_persistent_context()`
|
||
|
||
与 `launch_context()` 相同，但使用持久化用户 profile。Cookies、localStorage 和缓存在多次会话之间保持。
|
||
|
||
在以下场景中使用：
|
||
|
||
- **保持登录状态**：多次运行之间 cookies/会话不丢失
|
||
- **绕过无痕模式检测**：部分站点会标记空的临时 profile
|
||
- **加载 Chrome 扩展**：扩展只能从真实的用户数据目录加载
|
||
- **构建自然的浏览历史**：缓存字体、service workers、IndexedDB 会随时间累积，使 profile 看起来更真实
|
||
- **播放受 DRM 保护的视频**（Widevine）——配合 sideload 的 CDM，封装层会在首次启动时启用 Widevine（参见 [Widevine / DRM](#widevine--drm)）
|
||
|
||
```python
|
||
from cloakbrowser import launch_persistent_context
|
||
|
||
# First run — creates the profile
|
||
ctx = launch_persistent_context("./my-profile", headless=False)
|
||
page = ctx.new_page()
|
||
page.goto("https://protected-site.com")
|
||
ctx.close() # profile saved
|
||
|
||
# Next run — cookies, localStorage restored automatically
|
||
ctx = launch_persistent_context("./my-profile", headless=False)
|
||
|
||
# Load Chrome extensions
|
||
ctx = launch_persistent_context(
|
||
"./my-profile",
|
||
headless=False,
|
||
extension_paths=["./my-extension"],
|
||
)
|
||
```
|
||
|
||
支持与 `launch_context()` 相同的全部选项：`proxy`、`user_agent`、`viewport`、`locale`、`timezone`、`color_scheme`、`geoip`、`extension_paths`。
|
||
|
||
异步版本：`launch_persistent_context_async()`。
|
||
|
||
**存储配额与无痕模式检测：** 二进制默认会规范化存储配额（同时也会隐藏真实磁盘大小）。通过配额推断隐私/无痕模式的检测器——例如 BrowserScan 的无痕检测（−10%）——会将默认值判为无痕。提高配额以呈现为普通 profile：
|
||
|
||
```python
|
||
ctx = launch_persistent_context("./my-profile", args=["--fingerprint-storage-quota=5000"])
|
||
```
|
||
|
||
### Widevine / DRM
|
||
|
||
该二进制内置 Widevine 支持，但 Widevine CDM 是 Google 的专有组件，我们无法再分发。可通过以下两种方式获取（完整背景见 [#96](https://github.com/CloakHQ/CloakBrowser/issues/96)):
|
||
|
||
**拉取**——无需安装 Chrome；从 Google 组件服务器下载 CDM（仅 Linux x86-64；经 SHA-256 + CRX3 签名校验）。文件会落到 `~/.cloakbrowser/WidevineCdm`，封装层会自动检测——无需设置环境变量：
|
||
|
||
```bash
|
||
python3 bin/fetch-widevine.py
|
||
```
|
||
|
||
**或从现有 Chrome 安装复制**，放在二进制文件旁边：
|
||
|
||
```bash
|
||
cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm
|
||
```
|
||
|
||
（在 Docker 中，只需传入 `-e CLOAKBROWSER_FETCH_WIDEVINE=1`——入口脚本会自动执行拉取；详见下文 Docker 说明。）
|
||
|
||
CDM 就位后，`launch_persistent_context()` 会在**首次启动**时启用 Widevine——封装层会自动将 CDM 提示文件写入 profile，因此无需手动两次启动的变通方案。这样即可播放受 DRM 保护的视频（例如 Netflix、Spotify Web）。
|
||
|
||
```python
|
||
from cloakbrowser import launch_persistent_context
|
||
|
||
# WidevineCdm sideloaded next to the binary -> Widevine works on first launch
|
||
ctx = launch_persistent_context("./my-profile", headless=False)
|
||
```
|
||
|
||
- **仅 Linux。** Chromium 的 hint-file 机制仅适用于 Linux/ChromeOS。在 Windows 上 CDM 无法初始化（DRM 主机验证），macOS 使用不同目录结构，因此在这些平台上 seeding 无效。
|
||
- **按存在自动启用。** 无需标志——sideload 的 CDM 即表示选择启用。使用 `CLOAKBROWSER_WIDEVINE_CDM=/path/to/WidevineCdm` 指向非默认位置的 CDM，或使用 `CLOAKBROWSER_WIDEVINE=0` 完全禁用 seeding。
|
||
- **Docker——自动拉取（可选）。** 镜像内没有可复制的 Chrome，因此官方镜像可代为拉取 CDM。运行时传入 `-e CLOAKBROWSER_FETCH_WIDEVINE=1`，首次启动时会从 Google 组件服务器（与 Chrome 相同来源）拉取 CDM，并缓存在挂载卷中的 `~/.cloakbrowser/WidevineCdm`，封装层会自动检测——免费版与 Pro 二进制，以及 `docker exec` 脚本均适用。**默认关闭**——除非你主动启用，否则不会发起网络请求——且为尽力而为，拉取失败不会阻止启动。安装前会校验签名与 checksum。裸机 Linux 用户可直接运行同一拉取器：`python3 bin/fetch-widevine.py`（仅 pip 安装可从仓库获取该独立文件）。
|
||
|
||
### CLI
|
||
|
||
预下载二进制、诊断环境，或从命令行管理缓存：
|
||
|
||
```bash
|
||
python -m cloakbrowser install # Download binary with progress output
|
||
python -m cloakbrowser info # Diagnostics: binary that will launch, license tier, env checks
|
||
python -m cloakbrowser update # Check for and download newer binary
|
||
python -m cloakbrowser clear-cache # Remove cached binaries
|
||
```
|
||
|
||
`info` 会报告根据你的许可证实际将启动的二进制，执行快速启动测试（并在 Linux 上标记缺失的系统库），显示许可证层级，并检查字体、GeoIP 及可选依赖。添加 `--quick` 可跳过启动测试，或使用 `--json` 获取机器可读输出。相同命令也可通过 `npx cloakbrowser <command>`（JS）和 `cloakbrowser` CLI（.NET）使用。
|
||
|
||
### 工具函数
|
||
|
||
```python
|
||
from cloakbrowser import binary_info, clear_cache, ensure_binary
|
||
|
||
# Check binary installation status
|
||
print(binary_info())
|
||
# {'version': '146.0.7680.177.5', 'platform': 'linux-x64', 'installed': True, ...}
|
||
|
||
# Force re-download
|
||
clear_cache()
|
||
|
||
# Pre-download binary (e.g., during Docker build)
|
||
ensure_binary()
|
||
```
|
||
|
||
## JavaScript / Node.js API
|
||
|
||
CloakBrowser 提供带完整类型定义的 TypeScript 包。可选择 Playwright 或 Puppeteer——底层使用相同的 stealth 二进制。
|
||
|
||
### Playwright（默认）
|
||
|
||
```javascript
|
||
import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';
|
||
|
||
// Basic
|
||
const browser = await launch();
|
||
|
||
// Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
|
||
const browser = await launch({ licenseKey: 'cb_xxxxxxxx' });
|
||
|
||
// With options
|
||
const browser = await launch({
|
||
headless: false,
|
||
proxy: 'http://user:pass@proxy:8080',
|
||
args: ['--fingerprint=12345'],
|
||
timezone: 'America/New_York',
|
||
locale: 'en-US',
|
||
humanize: true,
|
||
});
|
||
|
||
// Convenience: browser + context in one call
|
||
const context = await launchContext({
|
||
userAgent: 'Custom UA',
|
||
viewport: { width: 1920, height: 1080 },
|
||
locale: 'en-US',
|
||
timezone: 'America/New_York',
|
||
});
|
||
const page = await context.newPage();
|
||
|
||
// Persistent profile — cookies/localStorage survive restarts, avoids incognito detection
|
||
const ctx = await launchPersistentContext({
|
||
userDataDir: './chrome-profile',
|
||
headless: false,
|
||
proxy: 'http://user:pass@proxy:8080',
|
||
});
|
||
```
|
||
|
||
> **注意：** 以上每个示例均为独立片段——不应作为一个代码块整体运行。
|
||
|
||
JS 中可使用全部 Python 选项：`stealthArgs: false` 用于禁用默认值，`geoip: true` 用于根据代理 IP 自动检测时区/区域设置。
|
||
|
||
### Puppeteer
|
||
|
||
> **注意：** 对于使用 reCAPTCHA Enterprise 的站点，建议使用 Playwright 封装。Puppeteer 的 CDP 协议会泄露自动化信号，reCAPTCHA Enterprise 可据此检测，导致间歇性 403 错误。这是 Puppeteer 的已知限制，并非 CloakBrowser 特有。为获得最佳效果，请使用 Playwright。
|
||
|
||
```javascript
|
||
import { launch } from 'cloakbrowser/puppeteer';
|
||
|
||
const browser = await launch({ headless: true });
|
||
const page = await browser.newPage();
|
||
await page.goto('https://example.com');
|
||
await browser.close();
|
||
```
|
||
|
||
### 工具函数（JS）
|
||
|
||
```javascript
|
||
import { ensureBinary, clearCache, binaryInfo } from 'cloakbrowser';
|
||
|
||
// Pre-download binary (e.g., during Docker build)
|
||
await ensureBinary();
|
||
|
||
// Check installation status
|
||
console.log(binaryInfo());
|
||
|
||
// Force re-download
|
||
clearCache();
|
||
```
|
||
|
||
## 人类行为模拟
|
||
|
||
传入 `humanize=True`，可使所有鼠标、键盘和滚动交互与真实用户无法区分。所有 Playwright 调用（`page.click()`、`page.fill()`、`page.type()`、`page.mouse.*`、`page.keyboard.*`、Locator API）和 Puppeteer 调用（`page.click()`、`page.type()`、`page.mouse.*`、`page.keyboard.*`、ElementHandle API）会自动替换为类人化等价操作。无需修改代码。
|
||
|
||
```python
|
||
browser = launch(humanize=True)
|
||
page = browser.new_page()
|
||
page.goto("https://example.com")
|
||
page.locator("#email").fill("user@example.com") # per-character timing, thinking pauses
|
||
page.locator("button[type=submit]").click() # Bézier curve, realistic aim point
|
||
```
|
||
|
||
```javascript
|
||
// Playwright
|
||
import { launch } from 'cloakbrowser';
|
||
const browser = await launch({ humanize: true });
|
||
```
|
||
|
||
```javascript
|
||
// Puppeteer
|
||
import { launch } from 'cloakbrowser/puppeteer';
|
||
const browser = await launch({ humanize: true });
|
||
```
|
||
|
||
**变化对比：**
|
||
|
||
| 交互 | 默认行为 | 使用 `humanize=True` |
|
||
|---|---|---|
|
||
| 鼠标移动 | 瞬间传送 | 带缓动与轻微过冲的 Bézier 曲线 |
|
||
| 点击 | 瞬间完成 | 逼真瞄准点 + 按住时长 |
|
||
| 键盘 | 瞬间填充 | 逐字符节奏、思考停顿、偶发打字错误并自我纠正 |
|
||
| 滚动 | 跳跃式 | 加速 → 匀速 → 减速的微步滚动 |
|
||
| `fill()` | 瞬间设值 | 清空现有内容，逐字符输入 |
|
||
|
||
**预设** — `default`（正常速度）或 `careful`（更慢、更从容，动作之间带有空闲微移动）：
|
||
|
||
```python
|
||
browser = launch(humanize=True, human_preset="careful")
|
||
```
|
||
|
||
```javascript
|
||
const browser = await launch({ humanize: true, humanPreset: 'careful' });
|
||
```
|
||
|
||
**自定义配置** — 可覆盖任意参数：
|
||
|
||
```python
|
||
browser = launch(humanize=True, human_config={
|
||
"mistype_chance": 0.05, # 5% typo rate with self-correction
|
||
"typing_delay": 100, # slower typing (ms per character)
|
||
"idle_between_actions": True, # micro-movements between clicks
|
||
"idle_between_duration": [0.3, 0.8], # idle duration range (seconds)
|
||
})
|
||
```
|
||
|
||
```javascript
|
||
const browser = await launch({
|
||
humanize: true,
|
||
humanConfig: {
|
||
mistype_chance: 0.05,
|
||
typing_delay: 100,
|
||
idle_between_actions: true,
|
||
idle_between_duration: [0.3, 0.8],
|
||
}
|
||
});
|
||
```
|
||
|
||
若某次调用需要原始速度，可通过 `page._original` 访问未经补丁的原始 Playwright 页面。
|
||
|
||
> **注意（Playwright）：** 请始终使用 `page.click(selector)`、`page.type(selector, text)`、`page.hover(selector)` 或 `page.locator(selector).*` — 这些会经过完整的类人化（humanize）流水线。请避免使用 `page.query_selector()` — `ElementHandle` 对象会绕过所有补丁，导致鼠标瞬间传送、键盘事件无节奏触发，且滚动没有类人曲线。
|
||
>
|
||
> **注意（Puppeteer）：** 基于选择器的方法（`page.click()`、`page.type()`）和 ElementHandle 方法（`el.click()`、`el.type()`）均已完全类人化。`page.$()`、`page.$$()` 和 `page.waitForSelector()` 会自动返回已打补丁的句柄。
|
||
|
||
> 贡献者：[@evelaa123](https://github.com/evelaa123) — 完整覆盖 Playwright 与 Puppeteer API。
|
||
|
||
## 配置
|
||
|
||
| 环境变量 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `CLOAKBROWSER_BINARY_PATH` | — | 跳过下载，使用本地 Chromium 二进制文件 |
|
||
| `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | 二进制缓存目录 |
|
||
| `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | 二进制文件的自定义下载 URL |
|
||
| `CLOAKBROWSER_AUTO_UPDATE` | `true` | 设为 `false` 可禁用后台更新检查 |
|
||
| `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | 仅适用于自定义 `CLOAKBROWSER_DOWNLOAD_URL`：设为 `true` 可跳过其校验和检查。官方下载路径上的签名校验为强制项，无法跳过。 |
|
||
| `CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS` | `5` | GeoIP 解析的最大等待秒数，超时后继续运行但不使用 GeoIP |
|
||
| `CLOAKBROWSER_WIDEVINE_CDM` | — | 旁加载 `WidevineCdm` 目录的路径（覆盖二进制文件旁自动检测）。参见 [Widevine / DRM](#widevine--drm) |
|
||
| `CLOAKBROWSER_WIDEVINE` | `1` | 设为 `0` 可禁用持久化上下文的自动 Widevine 提示文件播种 |
|
||
| `CLOAKBROWSER_FETCH_WIDEVINE` | `0` | 仅 Docker：设为 `1` 可在容器启动时自动获取 Widevine CDM（仅 Linux x86-64）。参见 [Widevine / DRM](#widevine--drm) |
|
||
| `CLOAKBROWSER_VERSION` | — | 锁定到精确的 Chromium 版本以便回滚（例如 `148.0.7778.215.2`）。适用于 Free 与 Pro 二进制文件 |
|
||
|
||
## 指纹管理
|
||
|
||
该二进制文件**默认具备隐匿性** — 无需任何标志。启动时会自动生成随机指纹种子，并伪造所有可检测值（GPU、硬件规格、屏幕尺寸、canvas、WebGL、音频、字体）。每次启动都会生成全新的、一致的身份。
|
||
|
||
**指纹工作原理：**
|
||
|
||
| 场景 | 行为 |
|
||
|----------|-------------|
|
||
| **无标志** | 启动时自动生成随机种子。GPU、屏幕、硬件规格及所有噪声补丁均自动伪造。每次启动都是全新身份。 |
|
||
| **`--fingerprint=seed`** | 由种子生成确定性身份。相同种子 = 跨启动相同指纹。用于会话持久化（回访用户）。 |
|
||
| **`--fingerprint=seed` + 显式标志** | 显式标志覆盖各自动生成的值。种子填充其余部分。 |
|
||
|
||
该二进制文件在编译时检测平台 — macOS 二进制报告为带 Apple GPU 的 macOS，Linux 二进制报告为带 NVIDIA GPU 的 Linux。**wrapper** 在 Linux 上通过传入 `--fingerprint-platform=windows` 覆盖此行为，使会话呈现为 Windows 桌面（更常见的指纹，更难聚类）。直接运行二进制文件时，可使用 `--fingerprint-platform` 进行跨平台伪造。
|
||
|
||
> **提示：回访同一站点时请使用固定种子。** 随机种子会让每次会话看起来像不同设备 — 从同一 IP 反复访问同一站点时可能显得可疑。对于 reCAPTCHA v3 Enterprise 及类似评分系统，固定种子可在跨会话产生一致指纹，使你看起来像回访用户：
|
||
>
|
||
> ```python
|
||
> browser = launch(args=["--fingerprint=12345"])
|
||
> ```
|
||
>
|
||
> ```javascript
|
||
> const browser = await launch({ args: ['--fingerprint=12345'] });
|
||
> ```
|
||
|
||
### 默认指纹
|
||
|
||
每次 `launch()` 调用都会自动设置这些。**wrapper** 应用平台感知默认值 — 在 Linux 上伪装为 Windows 以获得更常见的指纹，在 macOS 上以原生 Mac 浏览器运行：
|
||
|
||
| 标志 | Linux/Windows 默认值 | macOS 默认值 | 控制项 |
|
||
|------|--------------|---------------|----------|
|
||
| `--fingerprint` | 随机（10000–99999） | 随机（10000–99999） | canvas、WebGL、音频、字体、client rects 的主种子 |
|
||
| `--fingerprint-platform` | `windows` | `macos` | `navigator.platform`、User-Agent OS、GPU 池选择 |
|
||
|
||
该二进制文件从种子自动生成其余一切：GPU、硬件并发数、设备内存和屏幕尺寸。每个种子产生唯一且一致的指纹。如需可改用显式标志覆盖。
|
||
|
||
> **直接运行二进制文件？** 零标志即可开箱即用 — 二进制会自动伪造一切。传入 `--fingerprint=seed` 可获得持久身份，或使用 `--fingerprint-gpu-renderer` 等显式标志覆盖任意自动生成值。
|
||
|
||
### 附加标志
|
||
|
||
二进制支持但**默认不设置** — 通过 `args` 传入以自定义：
|
||
|
||
| 标志 | 控制项 |
|
||
|------|----------|
|
||
| `--fingerprint-gpu-vendor` | WebGL `UNMASKED_VENDOR_WEBGL`（根据 seed + 平台自动生成） |
|
||
| `--fingerprint-gpu-renderer` | WebGL `UNMASKED_RENDERER_WEBGL`（根据 seed + 平台自动生成） |
|
||
| `--fingerprint-hardware-concurrency` | `navigator.hardwareConcurrency`（自动生成：`8`） |
|
||
| `--fingerprint-device-memory` | `navigator.deviceMemory`，单位 GB（自动生成：`8`） |
|
||
| `--fingerprint-screen-width` | 屏幕宽度（自动生成：`1920` Win/Linux，`1440` macOS） |
|
||
| `--fingerprint-screen-height` | 屏幕高度（自动生成：`1080` Win/Linux，`900` macOS） |
|
||
| `--fingerprint-brand` | 浏览器品牌：`Chrome`、`Edge`、`Opera`、`Vivaldi` |
|
||
| `--fingerprint-brand-version` | 品牌版本（UA + Client Hints） |
|
||
| `--fingerprint-platform-version` | Client Hints 平台版本 |
|
||
| `--fingerprint-location` | 地理位置坐标 |
|
||
| `--fingerprint-timezone` | 时区（例如 `America/New_York`） |
|
||
| `--fingerprint-locale` | 区域设置（例如 `en-US`） |
|
||
| `--fingerprint-storage-quota` | 覆盖存储配额（单位 MB）— 影响 `storage.estimate()`、`storageBuckets` 以及旧版 webkit API。设置 `--fingerprint` 时会自动规范化 |
|
||
| `--fingerprint-taskbar-height` | 覆盖任务栏高度（二进制默认值：Win=48，Mac=95，Linux=0） |
|
||
| `--fingerprint-fonts-dir` | 包含目标平台字体的目录路径（参见 [Linux 字体配置](#font-setup-on-linux)） |
|
||
| `--fingerprint-windows-font-metrics` | **仅限 Chromium 148+ 二进制版本**（更早版本无效）。在 Linux 上伪装为 Windows 时，使字体度量与 Windows 平台对齐 — 用于 [FingerprintJS 配置](#detected-by-fingerprintjs)。需要安装 Windows 字体（参见 [Linux 字体配置](#font-setup-on-linux)）；未安装则无效果 |
|
||
| `--fingerprint-webrtc-ip` | WebRTC ICE 候选 IP 替换。使用 `auto` 从代理出口 IP 解析（通过代理发起 HTTP 请求），或传入显式 IP。设置 `geoip=True` 时自动注入 |
|
||
| `--fingerprint-noise=false` | 禁用噪声注入（canvas、WebGL、audio、client rects），同时保持确定性指纹 seed 处于活动状态 |
|
||
| `--fingerprint=off` | **仅限 Chromium 148+ 二进制版本。** 透传调试模式 — 关闭伪装并呈现机器的**真实原生指纹**（仅保留任何 Chrome 所需的基础配置）。二进制会剥离注入的 seed *以及* `--fingerprint-platform`，因此不会出现混合 OS 配置。在真正的 Windows 机器上最有用，可用于判断问题是出在伪装还是环境。接受 `off`/`false`/`0`/`disable`/`disabled`。若要实现*纯*透传，请勿与 `geoip=True` / 显式时区 / 区域设置组合使用 — 这些设置仍会生效。 |
|
||
| `--fingerprint-allow-3p-cookies` | **仅限 Chromium 148+ 二进制版本。** 为需要第三方 Cookie 的嵌入式流程重新启用（reCAPTCHA v3、SSO、部分支付验证）。默认关闭；仅在登录/支付/嵌入式验证能加载但始终无法完成时开启。 |
|
||
| `--license-through-proxy` | **仅限 Chromium 148+ 二进制版本，目前仅支持 Linux。** 将 Pro 许可证/会话调用经由你的 `--proxy-server` 路由，而非直连 cloakbrowser.dev。默认关闭（这些调用直连，因此不会占用代理带宽或影响你的爬取会话）。 |
|
||
| `--enable-blink-features=FakeShadowRoot` | 访问封闭的 shadow DOM 元素 |
|
||
|
||
> **注意：** 所有隐身测试均使用上述默认指纹配置验证。修改这些标志可能影响检测结果 — 投入生产前请先测试你的配置。
|
||
|
||
### Linux 字体配置
|
||
|
||
**对抗强反爬站点（Kasada、Akamai）所必需。** 这些系统会在隐藏 canvas 上渲染 emoji 并对像素输出进行哈希。精简的 Linux 环境（Docker、云虚拟机）通常缺少 emoji 和扩展字体，生成的哈希与任何真实浏览器都不匹配。安装标准字体包即可修复：
|
||
|
||
```bash
|
||
sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
|
||
fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf
|
||
```
|
||
|
||
Docker 镜像（`cloakhq/cloakbrowser`）已预装这些字体。若直接在 Linux 服务器上运行二进制，或在自定义 Docker 镜像中运行，需手动安装。
|
||
|
||
**可选：用于 CreepJS 字体枚举的 Windows 字体。** 上述字体包可修复反爬 canvas 检测，但无法提升 CreepJS 字体得分。为此，你需要来自 Windows 机器 `C:\Windows\Fonts\` 目录的真实 Windows 字体（Segoe UI、Calibri、Bahnschrift 等）— `ttf-mscorefonts-installer` 仅有旧的 XP 时代字体，不够用。
|
||
|
||
```bash
|
||
mkdir -p ~/.local/share/fonts/windows
|
||
cp /path/to/windows/fonts/*.ttf ~/.local/share/fonts/windows/
|
||
cp /path/to/windows/fonts/*.TTF ~/.local/share/fonts/windows/
|
||
fc-cache -f # mandatory for manually copied fonts
|
||
```
|
||
|
||
```python
|
||
browser = launch(
|
||
args=["--fingerprint-fonts-dir=/home/user/.local/share/fonts/windows"],
|
||
)
|
||
```
|
||
|
||
### 示例
|
||
|
||
```python
|
||
# Pin a seed for a persistent identity
|
||
browser = launch(args=["--fingerprint=42069"])
|
||
|
||
# Full control — disable defaults, set everything yourself
|
||
browser = launch(stealth_args=False, args=[
|
||
"--fingerprint=42069",
|
||
"--fingerprint-platform=windows",
|
||
])
|
||
|
||
# Override GPU to look like a specific machine
|
||
browser = launch(args=[
|
||
"--fingerprint-gpu-vendor=Intel Inc.",
|
||
"--fingerprint-gpu-renderer=Intel Iris OpenGL Engine",
|
||
])
|
||
```
|
||
|
||
## 示例
|
||
|
||
**Python** — 参见 [`examples/`](examples/)：
|
||
|
||
- [`basic.py`](examples/basic.py) — 启动并加载页面
|
||
- [`persistent_context.py`](examples/persistent_context.py) — 持久化配置，支持 cookie/localStorage 持久化
|
||
- [`recaptcha_score.py`](examples/recaptcha_score.py) — 检查你的 reCAPTCHA v3 得分
|
||
- [`stealth_test.py`](examples/stealth_test.py) — 在 6 个检测站点上运行测试
|
||
- [`fingerprint_scan_test.py`](examples/fingerprint_scan_test.py) — 针对 fingerprint-scan.com 和 CreepJS 进行测试
|
||
|
||
**JavaScript** — 参见 [`js/examples/`](js/examples/)：
|
||
|
||
- [`basic-playwright.ts`](js/examples/basic-playwright.ts) — Playwright 启动并加载
|
||
- [`basic-puppeteer.ts`](js/examples/basic-puppeteer.ts) — Puppeteer 启动并加载
|
||
- [`stealth-test.ts`](js/examples/stealth-test.ts) — 在 6 个检测站点上运行测试
|
||
|
||
### 框架集成
|
||
|
||
CloakBrowser 可与任何使用 Playwright 或 Chromium 的框架配合使用：
|
||
|
||
```python
|
||
# Option 1: Framework launches our binary directly (Selenium, Stagehand, UC)
|
||
from cloakbrowser.download import ensure_binary
|
||
from cloakbrowser.config import get_default_stealth_args
|
||
binary_path = ensure_binary() # auto-downloads if needed
|
||
stealth_args = get_default_stealth_args() # all fingerprint flags
|
||
|
||
# Option 2: CloakBrowser launches first, framework connects via CDP (browser-use, Crawl4AI, Scrapling)
|
||
from cloakbrowser import launch_async
|
||
browser = await launch_async(args=["--remote-debugging-port=9242"])
|
||
# Connect your framework to http://127.0.0.1:9242 — all stealth flags are set
|
||
# Note: humanize requires the wrapper (see below)
|
||
```
|
||
|
||
> **通过 CDP 实现 Humanize**：隐身指纹补丁可通过 CDP 自动生效，但 `humanize=True` 是封装层功能。若从独立脚本通过 CDP 连接 CloakBrowser，需导入补丁函数以添加 humanization：
|
||
>
|
||
> ```js
|
||
> import { patchBrowser, resolveConfig } from 'cloakbrowser/human';
|
||
> patchBrowser(browser, resolveConfig('default'));
|
||
> ```
|
||
|
||
| 框架 | Stars | 语言 | 示例 |
|
||
|-----------|-------|----------|---------|
|
||
| [browser-use](https://github.com/browser-use/browser-use) | 70K | Python | [`browser_use_example.py`](examples/integrations/browser_use_example.py) |
|
||
| [Crawl4AI](https://github.com/unclecode/crawl4ai) | 58K | Python | [`crawl4ai_example.py`](examples/integrations/crawl4ai_example.py) |
|
||
| [Crawlee](https://github.com/apify/crawlee-python) | 8.6K | Python | [`crawlee_example.py`](examples/integrations/crawlee_example.py) |
|
||
| [Scrapling](https://github.com/D4Vinci/Scrapling) | 21K | Python | [`scrapling_example.py`](examples/integrations/scrapling_example.py) |
|
||
| [Stagehand](https://github.com/browserbase/stagehand) | 21K | TypeScript | [`stagehand.ts`](js/examples/stagehand.ts) |
|
||
| [LangChain](https://github.com/langchain-ai/langchain) | 100K+ | Python | [`langchain_loader.py`](examples/integrations/langchain_loader.py) |
|
||
| [Selenium](https://github.com/SeleniumHQ/selenium) | — | Python | [`selenium_example.py`](examples/integrations/selenium_example.py) |
|
||
| [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver) | 12K | Python | [`undetected_chromedriver.py`](examples/integrations/undetected_chromedriver.py) |
|
||
| [agent-browser](https://github.com/nichochar/agent-browser) | — | Shell | [`agent_browser.sh`](examples/integrations/agent_browser.sh) |
|
||
|
||
### 部署集成
|
||
|
||
| 平台 | 示例 |
|
||
|----------|---------|
|
||
| [AWS Lambda](https://aws.amazon.com/lambda/) | [`aws_lambda/`](examples/integrations/aws_lambda/) — Lambda 中的单次抓取（容器镜像） |
|
||
|
||
## 平台
|
||
|
||
| 平台 | 免费版 | Pro 版 | 状态 |
|
||
|---|---|---|---|
|
||
| Linux x86_64 | Chromium 146 (58 patches) | Chromium 148 (66 patches) | ✅ |
|
||
| Linux arm64 (RPi, Graviton) | Chromium 146 (58 patches) | Chromium 148 (66 patches) | ✅ |
|
||
| macOS arm64 (Apple Silicon) | Chromium 145 (26 patches) | Chromium 148 (66 patches) | ✅ |
|
||
| macOS x86_64 (Intel) | Chromium 145 (26 patches) | Chromium 148 (66 patches) | ✅ |
|
||
| Windows x86_64 | Chromium 146 (58 patches) | Chromium 148 (66 patches) | ✅ |
|
||
|
||
封装器会根据你的平台自动下载对应的二进制文件。
|
||
|
||
**macOS 首次启动：** 二进制文件为 ad-hoc 签名。首次运行时，macOS Gatekeeper 会阻止其运行。右键点击应用 → **打开（Open）** → 在对话框中点击 **打开（Open）**。此操作仅需执行一次。
|
||
|
||
## Docker
|
||
|
||
Docker Hub 上的预构建镜像 —— 无需安装、无需配置。
|
||
|
||
> **Pro 版：** 镜像内置免费版二进制。设置 `CLOAKBROWSER_LICENSE_KEY`（例如 `-e CLOAKBROWSER_LICENSE_KEY=cb_xxx`，或在 Compose 中设置），运行时即可下载最新二进制。
|
||
|
||
### 快速测试
|
||
|
||
```bash
|
||
docker run --rm cloakhq/cloakbrowser cloaktest
|
||
```
|
||
|
||
### 运行脚本
|
||
|
||
```bash
|
||
# Inline script
|
||
docker run --rm cloakhq/cloakbrowser python -c "
|
||
from cloakbrowser import launch
|
||
browser = launch()
|
||
page = browser.new_page()
|
||
page.goto('https://example.com')
|
||
print(page.title())
|
||
browser.close()
|
||
"
|
||
|
||
# Mount your own script
|
||
docker run --rm -v ./my_script.py:/app/my_script.py cloakhq/cloakbrowser python my_script.py
|
||
|
||
# With a proxy
|
||
docker run --rm cloakhq/cloakbrowser python -c "
|
||
from cloakbrowser import launch
|
||
browser = launch(proxy='http://user:pass@proxy:8080')
|
||
page = browser.new_page()
|
||
page.goto('https://example.com')
|
||
print(page.title())
|
||
browser.close()
|
||
"
|
||
```
|
||
|
||
### CDP 服务器模式
|
||
|
||
启动持久的隐身浏览器，并通过 Chrome DevTools Protocol（CDP）远程连接：
|
||
|
||
```bash
|
||
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser cloakserve
|
||
```
|
||
|
||
然后从宿主机连接：
|
||
|
||
```python
|
||
from playwright.sync_api import sync_playwright
|
||
|
||
pw = sync_playwright().start()
|
||
browser = pw.chromium.connect_over_cdp("http://localhost:9222")
|
||
page = browser.new_page()
|
||
page.goto("https://example.com")
|
||
print(page.title())
|
||
browser.close()
|
||
```
|
||
|
||
若你的框架需要直接的 WebSocket 端点，请获取 Chrome 的发现文档并使用重写后的 `webSocketDebuggerUrl`。该 URL 通过 `cloakserve` 回连，以便 CDP 代理保持按 seed 的路由不变：
|
||
|
||
```bash
|
||
curl http://localhost:9222/json/version | jq -r .webSocketDebuggerUrl
|
||
# ws://localhost:9222/devtools/browser/<browser-id>
|
||
|
||
curl 'http://localhost:9222/json/version?fingerprint=11111' | jq -r .webSocketDebuggerUrl
|
||
# ws://localhost:9222/fingerprint/11111/devtools/browser/<browser-id>
|
||
```
|
||
|
||
当 `cloakserve` 运行在反向代理或 TLS 终结器之后时，请转发公共主机/协议头，使生成的 WebSocket URL 使用客户端实际可访问的地址：
|
||
|
||
```nginx
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Forwarded-Host $host;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
```
|
||
|
||
设置这些头后，`/json/version` 将返回诸如 `wss://cdp.example.com/fingerprint/11111/devtools/browser/<browser-id>` 的公共端点，而非内部容器主机。
|
||
|
||
向浏览器传递额外参数：
|
||
|
||
```bash
|
||
# With proxy
|
||
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
|
||
cloakserve --proxy-server=http://proxy:8080
|
||
|
||
# Headed mode (renders to Xvfb inside container)
|
||
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
|
||
cloakserve --headless=false
|
||
|
||
# Reap disconnected per-seed browser processes after 5 minutes
|
||
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
|
||
cloakserve --idle-timeout=300
|
||
```
|
||
|
||
停止服务器：
|
||
|
||
```bash
|
||
docker stop cloak && docker rm cloak
|
||
```
|
||
|
||
> **安全：** CDP 可完全控制浏览器（执行 JS、读取页面、访问文件）。
|
||
> 示例绑定到 `127.0.0.1`，因此仅你的机器可连接。切勿在未增加额外认证的情况下将 9222 端口
|
||
> 暴露到公网。
|
||
|
||
### Docker Compose
|
||
|
||
```yaml
|
||
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
|
||
```
|
||
|
||
**按连接划分的指纹 seed** —— 从单个容器运行多个浏览器身份。每个不同的 seed 会启动独立的 Chrome 进程，并拥有各自的指纹：
|
||
|
||
```python
|
||
# Each seed gets unique canvas noise, client rects, and other browser signals
|
||
b1 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=11111")
|
||
b2 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=22222")
|
||
|
||
# Full identity control via query params
|
||
b3 = pw.chromium.connect_over_cdp(
|
||
"http://localhost:9222?fingerprint=33333"
|
||
"&timezone=Asia/Tokyo&locale=ja-JP&platform=macos"
|
||
"&hardware-concurrency=4&device-memory=8"
|
||
)
|
||
|
||
# Auto-detect timezone/locale from proxy exit IP
|
||
b4 = pw.chromium.connect_over_cdp(
|
||
"http://localhost:9222?fingerprint=44444"
|
||
"&proxy=http://proxy:8080&geoip=true"
|
||
)
|
||
```
|
||
|
||
支持的查询参数：`fingerprint`、`timezone`、`locale`、`platform`、`platform-version`、`brand`、`brand-version`、`gpu-vendor`、`gpu-renderer`、`hardware-concurrency`、`device-memory`、`screen-width`、`screen-height`、`proxy`、`geoip`。相同 seed 复用同一进程（以首次连接的参数为准）。无 seed = 共享默认进程（向后兼容）。
|
||
|
||
默认情况下，按 seed 的进程会一直保持运行，直到 `cloakserve` 退出。若客户端创建了许多不同的 seed，可设置 `--idle-timeout=SECONDS` 或 `CLOAKSERVE_IDLE_TIMEOUT=SECONDS`，在其最后一次 CDP WebSocket 断开后自动终止该 seed 的 Chrome 进程。`0`、`off`、`false`、`none` 或 `disabled` 可禁用空闲清理。执行清理时，`--data-dir` 下该 seed 的临时 profile 目录也会被删除。可在 `GET /` 查看活跃进程（返回包含 PID、端口、连接数、空闲超时和待清理状态的 JSON）。
|
||
|
||
**持久化 profile** —— 挂载卷以在容器重启后保留 cookie 和会话：
|
||
|
||
```bash
|
||
docker run --rm -v ./my-profile:/profile cloakhq/cloakbrowser python -c "
|
||
from cloakbrowser import launch_persistent_context
|
||
ctx = launch_persistent_context('/profile')
|
||
page = ctx.new_page()
|
||
page.goto('https://example.com')
|
||
ctx.close()
|
||
"
|
||
```
|
||
|
||
使用同一卷再次运行 —— cookie、localStorage 和 cache 会自动恢复。
|
||
|
||
要在持久化 profile 中启用 Widevine DRM（Netflix、Spotify Web 等），请添加 `-e CLOAKBROWSER_FETCH_WIDEVINE=1` 以在首次启动时自动获取 CDM（参见 [Widevine / DRM](#widevine--drm)）；它会缓存在挂载的卷中。
|
||
|
||
**资源占用：** 空闲时约 190MB RAM，3 个标签页时约 280MB。每增加一个标签页约 30MB。
|
||
|
||
### 使用自定义镜像扩展
|
||
|
||
```dockerfile
|
||
FROM cloakhq/cloakbrowser
|
||
COPY your_script.py /app/
|
||
CMD ["python", "your_script.py"]
|
||
```
|
||
|
||
**通过 pip 构建自定义镜像** —— 使用 `python -m cloakbrowser install` 在构建期间下载二进制文件并显示进度：
|
||
|
||
```dockerfile
|
||
FROM python:3.12-slim
|
||
RUN pip install cloakbrowser && python -m cloakbrowser install
|
||
COPY your_script.py /app/
|
||
CMD ["python", "/app/your_script.py"]
|
||
```
|
||
|
||
**从源码构建** —— 若你更喜欢自行构建镜像，也提供了 [`Dockerfile`](Dockerfile)：
|
||
|
||
```bash
|
||
docker build -t cloakbrowser .
|
||
```
|
||
|
||
CloakBrowser 在本地、Docker 和 VPS 上行为一致。无需针对特定环境进行配置。
|
||
|
||
**注意：** 若在带 uvloop 的 Web 服务器中运行 CloakBrowser（例如 `uvicorn[standard]`），请使用 `--loop asyncio` 以避免子进程管道挂起。
|
||
|
||
## 故障排除
|
||
|
||
---
|
||
|
||
### 在强对抗站点（DataDome、Turnstile）上仍被封禁？
|
||
|
||
有些网站即使使用了我们的 C++ 补丁，仍会检测到无头（headless）模式。请在虚拟显示器上以 **headed mode**（有界面模式）运行：
|
||
|
||
```bash
|
||
# Install Xvfb (virtual framebuffer)
|
||
sudo apt install xvfb
|
||
|
||
# Start virtual display
|
||
Xvfb :99 -screen 0 1920x1080x24 &
|
||
export DISPLAY=:99
|
||
```
|
||
|
||
```python
|
||
from cloakbrowser import launch
|
||
|
||
# Headed mode + residential proxy for maximum stealth
|
||
browser = launch(headless=False, proxy="http://your-residential-proxy:port")
|
||
page = browser.new_page()
|
||
page.goto("https://heavily-protected-site.com") # passes DataDome, etc.
|
||
browser.close()
|
||
```
|
||
|
||
这会在虚拟显示器上运行真实的 headed 浏览器，无需物理显示器。结合下方推荐配置，可获得最佳隐匿效果。
|
||
|
||
---
|
||
|
||
### 反机器人站点的推荐配置
|
||
|
||
大多数封禁源于以下三项配置中缺失其一，而非浏览器指纹检测：
|
||
|
||
```python
|
||
browser = launch(
|
||
proxy="http://your-residential-proxy:port", # residential IP — datacenter IPs get blocked by reputation alone
|
||
geoip=True, # matches timezone + locale to proxy exit IP (without this: UTC + en-US = bot signal)
|
||
headless=False, # headed mode — some sites detect headless even with C++ patches
|
||
humanize=True, # human-like mouse, keyboard, scroll behavior
|
||
)
|
||
```
|
||
|
||
```javascript
|
||
const browser = await launch({
|
||
proxy: 'http://your-residential-proxy:port',
|
||
geoip: true,
|
||
headless: false,
|
||
humanize: true,
|
||
});
|
||
```
|
||
|
||
若代理支持 SOCKS5，建议使用以获得更好兼容性 — SOCKS5 隧道传输原始 TCP，可避免部分代理在 HTTP/2 下出现的 HTTP CONNECT 问题：
|
||
|
||
```python
|
||
browser = launch(proxy="socks5://user:pass@proxy:1080", geoip=True, headless=False, humanize=True)
|
||
```
|
||
|
||
若仍被封禁，请检查下方字体配置。
|
||
|
||
---
|
||
|
||
### 被 FingerprintJS 检测到？
|
||
|
||
FingerprintJS（`demo.fingerprint.com/playground`）会检查多种信号。每项检测结果都有具体原因：
|
||
|
||
| 检测项 | 原因 | 修复 |
|
||
|-----------|-------|-----|
|
||
| **`nodriver` / bad bot** | 二进制/wrapper 过期、缺少当前 FPJS 补丁，或代理 IP 信誉不佳 | 升级至最新 Pro 二进制（`148.0.7778.215.5+`），搭配 `geoip=True` 使用住宅代理，并采用下方配置。 |
|
||
| **Browser tampering** | ML 检测到噪声注入 | `--fingerprint-noise=false` |
|
||
| **Browser tampering**（fonts） | 字体度量与伪装的 Windows 平台不匹配 | `--fingerprint-windows-font-metrics`（Chromium 148+ 二进制；需要[安装 Windows 字体](#font-setup-on-linux)） |
|
||
| **Virtual machine** | 屏幕尺寸与 viewport 不匹配 | `--fingerprint-screen-width/height` 与 viewport 匹配 |
|
||
|
||
在最新二进制上可通过 FPJS 的配置（Linux，住宅代理）：
|
||
|
||
```python
|
||
browser = launch(
|
||
headless=False,
|
||
proxy="http://user:pass@residential-proxy:port",
|
||
geoip=True,
|
||
args=[
|
||
"--fingerprint-noise=false", # prevents tampering detection
|
||
"--fingerprint-windows-font-metrics", # align font metrics — 148+ binary, needs Windows fonts
|
||
],
|
||
)
|
||
```
|
||
|
||
```javascript
|
||
const browser = await launch({
|
||
headless: false,
|
||
proxy: 'http://user:pass@residential-proxy:port',
|
||
geoip: true,
|
||
args: [
|
||
'--fingerprint-noise=false',
|
||
'--fingerprint-windows-font-metrics', // align font metrics — 148+ binary, needs Windows fonts
|
||
],
|
||
});
|
||
```
|
||
|
||
需要 **Chromium 148+ 二进制** 和已安装的 **Windows 字体**（见 [Font Setup on Linux](#font-setup-on-linux)）；配合 **住宅代理** 和 `geoip=True` 运行。
|
||
|
||
**Persistent contexts**（`launch_persistent_context` / `launchPersistentContext`）在最新 Pro 二进制上使用相同的 FPJS 配置。请使用真实的 `userDataDir`。此处存储配额（storage quota）调优与 FingerprintJS 无关；它仅影响从配额推断无痕模式的检测器，例如 BrowserScan（见 [storage quota](#launch_persistent_context)）。DRM/媒体播放见 [Widevine / DRM](#widevine--drm)。
|
||
|
||
---
|
||
|
||
### 配置正确仍被 Kasada / Akamai 站点封禁？
|
||
|
||
在精简 Linux 环境中，缺少字体包会导致 canvas emoji 渲染产生的哈希值无法被反机器人系统识别。在代理、geoip 和有界面模式均已正确配置后，这是防护严格站点上最常见的封禁原因。
|
||
|
||
安装上文 [Linux 字体配置](#font-setup-on-linux) 中列出的字体包。
|
||
|
||
---
|
||
|
||
### 部分网站会挑战新会话，首次访问后则可正常工作
|
||
|
||
一些网站会通过 HTTP/2 对没有 cookie 的首次访客进行挑战（challenge）。这会影响所有 Chromium 浏览器，而不仅是 CloakBrowser。使用持久化配置文件（persistent profile）预先预热 cookie，然后在各次会话中复用：
|
||
|
||
```python
|
||
from cloakbrowser import launch_persistent_context
|
||
|
||
# First run: warm up with --disable-http2
|
||
ctx = launch_persistent_context("./profile", args=["--disable-http2"])
|
||
page = ctx.new_page()
|
||
page.goto("https://example.com") # warms up cookies
|
||
ctx.close()
|
||
|
||
# Future runs — no --disable-http2 needed
|
||
ctx = launch_persistent_context("./profile")
|
||
page = ctx.new_page()
|
||
page.goto("https://example.com") # passes with saved cookies
|
||
```
|
||
|
||
```javascript
|
||
import { launchPersistentContext } from 'cloakbrowser';
|
||
|
||
// First run: warm up with --disable-http2
|
||
let ctx = await launchPersistentContext({ userDataDir: './profile', args: ['--disable-http2'] });
|
||
let page = await ctx.newPage();
|
||
await page.goto('https://example.com');
|
||
await ctx.close();
|
||
|
||
// Future runs — no --disable-http2 needed
|
||
ctx = await launchPersistentContext({ userDataDir: './profile' });
|
||
```
|
||
|
||
对于无状态/临时使用场景，`launch(args=["--disable-http2"])` 会强制使用 HTTP/1.1，从而绕过该检查。仅对确实需要此选项的网站使用此标志——大多数网站在 HTTP/2 下可正常工作。若你的代理支持 SOCKS5，可改用 `proxy="socks5://user:pass@host:port"`——SOCKS5 可完全绕过 HTTP CONNECT。
|
||
|
||
---
|
||
|
||
### 遇到问题？请确保已升级到最新版本
|
||
|
||
旧版本可能使用过时的隐身参数（stealth args），或下载较旧的二进制文件：
|
||
|
||
```bash
|
||
pip install -U cloakbrowser # Python
|
||
npm install cloakbrowser@latest # JavaScript
|
||
docker pull cloakhq/cloakbrowser:latest # Docker
|
||
```
|
||
|
||
### 新更新导致问题？回滚版本
|
||
|
||
有两种方式可回到可用的版本：
|
||
|
||
**固定二进制版本**（保留当前 wrapper，仅使用较旧的 Chromium）—— 适用于 Free 和 Pro：
|
||
|
||
```python
|
||
# Free — pin a public release
|
||
browser = launch(browser_version="146.0.7680.177.5")
|
||
|
||
# Pro — pin a previous Pro version
|
||
browser = launch(license_key="cb_xxxxxxxx", browser_version="148.0.7778.215.2")
|
||
```
|
||
|
||
```bash
|
||
export CLOAKBROWSER_VERSION=146.0.7680.177.5 # env var for all launches
|
||
```
|
||
|
||
```javascript
|
||
// Free — pin a public release
|
||
const browser = await launch({ browserVersion: '146.0.7680.177.5' });
|
||
```
|
||
|
||
固定操作不会持久保留——未固定时启动始终使用最新可用版本。
|
||
|
||
**或降级 wrapper**（每个 wrapper 版本会硬编码其下载的二进制版本）：
|
||
|
||
```bash
|
||
pip install cloakbrowser==0.3.21 # Python
|
||
npm install cloakbrowser@0.3.21 # JavaScript
|
||
docker pull cloakhq/cloakbrowser:0.3.21 # Docker
|
||
```
|
||
|
||
---
|
||
|
||
设置自定义下载 URL 或使用本地二进制文件：
|
||
|
||
```bash
|
||
export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome
|
||
```
|
||
|
||
### macOS：“App 已损坏”或 Gatekeeper 阻止启动
|
||
|
||
该二进制文件为 ad-hoc 签名。macOS 会对下载的文件进行隔离（quarantine）。运行以下命令一次即可清除：
|
||
|
||
```bash
|
||
xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app
|
||
```
|
||
|
||
---
|
||
|
||
### “playwright install”与 CloakBrowser 二进制文件
|
||
|
||
你不需要 `playwright install chromium`。CloakBrowser 会自行下载其二进制文件。你只需安装 Playwright 的系统依赖：
|
||
|
||
```bash
|
||
playwright install-deps chromium
|
||
```
|
||
|
||
---
|
||
|
||
### 网站检测到无痕/隐私浏览模式
|
||
|
||
默认情况下，`launch()` 会打开无痕上下文（incognito context）。部分网站会因此进行限制。使用 `launch_persistent_context()` 可获得带 cookie 持久化的真实配置文件：
|
||
|
||
```python
|
||
from cloakbrowser import launch_persistent_context
|
||
|
||
ctx = launch_persistent_context("./my-profile", headless=False)
|
||
```
|
||
|
||
若网站仍将你标记为无痕模式，可提高存储配额（storage quota）以呈现为常规浏览会话。详见 [存储配额权衡](#launch_persistent_context)，了解其对不同检测服务的影响。
|
||
|
||
---
|
||
|
||
### reCAPTCHA v3 分数偏低（0.1–0.3）
|
||
|
||
避免使用 `page.wait_for_timeout()` —— 它会发送 reCAPTCHA 可检测到的 CDP 协议命令。请改用原生 sleep：
|
||
|
||
```python
|
||
# Bad — sends CDP commands, reCAPTCHA detects this
|
||
page.wait_for_timeout(3000)
|
||
|
||
# Good — invisible to the browser
|
||
import time
|
||
time.sleep(3)
|
||
```
|
||
|
||
```javascript
|
||
// Bad — sends CDP commands
|
||
await page.waitForTimeout(3000);
|
||
|
||
// Good — invisible to the browser
|
||
await new Promise(r => setTimeout(r, 3000));
|
||
```
|
||
|
||
提高 reCAPTCHA 分数的其他建议：
|
||
|
||
- **使用 Playwright，而非 Puppeteer** —— Puppeteer 会发送更多 reCAPTCHA 可检测到的 CDP 协议流量（[详情](#puppeteer)）
|
||
- **使用住宅代理（residential proxies）** —— 被标记的是数据中心 IP 的 IP 信誉，而非浏览器指纹
|
||
- **在触发 reCAPTCHA 前在页面上停留 15 秒以上** —— 访问时间过短会导致分数偏低
|
||
- **错开请求** —— 同一会话中连续调用 `grecaptcha.execute()` 会被惩罚。在含有 reCAPTCHA 的页面之间等待 30 秒以上
|
||
- **使用固定的 fingerprint seed**，以便在多个会话间保持一致的设备身份（参见 [指纹管理](#fingerprint-management)）
|
||
- **填表时使用 `page.type()`，而非 `page.fill()`** —— `fill()` 会直接设置值而不产生键盘事件，reCAPTCHA 的行为分析会将其标记为可疑。带 delay 的 `type()` 可模拟真实按键：
|
||
|
||
```python
|
||
page.type("#email", "user@example.com", delay=50)
|
||
```
|
||
|
||
- **在 reCAPTCHA 检查触发前尽量减少 `page.evaluate()` 调用** —— 每次调用都会产生 CDP 流量
|
||
|
||
## 常见问题
|
||
|
||
**问：这合法吗？**
|
||
答：CloakBrowser 是基于开源 Chromium 构建的浏览器。我们不纵容非法用途。未经授权自动化系统、撞库（credential stuffing）以及滥用账号创建均被明确禁止。完整条款见 [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)。
|
||
|
||
**问：CloakBrowser 免费吗？**
|
||
答：封装层（Python + JS）采用 MIT 许可，永久免费。二进制采用延迟免费开放模式：上一版 Chromium 主版本（当前为 v146）可在 GitHub Releases 免费下载，会话数不限；最新主版本面向 [Pro 订阅用户](https://cloakbrowser.dev).。每次新的主版本发布后，上一主版本会降为免费版。
|
||
|
||
**问：免费版需要许可证密钥吗？**
|
||
答：不需要。免费版二进制会自动下载，无需密钥。许可证密钥仅用于解锁最新（Pro）二进制。
|
||
|
||
**问：取消 Pro 订阅会怎样？**
|
||
答：订阅会保持有效直至当前计费周期结束——取消不会立刻中断服务。周期结束后，封装层会停止拉取新的 Pro 版本，并在下一次许可证检查（缓存约 24 小时）时回退到免费二进制。你只是不再获得新版本。
|
||
|
||
**问：这与 Camoufox 有何不同？**
|
||
答：Camoufox 修补的是 Firefox。我们修补的是 Chromium。Chromium 意味着原生 Playwright 支持、更大的生态，以及可与真实 Chrome 匹配的 TLS 指纹。Camoufox 于 2026 年初回归，但处于不稳定的 beta 阶段——CloakBrowser 已可用于生产环境。
|
||
|
||
**问：检测站点最终会识破吗？**
|
||
答：有可能。机器人检测是一场军备竞赛。源码级补丁比配置级补丁更难被检测，但并非不可能。我们会主动监控，并在检测手段演进时及时更新。
|
||
|
||
**问：可以使用自己的代理吗？**
|
||
答：可以。将 `proxy="http://user:pass@host:port"` 或 `proxy="socks5://user:pass@host:port"` 传给 `launch()`。原生支持 HTTP 与 SOCKS5 代理。
|
||
|
||
## 链接
|
||
|
||
- 📋 **更新日志** — [CHANGELOG.md](CHANGELOG.md)
|
||
- 🌐 **官网** — [cloakbrowser.dev](https://cloakbrowser.dev)
|
||
- 🐛 **缺陷报告与功能请求** — [GitHub Issues](https://github.com/CloakHQ/CloakBrowser/issues)
|
||
- 📦 **PyPI** — [pypi.org/project/cloakbrowser](https://pypi.org/project/cloakbrowser/)
|
||
- 📦 **npm** — [npmjs.com/package/cloakbrowser](https://www.npmjs.com/package/cloakbrowser)
|
||
- ☕ **支持** — [ko-fi.com/cloakhq](https://ko-fi.com/cloakhq)
|
||
- 📧 **联系** — <cloakhq@pm.me>
|
||
|
||
## 安全
|
||
|
||
封装层在解压前会自动根据已发布校验和上的固定 Ed25519 签名验证每一次二进制下载——被攻陷的镜像无法提供被篡改或降级的二进制。发行版还会额外签名，以便手动进行供应链验证：
|
||
|
||
```bash
|
||
# Verify GPG signature (binary release tag)
|
||
gpg --keyserver keyserver.ubuntu.com --recv-keys C60C0DDC9D0DE2DD
|
||
git verify-tag chromium-v146.0.7680.177.5
|
||
|
||
# Verify GitHub binary attestation (Sigstore)
|
||
gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser
|
||
|
||
# Verify Docker image signature (Cosign/Sigstore)
|
||
cosign verify \
|
||
--certificate-identity-regexp "https://github.com/CloakHQ/CloakBrowser/" \
|
||
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
|
||
cloakhq/cloakbrowser:latest
|
||
```
|
||
|
||
## 许可证
|
||
|
||
- **封装层代码**（本仓库）—— MIT。详见 [LICENSE](https://github.com/CloakHQ/CloakBrowser/blob/main/LICENSE).
|
||
- **CloakBrowser 二进制**（编译版 Chromium）：
|
||
- **v146 及更早版本** —— 个人与商业使用免费，不可再分发（向第三方提供服务需 OEM/SaaS 许可）。
|
||
- **v148+（最新版）** —— 下载需有效的 [CloakBrowser Pro](https://cloakbrowser.dev) 订阅。
|
||
- 完整条款见 [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)。
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 与 PR。如有问题，请 [提交 issue](https://github.com/CloakHQ/CloakBrowser/issues) —— 我们会尽快回复。
|
||
|
||
## 贡献者
|
||
|
||
- [@evelaa123](https://github.com/evelaa123) —— 人性化行为、持久化上下文、Windows 修复、.NET 客户端
|
||
- [@yahooguntu](https://github.com/yahooguntu) —— 持久化上下文
|
||
- [@kitiho](https://github.com/kitiho) —— null viewport 修复
|
||
- [@eofreternal](https://github.com/eofreternal) —— humanConfig 类型修复、humanized 方法选项类型、iframe pointer-events 修复
|
||
- [@manaskarra](https://github.com/manaskarra) —— humanized frame 操作的 iframe 作用域修复、GeoIP 超时保护
|
||
- [@Youhai020616](https://github.com/Youhai020616) —— SOCKS5 凭据编码日志
|
||
- [@AlexTech314](https://github.com/AlexTech314) —— AWS Lambda 集成、冷启动加固
|
||
- [@dgtlmoon](https://github.com/dgtlmoon) —— 优雅的 pw.stop() 清理
|
||
- [@zackycodes](https://github.com/zackycodes) —— Chrome 扩展加载
|
||
- [@aaronjmars](https://github.com/aaronjmars) —— 安全修复（shell 注入、依赖升级）
|
||
- [@Seryiza](https://github.com/Seryiza) —— Nix/NixOS flake
|
||
- [@245678000000](https://github.com/245678000000) —— package-lock 同步
|
||
- [@honor2030](https://github.com/honor2030) —— cloakserve WebSocket origin 防护、CDP WebSocket URL 重写、可组合的 JS 启动辅助函数
|
||
- [@sparanoid](https://github.com/sparanoid) —— Docker Xvfb 锁清理
|
||
- [@Kumario1](https://github.com/Kumario1) —— 带 seed 配置的 cloakserve 空闲清理
|
||
- [@0xlally](https://github.com/0xlally) —— 安全报告（cloakserve 路径遍历、WebSocket origin 绕过）
|
||
|
||
## Star 历史
|
||
|
||
<a href="https://www.star-history.com/?repos=CloakHQ%2FCloakBrowser&type=date&legend=top-left">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=CloakHQ/CloakBrowser&type=date&theme=dark&legend=top-left" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=CloakHQ/CloakBrowser&type=date&legend=top-left" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=CloakHQ/CloakBrowser&type=date&legend=top-left" />
|
||
</picture>
|
||
</a>
|