App Engine 错误问题排查

本页面介绍了在使用 App Engine 时可能遇到的错误的问题排查方法。

如需了解影响 Google Cloud 服务(例如 App Engine)的突发事件,请参阅 Google Cloud Service Health 信息中心

部署

如果您在使用 App Engine Admin API 部署应用时遇到问题,请参阅本部分,其中列出了错误消息以及有关如何修正每个错误的建议。

调用者无权访问项目

部署应用时,系统会出现以下错误:

User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist): The caller does not have permission

如果您用于部署应用的账号无权为当前项目部署应用,则会发生此错误。

如需解决此问题,请向账号授予 App Engine Deployer (roles/appengine.deployer) 角色。如需查看用于部署的账号,请执行以下操作之一:

  • 如果您使用 Google Cloud CLI 进行部署,请运行 gcloud auth list 命令。
  • 如果您从 IDE 部署,请查看 Cloud Tools 插件的设置。

无法从注册表提取元数据

部署应用时,系统会出现以下错误:

Failed to fetch metadata from the registry, with reason: generic::permission_denied

如果您通过没有 Storage Admin (roles/storage.admin) 角色的服务账号使用 gcloud app deploy 命令,则会发生此错误。

如需解决此问题,请向服务账号授予 Storage Admin 角色

  • 如需查看您使用的账号,请运行 gcloud auth list 命令。
  • 如需了解在某些情况下仅分配 App Engine Deployer (roles/appengine.deployer) 角色可能不够的原因,请参阅 App Engine 角色

服务账号必须具备映像的权限

部署应用时,系统会出现以下错误:

The App Engine appspot and App Engine flexible environment service accounts must
have permissions on the image IMAGE_NAME

发生此错误是由以下某种原因造成的:

未能创建 Cloud Build

部署应用时,系统会出现以下错误:

Failed to create cloud build: Permission denied

如果您通过没有 Cloud Build Editor (roles/cloudbuild.builds.editor) 角色的账号使用 gcloud app deploy 命令,则会发生此错误。

如需解决此问题,请向用于部署应用的服务账号授予 Cloud Build Editor 角色

如需查看您使用的账号,请运行 gcloud auth list 命令。

提取应用时出现权限错误

部署应用时,系统会出现以下错误:

Permissions error fetching application apps/app_name. Please make sure you are using the correct project ID and that you have permission to view applications on the project

如果您运行的是 Google Cloud CLI 版本 328 或更高版本,则当您部署应用时,系统会出现以下错误:

Permissions error fetching application apps/app_name. Please
make sure that you have permission to view applications on the project and that
SERVICE_ACCOUNT has the App Engine Deployer (roles/appengine.deployer) role.

如果用于部署应用的账号没有 App Engine Deployer (roles/appengine.deployer) 角色,则会发生此错误。

如需解决此问题,请确认您已向用于部署应用的服务账号授予 App Engine Deployer 角色;如果服务账号没有该角色,请授予该角色。如需查看用于部署的账号,请执行以下操作之一:

  • 如果您使用 Google Cloud CLI 进行部署,请运行 gcloud auth list 命令。
  • 如果您从 IDE 部署,请查看 Cloud Tools 插件的设置。

新项目部署失败

在新项目中首次部署应用时,您可能会看到以下错误:

ERROR: (gcloud.app.deploy) Error Response: [13] Failed to create cloud build: com.google.net.rpc3.client.RpcClientException:..........invalid bucket "staging.PROJECT-ID.appspot.com"; service account PROJECT-ID@appspot.gserviceaccount.com does not have access to the bucket

各种因素都可能会导致此错误,例如缺少权限和组织政策更改。

如需解决此问题,请验证您是否已向默认服务账号授予 Storage Admin (roles/storage.admin) 角色。如需授予 Storage Admin 角色,请参阅将构建日志存储在用户创建的存储桶中

如果您已授予 Storage Admin 角色,并且根据部署期间遇到的不同权限错误授予了其他必需角色,但仍无法部署应用,则可能是因为以下组织政策更改导致:

  • 从 2024 年 5 月开始,Google Cloud 对所有组织资源强制执行从设计上保证安全的组织政策。默认情况下,此政策会阻止 App Engine 向 App Engine 默认服务账号授予 Editor 角色。

  • 从 2024 年 6 月开始,Cloud Build 更改了 Cloud Build 在新项目中使用服务账号的默认行为。Cloud Build 服务账号更改中详细说明了此更改。由于此更改,首次部署版本的新项目可能会使用权限不足的默认 App Engine 服务账号来部署版本。

如需解决此问题,请执行以下操作:

  • Editor 角色授予 App Engine 默认服务账号 (PROJECT_ID@appspot.gserviceaccount.com)。

  • 查看 Cloud Build 指导,了解默认服务账号的更改并停用新项目中的默认更改

等待应用基础架构运行状况恢复正常时超时

部署应用时,系统会出现以下错误:

Timed out waiting for the app infrastructure to become healthy

