Skip to content

Commit bb99d36

Browse files
committed
fix(webui): 修复 Node 24.19.0 上进程被 abort 的致命崩溃 —— better-sqlite3 升级到 N-API 13 + 运行时守卫
现象(可复现):服务启动后,浏览器打开小说工作台页(/novels/:id)即让 node 进程直接消失, stderr 留下 native 断言: node::RemoveEnvironmentCleanupHook ... Assertion failed: (env) != nullptr Statement::`scalar deleting destructor`(better_sqlite3.node) 定位:这是 Node v24.19.0 的 node::ObjectWrap 清理钩子回归(nodejs/node#65446), 任何用 node::ObjectWrap 的 addon 在 GC 时都会 abort;better-sqlite3 < 13 的 Statement 正好走该路径 (WiseLibs/better-sqlite3#1515 同源报告)。本机组合 Node 24.19.0 + better-sqlite3 12.11.1 100% 复现。 修复 - better-sqlite3 12.11.1 → ^13.0.3:13 起改用 node-addon-api(N-API),结构上不再走 ObjectWrap 清理路径,且自带跨 Node 版本预编译产物(不再需要 prebuild-install / node-gyp / Python) - 新增 server/db/runtimeGuard.test.ts:锁定 better-sqlite3 主版本 >= 13 并实测建表/读写, 依赖被降级即测试失败 - package.json:移除已失效的 allowScripts 条目(v13 无安装脚本) 验证(Node 24.19.0 实测) - 修复前:工作台页加载 5/5 次崩溃;修复后:30 轮「工作台 + 流程看板」页面压测全存活 - npm run guards:typecheck + 161 测试 + check:no-python 全绿 - npm run smoke 45/45、verify:api 63/63、verify:ui 16/16(真实 Chromium)、verify:page 4/4 - 文档:README「运行环境(重要)」+ CHANGELOG 记录事故与约束
1 parent e73d2c7 commit bb99d36

5 files changed

Lines changed: 58 additions & 400 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
### 修复(webui)
1313

14+
- **启动即崩(致命)**:Node v24.19.0 的 `node::ObjectWrap` 清理钩子回归(nodejs/node#65446)使 better-sqlite3 < 13 的 `Statement` 在 GC 时 abort 整个进程 —— 实测打开小说工作台页即复现,服务进程直接消失。升级 `better-sqlite3` 到 `^13.0.3`(N-API,自带跨版本预编译产物,无需 node-gyp),新增 `server/db/runtimeGuard.test.ts` 锁定版本下限;30 轮工作台/看板页面压测不再复现
1415
- **job 永不落终态**(engine/state.ts、stageRunner.ts):跑完的 job 停在 `queued`,导致成本面板恒为 0、`health?depth=full` 永远报挂起任务、重启自愈把已完成任务误标 `killed(restart-recovery)`;且 `INSERT OR REPLACE` 命中 `idx_jobs_busy` 部分唯一索引后**整行替换**上一条 job,任务历史被静默抹除。现改为 `queued→running→review|done|error` 显式收尾 + 普通 INSERT + 在途 job 复用
1516
- **空阶段被批阅放行**(engine/state.ts):确认通过后会把「下一个 pending 阶段」置为 `review`,从未运行过的阶段因此可直接被「通过」,流程可在无任何产物的情况下推进。现仅在真实产出后进入 review
1617
- **成本面板恒为 0 / by_model 恒为空**(routes/pipeline.ts):统计口径改为已执行任务,并从 `jobs.detail_json` 聚合实际渠道/模型
@@ -22,7 +23,7 @@
2223

2324
- 首屏体积:CodeMirror 6 改按需加载 + 三方库拆 chunk,首屏 JS 由 384 kB(gz) 降至约 210 kB(gz),编辑器 chunk 仅在打开手稿时加载
2425
- 脚本可配置:`e2e-fake` / `verify-api` / `verify-ui` 支持 `--base` 与 `WEBUI_BASE`,不再硬编码 3081 与本机路径;`e2e-fake` 由「只打印」改为断言式(可进 CI)
25-
- `package.json` 记录 `allowScripts`(npm 11 安装脚本白名单:better-sqlite3/esbuild),使 `npm install` 可复现
26+
- `package.json` 记录 `allowScripts`(npm 11 安装脚本白名单:esbuild;better-sqlite3 13 起自带预编译产物、无需安装脚本),使 `npm install` 可复现
2627
- 仓库 `.gitignore` 修复乱码注释并补充本地验证残留(`.npm-cache/`、`.tmp-webui-*/`、`webui/.tmp-*/`)
2728

2829
## v2.4.0

‎webui/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@
55
- 规格:docs/design/(standalone-webui / process-definition / agents-runtime / gates-runner / api-contract / data-model / importing-existing / export-publish / ops-observability / scale-performance / webui-frontend 等十七篇)
66
- 技术栈:Node ≥ 22.19 · Fastify + better-sqlite3(WAL) · React 18 + Vite + antd + CodeMirror 6 · pi-ai / pi-agent-core @0.85.x
77

8+
## 运行环境(重要)
9+
10+
- Node **>= 22.19**(`engines`)。
11+
- **better-sqlite3 必须 >= 13**(本仓库已锁 `^13.0.3`):Node **v24.19.0** 存在 `node::ObjectWrap` 清理钩子回归([nodejs/node#65446](https://github.com/nodejs/node/issues/65446)),会让 better-sqlite3 < 13 的 `Statement` 在 GC 时命中 `Assertion failed: (env) != nullptr` 并**直接 abort 整个进程**(本仓库实测:打开小说工作台页即复现,服务当场消失;见 [better-sqlite3#1515](https://github.com/WiseLibs/better-sqlite3/issues/1515))。13 起改用 N-API(node-addon-api),不再走该路径,且自带跨 Node 版本预编译产物(无需 node-gyp / Python)。
12+
- 该下限由 `server/db/runtimeGuard.test.ts` 锁定:依赖被降级会直接测试失败。
13+
- 若必须在 24.19.0 上跑旧依赖,只能改用 Node 22.x / 24.18.x;本项目不依赖该环境。
14+
815
## 快速开始(开发)
916
```bash
1017
cd webui
@@ -24,7 +31,7 @@ npm start -- --port 3081 --root <workspace>
2431
2532
## 检查(guards)
2633
```bash
27-
npm install # npm 11 需先批准原生构建脚本:npm approve-scripts better-sqlite3 esbuild
34+
npm install # npm 11 需先批准原生构建脚本:npm approve-scripts esbuild
2835
npm run guards # typecheck(server+client) + vitest + check:no-python
2936
npm run guards:full # guards + smoke(起临时后端跑端到端断言)
3037
```

0 commit comments

Comments
 (0)