部署 Java 應用程式

部署您的應用程式以上傳到 App Engine 上執行。部署應用程式時,您必須在 App Engine 中建立應用程式的版本及對應的服務。您可以部署完整的應用程式 (包括所有原始碼和設定檔),也可以部署及更新個別版本或設定檔

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

事前準備

在您部署應用程式之前,請先完成下列事項:

如要使用 Maven 建構工具部署應用程式,您必須設定專案可使用 App Engine 的 Maven 外掛程式

安裝 gcloud 指令列工具

如要使用 gcloud 工具部署應用程式,您必須下載、安裝並初始化 Cloud SDK

下載 SDK

如果您已安裝 gcloud 工具,並想將其設為使用某組 GCP 專案 ID,而非工具初始化時使用的 ID,請參閱管理 Cloud SDK 設定一文。

使用 Proxy

如果您是從使用 HTTP 或 HTTPS Proxy 的系統執行部署指令,則必須設定工具,讓它能夠透過 Proxy 通訊。

gcloud

執行以下指令以設定 gcloud 工具:

gcloud config set proxy/type [PROXY_TYPE]
gcloud config set proxy/address [PROXY_ADDRESS]
gcloud config set proxy/port [PROXY_PORT]

您還可以設定用於 Proxy 的 usernamepassword。詳情請參閱 gcloud config 一文。

appcfg

設定與您 Proxy 對應的環境變數:

Mac/Linux
export HTTP_PROXY="http://cache.example.com:3128"
export HTTPS_PROXY="http://cache.example.com:3128"
Windows
set HTTP_PROXY=http://cache.example.com:3128
set HTTPS_PROXY=http://cache.example.com:3128

部署應用程式

如要將應用程式部署到 App Engine,請在應用程式根目錄內使用 Maven 建構工具 (建議)、appcfg 工具或 gcloud app deploy 指令。

如要使用 Maven 建構工具部署應用程式,請在 pom.xml 檔案所在的專案頂層目錄中執行下列指令。

使用 appcfg

如要部署應用程式,請搭配 update 動作,對 WAR 檔案的目錄路徑執行 appcfg 指令,例如:

Windows

appengine-java-sdk\bin\appcfg.cmd [options] update [WAR_LOCATION]

Mac/Linux

./appengine-java-sdk/bin/appcfg.sh [options] update [WAR_LOCATION]

如果您要使用 HTTP Proxy,請加入 --proxy 引數以告知 appcfg 其位址。如果您針對 HTTPS 使用不同的 Proxy,則請也加入 --proxy_https 引數。詳情請參閱 appcfg 指令列引數一文。

Windows

appengine-java-sdk\bin\appcfg.cmd --proxy=10.1.2.3 update [WAR_LOCATION]

Mac/Linux

./appengine-java-sdk/bin/appcfg.sh --proxy=10.1.2.3 update [WAR_LOCATION]

根據預設,您部署至服務的初始版本會自動設定為接收 100% 的流量。然而,您必須手動設定所有部署至相同服務的後續版本,否則這些版本會無法接收流量。

此工具會自動使用 appengine-web.xml 檔案中的應用程式 ID。 但是,我們的許多範例應用程式都會省略 appengine-web.xml 檔案中的 <application>,以及 <version>。 因此,您必須確保為應用程式 ID 指定 GCP 專案 ID 以及您選擇的版本 ID,例如:

Windows

appengine-java-sdk\bin\appcfg.cmd -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [WAR_LOCATION]

Mac/Linux

./appengine-java-sdk/bin/appcfg.sh -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [WAR_LOCATION]

如果您部署版本的版本 ID 與目前已在 App Engine 的版本相同,則您部署的檔案會覆寫現有版本。當您覆寫應用程式時,流量可能會中斷。建議您使用專屬版本 ID 來部署應用程式,並遷移流量至新版本。

使用 gcloud 指令列

gcloud app deploy [YOUR_DEPLOYMENTS]

其中,[YOUR_DEPLOYMENTS] 是一或多個設定檔的路徑和名稱,並以一個空格分隔。

