如何在Node.js的https模块中记录SSL握手日志排查连接失败？

阿华AIGC实验室

2026-5-25

排查Node.js双向SSL服务器连接失败：启用SSL握手日志方案

嘿，我来帮你搞定这个双向SSL连接的排查问题！Node.js的HTTPS模块其实提供了直接的调试日志能力，再加上代码里的事件监听，就能精准抓到握手阶段的所有细节，帮你定位客户端连不上的原因。

1. 快速启用全局SSL调试日志

最简单的方式是用Node.js的NODE_DEBUG环境变量，启动服务器时加上它就能输出SSL握手的全流程日志：

NODE_DEBUG=ssl node your-server-file.js

这个命令会打印出从客户端发起连接、证书交换到验证的每一步细节，比如CA证书是否匹配、客户端证书是否被接收、握手失败的具体错误码，这些信息足够帮你定位大部分常见问题，比如证书信任链缺失、客户端未提交证书之类的。

2. 代码内添加自定义握手日志（更灵活）

如果需要更定制化的日志记录，你可以监听HTTPS服务器的两个核心事件：secureConnection（握手成功时触发）和tlsClientError（握手失败时触发）。把你的代码改成这样：

var https = require('https');
var express = require('express');
var app = express();

var options = { 
  key: ..., 
  cert: ..., 
  ca: ..., 
  requestCert: true, 
  rejectUnauthorized: true 
};

const server = https.createServer(options, app);

// 记录成功的握手信息
server.on('secureConnection', (socket) => {
  console.log(`[SSL握手日志] 客户端 ${socket.remoteAddress} 握手成功`);
  console.log(`[SSL握手日志] 客户端证书状态: ${socket.authorized ? '已通过授权' : '未授权'}`);
  if (!socket.authorized) {
    console.error(`[SSL握手日志] 未授权原因: ${socket.authorizationError}`);
  }
});

// 捕获握手失败的错误细节
server.on('tlsClientError', (err, socket) => {
  console.error(`[SSL握手错误] 客户端 ${socket.remoteAddress} 连接失败`);
  console.error(`[SSL握手错误] 错误信息: ${err.message}`);
  console.error(`[SSL握手错误] 错误栈: ${err.stack}`);
});

server.listen(port, host, () => {
  console.log(`双向SSL服务器已启动: https://${host}:${port}`);
});