測試及部署應用程式

區域 ID

REGION_ID 是 Google 根據您在建立應用程式時選取的地區所指派的縮寫代碼。此代碼不對應至國家/地區或省份，即使部分區域 ID 可能與常用的國家/地區和省份代碼相似。如果是 2020 年 2 月後建立的應用程式，App Engine 網址會包含 REGION_ID.r。如果是這段時間前建立的現有應用程式，網址可選擇是否包含地區 ID。

進一步瞭解區域 ID。

瞭解如何在本機執行應用程式、進行部署，然後在 App Engine 上測試。

在本機上執行

如要在部署前先測試應用程式，請使用您常用的開發工具，在本機環境中執行應用程式。 舉例來說，您通常可以使用 Flask 的開發伺服器，透過下列指令來執行 Flask 應用程式：

python main.py

使用下列指令啟動 Django 應用程式：

python manage.py runserver

如要模擬 App Engine 實際工作環境，您可以在本機執行完整的網路伺服器閘道介面 (WSGI) 伺服器。使用 app.yaml 檔案中指定的 entrypoint 指令，例如：

gunicorn -b :$PORT main:app

部署應用程式

使用 gcloud app deploy 指令，將應用程式部署到 App Engine。

Cloud Build 服務會自動將部署作業建構為容器映像檔，並將該映像檔部署至 App Engine 彈性環境。容器中會包含您對執行階段映像檔所進行的任何本機修訂。

如要透過程式部署應用程式，請使用 Admin API。

事前準備

部署應用程式之前：

確保成功部署

如果您啟用更新版健康狀態檢查，但是應用程式並未達到健康狀態良好狀態，則部署將會復原到未部署的狀態。當您將第一個應用程式部署至彈性環境時，可能會因為系統設定虛擬機器 (VM) 和其他基礎架構而發生延遲。完成初始設定後，健康狀態檢查可確保執行個體的健康狀態良好，且已準備好可以接收流量。如果應用程式沒有在指定時間 (依 app.yaml 檔案之 liveness_check 區段的 initial_delay_sec 欄位指示) 內達到就緒狀態，部署作業將會失敗並復原到未部署的狀態。

您的應用程式可能需要更多時間才能準備就緒。例如，您可能是透過下載大型檔案或預先載入快取內容來初始化應用程式。如果您使用更新版健康狀態檢查，則可以修改 app.yaml 檔案裡 readiness_check 區段中的 app_start_timeout_sec 配置設定來延長時間。

如果部署失敗，請確認專案已啟用 Cloud Build API。首次部署應用程式時，App Engine 會自動啟用這項 API，但如果有人之後停用這項 API，部署作業就會失敗。

部署服務

您可以透過部署應用程式各項服務的版本及設定檔，將應用程式部署至 App Engine。

如要部署應用程式服務，請從服務的 app.yaml 檔案所在的目錄執行下列指令：

gcloud app deploy

根據預設，gcloud app deploy 指令只會部署目前目錄中的 app.yaml 檔案。每當您執行這項指令時，App Engine 會為您部署的版本產生唯一 ID、將該版本部署至您設定 gcloud CLI 所使用的Google Cloud 專案，並將所有流量轉送至新版本。新版本會成為預設版本。

您可以指定特定檔案、指定版本或加入其他參數，變更部署指令的預設行為：

  • 如要部署服務的其他設定檔，請個別指定及部署每個檔案，例如：

    gcloud app deploy cron.yaml
gcloud app deploy dispatch.yaml
gcloud app deploy index.yaml

  • 如要指定自訂版本 ID，請使用 --version 標記。

  • 如要避免系統將流量自動轉送至新版本，請使用 --no-promote 標記。

  • 如要部署到特定 Google Cloud 專案，請使用 --project 標記。

舉例來說，如要將 app.yaml 檔案定義的服務部署至特定Google Cloud 專案，請為該服務指派自訂版本 ID，還要避免將流量轉送至新版本：

gcloud app deploy --project PROJECT_ID --version VERSION_ID --no-promote

