排解 App Engine 中的部署問題

App Engine 部署錯誤的原因有很多，包括缺少權限、機構政策異動，以及應用程式設定問題。

本頁面說明 App Engine 中常見的部署錯誤，以及疑難排解方法：

• 權限錯誤
• 常見部署錯誤

權限錯誤

本節說明因缺少帳戶權限或機構政策變更，導致應用程式部署時可能發生的錯誤。

如要找出您用來存取 Google Cloud CLI 和 Google Cloud 平台中其他工具的有效帳戶，請執行下列其中一項操作：

• 如果您使用 Google Cloud CLI 部署，請執行 gcloud auth list 指令。

• 如果您是從 IDE 部署，請查看 Cloud Tools 外掛程式的設定。

如要瞭解為何在某些情況下，只指派 App Engine 部署者 (roles/appengine.deployer) 角色可能不夠，請參閱「App Engine 角色」。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」一文。

新專案的部署作業失敗

在新的專案中首次部署應用程式時，您可能會看到下列錯誤訊息：

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 [e-mail] does not have access to the bucket

如要解決這個問題，請將「Storage 管理員 (roles/storage.admin)」角色授予預設服務帳戶。詳情請參閱「將建構記錄儲存在使用者建立的 bucket」。

如果您已授予「儲存空間管理員」角色，以及部署期間遇到不同權限錯誤時所需的其他角色，但仍無法部署應用程式，可能是因為機構政策有下列變更：

• 自 2024 年 5 月起， Google Cloud 會對所有機構資源強制執行預設安全機構政策。這項政策可防止 App Engine 將 Editor 角色授予 App Engine 預設服務帳戶。

• 2024 年 6 月，Cloud Build 變更了新專案中服務帳戶的預設使用方式。詳情請參閱「Cloud Build 服務帳戶異動」。因此，首次部署版本的新專案可能會使用預設的 App Engine 服務帳戶，但該帳戶的權限不足，無法部署版本。

如要解決這個問題，請按照下列步驟操作：

• 將 Editor 角色授予 App Engine 預設服務帳戶 ([e-mail])。

• 請參閱 Cloud Build 指南，瞭解預設服務帳戶的異動，並在新專案中停用預設異動。

呼叫者沒有專案存取權

如果服務帳戶沒有在目前專案中部署應用程式的權限，就會發生下列錯誤：

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

如要解決這個問題，請將 App Engine 部署者 (roles/appengine.deployer) 角色授予服務帳戶。

無法從登錄檔擷取中繼資料

如果從沒有「Storage Admin (roles/storage.admin)」角色的服務帳戶使用 gcloud app deploy 指令，就會發生下列錯誤：

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

如要解決這個問題，請將 Storage 管理員角色授予服務帳戶。

服務帳戶必須具備映像檔的權限

部署應用程式時會發生下列錯誤：

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

發生這項錯誤的原因如下：

• 預設 App Engine 服務帳戶沒有 Storage 物件檢視者 (roles/storage.objectViewer) 角色。

  如要解決這個問題，請將 Storage 物件檢視者角色授予服務帳戶。

• 您的專案有 VPC Service Controls 服務範圍，可使用存取層級限制 Cloud Storage API 存取權。

  如要解決這個問題，請將用於部署應用程式的服務帳戶新增至對應的 VPC Service Controls 服務範圍 accessPolicies。

• 2024 年 5 月 15 日之後，如果專案先前未使用過 Container Registry，專案中的 gcr.io 網域映像檔就會託管於 Artifact Registry。 Google Cloud 如果您在上述日期後建立的新專案中部署現有應用程式，服務帳戶可能沒有部署應用程式的必要權限。如要授予必要權限，請參閱「部署至 App Engine」。

無法建立 Cloud Build

如果您從沒有 Cloud Build 編輯者 (roles/cloudbuild.builds.editor) 角色的服務帳戶使用 gcloud app deploy 指令，就會發生下列錯誤。

Failed to create cloud build: Permission denied

如要解決這個問題，請將 Cloud Build 編輯者角色授予服務帳戶。

擷取應用程式時發生錯誤

如果您用來部署應用程式的服務帳戶沒有 App Engine 部署者角色，就會發生下列錯誤。

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.

If you are running Google Cloud CLI version 328 or later, the following error occurs
when you deploy your app:

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 部署者角色授予用於部署應用程式的服務帳戶。

使用無伺服器虛擬私有雲存取連接器部署服務時發生錯誤

如果嘗試使用無伺服器虛擬私有雲存取連接器部署應用程式的使用者或服務帳戶沒有必要權限，就會發生下列錯誤：

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

如要解決這個問題，請確認用於部署作業的使用者或服務帳戶具有「無伺服器虛擬私有雲存取使用者」和「Compute 檢視者 IAM」角色。

等待應用程式基礎架構進入良好狀態的時間過久，因此已逾時

部署應用程式時會發生下列錯誤：

Timed out waiting for the app infrastructure to become flex_await_healthy

