SSL握手失败通常源于客户端根证书库陈旧、TLS协议不兼容或证书路径配置错误；需更新系统证书、升级OpenSSL至1.1.1+、配置pip使用系统证书、替换JVM cacerts，并仅在调试环境临时禁用验证。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在安装WorkBuddy过程中遇到SSL握手失败错误，该问题通常源于客户端系统无法验证远程服务器（如QQ频道开放平台、证书颁发机构或依赖仓库）的HTTPS响应，常见诱因包括系统根证书库陈旧、缺失关键CA证书，或TLS协议版本不兼容。以下是解决此问题的步骤：
一、更新系统根证书库
操作系统内置的根证书信任库若长期未更新，将无法识别新签发或已轮换的SSL证书，导致握手时因“证书不受信任”而中止。尤其在使用较旧Linux发行版或未启用自动更新的容器环境中，该问题高发。
1、确认当前系统证书存储路径：Ubuntu/Debian系统通常为/etc/ssl/certs/ca-certificates.crt，CentOS/RHEL系统为/etc/pki/tls/certs/ca-bundle.crt。
2、执行系统级证书更新命令：Ubuntu/Debian运行sudo apt update && sudo apt install --reinstall ca-certificates；CentOS 7运行sudo yum update ca-certificates，CentOS 8+或RHEL 8+运行sudo dnf update ca-certificates。
3、强制刷新证书软链接：执行sudo update-ca-certificates --fresh（Debian系）或sudo update-ca-trust（RHEL系），确保新证书被加载至运行时信任链。
4、验证更新结果：运行openssl s_client -connect qun.qq.com:443 -servername qun.qq.com 2>/dev/null | openssl x509 -noout -issuer，检查输出中是否包含可信CA名称（如“DigiCert Trusted G5”或“GlobalSign Root CA”）。
二、升级OpenSSL与启用TLS 1.2/1.3支持
WorkBuddy安装脚本或其依赖组件（如pip、curl、Node.js fetch）若链接到过时的OpenSSL库（如1.0.2或更早），将默认禁用TLS 1.2及以上协议，而现代API服务（如QQ频道网关）已强制要求TLS 1.2+，握手必然失败。
1、检查当前OpenSSL版本：运行openssl version，若输出为OpenSSL 1.0.2*或低于1.1.1，需升级。
2、Ubuntu 20.04及以下用户：添加官方PPA源，执行sudo apt install software-properties-common && sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt update && sudo apt install openssl。
3、CentOS 7用户：启用EPEL与PowerTools仓库，运行sudo yum install epel-release && sudo yum config-manager --enable powertools && sudo yum install openssl11，随后设置环境变量export OPENSSL_CONF=/etc/ssl/openssl.cnf并重载shell。
4、验证TLS能力：执行openssl s_client -tls1_2 -connect qun.qq.com:443 -servername qun.qq.com 2>/dev/null | grep "Protocol"，应返回Protocol : TLSv1.2；同理测试-tls1_3确认支持。
三、配置Python pip使用更新后的证书路径
WorkBuddy安装常依赖pip拉取PyPI包，若pip未指向系统最新证书库，即使系统已更新，pip仍会沿用内置旧证书集，导致HTTPS连接失败。
1、定位pip当前信任证书路径：运行python -c "import pip._vendor.certifi; print(pip._vendor.certifi.where())"。
2、强制pip使用系统证书：创建或编辑~/.pip/pip.conf（Linux/macOS）或%APPDATA%\pip\pip.ini（Windows），在[global]节下添加global.cert = /etc/ssl/certs/ca-certificates.crt（路径按实际系统证书位置调整）。
WorkBuddy 会议助手——会议价值不该散会就流失。它把会议的采集、提炼、确认、分发串成一条流水线：从腾讯会议 / IMA / 企业微信多端取料，按 15 类场景模板自动提炼成结构化纪要，你过目确认后一键分发到钉钉、飞书、腾讯文档或企业微信。全程由 workflow 工作流编排驱动，只抽取不编造、先预览后推群、自动去重。 触发：「把会议纪要做一下发钉钉」「总结 IMA 里的 XX 录音」「按面试模板整理这场会」「把这场复盘发飞书」「发到腾讯文档让我手动改」「整理企业微信里的会议纪要」。 能力：腾讯
3、验证配置生效：执行pip install --upgrade pip --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org，观察是否跳过证书警告且安装成功。
4、如仍报错，临时覆盖环境变量：运行export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt（Linux/macOS）或set SSL_CERT_FILE=C:\Windows\System32\cacert.pem（Windows，需先下载最新cacert.pem），再执行pip命令。
四、替换Java运行时的cacerts信任库（适用于JVM版WorkBuddy）
若WorkBuddy以Java应用形式部署（如JAR包启动），其JVM内置cacerts文件可能多年未更新，无法验证QQ频道等现代HTTPS端点。
1、定位JVM cacerts路径：运行java -XshowSettings:properties -version 2>&1 | grep "java.home"，随后进入$JAVA_HOME/jre/lib/security/cacerts或$JAVA_HOME/lib/security/cacerts。
2、备份原文件：执行cp cacerts cacerts.bak。
3、下载最新Mozilla CA证书包：访问https://curl.se/ca/cacert.pem，保存为本地文件。
4、导入证书至JVM信任库：运行keytool -importcert -alias mozilla-ca -file cacert.pem -keystore cacerts -storepass changeit -noprompt（默认密码为changeit）。
5、验证导入结果：执行keytool -list -v -keystore cacerts -storepass changeit | grep "mozilla-ca"，确认别名存在且条目数显著增加。
五、绕过证书验证（仅限调试环境）
在严格隔离的离线开发或CI测试环境中，若无法即时同步公网证书，可临时禁用SSL验证以确认是否为证书问题本身，但严禁在生产环境启用该设置。
1、对pip命令添加全局忽略参数：在安装命令前添加PIP_DISABLE_PIP_VERSION_CHECK=1 pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org --trusted-host qun.qq.com。
2、对curl操作禁用验证：在WorkBuddy安装脚本中查找curl调用，将curl -X POST ...改为curl -k -X POST ...。
3、对Python requests库设置环境变量：在执行脚本前运行export PYTHONHTTPSVERIFY=0，使所有requests请求跳过证书校验。
4、对Node.js应用：启动时添加NODE_TLS_REJECT_UNAUTHORIZED=0环境变量，例如NODE_TLS_REJECT_UNAUTHORIZED=0 npm install。
