使用 App Design Center 快速部署應用程式

1. 簡介

在本程式碼研究室中，您將學習如何使用 Google Cloud App Design Center (ADC) 部署全端應用程式。您將部署「The Cymbal London Concierge」應用程式，其中包含 Vue 3 前端、FastAPI 後端，以及保存應用程式資料的 MCP 伺服器。

ADC 可讓您以視覺化方式定義應用程式架構，並以單一單元的形式部署，自動管理依附元件和連線。

學習內容

  • 設定 App Design Center。
  • 以視覺化方式組裝應用程式元件。
  • 部署應用程式架構。
  • 確認應用程式正在執行。
  • 確認應用程式已向 App Hub 註冊。
  • 在應用程式監控中驗證應用程式指標、追蹤記錄和記錄檔。

軟硬體需求

  • 網路瀏覽器，例如 Chrome。
  • 已啟用計費功能的 Google Cloud 專案。

本程式碼研究室適合各種程度的開發人員，包括初學者。

預估時間：45 分鐘 預估費用：不到 $2.00 美元

2. 設定

專案設定

建立 Google Cloud 專案

  1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
  2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

啟動 Cloud Shell

Cloud Shell 是在 Google Cloud 中運作的指令列環境，已預先載入必要工具。

  1. 點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」。
  2. 連至 Cloud Shell 後，請驗證您的驗證：
    gcloud auth list
  3. 確認專案已設定完成：
    gcloud config get project
  4. 如果專案未如預期設定，請設定專案：
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

3. 設定 App Design Center

您必須先在 ADC 中設定工作區，才能組裝應用程式。

  1. 在 Google Cloud 控制台搜尋並前往「App Design Center」。
  2. 如果這是您第一次在這個專案中使用 ADC，系統會顯示設定畫面。
  3. 按一下「前往設定」。

設定 App Design Center

  1. 如果尚未啟用必要 API，系統會提示您啟用。按一下「啟用」繼續操作。

啟用 API

4. 探索 ADC 功能

在這項工作中，您將瞭解 ADC 的核心元件：空間、目錄和範本。

ADC Spaces

工作區是建立範本及部署應用程式的位置。每個工作區都屬於 Google Cloud 專案。ADC 會在初始設定期間建立預設空間，但您之後可以自由在不同區域建立其他空間。

如要透過終端機查看空間，請按照下列步驟操作：

  1. 點按 Cloud Shell 工具列中的「開啟編輯器」，或使用終端機。
  2. 執行下列指令：
gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

輸出內容應如下所示，表示該區域有預設空間。

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5. 組裝範本

在這個步驟中，您將扮演平台團隊工程師的角色。您的目標是為貴機構的代理程式應用程式建立可重複使用、安全且符合法規的範本。您將新增元件並設定限制，確保從這個範本部署的任何應用程式都符合貴公司的雲端政策。

1. 建立新設計

  1. 在 ADC 控制台中，依序點選「範本」>「建立範本」。
  2. 將範本命名為 simple-3-tier-agentic-app，因為這個範本將用於部署 Cymbal London Concierge 應用程式和其他類似應用程式。建立範本

2. 新增資料 MCP 伺服器

這個元件會處理資料庫互動和向量搜尋。

  1. 依序點選「Add Component」 >「Cloud Run (Service)」。點選該元件後，右上角會顯示元件 ID。格式為 cloud-run-1。我們可以在程式碼檢視畫面中編輯，將其變更為 data-mcp-server (稍後會討論)，但先保留原樣。新增元件
  2. 輸入「Service Name」(服務名稱)：data-mcp-server。
  3. 在「顯示進階設定」下方，將「成員」設為：allUsers。(注意：在正式環境中，您可能會限制這項設定，但我們在這裡使用這項設定，是為了簡化程式碼研究室。)
  4. 在「顯示進階設定」下方，設定「虛擬私有雲存取」，並將「輸出」設為：PRIVATE_RANGES_ONLY。
  5. (選用) 在「顯示進階設定」下方，取消勾選「啟用 Prometheus Sidecar」。虛擬私有雲存取權
  6. 按一下 [儲存]。

