chii/onesvm-browser-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
onesvm-browser-server/.dsh/contracts/contract-20260901-browser-arch.md
chii 983259836d chore: init workspace with onesvm-dev-md + casa-commander 
docs: 联网搜索服务架构方案全套（plan-final/design-arch/选型决策/整合导览/MCP文档/部署预设/联调手册）
bench: 5 方案 + 代理 + 站点矩阵本机实测工程（无密钥）
部署目标：primary mgr1 先行测试（待批准后执行）
2026-09-01 15:19:52 +08:00

7.1 KiB
Raw Blame History

Contract: onesvm-browser-server 联网搜索服务架构选型与实测评定

状态: done 创建: 2026-09-01（Asia/Shanghai） run_id: run-20260901-browser-arch CASA Contract Gate — 仅 approved / in_progress 后进入 Execute

deliverable_type

docs + spike（架构方案文档 + 开源方案实测评定；本轮不写生产业务代码）

complexity

core_framework（最终方案须经 Architecture Review 通过才可 done）

model_family

architect（最终方案）；实测/调研步骤 hard/simple 见 Plan 步骤表

model_override

（空）

档位

commander（用户明确「作为开发架构与开发指挥官」）

背景

新仓 onesvm-browser-server 要构建「支持可扩容、集成多浏览器自构建方案、高并发排队」的联网搜索服务，服务对象为 Vlepontas（60 会话级）与 EAI 等内部 toB 智能体。用户给出 6 项任务：统一出口 / 集群与排队 / 拓展坞协议+整合器 / ProxyManager 合规代理 / 开源方案筛选实测 / 最终方案 review。用户已确认四项关键决策：① 部署目标 dev-swarm 内网集群；② 已有代理订阅（容灾后续补充，明文仅存 .dsh/artifacts/proxy-subscriptions.local.md，gitignore）；③ 出口 MCP Server 为主 + HTTP API 兜底；④ 本机 Docker 全量实测。

scope

in_scope

