koffi 在 Alpine 上直接 abort:一次 musl 预编译排查

1522 字
8 分钟
koffi 在 Alpine 上直接 abort:一次 musl 预编译排查
koffi 在 Alpine 上直接 abort:一次 musl 预编译排查

起因#

我的 dsh(DeepSeek Harness)跑在 Alpine Linux edge 上,环境是Node 24。dsh web 能正常启动,页面上问一句「4+4 等于几」也能正常回答,看起来一切正常。

但只要让它干点需要调用工具的活,比如执行一条 shell 命令,整个进程就会突然消失。日志里只有这么几行:

terminate called after throwing an instance of 'std::system_error'
what(): No error information
Aborted (core dumped)

退出码 134,也就是 SIGABRT。不是 JavaScript 异常,不是 unhandled rejection,是 C++ 层直接把进程终止了。

定位:问题出在 koffi#

dsh 的本地子进程执行器 dsh-subprocess-local 用 koffi 绑定 libc 的 execve、fcntl 等函数。koffi 是一个 Node.js 的 FFI 库,底层是原生 .node 模块。

先排除 dsh 本身的干扰,直接写一个最小复现:

Terminal window
node -e "require('koffi')"

同样 abort。再试试显式加载 musl 版本:

Terminal window
node -e "require('/usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@koromix/koffi-linux-arm64/musl_arm64/koffi.node')"

这次正常加载,没有崩溃。

问题范围一下就缩小了:musl 预编译二进制是好的,坏的是加载路径。

为什么回退逻辑没生效#

koffi 3.1.1 的平台包 @koromix/koffi-linux-arm64 里同时放了两个预编译二进制:

目录目标 C 库
linux_arm64/koffi.nodeglibc
musl_arm64/koffi.nodemusl

它的加载器逻辑非常直接:

let native = null;
let err = null;
if (native == null) {
try {
native = require("./linux_arm64/koffi.node");
} catch (e) {
err = e;
}
}
if (native == null) {
try {
native = require("./musl_arm64/koffi.node");
} catch (e) {
err = e;
}
}
if (native == null)
throw err;
module.exports = native;

设计意图是「先试 glibc,失败再试 musl」。问题在于:在 musl 上,glibc 版本不是抛一个普通的 JavaScript 异常,而是直接把进程 abort 掉。

dlopen 这一关它居然过了,然后进入 C++ 静态初始化,抛出 std::system_error,errno 还是 0。异常没人接,std::terminate 被调用,进程结束。加载器里的 catch 永远等不到执行机会。

也就是说,这段回退逻辑在 Alpine 上形同虚设:第一个 require 不是「失败」,是「同归于尽」。

后来查 koffi 的更新记录,3.3.8 已经改成先检测 libc 再选择预编译二进制。但 dsh 0.2.2-rc.1 固定依赖的是 koffi@3.1.1,所以这个问题在旧版本上依然存在。

修复思路:在加载之前改道#

既然不能等 require 失败,那就别让它去碰 glibc 版本。思路很简单:

.../linux_<abi>/koffi.node -> .../musl_<abi>/koffi.node

在 Node 真正打开文件之前,把请求重定向到 musl 兄弟目录。

这个改动需要同时覆盖两个入口:

  1. Module._load:koffi 加载器用的是相对路径 require("./linux_arm64/koffi.node"),会先经过这里;
  2. process.dlopen:Node 把 .node 请求解析成绝对路径后,最终从这里进入原生加载。

两个钩子都只做一件事:命中 linux_<abi>/koffi.node 时,检查同级的 musl_<abi>/koffi.node 是否存在;存在就替换,不存在就原样放行。

核心匹配逻辑大概是这样:

const GLIBC_PREBUILD = /(^|[\\/])linux_([a-z0-9_]+)[\\/]koffi\.node$/i
export function muslSibling(path) {
if (typeof path !== 'string' || !GLIBC_PREBUILD.test(path)) return undefined
return path.replace(GLIBC_PREBUILD, '$1musl_$2/koffi.node')
}

libc 检测没有去读 /etc/os-release,也没有 spawn ldd,而是用了 Node 自带的诊断报告:

const header = process.report.getReport().header
const isMusl = header.glibcVersionRuntime === undefined

Node 只在 glibc 主机上设置 glibcVersionRuntime,所以这个字段缺失就可以判断为 musl。拿不到报告时宁可保持不启用,也不猜。

整个修复是保守的:

  • 只在 Linux 上启用;
  • 只在 musl 上启用;
  • 只改写 koffi 的 linux_<abi>/koffi.node;
  • 只有 musl 兄弟文件确实存在才改写;
  • 其他平台、其他模块、其他路径完全不动。