3. 新增代理程式後端

這是用來調度代理行為的 FastAPI 應用程式。

  1. 依序點選「Add Component」 >「Cloud Run (Service)」。
  2. 將其命名為 agent-backend。
  3. 在「顯示進階欄位」下方，勾選「建立服務帳戶」，然後在「服務帳戶專案角色」下方逐一新增下列角色：
    • roles/monitoring.metricWriter
    • roles/logging.logWriter
    • roles/cloudtrace.agent
    • roles/telemetry.writer
    • roles/serviceusage.serviceUsageConsumer。這些角色可讓代理程式使用 Cloud Monitoring、Cloud Logging 和 Cloud Trace。法規遵循設定：平台團隊會明確列出必要角色，強制執行最小權限原則。
    角色
  4. 在「顯示進階設定」下方，將「成員」設為：allUsers。
  5. 在「顯示進階設定」下方，設定「虛擬私有雲存取」，並將「輸出」設為：PRIVATE_RANGES_ONLY。
  6. (選用) 在「顯示進階設定」下方，取消勾選「啟用 Prometheus Sidecar」。
  7. 將 agent-backend 拖曳至 data-mcp-server，即可連結兩者。agent-backenddata-mcp-server
  8. 按一下 [儲存]。

4. 新增前端

前端 UI。

  1. 依序點選「Add Component」 >「Cloud Run (Service)」。
  2. 輸入「Service Name」(服務名稱)：frontend。
  3. 在「顯示進階設定」下方，取消勾選「建立服務帳戶」。
  4. 在「顯示進階設定」下方，將「Ingress」設為 INGRESS_TRAFFIC_INTERNAL_LOADBALANCER。法規遵循設定：封鎖前端容器的直接公開存取權，強制流量通過負載平衡器。
  5. 在「顯示進階設定」下方，將「成員」設為：allUsers。前端
  6. (選用) 在「顯示進階設定」下方，取消勾選「啟用 Prometheus Sidecar」。
  7. 按一下 [儲存]。
  8. 將 frontend 拖曳至 agent-backend，即可連結兩者。frontendagent-backend

5. 新增 Vertex AI 元件

  1. 依序點選「新增元件」 >「Vertex AI」。
  2. 將其命名為 vertex-ai。
  3. 將 vertex-ai 中的兩個連線分別拖曳至 agent-backend 和 data-mcp-server，即可將 vertex-ai 連線至 agent-backend 和 data-mcp-server。由於 agent-backend 和 data-mcp-server 已連結至 Vertex AI 元件，因此 aiplatform.user 角色會自動指派給這兩個服務帳戶。

6. 新增全域負載平衡器

負載平衡器會將前端公開發布到網路上。在 ADC 中，這會分成後端和前端元件。

A. 新增負載平衡器後端

  1. 依序點選「Add Component」>「Global Cloud Load Balancing (Backend)」。
  2. 將其命名為 galb-backend。
  3. 按一下「新增連線」，然後連線至 frontend。

B. 新增負載平衡器前端

  1. 依序點選「Add Component」>「Global Cloud Load Balancing (Frontend)」。
  2. 將其命名為 galb-frontend。
  3. 按一下「新增連線」，然後連線至 galb-backend。
  4. 將 galb-frontend 拖曳至 galb-backend，即可連結兩者。galb-frontendgalb-backend

應用程式範本

在目錄中分享範本

您可透過目錄在不同工作區之間共用應用程式範本，進而控管架構。目錄是範本的中央存放區，平台團隊建立並核准的範本都會儲存在這裡。在空間之間共用目錄可避免重複處理常見專案，並縮短啟動時間。

