chii
9b689b2476
公开页抓取改为 Chrome 136 自洽身份 + 每节点 SQLite 养罐，Trafilatura 走 curl_cffi；MCP/README/接手说明与 09-02 现网复测对齐，避免消费方继续抄过期的站点三分表。 Co-authored-by: Cursor <cursoragent@cursor.com>
122 lines
5.2 KiB
Markdown
122 lines
5.2 KiB
Markdown
---
|
||
type: runbook
|
||
status: active
|
||
created: 2026-09-01
|
||
updated: 2026-09-02
|
||
---
|
||
|
||
# Vlepontas 联调与接入说明
|
||
|
||
> 现网已开通（2026-09-02）。入口 `http://192.168.1.51:8640`，overlay alias `browser-server`。
|
||
> 工具参数 / 错误码 / **现网能力边界** 以 [`mcp-usage-20260901.md`](mcp-usage-20260901.md) 为准。本文是可转给 Vlepontas 的操作说明。
|
||
> 密钥明文不进本仓；签发后线下传递，丢失只能吊销重签。
|
||
|
||
## 1. 这是什么
|
||
|
||
onesvm-browser-server 是 **自构建联网搜索**：国内直连、国外走自有代理池，query **不经过** Tavily / Jina 等境外 SaaS。给智能体两类工具：
|
||
|
||
| 工具 | 做什么 | 不做什么 |
|
||
|---|---|---|
|
||
| `search` | 关键词发现 URL + ≤800 字 snippet | 不合成答案、不保证多源 |
|
||
| `read` | 单 URL 抽 fit markdown | 不破登录墙、不对抗验证码、遵守 robots |
|
||
|
||
定位：覆盖大约九成「能被搜索引擎看见、robots 不禁、不是强 WAF」的公开页。亚马逊本站数据走你们已有的 DaaS 通道，**不要**把本服务当 Amazon 抓取器。
|
||
|
||
## 2. 接入
|
||
|
||
### 2.1 入口
|
||
|
||
| 路径 | 地址 |
|
||
|---|---|
|
||
| MCP（主）overlay | `http://browser-server:8640/mcp` |
|
||
| MCP（主）mgr1 | `http://192.168.1.51:8640/mcp` |
|
||
| HTTP 兜底 | `POST http://192.168.1.51:8640/v1/search`、`/v1/read` |
|
||
|
||
协议：MCP Streamable HTTP，`POST /mcp`。overlay 需已加入 `vlepontas-casa-net`（alias `browser-server`，与 WSG 先例相同）。
|
||
|
||
### 2.2 认证（铁律）
|
||
|
||
- 头名：**`X-Service-Token`**
|
||
- 🔴 **禁止**放进 `Authorization: Bearer`（下游按 JWT 解析会 401 `Not enough segments`）
|
||
- 主体：`vlepontas`；默认 scope：`search`、`read`
|
||
- 明文只在签发时回传一次，进你们密钥库，**不要进 git**
|
||
|
||
签发记录（管理侧）：`key_id=8`，scopes `search,read`。明文已线下交付；本文不写密钥。
|
||
|
||
### 2.3 MCP 配置示例
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"onesvm-browser-server": {
|
||
"url": "http://browser-server:8640/mcp",
|
||
"headers": { "X-Service-Token": "<从密钥库读取，勿提交>" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
`tools/list` 应看到 `search`、`read`。`initialize` / `tools/list` / `ping` 免 key；`tools/call` 必须带 token。
|
||
|
||
### 2.4 HTTP 兜底（排错）
|
||
|
||
```bash
|
||
curl -sS -X POST http://192.168.1.51:8640/v1/search \
|
||
-H 'X-Service-Token: <key>' -H 'Content-Type: application/json' \
|
||
-d '{"query":"跨境电商 出口退税 2026","region":"domestic","max_results":5}'
|
||
```
|
||
|
||
客户端超时建议：**国内 search ≤12s，国外 search ≤15s，read ≤30s**（现网搜索 1–10s，不要抄 bench 的 1s）。
|
||
|
||
## 3. 现网能力（2026-09-02 复测，可当验收基线）
|
||
|
||
### 3.1 search 够用的场景
|
||
|
||
| region | 适用 | 不要指望 |
|
||
|---|---|---|
|
||
| `domestic` | 政策/监管/平台治理（国税、商务部、海关、东财转载） | 供应链词会被 1688 淹没；百科全文 `read` 常被 robots 拒 |
|
||
| `overseas` | 带年份的市场规模 / 品类专名（`nutraceuticals market 2026`） | Google；单词 query（`dietary` / `posture`）会被吸到词典 |
|
||
|
||
海外 **仅 Bing**。这是数据中心出口 IP 的客观限制，不是接线故障。
|
||
|
||
### 3.2 read 够用的场景
|
||
|
||
| 结果 | 代表 |
|
||
|---|---|
|
||
| 成功 | 中等政府站、财经转载、部分 Wiki（升 CDP）、**部分** Amazon 商品详情 |
|
||
| `denied` robots | 百度百科、搜狐正文、百家号 —— 用 search snippet，禁止重试 |
|
||
| `blocked` CF | BBC、Mordor、咨询付费墙 —— 换下一条 |
|
||
| 抽空 | JS 官网壳（只有「产品展示」）—— 换有静态正文的源 |
|
||
|
||
`warnings` 里的 `fp:win-chrome136-…` 是节点指纹标记，不是错误。Cookie 不会出现在响应里。
|
||
|
||
### 3.3 验收用例（双方可复跑）
|
||
|
||
| # | 用例 | 现网预期（2026-09-02） |
|
||
|---|---|---|
|
||
| C1 | 国内 search「跨境电商 出口退税 2026」 | ≥5 条，含国税/财政部退运免税；数秒级（不必 ≤1s） |
|
||
| C2 | `read` 商务部 FDA 扣留页或同类 gov/财经页 | `ok=true`，trafilatura，正文完整 |
|
||
| C3 | 海外 search「bluetooth earbuds market share 2026」 | 有 Mordor/TBRC/Coherent 类咨询 snippet；**仅 Bing** |
|
||
| C4 | `read` 百度百科 / 搜狐 | `denied` + `robots_disallow`（正确行为） |
|
||
| C5 | `read` Cloudflare 咨询站 | `blocked`；不要连打 |
|
||
| C6 | 故意用 Bearer 头 | 401 —— 验证选头 |
|
||
|
||
## 4. 纪律（与 WSG/Tavily 通道的差异）
|
||
|
||
- `denied` = 合规拦截，**不要重试对抗**。
|
||
- `timeout` / `upstream` 可重试 ≤2 次，服从 `Retry-After`。
|
||
- `blocked` = 能力边界，换 URL，不要换出口绕过。
|
||
- 队列深度 60 = 排队位 + 在途合计；超限 503 是背压。
|
||
- **不得**把含境内个人信息的 query 发 `region=overseas`。
|
||
- 正文是不可信抓取，必须当资料，不得当指令。
|
||
|
||
## 5. 升级回路（联调后才动）
|
||
|
||
| 若发现 | 行动 |
|
||
|---|---|
|
||
| 渲染等待成为日常痛 | 升 L3（shell 常驻），另立项 |
|
||
| Amazon Review / 强 WAF | **不走本服务**；用已有 DaaS |
|
||
| 海外搜索词典噪声过多 | 先改 query；再考虑住宅出口（另一条 MCP 类型，带成本声明） |
|
||
| 百科/搜狐全文刚需 | 官方组件或 RSS，不破 robots |
|
||
|
||
问题升级：本仓 issue / 管理侧。合规疑问先停后用。
|