7.3 KiB
7.3 KiB
Web 热路径:单解释器串行化(设计缺陷说明)
| 状态 | Accepted(缺陷记录 + 缓解已落地) |
| 日期 | 2026-10-26 |
| 规范决策 | ADR 0008 |
| 相关 | ext-web-go-rewrite.md · ext-abi.md · ADR 0004 · ADR 0007 |
本文把「页面卡死 / 像单线程」拆成可验证的架构事实、错误语义与演进边界。
结论先行:HTTP 是多线程的;卡住是因为所有 Endpoint 共享一把解释器锁。
增量实施提案见 隔离执行与响应式 Web 运行时(2026-10-26):独立进程池、控制/读取容量、请求级事件与取消、缓存和恢复。提案通过验收前,本文件及 ADR 0008 的现行单飞约束不变。
1. 问题陈述
1.1 用户可见症状
- 发起一次长对话(OpenAI 兼容
POST …/v1/chat/completions+stream:true/sse-live)。 - 对话尚未结束时,打开设置、拉
/v1/models、或其它短 JSON API。 - 旧行为:浏览器请求一直 pending,整页像死机;只能杀
marqdo run serve…恢复。 - 目标行为:短请求在约 1.5s 内得到 HTTP 503,错误体标明
interpreter busy;对话 SSE 继续;结束后短请求立刻恢复 200。
1.2 错误归因(不要再说错)
| 错误说法 | 正确说法 |
|---|---|
| 「web 插件是单线程的」 | Go net/http 与 SSE 刷写是多 goroutine |
| 「忘记启动进程所以卡死」 | 进程在跑;是 锁争用 导致短请求永不返回 |
| 「把 SSE 的等待时间调大就能修好」 | 进程级拉长 MARQDO_INVOKE_WAIT_MS 会让短请求一起卡死 |
| 「去掉 INVOKE_LOCK 即可并行」 | HostContext 非 Sync,无锁并行会数据竞争 / 未定义行为 |
2. 调用栈与锁边界
Browser
│ GET /v1/models POST /v1/chat/completions (SSE)
▼
Go plugins/web (多 goroutine)
handleInvoke / handleInvokeLiveSSE
│
▼ C ABI host_query("call_lib_path", {path, args})
Rust src/host/plugin.rs
┌─────────────────────────────┐
│ INVOKE_LOCK (进程级 Mutex) │ ← 同一时刻只允许一个 worker 进入
└─────────────────────────────┘
│
▼
HostContext:装载/求值作者 .mq.md、写回、事件总线、LLM 插件回调…
要点:
- 锁在宿主,不在 Go 业务路由表。 增加更多 Go handler 不会自动并行执行 Marqdo。
- SSE 持锁时间 ≈ 整次 Endpoint 求值时间(含多次 LLM 往返),可达数十秒到数分钟。
- 事件转发(
MARQDO_EVENT_FORWARDNDJSON)与 取消(MARQDO_CANCEL_TOKEN)在持锁期间仍可由其它 goroutine 写文件/读桥;它们不进入解释器,故不受INVOKE_LOCK保护,也不应误设长等待。
3. 为何不能简单「多线程跑 Marqdo」
HostContext 持有(非穷尽):
- 当前模块图、函数表、写回缓冲与 FS 根;
- 插件注册与
CURRENT_HOST/ 全局 host 指针; - Agent / LLM 运行时与 stream 发布钩子;
- 与文档写回、会话态相关的可变结构。
这些状态在实现上按单线程求值建模。把它标成 Sync 或去掉 INVOKE_LOCK 而没有隔离运行时,属于未定义行为,不是性能优化。
真并行的合法方向(未实现):
- 解释器池:每请求或每会话一个
HostContext(或可重置的 isolate),路由层选闲置实例; - 只读快照 + 写队列:热路径只读克隆,写回串行合并(适合纯查询 Endpoint,不适合带写回的 agent);
- 把长任务移出解释器:Marqdo 只做编排,重活在独立进程/队列(与「代码即文档」主路径权衡后再定)。
在上述任一方案落地并经金样例验收前,产品必须以「单飞解释器」为约束设计 UX。
4. 缓解契约(已实现)
4.1 宿主:限时争锁
文件:src/host/plugin.rs
- 仅当从 worker 线程进入(
CURRENT_HOST为空、走全局 host)时争INVOKE_LOCK。 acquire_invoke_lock:try_lock循环,预算默认 1500ms(MARQDO_INVOKE_WAIT_MS,最小 1)。- 超时:
set_err("interpreter busy: another request holds the Marqdo invoke lock (waited …ms)"),返回非 0。 - 不要在 SSE 入口把该环境变量设成数分钟:它是进程级的,会污染并发短请求。
4.2 Web 插件:503
文件:plugins/web/internal/httpx/routes_invoke.go
- 普通 JSON invoke:错误信息含
interpreter busy→ 503 +Retry-After: 2+{ok:false, error:…}。 - Live SSE:若启动时即 busy,以失败事件/错误结束该流,不得无限挂起握手。
4.3 客户端:超时与文案
短 API(模型列表、设置、registry 探测等)必须:
- 设置合理
fetch超时(秒级,例如 8s); - 将 503 /
interpreter busy展示为「服务正忙(对话进行中)」类可读提示,而不是空白转圈。
(qdagent 前端 frontend/src/lib/api.ts 已按此契约处理。)
4.4 验收探针
在本地 serve 上:
# 终端 A:启动长 SSE 对话(持锁)
curl -N -m 120 -H 'Authorization: Bearer …' -H 'Content-Type: application/json' \
-d '{"stream":true,…}' http://127.0.0.1:PORT/v1/chat/completions
# 终端 B:对话进行中
curl -sS -w 'http=%{http_code} time=%{time_total}\n' --max-time 5 \
-H 'Authorization: Bearer …' http://127.0.0.1:PORT/v1/models
# 期望:http=503,time≈1.5,body 含 interpreter busy
# 对话结束后再打同一 URL → http=200,time≪1s
5. 运维与调参
| 变量 | 默认 | 含义 |
|---|---|---|
MARQDO_INVOKE_WAIT_MS |
1500 |
worker 进入解释器前最长等待;超时 → busy |
建议:
- 开发机 / 产品默认保持 1–3s。
- 禁止为「让第二个聊天排队」而把默认调到分钟级——那等于恢复卡死。
- 需要排队时,应在 应用层(会话队列、UI 禁用「再发一条」),而不是拉长宿主锁等待。
6. 与其它机制的边界
| 机制 | 与 INVOKE_LOCK 的关系 |
|---|---|
MARQDO_EVENT_FORWARD |
SSE 期间写 NDJSON;不替代争锁;不延长等待 |
MARQDO_CANCEL_TOKEN |
断开连接时可取消 LLM;释放锁仍取决于解释器何时回到 FFI |
web.serve / 静态资源 |
通常不经 call_lib_path,不受本锁影响 |
| 插件内部 Tokio/Go 并发 | 可以;只要不再次 call_lib_path 进同一 HostContext |
7. 演进检查清单(根治前勿宣称「已支持并行 Endpoint」)
- 多
HostContext或 isolate 的生命周期与 ABI(装载、shutdown、写回冲突)有设计稿与金样例。 - 池化后
call_lib_path不再依赖进程级单锁,或锁粒度降到实例级。 - 两个并发长 SSE + 一个短
/v1/models的压力测试:短请求稳定 200,长请求互不污染会话写回。 - 更新本文件与 ADR 0008 Status(例如改为 Superseded by ADR NNNN)。
在清单完成前,对外与文档中应明确:Marqdo Web Endpoint 求值在单进程内串行;HTTP 层并发,解释器层单飞。