現在，請將範本新增至目錄：

  1. 按一下「目錄」分頁標籤。
  2. 按一下「新增範本」，然後選取 simple-3-tier-agentic-app 範本。
  3. 按一下「新增至目錄」。新增至目錄

範本有三種：Google 範本 (預先定義的模式)、共用範本 (在貴機構中共用)，以及範本 (工作區中的自訂藍圖)。

6. 部署應用程式

現在請扮演應用程式開發人員，使用這個範本部署 cymbal-london-concierge 應用程式。

  1. 在 ADC 控制台中，於「範本」分頁中重新開啟範本，然後按一下「設定應用程式」按鈕。設定應用程式
  2. 按一下「建立新應用程式」。
  3. 設定應用程式：
    • 應用程式名稱：cymbal-london-concierge
    • 部署專案：您的專案 ID
    • Region (區域)：us-central1
    • 輸入屬性>環境：Development
    • 輸入屬性>重要性：Low
  4. 按一下「建立應用程式」。如要部署正式版，請為「環境」選取「正式版」，並為「重要性」選取「高」。這些標記可協助 SRE 和營運團隊分類並優先處理發生的任何問題。
  5. 系統應會開啟應用程式範本的部署詳細資料頁面。由於這只是範本，我們仍需新增應用程式專屬的設定。
  6. 現在來設定前端。按一下「前端」元件。
    1. 依序點選「容器」>「編輯容器」。
    2. 我們需要將一般容器映像檔換成要用於應用程式的映像檔。
    3. 將「Container Image」(容器映像檔) 設為：us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1變更容器映像檔
    4. 將通訊埠 http1 設為 80。
    5. 設定下列環境變數：
      • API_BASE_URL：module.cloud-run-2.service_uri (請確認 cloud-run-2 是代理程式後端元件的名稱，如果不是，請將其替換為元件的實際名稱)
    6. 按一下 [儲存]。
  7. 現在來設定代理程式後端。點選「agent-backend」元件。
    1. 依序點選「容器」>「編輯容器」。
    2. 我們需要將一般容器映像檔換成要用於應用程式的映像檔。
    3. 將「Container Image」(容器映像檔) 設為：us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1
    4. 設定下列環境變數：
    5. GOOGLE_CLOUD_PROJECT：
    6. GOOGLE_CLOUD_LOCATION：us-central1
    7. DATA_BACKEND_URL：module.cloud-run-1.service_uri (請確認 cloud-run-1 是資料 mcp 伺服器元件的名稱，如果不是，請將其替換為元件的實際名稱)
    8. 將通訊埠 http1 設為 8000。
    9. 按一下 [儲存]。
  8. 讓我們設定資料 MCP 伺服器。點選「data-mcp-server」元件。
    1. 依序點選「容器」>「編輯容器」。
    2. 我們需要將一般容器映像檔換成要用於應用程式的映像檔。
    3. 將「Container Image」(容器映像檔) 設為：us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1
    4. 設定下列環境變數：
    5. GOOGLE_CLOUD_PROJECT：
    6. GOOGLE_CLOUD_LOCATION：us-central1
    7. DB_TYPE：sqlite
    8. EMBEDDING_MODEL：text-embedding-005
    9. 將通訊埠 http1 設為 8002。
    10. 按一下 [儲存]。
    在實際的生產環境中，您也會設定 CloudSQL 或 AlloyDB 等資料庫，並提供資料 mcp 伺服器的資料庫連線字串。但本實驗室會使用記憶體內資料庫。您也可以將 mcp 伺服器和資料庫設為私人，僅允許從代理程式後端或網路內存取。
  9. 按一下頁面頂端的「程式碼」按鈕，即可查看應用程式的 Terraform 程式碼。您也可以點選「取得程式碼」按鈕，下載應用程式的 Terraform 程式碼，並儲存在程式碼集應用程式範本中。
  10. 點選頁面右上角的「Deploy」按鈕，即可部署應用程式。
  11. 部署頁面會要求您為部署管道建立服務帳戶，或選擇現有帳戶。按一下「建立服務帳戶」 (系統會自動填入名稱)，然後按一下「繼續」。系統會在幾秒內建立新的服務帳戶。