造成這項錯誤的原因有很多，例如缺少權限、程式碼錯誤、CPU 或記憶體不足，或是健康狀態檢查失敗。

如要解決這個問題，請排除下列可能原因：

1. 檢查專案的機構政策是否限制存取外部 IP 位址。詳情請參閱「App Engine 彈性環境已知問題」。

2. 確認您已將下列角色授予用於執行應用程式的服務帳戶 (通常是預設服務帳戶，[e-mail])：

   • 編輯者 (roles/editor)

   • 儲存空間物件檢視器 (roles/storage.objectViewer)

   • 記錄寫入者 (roles/logging.logWriter)

3. 如果服務帳戶沒有其餘角色，請根據部署錯誤授予這些角色。

4. 如果您在共用虛擬私有雲設定中部署，並在 app.yaml 檔案中設定 instance_tag，請參閱「在共用虛擬私有雲設定中部署時發生值無效的錯誤」一文，瞭解如何修正問題。

重新啟動執行中版本下的執行個體時發生錯誤

部署應用程式時會發生下列錯誤：

error when restarting the instance under the running versions

自 2024 年 5 月起， Google Cloud 會對所有新機構強制執行預設安全的機構政策。這項政策規定，新專案中建立的所有 VM 執行個體都必須啟用 VM 管理員。如果在新專案和現有專案中設定這項限制，就無法進行會在專案或執行個體層級停用 VM 管理員的中繼資料更新作業。

如要解決這個問題，請停用機構政策限制「需要 OS 設定」(constraints/compute.requireOsConfig)。

如果問題仍未解決，您也必須停用下列可能在專案或機構層級啟用的機構政策：

• 為 VM 執行個體定義允許的外部 IP (constraints/compute.vmExternalIpAccess)。如果您的應用程式設定為僅使用私人網路，則不必停用這項限制。

• 停用 Compute Engine 中繼資料的訪客屬性 (constraints/compute.disableGuestAttributesAccess)

必要compute.firewalls.list權限

在共用虛擬私有雲網路上部署應用程式時，會發生下列錯誤：

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 網路使用者 (roles/compute.networkUser) 角色，就會發生這個錯誤：

• Google API 服務代理
• App Engine 彈性環境服務代理

注意： 主專案是包含共用虛擬私有雲的專案，而不是您用來部署 App Engine 應用程式的服務專案。

Google Cloud

如要解決這個問題，請將Compute 網路使用者角色授予主專案的 Google API 服務代理人和 App Engine 彈性環境服務代理人服務帳戶。

因機構政策限制而無法部署

部署應用程式時發生下列錯誤：

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

這可能是因為部署應用程式時，系統強制執行 constraints/compute.disableGuestAttributesAccess 限制。App Engine 彈性環境中的所有應用程式預設都會強制執行這項機構政策。

如要解決這個問題，請停用 constraints/compute.disableGuestAttributesAccess 限制。

常見部署錯誤

本節說明如何排解應用程式或專案中的設定錯誤。

在共用 VPC 設定中部署時發生無效值錯誤

部署應用程式時，彈性 VM 執行個體的 Cloud Logging 會顯示下列錯誤：

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

這是已知問題，在 app.yaml 檔案中設定 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.

每個專案可建立的執行個體數量上限為 100 個。如果超出這項限制，建立其他執行個體的要求就會失敗。

如要解決這個問題，請將 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 值區設定了資料保留政策。

如要解決這個問題，請變更 bucket 的下列設定：

• 將加密設為 Google-owned and Google-managed encryption keys。
• 移除保留政策。

部署至現有 App Engine 版本時發生錯誤

部署至 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 映像檔更新現有版本，但這並非最佳做法。如果版本失敗，系統不會復原。

在共用 VPC 設定中部署時發生內部 IP 錯誤

在服務專案中部署至共用虛擬私有雲網路設定時，如果使用預設的私人 IP 位址設定 (private-ranges-only)，可能會發生下列錯誤。

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred.

這項錯誤可能表示共用虛擬私有雲主專案中的 App Engine 彈性環境服務代理程式無法使用。可能是因為 App Engine 彈性環境服務代理人已遭移除，或是主專案未啟用 App Engine API。

如何解決這個問題：

1. 在共用虛擬私有雲網路的主專案中啟用 App Engine API。
2. 如果已啟用 App Engine API，專案中就不會存在 App Engine 彈性環境服務代理人。請參閱「還原服務代理的必要角色」。

無法連線至 Google API，因此部署失敗

部署應用程式時會發生下列錯誤：

Your deployment has failed to become healthy in the allotted time and therefore was rolled back. If you believe this was an error, try adjusting the app_start_timeout_sec setting in the readiness_check section.

如要解決這個問題，請確認與應用程式相關聯的 VPC 具有目的地為 0.0.0.0/0 的本機靜態路徑，以及預設網際網路閘道下一個躍點。如果您使用僅限內部使用的私人服務，請在所選子網路啟用 PGA。