選用標記:

  • 加上 --version 標記可指定自訂版本 ID;如未加入,則由系統產生。
  • 如要部署應用程式但不將所有流量自動轉送至這個版本,請加入 --no-promote 標記。
  • 加上 --project 標記以指定替代 GCP 專案 ID,而不使用您在 gcloud 工具中初始化為預設值的 ID。

根據預設,您部署的每個版本都會自動設定為接收 100% 的流量。如想瞭解設定選項,請參閱 gcloud app deploy 參考資料中的 --promote 標記。

提示:從指令列執行 gcloud help,即可取得完整的引數和標記清單。

選擇不重覆的版本 ID

如果是手動調整資源配置的執行個體,版本的 ID 應以字母開頭,藉以區別數字執行個體 ID。這可確保要求會轉送至正確的目的地,避免與 123.my-service.appspot.com 之類的網址模式混淆不清,這類模式可以有兩種解讀方式:

  • 如果 123 版本存在,要求會轉送至 my-service 服務的 123 版本。
  • 如果 123 版本不存在,要求會改為轉送至執行 my-service 服務版本的執行個體 ID 123

對於設定成自動調整或基本資源配置的執行個體,您可以任意為版本命名,因為系統不支援將這些執行個體指定為目標

部署多服務應用程式

當應用程式納入多個服務時,您可以個別部署和更新指定的服務,或同時部署和更新所有服務。部署服務更新可包括更新個別的設定檔,或是更新對應版本中的原始碼。

舉例來說,您可以在 App Engine 中部署及建立兩個版本,這兩個版本分別在各自的服務中執行。第一個版本做為前端服務,另一個版本則做為應用程式的後端。接著,您可以透過部署各自的設定檔,僅更新服務的設定。您也可以選擇部署服務的新版本,以同時更新前端及/或後端的原始碼。

部署多個服務的需求

您可以使用相同的部署指令來部署和更新應用程式的多個服務,但必須符合下列需求:

  • 您必須先將應用程式的一個版本部署到 default 服務,然後才能建立和部署後續服務。

  • 您必須在對應版本的 appengine-web.xml 設定檔中指定服務的 ID。如要指定服務 ID,請在每個設定檔中加入 module: [YOUR_SERVICE_ID] 元素定義。根據預設,從設定檔排除此元素定義,會將版本部署至 default 服務。

  • 在部署指令中,您必須指定所有對應的 appengine-web.xml 設定檔,才能同時部署多項服務。default 服務必須優先列出。

部署多服務的方式

從設定檔所在的應用程式根目錄執行部署指令,並針對每個服務的 appengine-web.xml 檔案指定相對的路徑和檔名:

使用 Maven 建構工具

如果專案的根目錄只包含您的服務,則可使用單一 Maven 指令部署所有服務。

Maven 部署指令會反覆查詢專案的每個服務,找出其設定檔,然後部署每個服務。

使用 Maven 外掛程式部署多個服務:

  1. 確認 appengine-maven-plugin 已新增至您的父項 pom.xml 檔案。
  2. 執行下列指令:

    mvn appengine:deploy
    

使用 gcloud

    gcloud app deploy [DEPLOYMENTS]

其中 [DEPLOYMENTS] 是一或多個設定檔的路徑和名稱。您可以使用單一空格分隔每個指定的設定檔。

使用 appcfg

Windows

appengine-java-sdk\bin\appcfg.cmd update [DEPLOYMENTS]

Mac/Linux

./appengine-java-sdk/bin/appcfg.sh update [DEPLOYMENTS]

其中 [DEPLOYMENTS] 是一或多個設定檔的路徑和名稱,並以一個空格分隔。例如:

Windows

appengine-java-sdk\bin\appcfg.cmd update [WAR_LOCATION] [SERVICE1_WAR_LOCATION] [MOD2_WAR_LOCATION]

Mac/Linux

./appengine-java-sdk/bin/appcfg.sh update [WAR_LOCATION] [SERVICE1_WAR_LOCATION] [MOD2_WAR_LOCATION]

