Node.js N-API C++插件uv_try_write处SIGPIPE崩溃问题排查处理

根因分析 #

从采集到的堆栈可以直接定位崩溃链路：

• 触发起点：libc writev系统调用向已断开的socket写入数据，内核触发SIGPIPE信号
• 信号处理环节：你开发的N-API插件pm_interface.node注册的自定义信号处理函数linux_sig_handler被内核调用
• 崩溃点：信号处理函数内执行PAppLogger::flush_output刷日志，内部调用pthread_mutex_lock加锁时触发段错误，进程终止

核心问题有两个：

• Node.js 自带的libuv层默认会将SIGPIPE设置为忽略状态，正常纯JS场景下写已关闭socket只会返回EPIPE错误，不会触发信号终止进程。如果N-API插件自行创建socket、修改信号处理注册逻辑，会打破这个默认保护。
• 信号处理函数执行在异步信号上下文，只能调用操作系统明确标注为异步信号安全的函数。你在handler里做日志刷盘、互斥锁加锁操作都是明确违规的：如果信号触发时锁刚好被主线程持有，handler里重入加锁会直接触发死锁、内存越界，这才是崩溃的直接原因，SIGPIPE只是触发这个bug的诱因。

定位排查步骤 #

• 检查SIGPIPE处理配置：在插件初始化、socket操作前后调用sigprocmask获取当前SIGPIPE的处理动作，确认是否被修改为自定义处理/默认终止，正常Node.js进程中SIGPIPE应为SIG_IGN忽略状态。
• 审计插件socket逻辑：如果插件自行创建socket（未使用libuv/js层的Stream封装），检查是否设置了SO_NOSIGPIPE选项，write/send类调用是否携带MSG_NOSIGNAL标志，未做这些配置会导致写断开fd时触发SIGPIPE。
• 审计所有自定义信号处理函数：排查所有通过signal/sigaction注册的handler，确认是否存在调用非异步信号安全函数的逻辑，包括日志输出、内存分配释放、锁操作、v8/libuv接口调用、JS回调执行，这些操作在信号上下文执行必然存在崩溃风险。

修复与规避方案 #

从根源避免SIGPIPE信号触发 #

• 插件内自行创建的socket，创建后立即设置socket选项禁止触发SIGPIPE：

int opt = 1;
setsockopt(sock_fd, SOL_SOCKET, SO_NOSIGPIPE, &opt, sizeof(opt));

• 所有write/send/writev类写入socket的系统调用，携带MSG_NOSIGNAL标志，禁止写入操作触发SIGPIPE：

// writev调用示例
writev(sock_fd, iov_arr, iov_cnt, MSG_NOSIGNAL);
// send调用示例
send(sock_fd, buf, buf_len, MSG_NOSIGNAL);

• 无特殊需求不要修改SIGPIPE的默认处理逻辑，保持libuv设置的忽略状态即可，写入失败会通过返回值+errno返回EPIPE错误，走常规错误处理流程。

修复信号处理函数违规逻辑 #

• 信号处理函数内仅允许做最简单的标记操作，禁止任何复杂逻辑。标记变量必须使用volatile sig_atomic_t类型保证读写原子性，后续在libuv主循环的check/idle回调中（正常执行上下文）再处理日志、错误上报等逻辑。
• 现有错误写法（直接导致崩溃）：

// 错误：信号上下文直接刷日志、加锁
void linux_sig_handler(int sig, sigcontext sc) {
  PAppLogger::flush_output(); // 内部调用pthread_mutex_lock，非信号安全
}

• 正确写法：

// 全局信号标记
static volatile sig_atomic_t sigpipe_triggered = 0;

// 信号处理函数仅设标记
void linux_sig_handler(int sig, sigcontext sc) {
  if (sig == SIGPIPE) {
    sigpipe_triggered = 1;
  }
}

// 注册到libuv主循环的check回调，执行在正常上下文
void sig_check_cb(uv_check_t* handle) {
  if (sigpipe_triggered) {
    sigpipe_triggered = 0;
    // 此处可安全执行加锁、日志、错误处理逻辑
    PAppLogger::error("SIGPIPE triggered, socket write failed");
  }
}

兜底保护 #

• 插件初始化阶段显式设置SIGPIPE为忽略状态，覆盖其他模块可能错误修改的信号配置：

signal(SIGPIPE, SIG_IGN);

• 若需要统计SIGPIPE触发次数，严格按照上述标记位+主循环处理的方式实现，绝对不要在信号handler内执行复杂操作。

注意：当前崩溃本质是信号处理函数的非法操作导致的，就算触发信号不是SIGPIPE，其他信号命中这个handler同样有概率触发崩溃，必须优先修正信号处理逻辑。

内容的提问来源于stack exchange，提问作者Narendra Regar