詳情請參閱 gcloud app deploy 參考資料。

您可以設定 gcloud CLI 的屬性，並建立及管理 SDK 設定，這樣每次進行部署時就不需要再指定 --project 等標記。

如果您在部署新版本時採用現有版本的名稱，App Engine 會立即將流量遷移至新版本。App Engine 將要求載入新版本時，延遲時間可能會遽增。新版本會覆寫舊版本，且無法將流量遷移至舊版本。如果您部署新版本時採用先前版本的名稱，App Engine 會將新的容器映像檔部署至現有的虛擬機器，以加快部署速度，並更新現有虛擬機器上的應用程式容器。

部署多項服務

您可以使用相同的部署指令來部署或更新組成應用程式的多項服務。

事前準備：

  • 您必須先將應用程式的某個版本部署到 default 服務，才能建立及部署後續服務。

  • 您必須在每項服務各自對應的app.yaml設定檔中指定服務 ID。如要指定服務 ID，請在每個設定檔中加入 service 元素定義。如果沒有在設定檔中加入這個元素定義，系統會依預設將版本部署到 default 服務。

如要部署多項服務，您必須個別部署每項服務的 app.yaml 檔案，例如：

gcloud app deploy service1/app.yaml
gcloud app deploy service2/app.yaml

您可以透過單一部署指令來指定多個檔案：

gcloud app deploy service1/app.yaml service2/app.yaml

忽略檔案

部署服務時，如果您不想讓系統將特定的檔案和目錄一併上傳至 .gcloudignore，可以使用 Google Cloud檔案來進行設定。如要略過不必隨著部署作業一起上傳的建構構件和其他檔案，這個方法十分實用。

如要進一步瞭解 .gcloudignore 檔案語法，請參閱 gcloud 參考資料。

手動建構用於部署的容器

如要在 Google Cloud外部建構容器映像檔：

  1. 將映像檔上傳至 Artifact Registry 存放區。詳情請參閱「推送及提取映像檔」。
  2. 使用 gcloud app deploy 指令部署至 App Engine。

舉例來說，如果您在本機環境中使用 Docker 建構容器映像檔，則可將這些映像檔推送至 Artifact Registry，然後在指令的 --image-url 標記中指定映像檔的網址：

gcloud app deploy --image-url LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

取代：

  • 將 LOCATION 替換為儲存映像檔的存放區位置。

  • 將 PROJECT-ID 替換為您的 Google Cloud專案 ID。

  • REPOSITORY 改為儲存映像檔的存放區名稱。

  • IMAGE 改為您的容器映像檔名稱。

使用自動化持續部署管道

您可以使用 Cloud Build 自動在持續部署管道中進行部署。詳情請參閱 Cloud Build 說明文件中的「部署至 App Engine」和「建立及管理建構觸發條件」。

Docker 基本映像檔

如要建構自訂執行階段應用程式，請參閱「建立 Docker 檔案」。

查看您的應用程式

將應用程式部署至 App Engine 之後，就能執行下列指令來啟動瀏覽器，並前往 https://PROJECT_ID.REGION_ID.r.appspot.com 查看：

gcloud app browse

在 App Engine 上測試

您可以先在 App Engine 上測試新版本，然後再設定該版本以接收流量。例如，您可採取下列做法測試 default 服務的新版本：

  1. 將 promote 參數設為 false，部署新版本： 並加入 --no-promote 旗標： 

    gcloud app deploy --no-promote

  2. 前往下列網址以存取新版本：

    https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

    您現在可以在 App Engine 執行階段環境中測試新版本。您可以在Google Cloud 控制台的記錄檔探索工具中查看應用程式記錄，藉此進行偵錯。詳情請參閱「寫入應用程式記錄」。

    系統仍會將傳送至 https://PROJECT_ID.REGION_ID.r.appspot.com 的要求轉送至先前設為要接收流量的版本。

  3. 當您要將流量傳送至新版本時，請使用Google Cloud 控制台遷移流量：

    管理版本

    選取您剛剛部署的版本，然後按一下 [Migrate traffic] (遷移流量)。

