青龙面板中OpenSSL版本导致的SSL/TLS连接问题解析-优快云博客

青龙面板中OpenSSL版本导致的SSL/TLS连接问题解析

【免费下载链接】qinglong 支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台（Timed task management platform supporting Python3, JavaScript, Shell, Typescript）项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong

你是否在使用青龙面板时遇到过SSL/TLS连接失败的问题？特别是当执行JavaScript或Python脚本时，经常出现"SSL certificate problem"或"unable to verify the first certificate"等错误？本文将深入解析这些问题的根源，并提供详细的解决方案，帮助你彻底解决青龙面板中的SSL/TLS连接难题。

问题背景

青龙面板（Qinglong Panel）作为一款支持Python3、JavaScript、Shell、Typescript的定时任务管理平台，广泛应用于自动化脚本运行场景。然而，许多用户在使用过程中会遇到与SSL/TLS相关的连接问题，这些问题往往与系统中的OpenSSL版本密切相关。

问题表现与常见错误

在青龙面板中，OpenSSL版本不兼容或配置不当通常会导致以下几类错误：

"SSL: CERTIFICATE_VERIFY_FAILED" 证书验证失败
"sslv3 alert handshake failure" SSL握手失败
"unable to get local issuer certificate" 无法获取本地颁发者证书
"tlsv1 alert protocol version" TLS协议版本不支持

这些错误通常出现在执行需要网络请求的脚本时，特别是在调用HTTPS接口或访问需要SSL证书验证的网站时。

问题根源分析

OpenSSL版本兼容性

青龙面板使用Node.js环境（通过观察项目结构中的大量.ts和.js文件推测），而Node.js对SSL/TLS的支持依赖于系统中的OpenSSL库。不同版本的OpenSSL支持不同的TLS协议版本和加密套件：

OpenSSL 1.0.2及以下：不支持TLS 1.3
OpenSSL 1.1.0及以上：支持TLS 1.3
OpenSSL 3.0.0及以上：增强了安全性，但可能不兼容某些旧协议

如果青龙面板运行环境中的OpenSSL版本过低，可能无法与现代化的HTTPS服务器建立连接；反之，如果版本过高，可能会禁用一些旧的但仍在使用的加密套件。

青龙面板中的HTTP客户端实现

青龙面板的后端代码中，HTTP客户端是通过back/config/http.ts文件实现的。该文件使用了undici库作为HTTP客户端，代码如下：

import { request as undiciRequest, Dispatcher } from 'undici';

// ... 省略部分代码 ...

async function request(
  url: string,
  options?: RequestOptionsWithOptions,
): Promise<Dispatcher.ResponseData<null>> {
  const { json, form, body, headers = {}, ...rest } = options || {};
  const finalHeaders = { ...headers } as Record<string, string>;
  let finalBody = body;

  if (json) {
    finalHeaders['content-type'] = 'application/json';
    finalBody = JSON.stringify(json);
  } else if (form) {
    finalBody = form;
    delete finalHeaders['content-type'];
  }

  const res = await undiciRequest(url, {
    method: 'POST',
    headers: finalHeaders,
    body: finalBody,
    ...rest,
  });

  return res;
}

这段代码中，undiciRequest函数默认会使用系统的OpenSSL库进行SSL/TLS握手，但没有显式配置SSL选项，这可能导致在某些环境下出现兼容性问题。

解决方案

方案一：升级系统OpenSSL版本

检查当前系统OpenSSL版本：
```
openssl version
```

根据操作系统升级OpenSSL：

Ubuntu/Debian:

sudo apt update && sudo apt install openssl

CentOS/RHEL:
```
sudo yum update openssl
```
macOS (使用Homebrew):
```
brew update && brew upgrade openssl
```

重启青龙面板使更改生效：

docker restart qinglong
# 或根据你的部署方式重启

方案二：配置环境变量解决证书问题

青龙面板的环境变量管理脚本shell/env.sh提供了环境变量的存储和恢复功能。我们可以通过设置以下环境变量来解决证书问题：

编辑青龙面板的启动脚本，添加以下环境变量：

# 忽略证书验证（仅临时测试用，不推荐生产环境）
export NODE_TLS_REJECT_UNAUTHORIZED=0

# 指定CA证书路径
export SSL_CERT_FILE=/path/to/ca-certificates.crt
export SSL_CERT_DIR=/path/to/ca-certificates

如果你使用Docker部署青龙面板，可以在docker-compose.yml中添加环境变量：

environment:
  - NODE_TLS_REJECT_UNAUTHORIZED=0
  - SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

方案三：修改HTTP客户端配置

对于高级用户，可以修改青龙面板的HTTP客户端配置，显式指定SSL选项。编辑back/config/http.ts文件，修改request函数：

const res = await undiciRequest(url, {
  method: 'POST',
  headers: finalHeaders,
  body: finalBody,
  ...rest,
  // 添加SSL选项
  tls: {
    rejectUnauthorized: process.env.NODE_ENV === 'production', // 生产环境验证证书
    minVersion: 'TLSv1.2', // 指定最低TLS版本
    maxVersion: 'TLSv1.3', // 指定最高TLS版本
    // 可添加其他SSL选项
  }
});

修改后需要重新构建青龙面板：

npm install
npm run build

验证解决方案

修改配置后，可以通过以下方法验证是否解决了SSL/TLS连接问题：

在青龙面板中创建一个测试脚本：

const https = require('https');

https.get('https://api.github.com', (res) => {
  console.log('状态码:', res.statusCode);
  console.log('响应头:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
}).on('error', (e) => {
  console.error('错误:', e);
});

运行该脚本，如果能够成功输出GitHub API的响应，则说明问题已解决。
检查青龙面板的日志文件，确认没有SSL/TLS相关的错误信息。

预防措施

为了避免未来出现类似的SSL/TLS连接问题，建议采取以下预防措施：

定期更新青龙面板到最新版本，以便获取最新的安全修复和改进。
监控系统的OpenSSL版本，及时应用安全更新。
在编写脚本时，尽量使用青龙面板提供的HTTP客户端back/config/http.ts，而不是直接使用Node.js或Python的原生HTTP模块，以便统一管理SSL配置。
对于重要的定时任务，设置失败通知，以便及时发现和解决SSL/TLS连接问题。

通过以上方法，你应该能够有效解决青龙面板中由OpenSSL版本导致的SSL/TLS连接问题，确保定时任务的稳定运行。如果问题仍然存在，请检查你的网络环境是否有特殊限制，或在青龙面板的GitHub仓库提交issue寻求帮助。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考