python requests ssl证书验证失败怎么排查?从 certifi 到企业根 CA 的完整修复步骤
python requests ssl证书验证失败最常见的原因是 requests 2.32.x 默认使用 certifi 的 cacert.pem,而该文件不含企业自签根 CA;先用 `requests.certs.where()` 确认路径,再合并根 CA 或用 `REQUESTS_CA_BUNDLE` 指向新 bundle。 定位命令:`openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts`,若输出 `Verify return code: 20 (unable to get local issuer certificate)`,说明缺中间证书或根 CA 不受信。 修复命令:`cat $(python -c 'import certifi;print(certifi.where())') corp-root.pem > /etc/ssl/certs/corp-bundle.pem`,再 `export REQUESTS_CA_BUNDLE=/etc/ssl/certs/corp-bundle.pem`,进程内所有 Session 生效。 `verify=False` 只用于本地确认根因,生产禁用;需要复用系统证书库时,Python 3.10+ 可在导入 requests 前调用 `truststore.inject_into_ssl()`。 验证:`openssl verify -CAfile corp-bundle.pem -untrusted chain.pem server.pem` 返回 `OK`,同时用旧 bundle 做负向测试应再次报 `CERTIFICATE_VERIFY_FAILED`。
python requests ssl证书验证失败:报错到底来自哪一层?
先把异常链完整打出来,它直接告诉你故障发生在哪一层。在 Python 3.11 和 requests 2.32.3 下,一次失败长这样:
# 用 -X dev 或直接捕获异常并打印 __cause__ 链,才能看到最底层信息
import requests
try:
requests.get("https://intranet.corp.example/", timeout=5)
except requests.exceptions.SSLError as e:
print(repr(e)) # 第一层:requests.exceptions.SSLError
print(repr(e.args[0])) # 第二层:urllib3.exceptions.SSLError
raise e.__cause__ # 第三层:ssl.SSLCertVerificationError
# 典型输出(行号随 Python 版本变化):
# SSLError(MaxRetryError("HTTPSConnectionPool(host='intranet.corp.example', port=443):
# Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(
# 1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
# unable to get local issuer certificate (_ssl.c:1006)'))))"
这条链说明:requests 只是把 urllib3 的异常包了一层,真正做判断的是 Python ssl 模块,底层是 OpenSSL 3.x。据 Python 官方 ssl 模块文档,SSLContext.verify_mode 默认就是 CERT_REQUIRED,check_hostname 默认 True;requests 侧 verify=True 也是默认值,Session.verify 与单请求的 verify= 同时生效且后者优先——所以”我没写 verify”从来不是免检的理由。
先把版本栈钉死,不同版本默认信任库不同(urllib3 2.2 起支持 truststore 走系统证书库):
python -c "import requests,urllib3,certifi,ssl;
print('requests',requests.__version__); print('urllib3',urllib3.__version__);
print('certifi',certifi.__version__, certifi.where()); print(ssl.OPENSSL_VERSION)"
# 期望:requests 2.32.x / urllib3 2.2.x / certifi 2024.x
# /Users/x/site-packages/certifi/cacert.pem / OpenSSL 3.0.13
三大根因按出现频率排列:
- CA 集合不匹配:默认只加载
certifi.where()那个 PEM 文件,企业自签根 CA 不在里面,于是报unable to get local issuer certificate。这是内网服务最常见的一类。 - 代理中间人:设了
HTTPS_PROXY=http://proxy.corp:8080后,代理用自己的 CA 重签证书,客户端不信任该 CA 同样抛CERTIFICATE_VERIFY_FAILED,而且报错域名看着完全正常,极易误判成服务端问题。 - 主机名、时间、TLS 版本:证书 SAN 不含请求域名(报
hostname mismatch);系统时间漂移超过 300 秒;服务端只开 TLS 1.0/1.1 或 SHA-1 签名,被 OpenSSL 3.x 默认SECLEVEL=2拒绝,都表现为 SSLError。
用 s_client 在客户端机器上复现握手,一次性区分”链不完整”和”根不受信”:
# -showcerts 打印服务端实际下发的整条链;-servername 必须带,否则拿到默认站点证书
openssl s_client -connect intranet.corp.example:443
-servername intranet.corp.example -showcerts -CAfile "$(python -c 'import certifi;print(certifi.where())')" </dev/null 2>&1 |
grep -E "Verify return code|^ *[0-9]+ s:|subject=|issuer="
| Verify return code | 含义 | 修复方向 |
|---|---|---|
0 (ok) |
链路完整且根受信 | 问题不在证书链,查主机名/时间/TLS 版本 |
20 |
unable to get local issuer certificate | 根 CA 不在信任库,或服务端没发中间证书 |
21 |
unable to verify the first certificate | 服务端漏发中间证书,需在服务端补全链 |
62 |
hostname mismatch | 证书 SAN 不含该域名 |
据 Let’s Encrypt 文档,完整证书链必须包含”叶证书 + 全部中间证书”,服务端漏发中间证书是最常见的部署失误;而 OpenSSL 官方文档明确 SECLEVEL=2 会拒绝 1024 位 RSA 与 SHA-1 签名,这解释了为何老内网设备在升级到 OpenSSL 3.x 后突然”证书验证失败”。
第一步到第四步:先定位 python requests ssl证书验证失败的真实原因
看到 SSLCertVerificationError,先别急着加 verify=False。它会把”根 CA 缺失””证书链不完整””主机名不匹配”三类完全不同的故障一起吞掉,让你在错误的层面上修问题。下面四步按”从报错原文到环境因素”的顺序定位,每步都留下可复核的输出。
第一步:原样复现,保留完整 traceback。用最小脚本触发,不要带任何 verify 参数。
# 不要加 verify=False,否则根因被掩盖;timeout 防止卡在握手上
python -c "import requests; requests.get('https://api.example.com', timeout=5)"
典型输出:requests.exceptions.SSLError: HTTPSConnectionPool(host=’api.example.com’, port=443): Max retries exceeded … (Caused by SSLError(SSLCertVerificationError(1, ‘[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)’)))。错误串决定了后续方向,对照下表:
| 报错片段 | 真实含义 | 下一步 |
|---|---|---|
| unable to get local issuer certificate | 服务端未下发中间证书,或本地缺根 CA | 走第三步看链 |
| self-signed certificate in certificate chain | 链中出现企业自签根 | 导入企业根 CA |
| Hostname mismatch / IP address mismatch | SNI 与实际 Host 不一致(RFC 6125 主机名校验) | 核对 servername |
| certificate has expired / not yet valid | 证书有效期或本机时钟问题 | 比对 date -u |
第二步:确认 requests 实际信任哪个 CA 包。requests 默认不读系统信任库,而是用 certifi 的 cacert.pem(据 certifi 文档,2024.08.30 版约 130 个根证书);只有当环境变量 REQUESTS_CA_BUNDLE 或 CURL_CA_BUNDLE 被设置时才改变。
# 两行通常指向同一文件;若不同,说明有人改过 REQUESTS_CA_BUNDLE
python -c "import requests,certifi;print('requests:',requests.certs.where());print('certifi :',certifi.where())"
# 系统默认信任库里的 CA 数量,与 certifi 数量不同即证明两者不等价
python -c "import ssl;print(len(ssl.create_default_context().get_ca_certs()))"
第三步:绕开 Python,用 openssl 独立看服务端链。这样能区分”服务端配置问题”和”客户端信任问题”。
# -servername 触发 SNI;只取叶子证书的 subject/issuer/有效期
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null
| openssl x509 -noout -subject -issuer -dates
# issuer 若是 CN=Corp Internal Root CA 之类,说明必须补企业根 CA,而不是换 certifi 版本
openssl s_client -connect api.example.com:443 -servername api.example.com -CAfile corp-root.pem /dev/null | grep 'Verify return code'
# 期望 Verify return code: 0 (ok)
第四步:排查环境侧的三类干扰项。
env | grep -iE 'https?_proxy|no_proxy' # requests 读取 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY
date -u # 与服务端 Date 头比较,偏差建议小于 300 秒
python -c "import ssl,sys;print(sys.version);print(ssl.OPENSSL_VERSION)"
代理场景下,拦截 TLS 的中间设备会签发自己的根 CA,必须向网络组索取该 PEM 并用 REQUESTS_CA_BUNDLE 指向它;no_proxy 没覆盖内网域名同样会走到代理上。版本方面,Python 3.12 自带 OpenSSL 3.x,而 macOS 系统 Python 常编译于 LibreSSL 2.8.3,urllib3 v2 会直接打印 NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the ‘ssl’ module is compiled with ‘LibreSSL 2.8.3’——这种环境本身就不适合作为排查基准,建议换 python.org 官方安装包或容器镜像复测。
第五步到第八步:修复 python requests ssl证书验证失败(不改业务代码也能生效)
拿到企业根 CA 的原始文件(常见 .crt/.cer,多为 DER 编码)后,先转成 OpenSSL 与 Python 都能直接读取的 PEM,并核对指纹——这一步是确认”你装进去的确实是公司那台 CA,而不是同名中间证书”的唯一可靠手段。据 OpenSSL 官方文档,-inform DER 与 -outform PEM 分别指定输入/输出编码,默认输入即为 PEM。
# 1) DER → PEM(若原文件已是 PEM,可省略 -inform DER)
openssl x509 -in corp-root.crt -inform DER -out corp-root.pem -outform PEM
# 2) 核对 Subject 与 SHA-256 指纹,与企业 IT 公告的指纹逐位比对
openssl x509 -in corp-root.pem -noout -subject -fingerprint -sha256
# 输出示例:
# subject=C = CN, O = Example Corp, CN = Example Corp Root CA
# sha256 Fingerprint=3A:7F:...:C1
# 3) 确认是自签根(Issuer == Subject)且未过期
openssl x509 -in corp-root.pem -noout -issuer -dates
6. 合并 certifi 与企业根 CA。requests 默认只信任 certifi 包内置的 Mozilla 根证书库,企业根 CA 不在其中,所以必须做”叠加”而非”替换”——直接把自己的 CA 覆盖 certifi 会让所有公网站点立刻报错。
# 定位 certifi 路径并追加企业根 CA
cat "$(python -c 'import certifi;print(certifi.where())')" corp-root.pem
> /etc/ssl/certs/corp-bundle.pem
# 校验:证书数量应等于原 certifi 数量 + 1
grep -c 'BEGIN CERTIFICATE' /etc/ssl/certs/corp-bundle.pem
若计数没变,说明 corp-root.pem 里没有 -----BEGIN CERTIFICATE----- 行(多半是第 5 步编码转错了)。注意 certifi.where() 指向 site-packages 内文件,升级 certifi 时会被覆盖,因此合并产物务必另存到 /etc/ssl/certs/ 这类稳定路径。
7. 环境变量方式(零代码改动)。据 requests 官方文档,CA bundle 的解析优先级为:REQUESTS_CA_BUNDLE > CURL_CA_BUNDLE > certifi 内置文件。这也是”python requests ssl证书验证失败”在企业环境里最推荐的修复方式——容器、CI、虚拟环境一改全生效,不必触碰业务代码。
# 写入 shell 配置或 Dockerfile ENV / CI 的 env 段
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/corp-bundle.pem
# 备选(部分工具链同时读这个变量)
export CURL_CA_BUNDLE=/etc/ssl/certs/corp-bundle.pem
# 验证:不发请求,先确认 requests 认到的路径
python -c "import os;print(os.environ.get('REQUESTS_CA_BUNDLE'))"
8. 代码方式(需要显式控制时)。Session.verify 对整个会话生效,单请求的 verify 参数优先级更高。据 requests 文档,timeout=(3.05, 27) 中的 3.05 秒是连接超时(业界惯例取略大于 3 的 TCP 重传窗口),27 秒是读取超时;不设 timeout 会让故障时的线程无限挂起。
import requests
s = requests.Session()
s.verify = '/etc/ssl/certs/corp-bundle.pem' # 会话级
r = s.get('https://intranet.example.com/api', timeout=(3.05, 27))
# 或单请求级(临时覆盖,不改全局)
r = requests.get('https://intranet.example.com/api',
verify='/etc/ssl/certs/corp-bundle.pem',
timeout=(3.05, 27))
容器与 CI 的系统级做法。把根 CA 装进系统信任库,对 curl、git、pip 同样有效;但 requests 仍只读 certifi,所以系统级与 REQUESTS_CA_BUNDLE 往往要一起做。
| 发行版 | 放置路径 | 刷新命令 | 对 requests 是否直接生效 |
|---|---|---|---|
| Debian / Ubuntu | /usr/local/share/ca-certificates/corp-root.crt |
update-ca-certificates |
否,需再设 REQUESTS_CA_BUNDLE |
| RHEL / CentOS / Rocky | /etc/pki/ca-trust/source/anchors/ |
update-ca-trust extract |
否,同上 |
| Alpine | /usr/local/share/ca-certificates/ |
update-ca-certificates |
否,同上 |
# Debian/Ubuntu 完整序列
cp corp-root.crt /usr/local/share/ca-certificates/corp-root.crt
update-ca-certificates # 输出 "1 added"
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/corp-bundle.pem
# RHEL 系
cp corp-root.pem /etc/pki/ca-trust/source/anchors/
update-ca-trust extract
临时绕过只用于定位根因。verify=False 会打印 InsecureRequestWarning: Unverified HTTPS request is being made to host ...,它只说明”跳过了校验”,并不能证明证书链有效——真正的修复永远是让校验通过。若必须本地调试,请保留告警(不要 urllib3.disable_warnings()),且不得合入主分支。据 Let’s Encrypt 文档,证书链不完整与本地信任库缺失是两类最常见的验证失败原因,前者需服务端补中间证书,后者才是本节要解决的。
配置与命令示例:python requests ssl证书验证失败的可用片段
第一步:先固定版本,别让 certifi 在 CI 里“偷偷升级”
很多“同一份代码,本地通过、CI 失败”的根因是 certifi 的 CA 包随依赖解析漂移。据 certifi 官方仓库说明,它打包的是 Mozilla CA 根证书集合,随版本更新会增删根证书。因此先锁定一组可复现基线,并把版本写进日志:
# 适用 Python 3.8+;这三个版本组合在 2024 年 Q3 是常见稳定基线
pip install requests==2.32.3 certifi==2024.8.30 urllib3==2.2.3
# 把实际生效版本打印到 CI 日志,出问题时可回放
pip show requests certifi urllib3
# 输出示例(节选):
# Name: requests / Version: 2.32.3 / Requires: certifi, charset-normalizer, idna, urllib3
# Name: certifi / Version: 2024.8.30
# Name: urllib3 / Version: 2.2.3
注意 requests 2.32.x 对 certifi 的声明是 certifi>=2017.4.17,上限是开放的——这正是漂移的来源,建议在 requirements 里用 == 而非 >=。
第二步:最小可复现脚本,返回 200 且未被重定向才算“通”
企业网关常见“证书其实没问题,但被 302 重定向到 SSO 登录页”,所以只看 status_code 不够,要同时看 r.url。另外 requests 的 timeout 默认值是 None(无限等待),必须显式给值:
import requests
r = requests.get(
'https://api.example.com/health',
verify='/etc/ssl/certs/corp-bundle.pem', # 显式指向企业 CA bundle
timeout=5, # 默认 None,不设会挂死
allow_redirects=False, # 防止被 302 到登录页后误判成功
)
print(r.status_code, r.url) # 期望 200 且 URL 未变
若失败,典型报错是:requests.exceptions.SSLError: ... (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)')))——unable to get local issuer certificate 基本等价于“缺中间证书或企业根 CA 未入 bundle”。
第三步:Session 复用 + 重试,避免握手抖动被误判成证书问题
urllib3 的 Retry 默认 total=10,但 requests 的 HTTPAdapter 默认 max_retries=0,即默认不重试。企业代理下 502/503 很常见,显式配置:
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
s = requests.Session()
s.mount('https://', HTTPAdapter(max_retries=Retry(
total=3,
backoff_factor=0.5, # 退避 0.5s/1s/2s
status_forcelist=[502, 503, 504],
allowed_methods=frozenset(['GET', 'HEAD']), # urllib3 2.x 参数名,1.x 为 method_whitelist
)))
s.verify = '/etc/ssl/certs/corp-bundle.pem'
print(s.get('https://api.example.com/health', timeout=5).status_code)
第四步:走代理时必须“双管齐下”
requests 会读取 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量(Session.trust_env 默认 True)。代理做 TLS 中间人时,必须把代理的根 CA也合入 bundle;NO_PROXY 用逗号分隔,支持域名后缀写法:
export HTTPS_PROXY=http://proxy.corp:8080
export NO_PROXY=".corp.example.com,localhost,127.0.0.1" # 逗号分隔,无空格
# 合并企业根 CA + 代理根 CA + certifi 公共根
cat /etc/ssl/certs/corp-root.pem /etc/ssl/certs/proxy-root.pem
"$(python -c 'import certifi;print(certifi.where())')" > /etc/ssl/certs/corp-bundle.pem
第五步:用 openssl 把“证书链”与“Python 配置”解耦验证
这一步能立刻区分是链不完整还是代码写错。-untrusted 用于提供中间证书:
# 抓取服务端证书链
openssl s_client -connect api.example.com:443 -servername api.example.com
-showcerts chain.pem
# 拆分出叶子证书 server.pem(第一段)后校验
openssl verify -CAfile /etc/ssl/certs/corp-bundle.pem
-untrusted chain.pem server.pem
# 成功:server.pem: OK
# 失败:server.pem: error 21 at 0 depth lookup: unable to verify the first certificate
据 OpenSSL 官方
verify(1)手册,error 20表示无法获取本地颁发者证书,error 21表示无法验证第一个证书——前者多为缺根/中间证书,后者多为顺序或-untrusted未提供。
第六步(可选):用 truststore 直接复用操作系统证书库
据 truststore 官方文档,它在导入 requests 之前调用 inject_into_ssl(),把 ssl.SSLContext 的验证委托给 OS 信任库(Windows CryptoAPI / macOS Keychain / Linux OpenSSL 默认路径),企业通过 GPO 或 MDM 下发的根 CA 会自动生效,无需维护 bundle 文件:
pip install truststore==0.10.0 # 要求 Python 3.10+
import truststore
truststore.inject_into_ssl() # 必须在 import requests 之前执行
import requests
print(requests.get('https://api.example.com/health', timeout=5).status_code)
几种 CA 来源方案怎么选
| 方案 | 关键写法 | 默认值/适用版本 | CI 可复现性 | 适用场景 |
|---|---|---|---|---|
| certifi 默认 | verify=True |
requests 默认即 True |
中,随 certifi 版本漂移 | 访问公网、无企业 CA |
| 环境变量指定 bundle | REQUESTS_CA_BUNDLE=/path/bundle.pem |
优先级高于 verify=True |
高 | 容器/CI 统一注入 |
代码内 verify= 路径 |
verify='/etc/ssl/certs/corp-bundle.pem' |
覆盖环境变量 | 高 | 单脚本、可显式审计 |
| truststore 注入 | truststore.inject_into_ssl() |
truststore 0.10.0,Python 3.10+ | 取决于 OS 镜像 | 复用企业系统证书库 |
| 关闭校验 | verify=False |
会触发 InsecureRequestWarning |
— | 仅限一次性排障,禁止上线 |
优先级顺序值得记住:verify= 参数 > REQUESTS_CA_BUNDLE > CURL_CA_BUNDLE > certifi 内置 bundle。排障时先确认到底哪一层在生效,再去改证书,能省掉大半时间。
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- Wildcard 通配符 SSL 证书安装部署续费申请
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- APP/小程序 HTTPS · SSL网站加密证书 · CA证书配置
- SSL证书安装服务 · 腾讯云 HTTPS 部署 · 证书过期更新
- NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
方案对比:REQUESTS_CA_BUNDLE、verify 参数、系统 CA 与 verify=False 怎么选?
先给结论:内网自签证书优先用 verify 参数或 REQUESTS_CA_BUNDLE;公网证书链过期或被替换,先升级 certifi;想让 requests 复用操作系统信任库,就用 truststore;verify=False 只允许出现在本机临时调试的命令行里。这四种方案常被混为一谈,但它们的生效层级完全不同——据 requests 官方文档,默认情况下 verify=True 指向的是 certifi 随包分发的 cacert.pem,而非 /etc/ssl/certs,所以“我在系统里装了根 CA 为什么还报错”是最常见的误判。
| 方案 | 生效范围 | 安全性 | 适用场景 |
|---|---|---|---|
verify='/path/corp-bundle.pem' |
单请求或单个 Session | 高 | 内网自签、需要精确控制信任集的调用 |
REQUESTS_CA_BUNDLE |
进程级 | 高 | 容器/CI 中统一注入,不侵入业务代码 |
系统 CA(update-ca-certificates) |
系统级 | 高 | requests 默认不读,须配合 truststore 或指向系统 bundle |
truststore.inject_into_ssl() |
进程级 | 高 | Python 3.10+ 直接复用操作系统信任库 |
verify=False |
单请求 | 低 | 仅限本地排障,禁止进入生产与公共库 |
| 升级 certifi | 进程级 | 中 | 公网证书链更新;对企业自签根 CA 无效 |
最省事也最可审计的做法是自建合并 bundle:把企业根 CA 追加到 certifi 的证书后面,得到一份专属 PEM,再用环境变量注入。
# 1) 查当前 certifi 证书位置(requests 默认信任的就是这个文件)
python -c "import certifi; print(certifi.where())"
# 2) 合并:certifi 公共根 + 企业根 CA(顺序无关,重复证书不影响校验)
cat "$(python -c 'import certifi; print(certifi.where())')"
/etc/ssl/certs/corp-root-ca.pem > /etc/ssl/certs/corp-bundle.pem
# 3) 进程级生效;不设置时 REQUESTS_CA_BUNDLE 默认为空,requests 回落到 certifi
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/corp-bundle.pem
python -c "import requests; print(requests.get('https://intranet.example.com/api', timeout=10).status_code)"
如果只有个别调用走内网,就不要污染全局环境,直接传参(requests 2.32.x 中 verify 默认值为 True,也接受 CA 目录路径):
import requests
# verify 指向 PEM 文件(或包含哈希链接的 CA 目录),仅对本次请求生效
r = requests.get("https://intranet.example.com/api",
verify="/etc/ssl/certs/corp-bundle.pem",
timeout=10)
在 Python 3.10+ 且希望“系统装什么就信任什么”时,truststore 0.10.0 只需一行,它把 ssl.SSLContext 的实现替换为操作系统信任库(Windows CryptoAPI、macOS Keychain、Linux OpenSSL 默认路径),须在任何 SSL 连接建立前调用:
import truststore
truststore.inject_into_ssl() # 必须在创建连接之前执行
import requests
print(requests.get("https://intranet.example.com/api", timeout=10).status_code)
为什么不建议 verify=False?它会同时关闭证书链校验和主机名校验,中间人可任意解密流量;urllib3 2.x 仍会打出警告,但不会阻断请求——这段告警经常被当成“噪音”忽略掉:
InsecureRequestWarning: Unverified HTTPS request is being made to host
'intranet.example.com'. Adding certificate verification is strongly advised.
See: https://urllib3.readthedocs.io/en/latest/advanced-usage.html#tls-warnings
版本与维护成本也要计入选型:requests 2.32.x 要求 urllib3 >=1.21.1,<3;macOS 自带的系统 Python 常链接 LibreSSL,容易触发 CERTIFICATE_VERIFY_FAILED,应改用 python.org 官方安装包或直接上 truststore。企业根 CA 建议登记 SHA-256 指纹以便审计与轮换,并用 checkend 做到期监控——返回 0 表示 30 天内不过期,非 0 就该排期更换:
openssl x509 -in /etc/ssl/certs/corp-root-ca.pem -noout -fingerprint -sha256
openssl x509 -in /etc/ssl/certs/corp-root-ca.pem -noout -checkend 2592000; echo "退出码=$?"
自建 bundle 的维护成本并不高:按季度核对一次,约 0.5 人时;真正拖垮线上的是没人记得 certifi 与内网 CA 合并文件的存在,所以务必把合并步骤写进镜像构建脚本,而不是靠某位同事的本地环境。
常见报错与排查:python requests ssl证书验证失败的真实错误信息
为什么同一个域名,浏览器能打开,python requests 却报 CERTIFICATE_VERIFY_FAILED?因为 requests 不读系统钥匙串,它默认用 certifi 打包的 Mozilla 根证书列表(requests 2.32.x 起固定走 certifi,见 requests 官方文档 “SSL Cert Verification” 一节)。企业内网自签根 CA、代理 MITM 根 CA、缺失中间证书,这四种情况都会让校验在客户端失败。先看真实报错,再对症下药。
报错一:unable to get local issuer certificate (_ssl.c:1006)——OpenSSL 顺着服务端发来的链找不到可信根,通常是服务端没发中间证书,或企业根 CA 不在 bundle 里。先抓链:
# 打印服务端实际下发的完整证书链(含中间证书)
openssl s_client -showcerts -servername api.example.com
-connect api.example.com:443 /dev/null
| openssl x509 -noout -subject -issuer -dates
# 确认 requests 正在用哪个 bundle(默认值来自 certifi)
python -c "import certifi; print(certifi.where())"
# 典型输出:/usr/local/lib/python3.12/site-packages/certifi/cacert.pem
据 OpenSSL 文档,-showcerts 会输出服务端发送的全部证书而非仅叶子证书;若只看到一张,说明中间证书缺失,需在服务端 SSLCertificateChainFile(Apache 2.4)或 fullchain.pem(Nginx)中补齐。根 CA 合并请用环境变量而非直接改 certifi 文件——pip install --upgrade certifi 会覆盖你的修改:
# 推荐:追加式合并,不污染 certifi 原件(Linux/macOS)
cat /etc/ssl/certs/corp-root-ca.pem >> /opt/certs/combined-bundle.pem
export REQUESTS_CA_BUNDLE=/opt/certs/combined-bundle.pem # requests 优先级最高
# 或在代码里显式指定,作用域更小
# requests.get(url, verify="/opt/certs/combined-bundle.pem", timeout=10)
报错二:hostname mismatch, certificate is not valid for 'api.example.com'——链是好的,但 SAN 里没有你请求的名字。常见诱因是用 IP 直连、或反向代理改写了 SNI。验证时要显式带 -servername,否则 OpenSSL 不发 SNI,拿到的可能是默认站点的证书:
# 指定 SNI + 指定后端 IP,检查返回证书的 SAN 是否包含 api.example.com
openssl s_client -servername api.example.com -connect 10.0.0.8:443 /dev/null
| openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
# 期望:DNS:api.example.com, DNS:*.example.com
报错三:certificate has expired——据 RFC 5280,客户端必须校验 notBefore/notAfter。先确认服务端证书本身:
openssl x509 -enddate -noout -in server.pem # notAfter=Nov 1 12:00:00 2025 GMT
date -u # 对比本机 UTC 时间
timedatectl set-ntp true # systemd 系校准 NTP
客户端时钟漂移同样触发该错误:经验上把偏差压在 300 秒以内可避开绝大多数边界问题,容器场景尤其常见(宿主机休眠后容器时间不走)。
报错四:SSLEOFError(8, 'EOF occurred in violation of protocol (_ssl.c:1006)')——握手阶段对端直接断连,多为 TLS 版本/密码套件不匹配,或中间代理切断。逐版本探测:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_3
python -c "import ssl; print(ssl.OPENSSL_VERSION)" # 例如 OpenSSL 3.0.13
报错五:ProxyError ... [SSL: CERTIFICATE_VERIFY_FAILED]——注意报错发生在”连代理”这一步,不是目标站点。先用 curl 单独验证代理自身证书链,再把代理的 MITM 根 CA 加进 REQUESTS_CA_BUNDLE:
curl -v https://proxy.corp:8080 2>&1 | grep -E "subject|issuer|SSL certificate"
export HTTPS_PROXY=http://proxy.corp:8080
export REQUESTS_CA_BUNDLE=/opt/certs/combined-bundle.pem
报错六:NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+——据 urllib3 v2 迁移说明,macOS 自带 Python 常链接 LibreSSL 2.8.3,直接不可用。换 python.org 的 3.12 安装包或 brew install python@3.12,再确认 ssl.OPENSSL_VERSION 为 OpenSSL 1.1.1+ 或 3.x。
| 真实报错片段 | 根因 | 一条命令定位 |
|---|---|---|
| unable to get local issuer certificate | 缺中间证书 / 根 CA 不在 bundle | openssl s_client -showcerts -connect host:443 |
| hostname mismatch | SAN 不含请求名 / SNI 被改写 | openssl s_client -servername host -connect ip:443 |
| certificate has expired | 证书过期或本机时钟漂移 | openssl x509 -enddate -noout -in server.pem |
| SSLEOFError(8, ‘EOF occurred…’) | TLS 版本/套件不匹配或代理断连 | openssl s_client -tls1_2 -connect host:443 |
| ProxyError … CERTIFICATE_VERIFY_FAILED | 代理证书或 MITM 根 CA 不受信 | curl -v https://proxy.corp:8080 |
| NotOpenSSLWarning (urllib3 v2) | Python 链接 LibreSSL | python -c "import ssl;print(ssl.OPENSSL_VERSION)" |
排错顺序建议固定为:openssl s_client -showcerts 看链 → openssl x509 -text 看 SAN 与有效期 → 比对 certifi.where() 与 REQUESTS_CA_BUNDLE 的实际取值。这三步能覆盖上面六类报错中的五类;剩下的一类(LibreSSL)在 ssl.OPENSSL_VERSION 里一眼可见。
如何验证 python requests ssl证书验证失败已修复?
怎么判断 python requests ssl证书验证失败真的修好了,而不是被”绕过”了?
最危险的状态不是报错,而是”看起来成功、实际没校验”。必须同时做正向验证(能连通)和负向验证(错误证书仍被拒绝),再叠加 OpenSSL 独立复核与 CI 回归。
正向验证:确认返回 200 且没被重定向到登录页
import logging, requests
logging.basicConfig(level=logging.DEBUG) # urllib3 会打印 Starting new HTTPS connection (1): api.example.com:443
r = requests.get("https://api.example.com/health", timeout=5, verify="corp-bundle.pem")
print(r.status_code, r.url, r.raw.version) # 期望:200 https://api.example.com/health 11
r.raw.version 取自 http.client:10=HTTP/1.0、11=HTTP/1.1、20=HTTP/2。requests 2.32.x + urllib3 2.x 默认走 HTTP/1.1,打印 11 说明请求确实在 TLS 之上完成。若 r.url 变成 https://api.example.com/login,那是 302 后的假成功——用 allow_redirects=False 复测,状态码应为 200 而非 302。同时确认控制台没有 InsecureRequestWarning(urllib3 仅在 verify=False 时抛出)。
负向验证:换成不含企业根的旧 bundle,必须再次失败
try:
requests.get("https://api.example.com/health", timeout=5,
verify="/usr/lib/python3/dist-packages/certifi/cacert.pem") # 纯公共根,无企业 CA
except requests.exceptions.SSLError as e:
print("校验生效:", e)
# 预期报错:[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)
注意 verify 默认值是 True,但环境变量 REQUESTS_CA_BUNDLE / CURL_CA_BUNDLE 会覆盖默认值——显式传参优先级最高,所以这里必须写死路径。若这段没抛异常,说明代码某处仍有 verify=False 或全局 session.verify 被改写。
OpenSSL 独立验证:绕开 Python 生态看真相
# 1) 校验叶子证书链:期望输出 server.pem: OK
openssl verify -CAfile corp-bundle.pem -untrusted chain.pem server.pem
# 2) 握手并看校验码:期望 Verify return code: 0 (ok)
openssl s_client -connect api.example.com:443 -servername api.example.com
-CAfile corp-bundle.pem /dev/null | grep "Verify return code"
据 OpenSSL 官方文档,verify 子命令按 RFC 5280 逐级构建信任链,而 s_client 的 Verify return code 是服务端握手时的实际校验结果;两者一致才能排除”Python 侧配置对、网络中间设备不对”的情况(SNI 必须显式带 -servername,否则多域名服务器可能回落到默认证书)。
CI 回归与到期监控
# tests/test_tls_trust.py
import requests
def test_tls_trust():
r = requests.get("https://api.example.com/health", timeout=5) # timeout 无默认值,必须显式给
assert r.status_code == 200 and r.url.startswith("https://")
# 固定 certifi 版本,防止流水线漂移
pip freeze > requirements.lock
# 证书 30 天内到期告警:返回码 0 且打印 Certificate will not expire 即安全
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null
| openssl x509 -out server.pem
openssl x509 -in server.pem -noout -checkend 2592000
-checkend 2592000 即 30 天(秒),返回码非 0 表示即将过期,适合放进 cron/定时流水线。据 Let’s Encrypt 文档,其证书有效期 90 天、官方建议在剩余 30 天时续期,这个阈值与之对齐。
| 验证手段 | 能发现什么 | 发现不了什么 | 期望输出 |
|---|---|---|---|
| requests 正向请求 | 应用层可用、是否被重定向 | 校验是否真的开启 | 200 … 11 |
| 旧 bundle 负向请求 | 校验是否被 verify=False/代理绕过 | 证书链本身是否完整 | CERTIFICATE_VERIFY_FAILED |
openssl verify |
链顺序、缺失中间证书 | 服务端实际下发的链 | server.pem: OK |
openssl s_client |
SNI、服务端真实证书链 | Python 侧 CA 路径配置 | Verify return code: 0 (ok) |
| urllib3 DEBUG 日志 | 是否真的新建 HTTPS 连接 | 证书内容细节 | Starting new HTTPS connection (1) |
四类证据齐备(200 + 负向失败 + OpenSSL OK + CI 绿灯),才算把 python requests ssl证书验证失败真正闭环;只靠一次成功请求,等于没验证。
只能临时定位,不能作为生产方案。verify=False 会同时关闭证书链校验和主机名校验,暴露中间人风险,且 requests 会打印 InsecureRequestWarning;生产应把企业根 CA 合入 bundle,或用 REQUESTS_CA_BUNDLE 指向新 bundle。
浏览器读操作系统信任库,requests 默认读 certifi 的 cacert.pem。企业根 CA 装在系统里但不在 certifi 里,所以浏览器正常、requests 失败;用 `requests.certs.where()` 可确认实际加载的 CA 路径。
requests 先读 REQUESTS_CA_BUNDLE,再读 CURL_CA_BUNDLE,两者都没设置才用 certifi。显式 `verify=` 参数优先级高于环境变量,适合单请求精确控制。
只对公网证书链变化有效,例如 Let's Encrypt 根证书更新;企业自签根 CA 不会因为升级 certifi 出现,必须手动合入。`pip install -U certifi` 后仍要用 `certifi.where()` 检查路径和证书数量。
不够。`update-ca-certificates` 只更新系统信任库,requests 仍默认读容器内 site-packages/certifi/cacert.pem;需要设置 `REQUESTS_CA_BUNDLE`,或在构建镜像时把企业根 CA 合并进 bundle。
需要复用操作系统证书库、Python 3.10+ 时用 truststore,`truststore.inject_into_ssl()` 要在导入 requests 前调用;需要跨平台固定行为、CI 可复现时用 certifi 加自维护 bundle。
检查请求 URL 的主机名是否在证书 SAN 列表,IP 访问通常不匹配。用 `openssl s_client -servername 域名 -connect IP:443` 验证 SNI,必要时改用域名访问或让运维补 SAN。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。