执行dbt deps时遇证书验证失败：证书链含自签名证书

问题背景 #

• 运行环境：Linux容器，dbt v1.7.14，连接Azure SQL
• 需求：安装dbt-labs/dbt_utils v1.1.1，用于通过dbt_utils.accepted_range（参数min_value: 0，max_value: 100）做值范围合规性测试
• 报错信息：执行dbt deps时无法从codeload.github.com下载包，触发SSL证书链自签名验证失败：

root@891906d968a0:/usr/app/dbt# dbt deps
17:17:03  Running with dbt=1.7.14
17:17:05  Installing dbt-labs/dbt_utils
17:17:17  Encountered an error:
External connection exception occurred: HTTPSConnectionPool(host='codeload.github.com', port=443): Max retries exceeded with url: /dbt-labs/dbt-utils/tar.gz/1.1.1 (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:992)')))

• 已尝试无效方案：
  • pip install pip_system_certs
  • python -m pip install python-certifi-win32（仅适用于Windows环境）
  • pip install certify
  • 执行macOS证书安装命令（仅适用于macOS环境）

针对性解决方案 #

方案1：更新容器系统CA证书（推荐）

针对Debian/Ubuntu系容器，更新系统证书存储以包含github的合法证书：

# 更新包索引并安装ca-certificates
apt update && apt install -y ca-certificates
# 刷新证书存储
update-ca-certificates

执行完成后重新运行dbt deps

方案2：配置dbt使用系统CA证书

通过配置或环境变量让dbt使用系统证书：

1. 在dbt项目的dbt_project.yml中添加配置：

config:
  use_system_certs: true

2. 或者设置环境变量（临时生效，重启容器后需重新设置）：

export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

设置完成后执行dbt deps

方案3：离线安装dbt_utils包

如果网络环境受企业代理/自签名证书限制，可手动下载后离线安装：

1. 本地机器下载指定版本的tar包：

wget https://codeload.github.com/dbt-labs/dbt-utils/tar.gz/1.1.1 -O dbt_utils-1.1.1.tar.gz

2. 将包复制到容器内的dbt项目目录：

docker cp dbt_utils-1.1.1.tar.gz <你的容器ID>:/usr/app/dbt/

3. 进入容器并解压安装：

# 进入容器
docker exec -it <你的容器ID> /bin/bash
# 切换到dbt项目目录
cd /usr/app/dbt
# 创建dbt_packages目录（如果不存在）
mkdir -p dbt_packages
# 解压包到dbt_packages
tar -xzf dbt_utils-1.1.1.tar.gz -C dbt_packages/
# 重命名目录为dbt_utils
mv dbt_packages/dbt-utils-1.1.1 dbt_packages/dbt_utils

4. 验证：执行dbt debug检查依赖是否正常加载

方案4：临时跳过SSL验证（不推荐）

仅用于测试环境，存在安全风险：

export PYTHONHTTPSVERIFY=0
dbt deps

内容的提问来源于stack exchange，提问作者D.Hodges