您只要將網址中的 default 替換成服務名稱，即可透過相同程序測試其他服務的新版本：

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

如要進一步瞭解如何指定特定服務和版本，請參閱要求的轉送方式。

使用建構環境變數

如果執行階段支援 buildpack，您也可以設定建構環境變數。

建構環境變數是鍵/值組合，可供您指定用來部署應用程式的 buildpack 設定。舉例來說，您可能想指定編譯器選項。

事前準備：

  • 鍵的開頭須為大寫 ASCII 字母，且只能包含大寫 ASCII 字母、數字和底線。
  • 請避免建立開頭為 GOOGLE_* 鍵前置字元的變數。
  • 下列鍵保留供 Google 使用：
    • GOOGLE_RUNTIME
    • GOOGLE_RUNTIME_VERSION
    • GOOGLE_ENTRYPOINT
    • GOOGLE_DEVMODE
  • 您可以使用建構套件支援的任何金鑰。

如要搭配建構套件使用環境變數，請在 app.yaml 檔案中指定 build_env_variables 欄位。

進一步瞭解建構套件。

使用 Cloud Trace

Cloud Trace 可協助您瞭解要求在應用程式中傳播的情形。您可以查看單項要求的詳細延遲資訊，或是瀏覽整個應用程式的匯總延遲資料。

您可以查看追蹤記錄詳細資料。 在追蹤記錄探索器中，您可以依特定 App Engine 服務和版本進行篩選。

疑難排解

以下是部署應用程式時可能會遇到的常見錯誤訊息：

PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
如果 Google Cloud 專案缺少必要的 App Engine 應用程式，gcloud app deploy 指令嘗試執行 gcloud app create 指令時可能會失敗。只有具備「擁有者」角色的帳戶才具有建立 App Engine 應用程式的必要權限。
502 Bad Gateway
如果 app.yaml 設定有誤， Google Cloud 專案可能無法啟動。查看應用程式記錄，瞭解更詳細的錯誤訊息。
[13] An internal error occurred while creating a Cloud Storage bucket.

App Engine 會在建立應用程式的同一區域，代表您建立預設 Cloud Storage 多區域值區。這個值區必須儲存應用程式的內容。如果無法建立這個 bucket，系統就會傳回錯誤，例如在下列情況中：

舉例來說，如果您的 App Engine 應用程式是在 europe-west 地區建立，即使該地區對應至 europe-west1 位置，您也必須修改限制，允許 in:eu-locations 中的資源，包括所有 EU 地區。這是必要步驟，因為 App Engine 建立的 Bucket 是多區域 Bucket。如果您的 App Engine 應用程式是在 US 地區建立，您必須允許 in:us-locations；如果應用程式是在 ASIA 地區建立，則必須允許 in:asia-locations。

[13] An internal error occurred.

如果您部署服務時使用的網路設定採用共用虛擬私有雲設定，就可能發生這項錯誤。請嘗試按照下列步驟操作：

  1. 確認 app.yaml 設定有效。
  2. 確認 App Engine 彈性環境符合共用 VPC 設定的所有需求。請參閱「在共用虛擬私有雲網路上使用 App Engine 彈性環境」。
  3. 請確認專案中已設定服務帳戶。如果不是，請務必還原帳戶。 共用虛擬私有雲主專案中的子網路區域，必須與建立 App Engine 環境的位置相符。

如果問題仍未解決，請使用 Google Cloud SDK 重新部署服務。請務必加上 --verbosity=debug 旗標。請與Google Cloud 支援團隊聯絡，並提供指令輸出內容。

IP space of {USER_SUBNETWORK_NAME} is exhausted and needs to be expanded.

如果部署作業失敗並顯示這則錯誤訊息，表示為 App Engine 服務設定的網路沒有足夠的位址，可供服務的新執行個體分配。如要解決這個問題，請在為 App Engine 彈性環境服務設定的子網路上擴展 VPC 範圍。