Python 证书验证失败表示 TLS 客户端无法确认连接所呈现的证书对于请求的主机名有效且受信任。请从完整错误消息、正在使用的 Python 解释器和客户端库,以及网络路径入手;然后根据证据修复系统时钟、主机名、服务器证书链或受信任 CA 配置。对于私有基础设施或经授权的检查代理,应配置从受信任管理员处获取的 CA 捆绑包,而不是关闭验证。本指南提供适用于标准库 HTTPS、requests 和 pip 的可复现诊断方法,包括如何确认修复结果。
初步处理与诊断范围
看到 [SSL: CERTIFICATE_VERIFY_FAILED] 时,请保留完整异常信息,尤其是 certificate verify failed 后面的文本。证书过期、主机名不匹配和缺少颁发者可能产生相同的概括性异常,但所需的修复方式不同。检查机器的日期、时间和时区;确认 URL 使用的是预期主机名;并确定失败发生在 urllib、requests、pip 还是其他客户端中。
使用与应用程序相同的解释器、环境、URL 和网络路径重现失败。对于 HTTPS 区块链 RPC 端点,请勿将 API 密钥或包含完整凭据的 URL 粘贴到日志或支持工单中。本文介绍服务器证书验证;客户端证书身份验证属于单独的配置问题。
浏览器能够成功访问并不能证明 Python 也能成功:浏览器和 Python 客户端可能使用不同的信任存储、代理设置或缓存的中间证书。反过来,TLS 连接成功只表示已建立经过身份验证的加密通道;这并不能证明 RPC 方法或应用凭据正确。
- 记录确切的主机名、异常详情、客户端库、Python 版本、操作系统或容器信息,以及是否涉及代理。
- 如果只有一个服务失败,请调查其证书和证书链;如果同一环境中的多个无关服务都失败,请调查本地信任配置、时间和网络拦截。
- 诊断期间保持验证启用。绝不要将
verify=False或全局未验证的 SSL 上下文作为生产环境修复方案。
前置条件与环境清单
请在实际发生失败的环境中使用终端:虚拟环境、容器、远程工作程序或 notebook 内核可能不会共享系统 Python 的软件包或证书。下面的标准库脚本不需要网络访问。请使用启动应用程序的那个解释器运行脚本;在 Windows 上,如有必要,请使用适当的 py 启动器。
ssl 报告的默认路径描述的是 OpenSSL 的默认配置,不一定是每个 HTTP 库使用的 CA 捆绑包。环境变量可以改变客户端行为,显式的应用程序配置也可以覆盖默认值。请将输出视为起点,而不是判断某个特定连接使用了哪个证书完成验证的依据。
- 单独检查代理设置,但不要打印凭据:
HTTPS_PROXY、HTTP_PROXY和NO_PROXY可能会影响路由。 - 对于 pip,请使用同一个解释器运行
python -m pip --version。在 notebook 中,请在内核内部检查sys.executable。 - 主机与其容器或 CI 作业之间的路径、环境变量和已安装 CA 软件包可能不同。
import os
import ssl
import sys
print('Python executable:', sys.executable)
print('Python version:', sys.version)
print('OpenSSL:', ssl.OPENSSL_VERSION)
print('Default verify paths:', ssl.get_default_verify_paths())
for name in ('SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'PIP_CERT'):
print(f'{name}:', os.environ.get(name, '<unset>'))
try:
import requests
print('requests version:', requests.__version__)
print('requests default bundle:', requests.certs.where())
except ImportError:
print('requests is not installed in this interpreter')证书验证与信任存储
在 TLS 握手期间,服务器会提供证书,通常还会提供构建证书链所需的中间证书,以连接到受信任的根证书颁发机构(CA)。客户端会检查该证书链、证书有效期以及请求的主机名。失败可能意味着服务器遗漏了中间证书、本地信任捆绑包缺少相关根证书,或者所呈现的证书对该主机名无效。
企业 TLS 检查代理可以使用组织控制的 CA 终止并重新签发 HTTPS 证书。如果代理经过授权,Python 客户端必须信任适当的组织 CA,以及其他目标所需的公共根证书。请通过组织经过身份验证的分发流程获取 CA 或经批准的捆绑包;不要盲目信任从当前失败连接中下载的证书。
Python 的标准 ssl 模块可以加载系统默认值或 OpenSSL 配置的默认值。Requests 通常使用其依赖配置提供的 CA 捆绑包,通常是 certifi;而 pip 的行为取决于其版本和 Python 版本。仅安装或导入 certifi 并不会配置所有客户端使用它。请参阅 Python SSL 文档 和 Requests 证书验证文档,了解相关客户端行为。
使用标准库重现问题
将 RPC_URL 设置为发生失败的 HTTPS URL,然后使用受影响的解释器运行此脚本。对于常规 Web 服务,也可以使用其 HTTPS URL 进行相同测试。脚本会发送 GET 请求,因此请使用允许此类请求的端点;测试 TLS 握手不要求应用程序返回成功响应。如果变量中包含密钥,请避免显示或分享该变量。
下面会单独报告 401、404 或 405 等 HTTP 错误:这表示 TLS 已完成且服务器返回了 HTTP 响应,并不表示应用程序请求成功。发生验证异常时,如果可用,脚本会打印 OpenSSL 的验证消息。
- 仅在策略允许的情况下比较容器内外或代理内外的结果;差异可以缩小调查范围,但本身无法确定原因。
- 标准库可以遵循代理环境变量。直接连接测试和经过代理的应用程序请求可能会到达呈现不同证书的服务端。
- 超时、DNS 失败和连接被拒绝不是证书验证失败;请单独排查这些网络问题。
import os
import ssl
import urllib.error
import urllib.request
url = os.environ['RPC_URL']
if not url.lower().startswith('https://'):
raise SystemExit('RPC_URL must use HTTPS')
try:
with urllib.request.urlopen(url, timeout=10) as response:
print('TLS succeeded; HTTP status:', response.status)
except urllib.error.HTTPError as exc:
print('TLS succeeded; HTTP error status:', exc.code)
except urllib.error.URLError as exc:
reason = exc.reason
if isinstance(reason, ssl.SSLCertVerificationError):
print('Certificate verification failed:', reason.verify_message)
else:
print('Connection failed:', type(reason).__name__, str(reason))解读证书失败详情
结合最具体的错误消息和环境清单选择修复方案。错误措辞会随 Python 和 OpenSSL 版本而变化;仅凭颁发者错误无法区分服务器证书链不完整、客户端缺少信任锚,还是存在检查代理。
如果你负责运行该服务,请检查实际路径上呈现的叶证书和中间证书,包括请求主机名对应的 SNI。例如,openssl s_client -connect HOST:443 -servername HOST -showcerts 可以显示直接连接所呈现的证书;请将 HOST 替换为主机名,而不是 URL。此命令不会自动重现 HTTP 代理路径,所显示的证书本身也不能证明证书链受信任。请勿分享敏感的连接详情。
certificate has expired或not yet valid:检查系统时钟和证书有效期;续期或替换无效的服务器证书。hostname mismatch或 IP 地址不匹配:使用预期的 DNS 主机名,或者让服务器运营方签发主题备用名称覆盖当前地址的证书。unable to get local issuer certificate或self-signed certificate in certificate chain:在修改信任配置前,调查服务器提供的中间证书、客户端 CA 捆绑包以及经授权的代理。- 私有部署或自签名部署需要显式信任的证书或私有 CA,并通过受控流程进行分发和轮换。
Python 客户端的 CA 捆绑包配置
对于公共服务器,优先在服务器端修复不完整的证书链,并更新受影响环境中受支持的 CA 软件包。对于经授权的私有 CA 或检查代理,请从管理员处获取 PEM 捆绑包,并在使用前验证其来源。显式捆绑包可能会替代客户端通常使用的根证书,而不是在其基础上添加证书,因此请提供包含应用程序目标所需全部信任锚的经批准捆绑包。信任额外的根证书会扩大可用于验证这些目标的颁发者范围;请相应地限定访问权限并管理变更。
下面的示例会将经批准的捆绑包加载到标准库默认上下文中,并发出 HTTPS 请求。将 CA_BUNDLE 设置为绝对 PEM 文件路径,将 RPC_URL 设置为预期端点。在这里提供 cafile 会使用该捆绑包,而不是隐式加载默认 CA 证书;主机名验证仍保持启用。
对于 Requests,等效的单请求设置是 requests.get(url, verify='/path/to/approved-bundle.pem', timeout=10)。会话可以使用 session.verify 设置作用域内的默认值。REQUESTS_CA_BUNDLE 可以通过环境变量配置 Requests;标准 OpenSSL 默认值则可能使用 SSL_CERT_FILE。这些变量并不能保证对每个库都可互换,显式设置也可能具有更高优先级。请查阅具体客户端的文档。
import os
import ssl
import urllib.error
import urllib.request
url = os.environ['RPC_URL']
if not url.lower().startswith('https://'):
raise SystemExit('RPC_URL must use HTTPS')
context = ssl.create_default_context(cafile=os.environ['CA_BUNDLE'])
try:
with urllib.request.urlopen(url, context=context, timeout=10) as response:
print('TLS succeeded; HTTP status:', response.status)
except urllib.error.HTTPError as exc:
print('TLS succeeded; HTTP error status:', exc.code)
except urllib.error.URLError as exc:
print('Connection failed:', type(exc.reason).__name__, str(exc.reason))pip、操作系统与隔离环境
如果 python -m pip install 失败,请先确认解释器、pip 版本、索引主机名、代理路径和时钟。Pip 支持使用 python -m pip install --cert /path/to/approved-bundle.pem PACKAGE 临时指定 CA 捆绑包;请替换其中两个占位符。PIP_CERT 设置也是一种选择。用于安装软件包的捆绑包必须覆盖软件包索引,以及 pip 会访问的其他 HTTPS 主机。
Pip 的证书存储行为取决于版本。根据 pip HTTPS 证书文档,在 Python 3.10 或更高版本上运行的 pip 24.2 及更高版本,默认会在 certifi 之外使用系统证书。更早的版本组合有所不同。适当时,请通过已经受信任的渠道升级 pip 或 CA 软件包;如果下载本身因同一信任失败而被阻止,尝试升级就无法修复该下载问题。
对于从 python.org 安装的 macOS Python,该安装可能会针对特定 Python 版本包含 Install Certificates.command。请使用安装随附的脚本,并检查其行为;它并不是 Homebrew、系统 Python 或容器 Python 的通用修复方案。在 Linux 和容器中,请检查发行版的 CA 证书软件包及其更新机制。在 Windows 上,请确定实际客户端使用的是哪个存储,而不要假设每个 Python 库都会自动使用 Windows 信任存储。
虚拟环境、conda 环境、容器镜像或 notebook 内核可能拥有自己的解释器和信任配置。请在正常部署工作流中重建或更新环境,并在更改环境变量或挂载的证书文件后重启受影响的进程。对于 conda,请查阅其自身的 SSL 和代理配置,不要假设 pip 设置会生效。
验证与可复现结果
对于 RPC 集成,请随后使用网络和客户端支持的无破坏性方法执行测试。不要仅根据 GET 响应推断端点健康状况,也不要记录 API 密钥、授权标头或包含凭据的完整 URL。
持续失败、权衡与后续步骤
如果错误仍然存在,请确认运行中的进程确实读取了更新后的捆绑包,并且该文件在其执行环境中可读取。检查是否存在过期的显式 verify 或 SSL 上下文设置、呈现不同证书的代理,以及不完整的服务器证书链。请与服务运营方或网络管理员对照证据;提供主机名、经过清理的错误信息、客户端版本以及相关证书颁发者详情,不要提供机密信息。
显式 CA 文件可以让信任关系更易于审计和移植,但需要进行分发和轮换。使用操作系统存储可以简化集中管理的信任配置,但前提是具体客户端和版本确实使用该存储。私有 CA 应限制在需要它的环境中使用。禁用验证会绕过证书链和主机名检查,使凭据和响应暴露于拦截风险中;这不是可靠的变通方案。
对于 OnFinality 集成,请查看 API 服务,检查 可用网络,并使用 RPC 端点指南了解端点概念。规划基础设施时,请查看 RPC 定价 和 专用节点选项,并浏览 Learn 资源库获取相关实现指导。这些资源不能替代对连接实际呈现证书的诊断。