Google Cloud CLI中的gcloud auth login、Application Default Credentials和具体云API调用，不是完全相同的凭据与网络路径。CLI能列出项目，不代表应用SDK就获得了正确ADC；Compute、Storage、Artifact Registry等服务也各自使用不同端点。
一、先区分三类身份
| 身份场景 | 常见用途 | 排查重点 |
|---|---|---|
| gcloud CLI账号 | 执行gcloud命令 | 当前账号、项目与权限 |
| ADC | 应用和SDK默认凭据 | 凭据来源与运行环境 |
| 服务账号或工作负载身份 | 自动化和云工作负载 | 最小权限、令牌获取与轮换 |
不要看到CLI登录成功就推断应用代码身份正常。诊断时记录身份类型，但不输出访问令牌、私钥或完整凭据文件。
二、代理设置应进入哪个进程
gcloud可以运行在本地Shell、Cloud VM、CI、容器或WSL。常见代理变量和CA必须存在于实际进程环境。图形浏览器完成OAuth交互，只说明浏览器链路可用，不证明CLI访问令牌和API端点的路径相同。
三、组件更新与业务API为何要分开
CLI组件或扩展下载使用分发端点，业务命令则访问对应Google Cloud API。组件更新成功不能覆盖Cloud Storage、Artifact Registry或区域服务。错误日志应保留实际主机、服务和状态码。
四、代理认证与IAM错误如何区分
- 407：企业代理认证；
- 401：云令牌失效或身份不正确；
- 403：IAM、组织策略、服务未启用或资源边界；
- TLS错误：CA、时间、域名或TLS检查；
- 超时：DNS、路由、代理或服务端点。
五、项目和区域为何会影响结果
gcloud配置可以保存当前项目、账号、区域和可用区。命令失败时先确认配置，不要在错误项目中做写操作来测试网络。部分API是全球端点，部分具有区域或专用端点，防火墙和私有访问策略可能不同。
六、ADC为什么经常在CI里失败
开发机可能使用个人ADC，CI则需要服务账号、工作负载身份联合或平台托管身份。把开发者凭据文件复制到CI既不安全，也会造成不可控权限。应按平台推荐的短期凭据机制配置，并确认令牌端点经代理可达。
七、元数据服务器应如何处理
云主机和部分托管环境通过链路本地元数据服务提供短期凭据。代理环境若截获此请求，可能导致超时或错误路径。应按当前SDK和运行环境对元数据地址设置精确绕过，不能把所有Google域名粗暴直连。
八、私有Google访问改变什么
VPC内可通过特定网络设计访问Google API，而不经普通互联网出口。是否走私有路径取决于DNS、子网设置、路由和组织策略。代理和NO_PROXY应与网络架构一致，并通过实际解析结果与路由验证。
九、证书错误怎样处理
检查系统时间、CLI使用的Python或运行时CA、企业根证书和目标证书链。容器与CI镜像不会自动继承宿主机证书。不要关闭TLS验证或使用来源不明的证书包。通用检查见HTTPS代理证书排查。
十、Storage和制品上传要单独测
大文件与镜像上传会产生分片、并发和重试，对代理容量和超时的要求远高于一个项目列表请求。先用授权测试桶或仓库上传小对象，再测试真实大小，并结合服务端对象状态判断超时后的结果。
分片和重试原理可参考对象存储代理上传排查。
十一、排查清单
- 记录gcloud版本、账号、项目和目标服务；
- 区分CLI账号、ADC和服务账号；
- 检查执行环境代理、NO_PROXY与CA；
- 分别测试身份端点和目标API；
- 区分407、IAM、组织策略、TLS与超时；
- 核对元数据、私有访问和公共端点路径；
- 清理临时凭据和诊断日志。
十二、结论
Google Cloud CLI代理故障要同时处理身份来源和服务端点。把gcloud认证、ADC、元数据与具体API拆开验证，才能避免用一个登录成功结果替代完整的云服务连通性。
