排解 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 PROJECT_ID@appspot.gserviceaccount.com 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 預設服務帳戶 (PROJECT_ID@appspot.gserviceaccount.com)。

  • 請參閱 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」角色。

常見部署錯誤

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

在共用 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

如果點按錯誤訊息中的連結後，發現所有建構步驟都成功，但應用程式仍建構失敗，可能的原因如下：

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

執行 Node.js 應用程式時建構失敗

部署 Node.js 應用程式時，可能會發生建構失敗的情況。

根據預設，如果 Node.js 執行階段在 package.json 檔案中偵測到建構指令碼，就會執行 npm run build。這可能會導致建構作業長時間執行，或發生記憶體不足錯誤等非預期行為。

如要解決這個問題，請在 app.yaml 檔案中指定 NODE_ENV=development，確保執行作業具備所有必要依附元件。

即使發生錯誤，您仍可在 app.yaml 檔案的 build-env-variables 下方指定 NODE_ENV: 'production'，強制進行生產：

  build_env_variables:
    NODE_ENV: 'production'

詳情請參閱「在部署期間執行自訂建構步驟」。