ADK-Samples项目中Travel-Concierge模块的SSL证书验证问题解析

在ADK-Samples项目的Travel-Concierge模块开发过程中，开发者可能会遇到一个典型的SSL证书验证失败问题。当执行poetry install命令时，系统会抛出SSLCertVerificationError错误，提示无法获取本地颁发者证书。

问题现象

具体错误表现为：

HTTPSConnectionPool(host='github.com', port=443): Max retries exceeded with url: /googleapis/python-aiplatform.git/info/refs?service=git-upload-pack (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1028)')))

这个错误表明Python的SSL模块无法验证GitHub服务器的SSL证书，因为缺少相应的根证书或中间证书。

问题根源

在macOS系统上，特别是较新版本如Sonoma 14.7.5，Python环境可能会遇到SSL证书验证问题，主要原因包括：

1. Python使用的SSL证书库与系统证书库不同步
2. 系统证书存储位置发生变化
3. 网络环境或安全设置影响了SSL连接
4. Python环境未正确配置系统证书路径

解决方案

方案一：更新Python证书库

对于使用Homebrew安装的Python，可以尝试重新链接证书：

brew reinstall openssl

方案二：手动指定证书路径

在Python代码或环境变量中明确指定证书路径：

export SSL_CERT_FILE=/etc/ssl/cert.pem

方案三：临时调整证书验证（不推荐用于生产环境）

对于开发环境，可以临时调整SSL验证设置：

git config --global http.sslVerify false

方案四：直接安装依赖包

如仓库协作者建议，可以绕过Poetry直接安装特定依赖：

pip install "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@copybara_738852226"

最佳实践建议

1. 定期更新系统的证书存储
2. 确保Python环境与系统证书库同步
3. 在开发环境中使用虚拟环境隔离依赖
4. 对于企业网络环境，可能需要配置特定的证书或网络设置

总结

SSL证书验证问题在Python开发中较为常见，特别是在依赖外部Git仓库时。理解证书验证机制和掌握相关调试方法，能够帮助开发者快速解决类似问题。对于ADK-Samples项目，除了上述解决方案外，保持开发环境的一致性也是预防此类问题的有效方法。