成功部署每個服務後,您會透過指令列收到驗證訊息。

更新索引

如要建立或更新應用程式使用的索引,請將 datastore-indexes.xml 設定檔上傳到 Cloud Datastore。上傳設定檔後,系統就會建立尚未存在的索引。

Cloud Datastore 可能需要一些時間來建立所有索引,因此索引不會馬上提供給 App Engine 使用。如果您的應用程式已設定為接收流量,當查詢所需的索引還在建置時,便會發生例外情況。

為了避免例外發生,請讓系統有充裕的時間來建置所有索引。

  • 先將 index.xml 設定檔上傳到 Cloud Datastore,然後再部署版本:

    1. index.xml 檔案上傳到 Cloud Datastore:

      appcfg
      appcfg.sh update_indexes [YOUR_APP_DIR]
    2. 使用 GCP 主控台監控所有索引的狀態:

      前往 Datastore 頁面

    3. 在所有索引建構完成後,將新版本部署至 App Engine

  • 先建構索引,再將流量遷移或拆分至您的版本:

    1. 在應用程式的 appengine-web.xml 檔案中定義新版本 ID。
    2. 部署新版本
    3. 使用 GCP 主控台監控所有索引的狀態:

      前往 Datastore 頁面

    4. 所有索引建構完成後,再使用 GCP 主控台遷移或拆分流量至該版本:

      前往「Versions」(版本) 頁面

如要進一步瞭解索引,請參閱設定 Datastore 索引一文。

疑難排解

以下是您可能會看到的常見錯誤訊息:

PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
如果 GCP 專案缺少必要的 App Engine 應用程式gcloud app deploy 指令嘗試執行 gcloud app create 指令時可能會失敗。只有具備「擁有者」角色的帳戶才具有建立 App Engine 應用程式的必要權限。
Command not found

如果您在安裝 (已淘汰) App Engine SDK 時,沒有建立 appcfg.shdev_appserver.sh 工具的符號連結,則可能需要指定完整的目錄路徑才能執行工具,例如:[PATH_TO_APP_ENGINE_SDK]/appcfg.sh[PATH_TO_APP_ENGINE_SDK]/dev_appserver.sh

Import Error

如果您安裝了 Cloud SDK 及原始 App Engine SDK,則 PATH 的不同項目之間可能會發生衝突,造成匯入錯誤。如果您在執行 Cloud SDK 指令時收到錯誤訊息,請嘗試明確使用原始的 App Engine SDK。您可以將原始 App Engine SDK 的項目移到 PATH 中較前面的位置,讓這些指令優先執行。您也可以指定完整的目錄路徑來執行指令:[PATH_TO_APP_ENGINE_SDK]/java_dev_appserver.sh
提示:您可以在 Linux 或 Mac 中執行 which dev_appserver.py,以確定 PATH 中優先的 SDK 版本。

[400] The first service (module) you upload to a new application must be the 'default' service (module)

部署及建立應用程式的多項服務前,請務必先部署並建立 default 服務。有關如何將版本部署至 default 服務的詳情,請參閱部署多服務應用程式一節。

Too Many Versions (403)

App Engine 對應用程式設有部署版本數量的限制。免費應用程式和已部署的應用程式各有不同的限制數量。您可以使用 GCP 主控台刪除較舊的版本,然後上傳最新的程式碼。 You do not have permission to modify this app (403)

如果您驗證的帳戶沒有部署應用程式 ID 的權限,而應用程式 ID 是在您的指令或 appengine-web.xml 中指定,則會發生這種情形。請檢查您的應用程式 ID 是否正確,以及是否符合 GCP 主控台專案 ID 的值。接下來,請檢查主控台的專案權限,確認您列出的帳戶是否具有足夠的權限層級,能夠允許您部署應用程式。如果帳戶權限與專案 ID 顯示正確,您可以嘗試從主目錄移除 .appcfg_oauth2_tokens 檔案來強制重新驗證 SDK,並重試部署指令。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Java 8 適用的 App Engine 標準環境