Document AI无法连接API：SSL证书验证失败求助

DevOps 小满

2026-7-28

问题描述

使用Google Cloud Document AI处理器，参考官方Python示例代码，已完成服务账号配置并将密钥JSON添加到环境变量，但运行代码时触发SSL握手失败，错误信息如下：

E0313 19:32:21.672264000 8728953088 ssl_transport_security.cc:1501] Handshake failed with fatal error SSL_ERROR_SSL: error:1000007d:SSL routines:OPENSSL_internal:CERTIFICATE_VERIFY_FAILED.

错误发生在执行以下rpc调用语句时：

response = rpc(
    request,
    retry=retry,
    timeout=timeout,
    metadata=metadata,
)

解决方案

补全系统根CA证书
这类错误大多是本地系统缺少验证Google Cloud服务证书所需的根CA证书：
- Linux（Debian/Ubuntu）：安装并更新证书包
```
sudo apt-get install ca-certificates
sudo update-ca-certificates
```
- Linux（RHEL/CentOS）：
```
sudo yum install ca-certificates
sudo update-ca-trust
```
- macOS：找到对应Python版本的证书安装脚本执行，比如Python 3.10：
```
/Applications/Python\ 3.10/Install\ Certificates.command
```
- Windows：通过Windows更新安装最新系统根证书，或手动导入Google的根CA证书。
指定自定义CA证书路径（代理/私有CA环境）
如果你的网络走代理或用私有CA，需要让gRPC客户端加载指定证书：
1. 准备好根CA证书文件（比如google_roots.pem）
2. 运行脚本前设置环境变量：
```
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/full/path/to/google_roots.pem
```
或者在Python代码开头添加：
```
import os
os.environ['GRPC_DEFAULT_SSL_ROOTS_FILE_PATH'] = '/full/path/to/google_roots.pem'
```
检查Python环境SSL配置
虚拟环境可能存在SSL证书异常：
- 执行命令验证SSL模块路径：
```
python -c "import ssl; print(ssl.get_default_verify_paths())"
```
  确认打印的cafile或capath存在且有效。
- Conda环境用户可更新依赖：
```
conda update conda openssl
```
排除网络拦截
防火墙、安全软件可能会拦截SSL连接，临时关闭相关软件测试，或确认网络允许访问*.documentai.googleapis.com域名。