Obscura 中文教程：先跑通 fetch，再接 CDP

Obscura 是一套独立的 Rust 无头浏览器引擎。它用 V8 执行 JavaScript，带自己的 DOM、渲染和网络层，并实现一部分 Chrome DevTools Protocol（CDP）。你可以直接用 CLI 抓取，也可以让 Puppeteer Core 或 Playwright Core 连接它。

1. 选对发行包

文件名同时区分 CPU、操作系统、是否带渲染和是否带 stealth transport。普通截图、PDF 或页面布局任务选择带 render 的默认包。并行 scrape 还需要 obscura-worker，解压后不要把它挪走。

./obscura --version
./obscura fetch https://example.com --eval "document.title"

官方 smoke test 的期望标题是 Example Domain。先用这种固定页面排除架构、glibc 和执行权限问题，再碰自己的复杂站点。

2. Docker 和控制端口

docker run -d --name obscura \
  -p 127.0.0.1:9222:9222 \
  -e OBSCURA_CDP_TOKEN="$(openssl rand -hex 32)" \
  h4ckf0r0day/obscura

绑定 127.0.0.1 可避免端口直接出现在所有网卡上。v0.2.3 对非回环 CDP/MCP 监听强制要求至少 32 字节 bearer token，还会拒绝异常 Host 和浏览器来源请求。token 不能写进镜像或公开日志。

3. 接入 Playwright 或 Puppeteer

启动 obscura serve --port 9222 后，Puppeteer 使用 browserWSEndpoint，Playwright 使用 chromium.connectOverCDP()。这只是协议兼容接口。遇到 iframe、扩展、复杂 CSS 或冷门 Web API 时，必须以目标页面实测为准。

4. 源码构建要求

cargo build --release -p obscura-cli --bins --features render

普通渲染构建使用 rustls。带 stealth transport 的构建还会编译 BoringSSL，并要求 CMake、Clang、libclang/LLVM 开发库。首次构建要从源码编译 V8，官方估计约五分钟，但机器和缓存会让耗时变化。

常见问题