建立服務帳戶

  1. 服務帳戶建立完成後，頁面會重新整理，您會看到「選取服務帳戶」旁邊顯示勾號。

已建立的服務帳戶

  1. 然後按一下頁面底部的「Deploy」。
  2. 這項作業需要幾分鐘才能完成。部署完成後，每個元件旁都會顯示綠色勾號。您也可以點選「Link to logs」(記錄檔連結) 按鈕，開啟 Cloud Build 記錄檔，查看部署狀態。按鈕可能需要幾分鐘才會顯示。
![Deployment Logs](./img/10b_logs.png)
  1. 您可以查看雲端建構記錄，瞭解部署狀態，或查看部署應用程式時可能發生的錯誤。您也可以在 Google Cloud 控制台中搜尋「Cloud Build」，然後點選「記錄」，直接前往 Cloud Build 記錄。應用程式的部署時間約為 5 到 8 分鐘。
![Cloud Build](./img/10c_cloudbuild.png)
  1. 部署完成後，「部署狀態」欄位旁會顯示綠色勾號。
![Deployment Complete](./img/11_deployed.png)

7. 驗證應用程式

讓我們測試代理是否正常運作。在部署作業詳細資料頁面的「輸出」部分，您會看到前端元件的網址。複製該網址並貼到瀏覽器中。請務必使用 http，而非 https。此外，由於前端使用 http，請接受瀏覽器中可能出現的任何警告。

與應用程式對話，要求製作倫敦旅遊行程。

前端

8. App Hub 和應用程式監控

  1. 在 ADC 控制台中，按一下頁面右上角的「在 App Hub 中查看應用程式」按鈕。

App Hub

  1. 系統會在 App Hub 中開啟該應用程式。您可以使用 App Hub 集中查看及管理所有應用程式，從以資源為主的檢視畫面轉移到以應用程式為主的檢視畫面。使用 ADC 建立應用程式時，系統會自動在 App Hub 中建立應用程式。您應該會看到組成應用程式的所有工作負載和服務。您可以將雲端資源視為單一應用程式的一部分，而非個別資源，簡化管理和控管作業。

App Hub

  1. 按一下「在可觀測性中查看」按鈕。這時應該會在 Observability 控制台中開啟應用程式。
  2. 開啟資訊主頁檢視畫面。資訊主頁會提供要求比率、錯誤率、延遲和飽和度等 4 大黃金訊號指標，讓您概略瞭解應用程式的效能和健康狀態。以應用程式為中心的監控方式，是維持可靠性的關鍵。您也可以查看應用程式的「記錄」和「追蹤」，以便找出信號之間的關聯，並找出瓶頸。在這種複雜的代理應用程式中，這點尤其重要，因為 Vertex AI 或資料 MCP 伺服器的回應速度緩慢，可能會降低使用者體驗。

資訊主頁

  1. 導覽探索：在應用程式中向智慧助理提出具體問題 (例如「倫敦有哪些必遊景點？」)。然後返回 Observability 控制台，查看「Traces」(追蹤記錄) 清單。找出與要求相應的追蹤記錄。按一下即可查看詳細的瀑布式檢視畫面。請注意，您可以看到前端、代理程式後端和 Vertex AI 呼叫所花費的時間。這有助於找出延遲的確切原因。

9. 恭喜

恭喜！您已使用 ADC 部署 3 層應用程式架構。

目前所學內容

  • 如何使用 ADC 視覺化組裝雲端架構。
  • 如何透過 UI 設定 ADC 並啟用 API。
  • 如何使用 ADC 部署應用程式。
  • 如何使用 App Hub，以應用程式為中心查看資源。
  • 如何使用可觀測性資訊主頁監控應用程式健康狀態。

參考文件