onesvm-browser-server

面向智能体的自构建联网搜索服务：消费者拿一把 X-Service-Token，用 MCP（主）或 HTTP（兜底）调用 search / read。国内直连，国外走自有代理池，query 不经过 Tavily / Jina 等境外 SaaS。

现网入口：http://192.168.1.51:8640（MCP POST /mcp，HTTP POST /v1/search /v1/read）。

你是谁	先读
消费方（Vlepontas / EAI）	docs/mcp-usage-20260901.md → docs/integration-vlepontas-20260901.md
接手开发	docs/dev-handoff-20260902.md（本文下面是设计与选型摘要）
改架构 / 拍板	docs/plan-final-20260901.md（决策权威）→ docs/design-arch-20260901.md（机制权威）

---

1. 要解决什么问题

智能体需要「上网查公开页」。买境外 SaaS 会把 query 送出境，且按次计费；自建浏览器集群又容易把整机内存和出口 IP 打爆。本仓的约束是：

• 境内闭环：搜索与精读默认不经境外托管 API。
• 内存纪律：常驻业务峰 ≤1GB（L2）；60 = 队列深度，不是 60 个浏览器。
• 零 Redis：SQLite WAL 单写者排队。
• 诚实能力：公开网页大约九成；登录墙 / 强 WAF / Google 搜索不承诺。住宅 IP 是另一条带成本声明的通道，本服务不做。

人交「事件怎么活、怎么死、多快死」；实现按 onesvm-dev-md/base/engineering-standards.md 事件表，缺格不补默认值开工。

---

2. 设计科学（为什么长这样）

2.1 统一出口，双形态同一内核

所有消费者注册主体、拿可吊销 key。MCP 与 HTTP 共用 Auth → Policy → Queue → Engine。错误码两面对齐。静态服务密钥只走 X-Service-Token，禁止塞进 Authorization: Bearer。

2.2 分层内核，而不是「一个大浏览器」

流量大约 90% 是搜索 + 纯 HTTP 精读，不该进 Chromium。

层	适配器	何时用
A 无浏览器	SearXNG-CN / SearXNG-Global / Trafilatura	搜索发现、静态正文
B 轻渲染	Lightpanda	HTTP 抽空、需要一点 JS
C 保真	chrome-headless-shell（按需槽，默认 0 副本）	轻核不够时
预留	Camoufox / 有头档	强对抗 + 住宅 IP，不在 1GB 预算内

降级链：C 满 → B → A → blocked/upstream。Cloudflare / WAF / 验证页不拿渲染空转，直接 blocked。

2.3 出口与身份分开记账

• 出口：国内域直连；境外经 ProxyManager + mihomo vless 热池。决定「Google 过不过」的是 IP 信誉，不是 UA 字符串。
• 身份（P0/P1，2026-09-02 落地）：每生产节点 8 套 Chrome 136 模版（与 Trafilatura curl_cffi impersonate=chrome136 自洽）；一等 Cookie 养在本节点 SQLite。罐按 模版 × http|cdp × 出口 × eTLD+1 隔离，节点内共享、不按消费者拆。登录态 Cookie 名直接丢弃。403/验证页整域丢罐。Cookie 不进 MCP、不进 jobs.payload。

Go 侧 httpx 仍是 Go TLS，UA 写诚实的 onesvm-browser-server-httpx/1.0，禁止再伪装 Chrome（TLS/UA 必须自洽）。

2.4 合规双向保险

请求侧在网关：SSRF、仅 80/443、域名策略、普通 key 遵守 robots。响应侧在 worker 模版层：体积/类型白名单、词表、PII 脱敏、注入包裹。命中即 denied 并审计，不假装成功。

---

3. 选用方案（实测后入选，不是目录堆砌）

2026-09-01 本机 Docker 评分（内存 30% / 质量 25% / 成功率 20% / 延迟 15% / 运维 10%）。全文：docs/decision-candidates-20260901.md。

方案	分	角色	为什么留
Trafilatura-HTTP	96.8	默认精读	60/60、p50 ~60ms、正文干净；现网已加 curl_cffi
Lightpanda	91.0	默认 JS	idle 3.6MB；CF/Amazon 仍过不了
chrome-headless-shell	85.5	保真按需	单槽 FIFO 零拒绝；重页 ~400MB
SearXNG-CN	71.5	国内搜索	政策词准；突发时百度/搜狗 CAPTCHA，靠排队钳 4–8
SearXNG-Global	62.0	国外搜索	实例稳，但数据中心 IP 下 仅 Bing；产品不承诺多源

明确排除：playwright-distributed（Redis）、Browserless（4GB 档）、Jina 云（query 出境）、Firecrawl 自托管（与 shell+模版层重叠且更重）。

用户已拍板：D1 先 L0→L2（≤1GB）；D2 接受 Bing-only 起步；D5 不做 Camoufox；Amazon 本站非本服务刚需。

现网能力以 docs/mcp-usage-20260901.md §4 为准（2026-09-02 mgr1 复测），不要把 09-01 bench 的「BBC 稳取 / Amazon 一律不行」抄进消费方文档。

---

4. 仓库地图

server/                  Go 单二进制，-role=gateway|scheduler|proxymanager
  cmd/browser-server/    入口
  internal/contract/     信封与 Job（Session 字段 json:"-"）
  internal/gateway/      MCP + /v1 + Auth + 策略预检
  internal/scheduler/    队列、路由、模版层整合器、junk 过滤、Cookie 绑定
  internal/dock/         五适配器（SearXNG×2、Trafilatura、Lightpanda、shell）
  internal/fingerprint/  每节点 Chrome 136 模版
  internal/session/      Cookie 罐（Sanitize / TTL / reap）
  internal/store/        SQLite（jobs、keys、fp_*、session_cookies）
  internal/proxymanager/ 订阅 / 探活 / 域名路由
  internal/policy/       SSRF / robots / 域名
  internal/safetyscan/   响应侧词表与包裹
stacks/                  Swarm stack + SearXNG 配置 + Trafilatura 镜像
scripts/                 smoke-local.sh、deploy-mgr1.sh（默认 dry-run）
bench/                   选型期实测（无密钥）
docs/                    决策 / 机制 / MCP / 接手

源文件硬上限 600 行（make wc）。禁止万能 util 包。

---

5. 本机怎么跑

make test              # go test（合入前加 -race：cd server && go test -race ./...）
make vet
make smoke             # compose + stub 引擎，12 步断言
make image             # onesvm/browser-server:dev（默认 linux/amd64）
make image-trafilatura # onesvm/trafilatura-http:dev

生产节点通常拉不到 Docker Hub。镜像必须在可联网机器构建/拉取，再 docker save | ssh … docker load，stack 用 --resolve-image never。同 tag 覆盖后必须 docker service update --force，否则任务还跑旧层。

mgr1 部署属 🟡：只在用户明确「确认执行」后跑 bash scripts/deploy-mgr1.sh --apply。密钥在 gitignore 的 deploy.env，不入 git。

---

6. 文档索引

完整表见 docs/README.md。冲突时：

1. docs/plan-final-20260901.md — 决策
2. docs/design-arch-20260901.md — 机制
3. 代码 — 现网行为（文档会过期，以代码与 §4 现网复测为准）