---
title: Netabrowser 反风控浏览器运行时
created: 2026-05-07
updated: 2026-05-07
type: entity
tags: [module, backend, runtime, tool]
sources: [packages/netabrowser-cli/, packages/backend/src/modules/netaclaw/browser-daemon/, packages/backend/skills/netabrowser-cli/, packages/backend/skills/patchwright-cli/, docs/superpowers/specs/2026-05-04-netabrowser-cli-s1-design.md]
---

# Netabrowser 反风控浏览器运行时

Netabrowser 是 2026-05-07 新增的浏览器自动化子系统，目标是为养号、电商自动化和 AI 探索复杂网页提供更接近真实用户的 Chromium 会话。它由 `packages/netabrowser-cli/`、NetaClaw 后端 `browser-daemon/` 和 `netabrowser-cli` skill 共同组成，并被 [[geo-module]] 用来启动账号绑定的持久 profile。

## 架构分层

```text
Agent / Geo / 电商自动化
  -> packages/backend/skills/netabrowser-cli/scripts/nb.cmd|nb.sh
  -> packages/netabrowser-cli CLI
  -> backend /admin/browser-daemon/*
  -> BrowserDaemonService
  -> patchright + neta-chromium + 持久 profile
```

`netabrowser-cli` skill 明确要求 AI 使用脚本封装而不是直接 curl HTTP；后端 daemon 则提供真实控制接口，便于 Geo 模块和前端管理页面复用。

## 后端 daemon

`packages/backend/src/modules/netaclaw/browser-daemon/` 包含：

| 目录/文件 | 职责 |
| --- | --- |
| `service/daemon.service.ts` | 打开/关闭/导航/交互/截图/cookie/state 的核心服务 |
| `runtime/session-registry.ts` | 活跃 session 注册表和 per-session lock |
| `runtime/session-scheduler.ts` | 并发槽位、优先级、idle timeout 和驱逐策略 |
| `runtime/chromium-launcher.ts` | Chromium 路径解析和启动参数 |
| `runtime/browser-data-dir.ts` | profile/state 路径 |
| `runtime/socks5-http-bridge.ts` | SOCKS5 用户名密码代理转本地 HTTP 桥 |
| `service/fingerprint.service.ts` | fingerprintSeed 到启动参数的映射 |
| `service/humanizer.service.ts` | 拟人化鼠标、滚动和输入 |
| `service/snapshot-ref.service.ts` | snapshot ref 到页面元素选择器的映射 |

daemon 对外通过 `/admin/browser-daemon/*` controller 暴露 session、navigation、interaction、inspect、state 等操作，并由 `control-auth.middleware.ts` 做控制入口鉴权。

## 会话与 profile

核心语义：

- `sessionName` 是浏览器会话和磁盘 profile 的稳定标识。
- 同名 session 启动时如果已活跃会返回 409，调用方可改用 `goto` 复用。
- profile 位于 `.netabrowser-data/profiles/<sessionName>`，state 文件位于 dataDir 的 states 目录。
- idle timeout 时 daemon 会保存 storage state 并关闭浏览器。
- `fingerprintSeed` 缺省时不注入 fingerprint 参数，避免中文字体 fallback 异常；传入时保持账号级稳定指纹。

## 反风控能力

当前能力组合：

- `patchright`：降低 Playwright 自动化痕迹。
- `fingerprint-chromium` / neta-chromium：提供 canvas、WebGL、字体、屏幕等硬件指纹差异。
- 拟人化交互：`click`、`hover`、`fill`、`type`、`scroll` 默认走 Humanizer。
- 中文字体补丁：通过 `addInitScript` 注入字体 fallback，避免 portable Chromium 中文乱码。
- SOCKS5 auth 兼容：Chromium 不支持带用户名密码的 SOCKS5 时，自动起本地 HTTP -> SOCKS5 桥。

## Skills

新增两个浏览器相关 skill：

- `netabrowser-cli`：面向国内强反风控站点和账号矩阵场景，要求使用 `scripts/nb.sh` / `nb.cmd`。
- `patchwright-cli`：面向 Cloudflare、DataDome 等国外反爬站点，是 Playwright CLI 的反检测替代。

两者都通过 [[skill-system]] 被发现。`netabrowser-cli` 属于 prompt/脚本型操作指南，实际 HTTP 控制仍落在 browser daemon。

## 相关页面

- [[geo-module]]
- [[skill-system]]
- [[tool-system]]
- [[frontend-architecture]]
- [[windows-runtime]]