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

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

默认的 App Engine 服务账号没有 Storage Object Viewer (roles/storage.objectViewer) 角色。
- 如需解决此问题，请向服务账号授予 Storage Object Viewer 角色。
您的项目具有 VPC 服务边界，该边界使用访问权限级别限制对 Cloud Storage API 的访问。
- 如需解决此问题，请将用于部署应用的服务账号添加到相应的 VPC 服务边界 accessPolicies。

未能创建 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 柔性环境中才会发生该错误。

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

验证您是否已向默认 App Engine 服务账号授予 Editor (roles/editor) 角色。
检查项目的组织政策是否限制对外部 IP 地址的访问。如需了解详情，请参阅 App Engine 柔性环境已知问题。
确认您已向用于运行应用的服务账号（通常是默认服务账号，即 app-id@appspot.gserviceaccount.com）授予以下角色：
- Storage Object Viewer (roles/storage.objectViewer)
- Logs Writer (roles/logging.logWriter)
如果此服务账号不具有这些角色，请授予这些角色。
如果您要在共享 VPC 设置中进行部署，并在 app.yaml 中传递 instance_tag，请参阅此部分以解决问题。

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

部署应用时，系统会出现以下错误：

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

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

要解决此问题，请确保执行部署的用户或服务账号具有 Serverless VPC Access User 和 Compute 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 when restarting the instance under the running versions

从 2024 年 5 月开始，Google Cloud 对所有新项目强制执行“需要 OS Config”组织政策。此政策要求在新项目中创建的所有虚拟机实例都必须启用虚拟机管理器。对于新项目和现有项目，此限制条件将阻止会在项目或实例级别停用虚拟机管理器的元数据更新。

如需解决此问题，您必须停用组织政策限制条件 constraints/compute.requireOsConfig。

必需的“compute.firewalls.list”权限

在共享 VPC 网络上部署应用时，系统会出现以下错误：

Request to https://compute.googleapis.com/compute/v1/projects/projects/PROJECT_ID/global/firewalls?key failed, details: Required 'compute.firewalls.list' permission for 'projects/PROJECT_ID'

如果宿主项目的以下服务账号没有 Compute Network User (roles/compute.networkUser) 角色，则系统会出现此错误：

如需解决此问题，请确认您是否已向宿主项目的 Google API 服务代理和 App Engine 柔性环境服务代理服务账号授予 Compute Network User 角色；如果这些服务账号没有该角色，请向其授予该角色。

在部署期间构建失败，但日志中没有错误

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

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 存储桶的以下设置：

将加密设置为 Google 拥有和 Google 管理的密钥。
移除保留政策。

由于组织政策限制条件，部署失败

部署应用时，系统会出现以下错误：

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/[VERSSION]/[PROJECT_ID]/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project [PROJECT_ID].

此错误可能是由于在部署应用时强制执行组织政策限制条件 constraints/compute.disableGuestAttributesAccess 而导致的。默认情况下，系统会对 App Engine 柔性环境中的所有应用强制执行此政策。

如需解决此问题，您必须停用组织政策限制条件 constraints/compute.disableGuestAttributesAccess。

部署到现有柔性环境版本时出错

部署到现有 App Engine 柔性环境版本时，可能会出现以下错误：

ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while
processing task /app-engine-flex/flex_await_healthy/flex_await_healthy

此错误表示使用有效的 Docker 映像更新健康状况不佳的部署并不总是会产生健康状况良好的部署。结果取决于健康状况不佳的部署中的实例状态。尽管存在错误，但如果您提供了良好的 Docker 映像，则部署最终可能会正常运行。虽然允许使用新的 Docker 映像更新现有版本，但这并不是一种好的做法。如果版本失败，系统不会回滚。

传送错误

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

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

首次启用 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 默认服务账号，或将其替换为成功部署后创建的服务账号。

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

Nginx 无法连接到应用容器或与之进行通信

以下错误仅发生在 App Engine 柔性环境中，通常会在发生错误后立即返回 502 错误：

recv() failed (104: Connection reset by peer) while reading response header from upstream

此错误表示 nginx 反向代理 (nginx sidecar) 无法访问应用容器。在日志中，您可以将 nginx 日志中的 502 错误的关闭时间与 nginx.error 日志中的时间进行比较。在发生 nginx.error 错误后紧接着发生 502 nginx 错误可能是导致发生 nginx 502 错误的原因。

当应用的连接 keepalive 超时小于 nginx 的 keepalive 超时时，通常会发生此错误。由于 App Engine 柔性环境中的 nginx 的 keepalive_timeout 为 650 秒，因此应用需要使连接至少在此时间中保持活动状态。默认情况下，Node.js 应用的 keepAliveTimeout 为 5000 毫秒。在这种情况下，您可以将 server.keepAliveTimeout 设置为 700000 毫秒。

如需排查问题，请连接到虚拟机实例以检查应用容器中运行的代码写入的日志，并在必要时添加更多日志记录以找到根本原因。

内存不足

App Engine 柔性环境中会发生以下错误，并且通常返回 502 错误：

kernel: [  133.706951] Out of memory: Kill process 4490 (java) score 878 or sacrifice child
kernel: [  133.714468] Killed process 4306 (java) total-vm:5332376kB, anon-rss:2712108kB, file-rss:0kB

此错误表示 App Engine 已终止应用。

当实例的内存不足时，会发生此错误。默认情况下，App Engine 柔性环境具有 1GB 内存，并且仅 600MB 内存可用于应用容器。

如需进行问题排查，请检查日志，看看是否存在“内存不足”条目。更新您的 memory_gb 配置并重新部署。

开放的连接数不足，无法处理传入请求

如果等待连接数上限等于或大于活跃连接数的 75%，则应用可能会出现 502 错误。

如需解决此问题，请检查 Cloud Monitoring 指标，查看活跃连接数和等待连接数上限，并减少等待连接数以确保等待连接数上限小于或等于活跃连接数的 75%。