如何让sphinx-build -blinkcheck信任企业内部CA证书？

针对你遇到的SSL证书验证失败问题，我整理了几个实用方案，覆盖你用tox、bash脚本和Python脚本执行检查的场景：

1. 直接配置Sphinx的conf.py（推荐） #

从Sphinx 1.8版本开始，linkcheck模块支持通过linkcheck_ca_file指定自定义CA证书文件。你只需在项目的conf.py中添加一行配置：

# 指定单个企业CA证书
linkcheck_ca_file = '/etc/pki/ca-trust/source/anchors/company_ca.pem'

或者，因为你的CentOS 7已经注册了该CA，系统合并后的证书 bundle 已经包含它，也可以指向系统默认的CA路径，这样后续新增其他CA时无需修改配置：

linkcheck_ca_file = '/etc/pki/tls/certs/ca-bundle.crt'

配置完成后，Sphinx的linkcheck会自动用这个CA文件验证内部HTTPS链接，无需额外调整环境。

2. 通过环境变量全局设置（适配bash/tox/Python脚本） #

如果你的Sphinx版本较旧，或者不想修改conf.py，可以通过Python识别的SSL环境变量解决：

适用于bash脚本执行 #

在调用sphinx-build前先导出环境变量：

# 指定单个企业CA
export REQUESTS_CA_BUNDLE=/etc/pki/ca-trust/source/anchors/company_ca.pem
# 或者用系统CA bundle（更通用）
# export REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ca-bundle.crt

# 执行linkcheck检查
sphinx-build -W -blinkcheck docs build/docs

也可以设置SSL_CERT_FILE变量，效果一致：

export SSL_CERT_FILE=/etc/pki/ca-trust/source/anchors/company_ca.pem

适用于tox配置 #

在tox.ini的测试环境配置中添加环境变量：

[testenv:linkcheck]
setenv =
    REQUESTS_CA_BUNDLE = /etc/pki/ca-trust/source/anchors/company_ca.pem
commands =
    sphinx-build -W -blinkcheck docs build/docs

这样tox执行linkcheck时会自动加载指定的CA证书。

适用于Python脚本执行 #

如果用Python脚本调用sphinx-build，可先在脚本内设置环境变量再执行命令：

import os
import subprocess

# 设置CA证书路径
os.environ['REQUESTS_CA_BUNDLE'] = '/etc/pki/ca-trust/source/anchors/company_ca.pem'
# 执行linkcheck命令
subprocess.run(['sphinx-build', '-W', '-blinkcheck', 'docs', 'build/docs'], check=True)

3. 验证CA配置是否生效 #

你可以先手动测试Python是否能信任内部链接，比如用requests库：

import requests
response = requests.get('https://你的内部Mantis地址')
print(response.status_code)

如果脚本执行不报错，说明CA配置已生效，再运行Sphinx的linkcheck就不会出现证书验证失败的问题了。

内容的提问来源于stack exchange，提问作者Sardathrion - against SE abuse