0045 插件存储预置槽位与 jsrt 沙箱实例池设计
- 状态:已接受(2026-11-18)
- 相关:设计文档
05-plugin-theme-standard.md、09-plugin-platform-plan.md;ADR 0003(ent/Atlas/goose 迁移)、0005(TS + JS 沙箱标准)、0007(插件存储不开放 SQL)
背景
ADR 0005 与 ADR 0007 确定了插件后端运行在纯 Go 内嵌 JS/WASM 沙箱中,且存储不开放裸 SQL。进入 P2-1 工程落地阶段,需要拍板两个直接决定多方言兼容性、运维安全性与高并发稳定性的关键工程细节:
- 文档集合(
plugin_docs)的动态索引方案:插件需要在plugin.json中声明少量索引字段(含唯一约束),如何在不执行运行时 DDL 的前提下同时兼容 SQLite / MySQL / PostgreSQL 与多副本部署? - JS/WASM 沙箱(
internal/jsrt)的并发模型与抢占中断:单个 QuickJS 实例是单线程非并发安全的;同时恶意或有缺陷插件可能触发死循环(while(true){})或内存爆炸(OOM),宿主必须在严格时限内物理抢占并无损恢复服务。
决策
1. plugin_docs 预置物理槽位与零运行时 DDL
ent/schema/plugindoc.go在plugin_docs表迁移期即一次性建好固定物理槽位与复合索引,运行期绝不执行CREATE INDEX/ALTER TABLE等 DDL:- 2 个唯一字符串槽位:
u1、u2(MaxLen(255),与(plugin, collection)构成唯一索引,映射清单"string:unique"); - 3 个普通字符串索引槽位:
s1..s3(MaxLen(255),映射"string"); - 3 个数值索引槽位:
n1..n3(float64,映射"number"); - 2 个时间索引槽位:
t1..t2(time.Time,映射"time")。
- 2 个唯一字符串槽位:
internal/plugin/storage_docs.go在加载集合清单时按字段名字母序确定性绑定到可用槽位,保证多副本 / 重启后同一字段永远对应同一物理列;索引超额或未声明即作为查询/排序条件时 fail-closed 返回ErrBadManifest或UnindexedFieldError,唯一键冲突统一映射为ErrUniqueConstraint。plugin_kv采用方言可移植的schema.KVValue([]byte+ 自定义 JSON 编解码),避免不同 Go 小版本下json.RawMessage别名差异引起ent生成代码漂移;所有field.Time显式声明SchemaType(datetimeType)保持三方言对齐。
2. internal/jsrt 沙箱池、抢占中断与损坏重建
- 纯 Go WASM 运行时与版本锁定:基于
github.com/fastschema/qjs v0.0.6与github.com/tetratelabs/wazero v1.9.0(CGO_ENABLED=0跨平台零 CGO);因fastschema/qjs将预编译模块跨越 compiler/instance 两个 wazeroStore实例化,锁定wazero v1.9.0以规避高版本跨 StoreTypeIDs签名校验不匹配问题。 - 预编译字节码与预热实例池:每插件加载时将 ES2023
server.js编译一次 QuickJS 字节码,并维护默认PoolSize = 2个已执行完模块评估与setup(ctx)绑定重放的暖实例;请求经Pool.Borrow/Pool.Do独占借出后归还。 - 硬隔离与资源配额:
- WASM 虚拟根目录隔离为空临时目录;
- 启动脚本剥离
os、std、bjson、setInterval、clearInterval、scriptArgs、navigator,仅保留受调用上下文生命周期回收约束的setTimeout/clearTimeout、console.*(桥接至宿主日志)、TextEncoder/TextDecoder、URL/URLSearchParams与基于crypto/rand的crypto.getRandomValues/randomUUID; - 单实例限制 WASM 内存上限
64 MiB、栈上限1 MiB、包体积上限5 MiB;Guard/Filter 超时2 s,插件 HTTP 路由超时30 s,生命周期/事件超时10 s,调用结束立即清理遗留定时器。
- 上下文抢占、OOM 识别与故障自动替换:启用
qjs.Option{CloseOnContextDone: true}并挂载超时监护关闭底层 runtime 上下文;无论while(true){}超时抢占、64 MiB OOM 还是 WASM trap,均将实例标记为tainted、丢弃损坏实例并在后台异步补充新暖实例,防止故障传染或阻塞后续请求。同时绕开fastschema/qjs v0.0.6中QJS_JSONStringify在 C 侧提前JS_FreeCString的悬垂读取缺陷,统一改由 JSJSON.stringify返回普通JSString读取,并在Promise.Await()后不重复释放已被js_std_await消费的句柄。 - 两阶段原子切换与熔断器:插件启停/热更新先完成池预热与 Hook/路由收集,再通过
hook.Bus.Replace("plugin:<id>", ...)与活跃路由表原子切换并优雅排水旧池;连续运行期异常(超时、OOM、未捕获 JS 异常)达DefaultCircuitThreshold = 5次即自动熔断,数据库中标记failed、从总线摘除所有 Hook 与路由、排水旧池并向活跃超级管理员发送站内故障通知。
备选方案
- 运行时为每个插件集合动态执行
CREATE INDEX/ 生成列 DDL:在只读迁移数据库账号、多实例滚动升级与 SQLite/MySQL/PostgreSQL 语法差异下风险极高,且会触发与 Atlas/goose 迁移校验的 Schema 漂移。 - 全插件共享单个隔离实例 + 全局互斥锁:单个插件执行 2 s Guard 阻塞或被超管配为 30 s HTTP 路由时直接卡死全站所有插件与热路径。
- 不区分损坏实例状态直接复用池内实例:QuickJS-NG 在超时强制中断或 OOM trap 后堆状态已不可信,直接复用会导致内存损坏或静默异常,必须在检测到异常后标记
tainted并剔除重建。
影响
- 容量限制清晰可控:单个文档集合上限为 2 个唯一字符串、3 个普通字符串、3 个数值与 2 个时间索引字段;需要更大索引空间时应拆分为多个集合或借助 KV 建立反向索引。
- 内存与冷启动开销:每个已启用插件默认常驻 2 个轻量化 QuickJS-NG WASM 暖实例(按需动态扩容内存上限至 64 MiB),且后续 P2-2~P2-6 阶段扩展
ctx.*命名空间时直接复用本沙箱池与熔断基础设施。