实际效果#

修好之后,dsh web 启动时会多一行日志:

koffi-musl-fix: musl host detected; koffi will use its musl prebuild

再让它执行 shell 命令,子进程正常启动,工具调用正常返回,dsh web 进程也不再退出。

这个修复没有改 node_modules,也没有替换任何二进制文件。它只是在当前进程里改写了模块加载路径,所以 dsh 升级后不会留下烂摊子;如果哪天真升级到已经修复 libc 检测的 koffi,插件也可以直接卸掉。

怎么用#

项目地址:

qwc-ch/dsh-koffi-musl-fix

它既可以作为 dsh 插件安装,也可以作为普通的 Node 预加载模块使用。

作为 dsh 插件#

包内已经带了标准 dsh bundle 元数据:

"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}

bundle 层就是插入一行插件:

- insert:
- id: koffi-musl-fix
name: dsh-koffi-musl-fix

npm 包还没正式发布,目前可以直接从仓库安装:

Terminal window
# 从 Git 安装
dsh plugin --profile web add git+https://github.com/qwc-ch/dsh-koffi-musl-fix.git
# 或者从本地 checkout 安装
dsh plugin --profile web add /path/to/dsh-koffi-musl-fix

安装后重启 dsh。dsh plugin 需要 pnpm(或启动器提供的包管理器)。

手动挂 home 级补丁#

如果不想走 bundle 安装,也可以直接挂本地目录:

~/.dsh/cordis.patch.yml
- insert:
- id: koffi-musl-fix
name: ./plugins/dsh-koffi-musl-fix/index.mjs

~/.dsh/cordis.patch.yml 里的路径相对于 ~/.dsh/。确认配置解析到了:

Terminal window
dsh --profile web --dump-config | grep -A2 koffi-musl-fix

作为 Node 预加载#

不跑 dsh、只是自己的 Node 项目里用了旧版 koffi,也可以直接预加载:

Terminal window
npm install dsh-koffi-musl-fix
NODE_OPTIONS="--import dsh-koffi-musl-fix/preload" node app.mjs

预加载必须在 koffi 第一次 require 之前执行。用本地 checkout 的话:

Terminal window
node --import ./preload.mjs app.mjs

编程方式#

import { install } from 'dsh-koffi-musl-fix/core'
const fix = install({
onRedirect({ kind, from, to }) {
console.error(`koffi-musl-fix: ${kind} ${from} -> ${to}`)
},
})
// fix.active 当前不是 Linux/musl 时为 false
// fix.redirected 已改写的请求数量
// fix.uninstall() 恢复原始加载钩子

同样要在第一次 require('koffi') 之前调用。

适用范围和限制#

这个补丁不是万能药:

  • 只适用于旧版 koffi 的 linux_<abi>/koffi.node / musl_<abi>/koffi.node 目录结构,koffi 换布局就失效;
  • 只修 koffi,不是其他原生模块的通用方案;
  • 如果依赖范围允许,优先升级 koffi,3.3.8 之后已经不需要这个 workaround;
  • 测试环境是 Alpine edge / aarch64、Node 24、koffi 3.1.1、dsh 0.2.2-rc.1,其他 musl 发行版理论上同理,但没有逐个验证。

仓库#

代码、测试和完整文档都在这里:

  • GitHub:https://github.com/qwc-ch/dsh-koffi-musl-fix
  • 入口:index.mjs(dsh/Cordis 插件)、preload.mjs(Node 预加载)、lib/core.mjs(无框架核心逻辑)
  • 测试:node --test,覆盖路径映射、相对/绝对请求改写、dlopen 改写和 musl 检测

如果你也在 musl 上跑 dsh,或者被旧版 koffi 坑过,可以去仓库看看。遇到别的原生模块在 musl 上的类似问题,也欢迎开 issue 交流。

文章分享

如果这篇文章对你有帮助,欢迎分享给更多人!

koffi 在 Alpine 上直接 abort:一次 musl 预编译排查
https://blog.amamo.top/posts/koffi-musl-alpine-abort/
作者
Admin
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0

评论区

Profile Image of the Author
年华
Hello, 欢迎来到我的小破站。
统计
公告
欢迎来到我的博客。我会用AI对博文进入修改和润色。
分类
标签
最新动态
站点统计
文章
37
分类
22
标签
76
总字数
33,173
运行时长
0 天
最后活动
0 天前
天气预报
站点信息
构建平台
GitHub Actions
博客版本
Firefly v6.16.9
文章许可
CC BY-NC-SA 4.0
文章目录