各种因素都可能会导致此错误,例如缺少权限、代码错误、CPU 或内存不足或健康检查失败。只有在 App Engine 柔性环境中才会发生该错误。

如需解决此问题,请排除以下可能的原因:

  1. 验证您是否已向默认 App Engine 服务账号授予 Editor (roles/editor) 角色
  2. 确认您已向用于运行应用的服务账号(通常是默认服务账号,即 app-id@appspot.gserviceaccount.com)授予以下角色:

  3. 如果此服务账号不具有这些角色,请授予这些角色。

  4. 如果您要在共享 VPC 设置中进行部署,并在 app.yaml 中传递 instance_tag,请参阅此部分以解决问题。

使用无服务器 VPC 访问通道连接器部署服务时出现权限错误

部署应用时,系统会出现以下错误:

Please ensure you have [compute.globalOperations.get] on the service project

当尝试使用无服务器 VPC 连接器部署应用的用户或服务账号没有所需的权限时,便会发生此错误。

要解决此问题,请确保执行部署的用户或服务账号具有 Serverless VPC Access UserCompute Viewer IAM 角色。

在共享 VPC 设置中进行部署时出现无效值错误

部署应用时,Flex 虚拟机实例的 Cloud Logging 中会显示以下错误:

Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert

出现该错误的原因是设置 instance_tag 会导致系统在创建实例时出错。

要解决此问题,请从 app.yaml 文件中移除 instance_tag 字段并重新部署。

部署实例数上限不超过 3 个的应用时出错

部署时将 max_instances 设置为 3 或更少的应用可能会遇到意外错误或停机。如需解决此问题,请在 app.yaml 文件中指定至少四个实例并重新部署。

超出实例数上限时发生错误

部署应用时,系统会出现以下错误:

You may not have more than 'xx' total max instances in your project.

每个项目可以创建的实例数存在上限。如果超出此限制,创建其他实例的请求会失败。

如需解决此问题,请在 app.yaml 文件中将 max_instances 的值设置为低于此限制的值,或者删除一些服务或版本以使 max_instances 的总和在此限制范围内。

部署期间构建失败,且日志中没有错误

部署应用时会出现以下错误:

ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at https://console.cloud.google.com/cloud-build/builds/BUILD_ID?project=PROJECT_NUMBER Failure status: UNKNOWN: Error Response: [2] Build failed; check build logs for details

错误消息中出现的链接表明所有构建步骤均已成功执行。但应用构建失败。

如果您使用的是 CMEK(客户管理的加密密钥),或者为 staging.PROJECT_ID.appspot.com 存储桶设置了数据保留政策,则会出现此问题。

如需解决此问题,请更改 staging.PROJECT_ID.appspot.com 存储桶的以下设置:

使用 NODE_ENV=development 运行时部署期间构建失败

部署 Node.js 应用时可能会发生此错误。默认情况下,如果 package.json 文件中检测到 build 脚本,则 Node.js 运行时将执行 npm run build

这可能会导致意外行为,例如长时间运行的构建或内存不足错误。

app.yaml 文件中指定 NODE_ENV=development,以确保执行具有所有必需的依赖项。

尽管存在错误,您也可以在 app.yaml 文件中的 build-env-variables 下指定 NODE_ENV: 'production' 来强制实现生产环境:

  build_env_variables:
    NODE_ENV: 'production'

如需了解详情,请参阅在部署期间执行自定义构建步骤

传送错误

以下部分介绍了应用初始化和服务错误。

使用默认服务账号创建应用时出现权限错误

首次启用 App Engine API 后创建应用时因以下错误而失败:

gcloud CLI

An internal error occurred while calling service consumer manager for service account.
Creating  App Engine application in project [PROJECT__ID] and [REGION]....failed. DEBUG: (gcloud.app.create) Error Response: [13] an internal error has occurred

请求日志

Service account creation is not allowed on this project.

控制台

Error while initialising App Engine.

此错误可能是由于在创建应用时强制执行组织政策限制条件 constraints/iam.disableServiceAccountCreation 而导致的。此政策会阻止预配 App Engine 默认服务账号 PROJECT_ID@appspot.gserviceaccount.com

如需解决此问题,您必须暂时移除组织政策限制条件 constraints/iam.disableServiceAccountCreation,以便创建和部署 App Engine 默认服务账号。该默认服务账号是创建应用所必需的,无法跳过。在使用版本级服务账号时,此方法同样适用。然后,您可以删除 App Engine 默认服务账号,或将其替换为成功部署后创建的服务账号。

如果您使用的是自己创建的服务账号,请查看角色建议概览以了解如何强制限制权限,例如针对该服务账号提供为服务代理创建的令牌创建者角色。

使用适用于 Python 的旧版捆绑服务时出现安全错误

如果您在 Python 3 应用启动时使用旧版捆绑服务 API,您可能会看到以下错误消息:

Attempted RPC call without active security ticket

当您的应用开始配置数据库连接或设置全局变量时,例如从 Memcache 读取某些值等情况下,可能会发生此错误。

如需解决此问题,您可以尝试将此类逻辑移至预热请求