本页面介绍问题排查策略,以及运行构建时可能看到的一些常见错误消息的解决方案。
您是否查看了构建日志?
使用 Logging 或 Cloud Storage 构建日志可以获取有关构建错误的详细信息。写入 stdout 或 stderr 的日志可以使用 Google Cloud 控制台和 gcloud CLI 查看。
由于用户无权访问构建日志,手动构建失败
您尝试运行手动构建时看到以下错误:
AccessDeniedAccess denied. [EMAIL_ADDRESS] does not have storage.objects.get access to the Google Cloud Storage object.
您之所以看到此错误,是因为 Cloud Build 要求运行手动构建并使用默认 Cloud Storage 日志存储分区的用户除了具有 Cloud Build Editor 角色之外,还具有 Project Viewer IAM 角色。若要解决此错误,您可以执行以下任一操作:
使用默认日志存储分区,并向运行构建的用户授予 Project Viewer 角色和 Cloud Build Editor 角色。有关授予此权限的说明,请参阅配置对 Cloud Build 资源的访问权限。
创建您自己的 Cloud Storage 存储桶来存储日志。如需了解相关说明,请参阅将构建日志存储在用户创建的存储分区中。
由于缺少 iam.serviceAccounts.actAs 权限,构建失败
尝试使用 Cloud Run 或 App Engine 等托管式服务部署 build 时,您会看到以下错误:
Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE ACCOUNT]
如需解决此错误,请配置指定的 Cloud Build 服务账号或默认 Cloud Build 服务账号,以模拟您用于构建的代管式服务的服务账号。如需详细了解此任务,请参阅为托管式服务配置 Cloud Build 服务账号模拟。
如需详细了解服务账号和权限,请参阅以下主题:
在 Cloud Run functions 上部署时出现“权限遭拒”错误
尝试使用 Cloud Run functions 时,您会看到以下错误:
ResponseError: status=[403], code=[Ok], message=[Permission 'cloudfunctions.functions.get' denied]
如需解决此错误,请向您的构建服务账号授予 Cloud Run functions Developer 角色。
由于缺少 cloudbuild.builds.create 权限,构建触发器失败
运行构建触发器时,您会看到类似以下内容的错误:
Failed to trigger build: Permission 'cloudbuild.builds.create' denied on resource 'projects/xxxxxxxx' (or it may not exist)
构建触发器使用服务账号来创建构建。此错误表示服务账号缺少 cloudbuild.builds.create IAM 权限,服务账号需要该权限才能运行构建触发器。您可以通过向用户指定的服务账号或默认服务账号授予 Cloud Build Service Account IAM 角色来解决此错误。
由于缺少服务代理权限,构建提交失败
如果 Cloud Build 服务代理被删除或缺少权限,则在提交 build 时可能会导致以下错误。
Caller does not have required permission to use project $PROJECT_ID. Grant the caller the roles/serviceusage.serviceUsageConsumer role, or a custom role with the serviceusage.services.use permission, by visiting https://console.developers.google.com/iam-admin/iam/project?project=$PROJECT_ID and then retry. Propagation of the new permission may take a few minutes.
在此场景中,调用方是 Cloud Build 服务代理。如需解决此权限问题,请按以下步骤操作:
确保 Cloud Build 服务代理存在。您可以前往 Google Cloud 控制台中的 IAM 页面,然后选中显示 Google 代管式服务复选框,查看项目的服务代理。如果不存在,您可以通过运行以下 gcloud CLI 命令来创建它:
gcloud beta services identity create --service=cloudbuild.googleapis.com \ --project=PROJECT_ID接下来,向 Cloud Build 服务代理授予
roles/cloudbuild.serviceAgentIAM 角色:gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild." \ --role="roles/cloudbuild.serviceAgent"
如果您想验证哪个 IAM 身份可能导致了服务代理权限问题,请按照以下步骤操作:
在 Google Cloud 控制台中打开 Logs Explorer。
在查询字段中输入以下文本:
resource.type="project" log_name="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity" "service-PROJECT_NUMBER@gcp-sa-cloudbuild."如果您在使用此查询后看到任何日志条目,请检查是否有任何日志条目正在从服务代理 (
service-PROJECT_NUMBER@gcp-sa-cloudbuild.) 中移除权限。 如果是,请查看该日志中的protoPayload.authenticationInfo.principalEmail,以确定是哪个 IAM 身份移除了权限或包含出错提示中列出的权限的roles/cloudbuild.serviceAgent角色。
触发器失败,并显示 Couldn't read commit 错误
运行构建触发器时您看到以下错误:
Failed to trigger build: Couldn't read commit
如果您尝试使用不存在的分支触发构建,Cloud Build 会返回此消息。检查目录名称的拼写和一致性。如需了解触发器设置说明,请参阅创建和管理构建触发器。
无法创建 Pub/Sub 触发器
创建 Pub/Sub 触发器时,您会看到以下错误:
Failed to create trigger: Request is prohibited by organization's policy
此错误表示 Pub/Sub API 在您的项目中受到限制。限制 Pub/Sub API 的项目会限制创建推送订阅的能力。您可以暂时从边界内的受限服务中移除 Pub/Sub,创建触发器,然后再次限制 Pub/Sub API 以解决错误。
由于以下错误,无法从私有代码库中拉取或提取分支:fatal: could not read Username
尝试在私有代码库的远程分支上执行 git pull 或 git fetch 时,您会看到以下错误:
fatal: could not read Username for '<REMOTE_URL>': No such device or address
在私有代码库中,此错误是预期的,因为在初始克隆代码库后,git 凭据辅助程序会被有意移除。如需从私有代码库中提取远程分支,请手动设置授权凭据(API 令牌、SSH 密钥)作为构建步骤。详细了解如何访问私有 GitHub 代码库。
由于 SSH 授权无效,构建失败
运行构建时您看到以下错误:
Could not parse ssh: [default]: invalid empty ssh-agent socket, make sure SSH_AUTH_SOCK is set
此错误表示 SSH 授权存在问题。一个常见的示例是,通过 Cloud Build 访问私有 GitHub 代码库时发生的 SSH 授权错误。如需了解如何为 GitHub 设置 SSH,请参阅访问私有 GitHub 代码库。
由于 No route to host 错误,构建失败
在专用池中运行构建时,您会看到以下或类似错误:
Unable to connect to the server: dial tcp 192.168.10.XX:<port>: connect: no route to host
Cloud Build 使用 Docker 容器在 Google 管理的项目内的虚拟机上运行其 Cloud Build 构建器。Docker 桥接接口(以及因此连接到此接口的容器)分配的 IP 范围为 192.168.10.0/24,这使得无法与同一子网中的外部主机进行通信。在配置专用池期间,为项目中的资源分配 IP 范围时,我们建议选择 192.168.10.0/24 以外的范围。如需查看相关说明,请参阅为专用池设置环境。
构建失败,并显示出错提示:“已过期”,且不显示任何日志
您触发或提交了构建,但构建失败,抛出“已过期”错误,并且未生成任何日志。
请检查配置中的以下内容:
您配置了较低的
queueTtl值(例如 20 秒)。请增加架构中的值,然后重新运行构建。如需了解详情,请参阅
queueTtl。您已达到并发构建的配额。
您可以通过 Google Cloud 控制台中的“配额”页面申请增加配额。如需了解详情,请参阅配额和限制。
您使用的是专用池,并且选择了非默认机器。
构建可能需要更长时间才能启动,因为它可能需要等待新的虚拟机启动。如需了解详情,请参阅机器类型。
您可以尝试更改机器类型。
您使用的是专用池,并且已为该池指定 IP 范围。
IP 的物理范围决定了池中工作器虚拟机的数量,从而决定了并发构建的限制,即使该限制低于并发构建配额也是如此。如果池中没有可用的工作器虚拟机,则构建会排队。
当指定子网中的可用 IP 地址被完全利用时,就会发生这种情况,导致没有地址可供新的 Cloud Build 工作器分配。请尝试增加子网中的范围,然后重新运行构建。
由于未启用外部 IP,与外部资源的连接失败
从专用池连接到外部资源时,您会看到以下错误:
Failed to connect to <external_domain>: Connection timed out
专用池使用外部 IP 访问公共互联网上的资源,例如外部代码库。创建或更新专用池时,选中相应复选框即可为专用池分配外部 IP。如需了解如何在专用池中创建或更新字段,请参阅创建和管理专用池。
I/O 超时错误
运行构建时您看到以下错误:
Timeout - last error: dial tcp IP_ADDRESS: i/o timeout
当您的构建尝试访问专用网络中的资源但失败时,可能会发生此错误。默认情况下,使用 Cloud Build 运行的 build 可以访问公共互联网中的私有资源,例如代码库或注册表中的资源。但是,只有在您使用专用池并将其配置为访问专用网络时,构建才能访问专用网络中的资源。请参阅在专用网络中使用 Cloud Build。
专用池工作器从内部 GitHub Enterprise 服务器克隆时超时
在专用池中运行从内部或本地 GitHub Enterprise 服务器克隆源代码的构建时,构建步骤会失败,并显示类似于以下内容的连接超时错误:
fatal: unable to access 'https://github.example.com/org/repo.git/': Failed to connect to github.example.com port 443: Connection timed out
或者:
fatal: unable to access 'https://github.example.com/org/repo.git/': Could not resolve host: github.example.com
如需解决私有池工作器与内部 GitHub Enterprise 服务器之间的连接超时问题,请验证以下网络和路由前提条件:
通过 Service Networking 对等互连导出自定义路由:专用池在 Google 代管式服务提供方网络中运行,该网络使用 Service Networking (
servicenetworking-googleapis-com) 与您的虚拟私有云 (VPC) 网络对等互连。默认情况下,VPC 网络对等互连仅交换子网路由。如果您的 GitHub Enterprise 服务器托管在本地或通过 Cloud VPN 或 Cloud Interconnect 访问的外部网络中,则 Cloud Router 学习的动态路由或 VPC 网络中的静态自定义路由不会自动与专用池共享。确保您的 VPC 网络对等互连配置会将自定义路由导出到服务提供方网络:
gcloud compute networks peerings update servicenetworking-googleapis-com \ --network=VPC_NETWORK \ --export-custom-routes将
VPC_NETWORK替换为与专用池对等互连的 VPC 网络的名称。如需了解详情,请参阅路由交换选项。为专用主机名配置内部 DNS 解析:如果没有 DNS 对等互连,专用池工作器虚拟机无法解析托管在专用 Cloud DNS 区域或本地 DNS 服务器中的专用主机名:
- 私有云 Cloud DNS 区域:使用专用服务访问通道 DNS 对等互连 (
gcloud services peered-dns-domains create) 与 Service Networking 提供方网络共享 DNS 后缀。 - 本地 DNS 服务器:在 VPC 网络中配置 Cloud DNS 转发可用区,并为同一 DNS 后缀配置专用服务访问通道 DNS 对等互连。出站转发查询源自
35.199.192.0/19,而不是专用池的 IP 范围,因此请验证类型 1 和类型 2 目标的防火墙规则和返回路由。
- 私有云 Cloud DNS 区域:使用专用服务访问通道 DNS 对等互连 (
验证防火墙规则和 GitHub Enterprise IP 许可清单:
- VPC 和边界防火墙:确保 VPC 网络中的防火墙规则以及任何中间本地防火墙都允许从专用池的已分配 IP 地址范围到 GitHub Enterprise 服务器的入站流量(通过 TCP 端口 443 [HTTPS] 或端口 22 [SSH])。
- GitHub Enterprise IP 许可清单:如果您的 GitHub Enterprise 组织或服务器强制执行 IP 许可清单,请将专用池对等互连子网的已分配 CIDR 范围添加到许可清单。如果您的专用池通过内部代理或自行管理的 NAT 网关路由出站流量,请改为将代理或 NAT IP 地址添加到许可清单。
解决非传递性 VPC 网络对等互连问题:VPC 网络对等互连不具有传递性。如果您的 GitHub Enterprise 服务器部署在与托管专用池的 VPC 网络对等互连的辅助 VPC 网络中,则专用池无法通过中间 VPC 网络访问 GitHub Enterprise。如需启用端到端连接,请使用 Cloud VPN、Cloud Interconnect 或中间代理连接网络。如需了解详情,请参阅具有多个对等互连的中转网络。
4xx 客户端错误
这组错误表示可能由于发送构建请求的用户一侧的错误而导致构建请求不成功。4xx 客户端错误的一些示例包括:
**Error**: 404 : Requested entity was not found**Error**: 404 : Trigger not found**Error**: 400 : Failed Precondition**Error**: 403 : Permission denied
如果出现 4xx 客户端错误,请查看构建日志,看看其是否包含有关此错误原因的详细信息。导致客户端错误的一些常见原因包括:
- 您指定的来源位置没有任何新内容要提交,并且工作树干净。在这种情况下,请检查您的源代码位置,然后尝试再次构建。
- 您的代码库不包含构建配置文件。如果是这种情况,请将构建配置文件上传到您的代码库,然后再次运行构建。
- 您指定的触发器 ID 不正确。
- 您最近在安装 GitHub 应用后添加了新代码库,但 Cloud Build 无权访问该新代码库。如果是这种情况,请将您的新代码库连接到 Cloud Build。
- 您需要向构建服务账号授予另一项权限。
由于配额限制,构建失败
您会看到以下错误,表明由于特定区域的配额限制,构建失败:
Failed to trigger build: generic::failed_precondition: due to quota restrictions, cannot run builds in this region. Please contact support.
请与 Cloud Customer Care 联系,以提高此特定区域的配额。
从 Docker 注册表拉取映像时出现超时问题
运行构建后,您会在 Cloud Build 日志中看到以下超时错误:
Step #0: Pulling image: python:3.8.16-alpine3.17
Step #0: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)
Step 1/7 : FROM python:3.8.16-alpine3.17
Get "https://registry-1.docker.io/v2/": dial tcp 34.205.13.154:443: i/o timeout
如需解决此错误,请使用 crane 下载 Docker 映像,然后继续将该映像加载到 Cloud Build Docker 映像中。
将以下代码段添加到 cloudbuild.yaml 文件中。
...
# Crane runs as a regular user so we need to allow it to access the directory where it saves the image.
- name: gcr.io/cloud-builders/docker
args:
- a+w
- /workspace
entrypoint: chmod
# Use crane to download the image through the proxy
- name: gcr.io/go-containerregistry/crane
env: - 'HTTPS_PROXY=HTTPS_PROXY'
args:
- pull
- 'python:3.8.16-alpine3.17'
- /workspace/image.tar
# Use docker load to add the image into the local Cloud Build registry
- name: gcr.io/cloud-builders/docker
args: [load, --input, "/workspace/image.tar"]
- .
HTTPS_PROXY:HTTP 代理的地址(例如https://proxy.example.com:8888/)。
加载映像后,您现有的 cloudbuid.yaml 步骤应正常运行,例如:
...
- name: python:3.8.16-alpine3.17
args:
- echo
- hello
entrypoint: bash
# Or use it internally on a Dockerfile
- name: gcr.io/cloud-builders/docker
args:
- build
长时间运行的 Docker 步骤出现 Unauthenticated 错误
如果构建步骤涉及运行时间超过一小时的 Docker 命令(例如将大型映像推送到 Artifact Registry),则可能会失败并出现身份验证错误。Cloud Build 每小时刷新一次身份验证令牌,但 Docker 可能无法获取这些新令牌,从而导致身份验证问题。您可以将具有自定义生命周期的令牌写入文件,并在 Docker 命令中引用该文件。
与 VPC 网络对等互连的专用池中的已排队构建
在专用池中运行构建时,如果专用池的服务提供方网络与您自己的 VPC 网络建立了对等互连,那么这两个网络之间的专用连接必须保持完好。如果您删除专用池所依赖的专用连接,则可能会破坏专用池。这可能表现为构建作业一直处于排队状态,直到最终超时。因此,如果您要删除专用连接,请务必同时删除其服务提供方网络通过此专用连接连接到您自己的 VPC 网络的所有专用池。
尝试批准或拒绝超过 2 个月的待处理构建
您无法批准或拒绝超过 2 个月的待处理构建。尝试这样做可能会导致出现如下所示的出错提示:
404, "message": "Requested entity was not
found.", "status": "NOT_FOUND" } }
如果出现这种情况,请尝试提交新 build。
未能创建专用池:工作器池未与 Service Networking API 对等互连
您尝试创建专用池。但是,您会收到以下错误消息:
Failed to create private pool private-worker-pool: generic::failed_precondition: network "projects/PROJECT_NAME/global/networks/vpc-scmdev-lab-vpc" is not peered to the Service Networking API; please check your configuration and the documentation for troubleshooting and setting up your pool
要使构建能够从 Virtual Private Cloud 网络访问私有资源,您必须在您的 Virtual Private Cloud 网络与专用池所在的 Virtual Private Cloud 网络之间建立对等互连连接。如需查看相关说明,请参阅在 VPC 网络与服务提供方网络之间设置专用连接。
未能创建专用池:无法访问 peered_network 配置
如果您使用的是共享 VPC,或者之前删除了 Service Networking 服务代理,则专用池创建可能会失败,并显示类似于以下内容的错误:
generic::permission_denied: cannot access peered_network config.
如需解决此问题,请确保服务项目中存在 Service Networking 服务代理 (service-PROJECT_NUMBER@service-networking.),并且该代理具有必要的权限。
如果服务账号缺失,请创建该账号:
gcloud beta services identity create \
--service=servicenetworking.googleapis.com \
--project=PROJECT_ID
向服务账号授予所需的 roles/servicenetworking.serviceAgent 角色:
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:service-PROJECT_NUMBER@service-networking." \
--role="roles/servicenetworking.serviceAgent"
后续步骤
- 了解如何管理构建日志。
构建日志显示顺序不正确
您运行了输出日志的构建步骤,并注意到 stderr(错误)日志在界面中显示的时间早于其对应的 stdout(标准输出)日志。日志未按时间顺序显示。
此顺序是标准的 Linux 和 Docker 流缓冲行为。当代码在非 TTY 环境(例如构建容器)中运行时,stdout 会进行块缓冲(延迟到缓冲区填满),而 stderr 仍不进行缓冲(立即输出)。
如需绕过此排序方法并保证严格的日志排序,您必须在构建步骤的执行环境中明确停用缓冲。
Python:设置 PYTHONUNBUFFERED 环境变量:
yaml
steps:
- name: 'python:3'
env: ['PYTHONUNBUFFERED=1']
script: |
python main.py
C/C++ 和 Bash 脚本:使用 stdbuf 命令强制执行行缓冲:
yaml
steps:
- name: 'ubuntu'
script: |
stdbuf -oL ./your_binary
Java:
Java 原生不支持使用标志停用缓冲,但您可以在关键日志语句后强制在代码中立即刷新:
java
System.out.println("Log message");
System.out.flush();