Ubuntu Node.js日志中的SSL证书错误怎么解决

Ubuntu Node.js日志中SSL证书错误的常见类型及解决方法

在Ubuntu环境下，Node.js应用运行时遇到的SSL证书错误主要与证书有效性、信任链完整性、系统配置相关，以下是具体错误类型的诊断与解决步骤：

1. 证书过期（CERT_HAS_EXPIRED）

错误表现：Node.js或npm操作（如npm install）报错“certificate has expired”，无法访问远程资源。
解决方法：

检查系统时间：运行date命令确认Ubuntu系统时间是否准确（若时间偏差过大，可通过sudo timedatectl set-ntp true开启NTP时间同步）。

更新npm与证书库：

npm install -g npm  # 升级npm至最新版本
sudo apt update && sudo apt install --reinstall ca-certificates  # 重装系统CA证书
sudo update-ca-certificates  # 更新证书库

临时禁用严格SSL（仅测试环境）：
```
npm config set strict-ssl false  # 关闭npm的严格SSL验证
```
⚠️ 生产环境严禁禁用SSL，否则可能导致中间人攻击。

2. 证书链不完整（UNABLE_TO_VERIFY_LEAF_SIGNATURE）

错误表现：Node.js发起HTTPS请求时报错“unable to verify the first certificate”，无法验证服务器证书的有效性。
解决方法：

检查服务器证书链：使用OpenSSL命令查看目标服务器的证书链是否完整（需包含服务端证书→中间证书→根证书）：
```
openssl s_client -connect example.com:443 -showcerts
```
若输出中缺少中间证书，需联系服务器管理员补全证书链（如将中间证书追加到服务端配置的证书文件中）。

添加自定义CA证书（自签名/内部CA）：
将自签名证书或内部CA证书（如/path/to/ca.pem）添加到Node.js信任列表：

export NODE_EXTRA_CA_CERTS=/path/to/ca.pem  # 临时生效（当前终端会话）

或在代码中配置（适用于特定请求）：

const https = require('https');
const fs = require('fs');
const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET',
  ca: [fs.readFileSync('/path/to/ca.pem')],  // 指定自定义CA证书
  rejectUnauthorized: true  // 保持验证开启（安全）
};
const req = https.request(options, (res) => { /* 处理响应 */ });

✅ 此方法既解决了证书链问题，又保持了通信安全，适用于生产环境。

3. 自签名证书未被信任（DEPTH_ZERO_SELF_SIGNED_CERT）

错误表现：连接使用自签名证书的服务器时，报错“self signed certificate in certificate chain”。
解决方法：

临时禁用验证（仅测试环境）：
在代码中设置rejectUnauthorized: false（如前面的代码示例），或通过环境变量全局禁用：
```
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'  # 不推荐生产环境使用
```

永久信任自签名证书：
将自签名证书添加到系统信任库（Ubuntu使用ca-certificates包）：

sudo cp self-signed-cert.pem /usr/local/share/ca-certificates/  # 复制证书到CA目录
sudo update-ca-certificates  # 更新系统证书库

此后Node.js会自动信任该证书。

4. 证书SAN不匹配（ERR_TLS_CERT_ALTNAME_INVALID）

错误表现：证书的Subject Alternative Name（SAN）与请求的域名不一致，报错“hostname doesn’t match”。
解决方法：

检查证书SAN：使用OpenSSL查看证书的SAN信息：
```
openssl x509 -in server-cert.pem -text -noout | grep -A 1 "Subject Alternative Name"
```
确认输出的域名列表包含请求的域名（如example.com、www.example.com）。
修正请求域名：确保Node.js应用中请求的hostname与证书SAN一致（如代码中的hostname: 'www.example.com'）。
重新签发证书：若SAN配置错误，需联系证书颁发机构（CA）重新签发包含正确域名的证书。

5. 系统根证书过旧（无法识别新CA）

错误表现：Node.js无法验证由新CA（如Let’s Encrypt新签发的证书）签发的证书，报错“unable to get local issuer certificate”。
解决方法：

更新Ubuntu CA证书包：

sudo apt update && sudo apt install --only-upgrade ca-certificates
sudo update-ca-certificates

升级Node.js版本：旧版Node.js可能内置过时的根证书库，升级至最新LTS版本（如v20.x）可解决此问题：
```
nvm install --lts  # 使用nvm安装最新LTS版本
nvm use --lts      # 切换至最新版本
```
✅ 更新系统证书库和Node.js是解决此类问题的根本途径。

通用调试技巧

启用详细TLS日志：通过NODE_DEBUG=tls环境变量查看TLS握手过程的详细信息，帮助定位问题根源：
```
NODE_DEBUG=tls node your-app.js
```
使用在线工具验证证书：通过SSL Labs等工具检查服务器证书配置是否正确（如链完整性、SAN、有效期）。

以上方法覆盖了Ubuntu Node.js环境下常见的SSL证书错误，根据具体错误类型选择对应方案即可解决。生产环境中务必优先选择“添加自定义CA”或“修正证书链”的方式，避免禁用SSL验证带来的安全风险。