chii
983259836d
docs: 联网搜索服务架构方案全套（plan-final/design-arch/选型决策/整合导览/MCP文档/部署预设/联调手册） bench: 5 方案 + 代理 + 站点矩阵本机实测工程（无密钥） 部署目标：primary mgr1 先行测试（待批准后执行）
85 lines
4.7 KiB
Markdown
85 lines
4.7 KiB
Markdown
---
|
||
type: runbook
|
||
status: active
|
||
created: 2026-09-01
|
||
---
|
||
|
||
# Vlepontas 联调使用说明（草稿 · 部署批准后生效）
|
||
|
||
> 状态说明：本文档在**用户批准部署预设**（`docs/deploy-prod-preset-20260901.md`）并完成 L0–L2 灰度上线后生效；文中地址/端口为预设值（`:8640`、`browser-server` alias），上线后以正式通知为准。
|
||
> 详细工具参数/错误码/能力范围见《MCP 使用文档》`docs/mcp-usage-20260901.md`，本文是联调操作手册。
|
||
|
||
## 1. 联调目标
|
||
|
||
验证 Vlepontas 真实业务流在本服务上的表现，回答三个问题：① 数据能力够不够（覆盖/质量）；② 性能体感是否达标（延迟/排队）；③ 是否需要升级数据能力（L4 强对抗档/官方 API）或性能（L3 1.5GB）。
|
||
|
||
## 2. 接入步骤
|
||
|
||
### 2.1 注册与拿 key
|
||
|
||
1. Vlepontas 侧提供：主体标识 `vlepontas`、联系人、预期负载（峰值会话数、搜索/读取/渲染比例）。
|
||
2. 管理侧签发：`X-Service-Token: bs_vlep_…`（明文只回传一次，线下传递）；默认 scope `search,read`；如需 `extract`（JSON schema 抽取）单独申请并审计。
|
||
3. 配额预设：rpm=120、daily=50k、concurrent_sessions=60（对齐 60 会话级上限；联调期可放宽观察）。
|
||
|
||
### 2.2 MCP 接入（主路径）
|
||
|
||
Vlepontas casa-worker 走 overlay（按 WSG 先例附加 `vlepontas-casa-net`）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"onesvm-browser-server": {
|
||
"url": "http://browser-server:8640/mcp",
|
||
"headers": { "X-Service-Token": "bs_vlep_…" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
工具两个：`search`（发现 URL，`region: domestic|overseas` 自选）与 `read`（URL 精读，默认 fit markdown）。
|
||
|
||
### 2.3 HTTP 兜底（排错/非 MCP 链路）
|
||
|
||
```bash
|
||
curl -X POST -H 'X-Service-Token: bs_vlep_…' -H 'Content-Type: application/json' \
|
||
http://192.168.1.61:8640/v1/search \
|
||
-d '{"query":"跨境电商 出口退税 政策 2026","region":"domestic","max_results":5}'
|
||
```
|
||
|
||
### 2.4 纪律（与现有 WSG/Tavily 通道的差异）
|
||
|
||
- 错误码语义：`denied`=合规拦截（不要重试对抗）；`timeout/upstream` 可重试（≤2 次，服从 `Retry-After`）；429/503 带 `running/queued` 现状，自行退避。
|
||
- 队列深度 60 = 排队位 + 在途合计；超限收 503 是背压不是故障。
|
||
- 渲染（JS 页）是稀缺槽位：先 `read` 默认通道，空正文再升级；不要对 `blocked` 站点（Amazon/Medium/Reddit/X/知乎/微博/百度百科/SO/YouTube）反复打。
|
||
|
||
## 3. 联调验收用例（双方共同执行，预期值来自 2026-09-01 实测）
|
||
|
||
| # | 用例 | 预期 |
|
||
|---|---|---|
|
||
| C1 | 国内搜索「跨境电商 出口退税 政策 2026」region=domestic | ≥5 条政策域结果，p50 ≤1s |
|
||
| C2 | `read` 该政策页（gov.cn 系） | 壳页 HTTP 通道可能抽空 → 升级 JS 通道得全文（实测 9577 字/约1s） |
|
||
| C3 | 国外搜索「best bluetooth earbuds 2026」region=overseas | 有结果但**仅 Bing 源**（D2 已定）；p50 ≤5s |
|
||
| C4 | `read` 一个 Shopify 独立站商品页 | 可能被 302 到集合页：系列/价格可见，指定 SKU 不保证——记录业务影响 |
|
||
| C5 | 60 会话 burst 混合负载（40 搜索+15 读+5 渲染） | 无 5xx 风暴；搜索/读全过；渲染排队（p95 等待可测） |
|
||
| C6 | 访问一个 deny 名单域（联调时指定） | `error.code=denied` + 审计记录，验证合规拦截 |
|
||
|
||
## 4. 观察指标与反馈回路
|
||
|
||
联调期 Vlepontas 侧记录：各工具感知延迟、空结果率、denied 命中、渲染等待体感。管理侧提供 `/pressure` 指标快照（队列深度/渲染槽占用/内存比/代理池存活）。
|
||
|
||
**升级决策回路**（联调结论 → 行动）：
|
||
|
||
| 若联调发现 | 行动 |
|
||
|---|---|
|
||
| 渲染等待 p95 超标 / shell 冷启动被感知 | 升 L3 1.5GB（shell 常驻 + 渲染免互斥） |
|
||
| Amazon 详情页/Review | **非刚需**（2026-09-01 用户确认：Vlepontas 有既有消费方案覆盖亚马逊数据，本服务不规划 Amazon 方向；L4 档仅理论预留） |
|
||
| 舆情（Reddit/X/知乎/微博）成刚需 | Reddit 商用 API（~$0.24/千次）/ RSSHub+Cookie 边车（知乎/订阅流）；X 维持 C 档（无免费读档） |
|
||
| 国外搜索质量不满（Bing-only 偏题） | 采购优质/住宅代理出口，或 Brave Search API（出境须法务） |
|
||
| 知乎/百科类中文知识需求 | 千帆百科组件（约 0.01–0.036 元/次）/ RSSHub 适配器 |
|
||
|
||
（依据：`.dsh/artifacts/run-20260901-browser-arch/research/06-blocked-sites.md` 分级路线图。）
|
||
|
||
## 5. 时间窗与联系
|
||
|
||
- 联调窗口：上线后一周（建议每日同步 15min）。
|
||
- 问题升级：本仓 issue / 管理侧负责人；合规疑问先停后用，走法务。
|