.dsh/contracts/**
.dsh/artifacts/**
.dsh/casa-runtime/**
docs/**
research/**
bench/**

out_of_scope

生产/primary 环境任何变更（本轮仅设计+本机实测）
其它业务仓（vlepontas / EAI 等）
onesvm-dev-md/base/credentials.md（只读不改）
git commit / push（除非用户明确要求）
代理订阅明文（禁止写入任何 in-scope 的可提交文件；仅 .dsh/artifacts/*.local.md）
生产级源码实现（src/** 本轮不建，方案通过后另开 Contract）

acceptance

  • 最终方案文档 docs/ 覆盖用户任务 1–6 全部要点，含 mermaid 拓扑
  • 实测报告覆盖国内外各 ≥2 套候选方案，每套含：数据质量样本、延迟、内存占用、成功率、反爬表现；搜索需求模板 ≥5 套（国内搜索 / 国内正文提取 / 国外搜索·代理 / 国外 JS 渲染页 / 60 会话 burst 压测）
  • 集群规格设计落在 dev-swarm 现实约束（3 节点 × ~6.5GB RAM）内，且本项目全栈（网关+排队+ProxyManager+无头 worker 集群）总内存 ≤1GB，按需求从低水位渐进递增至 1GB 上限；给出无 Redis 排队机制与横向扩展公式（含 1GB 内的渐进扩容档位表）
  • ProxyManager 设计含：订阅解析容灾、健康检查轮换、出口端合规拦截（违反中国法律的数据获取直接拦截）+ MCP 文档消费侧规则（双向保险）
  • 出口形态 = MCP Server 为主 + HTTP API 兜底；HTTP 侧采用组织 urlapi 惯例（独立端口 + /search-api 类前缀），认证头遵循 service-secret-protocol（静态 key 走 X-Service-Token/X-API-Key，禁 Bearer）
  • 有头浏览器仅抽象插拔预留，不建具体设施
  • 所有实测数据来自本机 Docker 真实运行，禁止纸面编造（每条数据可追溯至 bench/ 产物）
  • Verify + 独立 Reverify 双过；Architecture Review PASS

constraints

  • 能不加 Redis 就不加（用户硬性偏好，排队机制须给无 Redis 方案）
  • 本项目集群总内存硬上限 1GB，且按需求渐进递增（起步低水位 → 逐步增至 1GB）：内存成为选型的决定性指标，实测必须精确记录每方案 idle/单会话/60 burst 三档内存；超轻量内核（Lightpanda/Bouncy/chrome-headless-shell/PinchTab 类）优先级上调，重型方案（Camoufox 等）须论证单实例内存或降为预留档
  • 若 bench 数据显示 1GB 无法维持 Vlepontas 60 会话级 + EAI 并发负载，最终方案必须附「扩容提议」：给出维持该负载所需的具体规格（内存总量/节点分布/各组件副本数）与预期性能（并发能力/延迟/吞吐），每项数字由 bench 实测数据换算支撑，供用户决策
  • 轻量化/无头优先；有头仅预留插拔
  • 候选方案最终评定：国内外各 ≥2，总数控制在 4–6 套，稳定质量好优先
  • 本机 Mac Docker 实测须控制资源（同时运行候选容器 ≤3，实测完即停）
  • 时间/时区一律 Asia/Shanghai
  • 源文件行数硬上限 600（本轮主要为文档与 bench 脚本）
  • 实测执行类委派 subagent_cursor（brief 写 Required model: grok-4.6?effort=high；复杂实测 xhigh）

artifact_io

stage 读取 (kinds/paths) 写入 (kinds/paths)
S1 research web + 用户附表 .dsh/artifacts/run-20260901-browser-arch/research/*.md
S2 select S1 产物 + 附表 .dsh/artifacts/run-20260901-browser-arch/select.md + bench/plan.md
S3a proxy-probe .dsh/artifacts/proxy-subscriptions.local.md .dsh/artifacts/run-20260901-browser-arch/proxy-probe.md
S3b/S3c bench S2 选定方案 + 代理 bench/** + .dsh/artifacts/run-20260901-browser-arch/bench/*.md,*.json
S4 arch-design KB + S1 docs/design-arch-*.md
S5 final-plan 全部前置产物 docs/plan-final-*.md
S6 verify/reverify S5 文档 + 全部产物 .dsh/artifacts/run-20260901-browser-arch/review*.md
S7 arch_review S5 + norms .dsh/artifacts/run-20260901-browser-arch/arch-review.md

stage_dag

[S1] ∥ [S3a] → [S2] → [S3b ∥ S3c] → [S5]
[S4（依赖 S1，与 S2/S3 并行）] ↗
[S5] → [S6 verify+reverify] → [S7 arch_review] → done

revisions

日期 变更摘要 作废 artifact
2026-09-01 初版；用户四问已确认（dev-swarm / 代理订阅已有 / MCP+HTTP / 本机全量实测） —
2026-09-01 用户补充硬约束：本项目集群总内存 ≤1GB 且按需求渐进递增；内存升为选型决定性指标 —
2026-09-01 用户补充：若 1GB 不够维持 Vlepontas+EAI 负载，须给出扩容提议（规格+预期性能，bench 数据支撑） —
2026-09-01 S6 ITERATE：Verify PASS + Reverify FAIL（P1×2/P2×4/P3×2）→ 主会话修订 plan-final 与 design-arch（记账口径/入队路径/420×/mihomo 标注/节点布局/扩容换算/端口取代/MCP 表述），送双重复查 reverify.md 初版结论 FAIL，待复审

notes

  • 组织 KB 入口：onesvm-dev-md/base/development-standards.md、deployment-rules.md、infrastructure-inventory.md；经验 experience/projects/vlepontas.md（既有 WSG/Tavily 先例，本服务为其自构建替代/升级）、dev-swarm.md
  • dev-swarm 事实：3 manager（.61/.62/.63，VM107/108/109），6656MB RAM/节点，overlay 10.60.0.0/16，Engine 29.5.3；镜像传输走 docker save/load + --resolve-image never
  • 已有 central-proxy（.53:7890，订阅 :8080/sub/onesvm.yaml）可作 ProxyManager 参考/复用点
  • 风险：① 代理订阅节点质量未知（S3a 先探活）；② 本机 Mac 资源有限，全量实测分批；③ 部分候选（Camoufox/Lightpanda）平台兼容性需实测验证
  • 回滚：本轮仅文档与本机容器，docker compose down + 删文档即可