使用 App Design Center 快速部署应用

1. 简介

在此 Codelab 中，您将学习如何使用 Google Cloud App Design Center (ADC) 部署全栈应用。您将部署“The Cymbal London Concierge”应用，该应用包含 Vue 3 前端、FastAPI 后端和一个用于保存应用数据的 MCP 服务器。

借助 ADC，您可以直观地定义应用架构，并将其部署为单个单元，同时自动管理依赖项和连接。

您将执行的操作

  • 设置 App Design Center。
  • 直观地组装应用组件。
  • 部署应用架构。
  • 验证正在运行的应用。
  • 验证应用是否已注册到 App Hub。
  • 在应用监控中验证应用指标、轨迹和日志。

所需条件

  • 网络浏览器，例如 Chrome。
  • 启用了结算功能的 Google Cloud 项目。

本 Codelab 适合各种水平的开发者，包括新手。

预计时长：45 分钟预计费用：不到 2 美元

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. 输入服务名称：data-mcp-server。
  3. 在显示高级设置下，将成员设置为：allUsers。（注意：在生产环境中，您可能会限制此权限，但为了简化 Codelab，我们在此处使用了此权限。）
  4. 在显示高级设置下，设置 VPC 访问通道，将出站流量设置为：PRIVATE_RANGES_ONLY。
  5. （可选）在显示高级设置下方，取消选中启用 Prometheus Sidecar。虚拟私有云 (VPC) 访问权限
  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. 在显示高级设置下，设置 VPC 访问通道，将出站流量设置为：PRIVATE_RANGES_ONLY。
  6. （可选）在显示高级设置下，取消选中启用 Prometheus Sidecar。
  7. 将 agent-backend 连接到 data-mcp-server，方法是从 agent-backend 拖动连接到 data-mcp-server。
  8. 点击保存。

4. 添加前端

前端界面。

  1. 依次点击 Add Component > Cloud Run (Service)。
  2. 输入服务名称：frontend。
  3. 在显示高级设置下，取消选中创建服务账号
  4. 在显示高级设置下，将 Ingress 设置为：INGRESS_TRAFFIC_INTERNAL_LOADBALANCER。合规性配置：阻止对前端容器的直接公共访问，强制流量通过负载平衡器。
  5. 在显示高级设置下，将会员设置为：allUsers。前端
  6. （可选）在显示高级设置下，取消选中启用 Prometheus Sidecar。
  7. 点击保存。
  8. 将 frontend 连接到 agent-backend，方法是从 frontend 拖动连接到 agent-backend。

5. 添加 Vertex AI 组件

  1. 依次点击 Add Component > 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-frontend 拖动连接到 galb-backend。

应用模板

共享目录中的模板

借助目录，您可以在不同空间之间共享应用模板，从而实现架构治理。目录充当平台团队创建并批准共享的模板的中央代码库。在空间之间共享目录可避免为常见项目重复付出精力，并缩短启动时间。

现在，将模板添加到目录：

  1. 点击目录标签页。
  2. 点击添加模板，然后选择 simple-3-tier-agentic-app 模板。
  3. 点击添加到目录。添加到目录

您可以在三个位置找到模板：Google 模板（预定义模式）、共享模板（在组织内共享）和模板（空间中的自定义蓝图）。

6. 部署应用

现在，您需要扮演应用开发者的角色，并使用此模板部署 cymbal-london-concierge 应用。

  1. 在 ADC 控制台中，重新打开模板标签页中的模板，然后点击配置应用按钮。配置应用
  2. 点击创建新应用。
  3. 配置应用：
    • 应用名称：cymbal-london-concierge
    • 部署项目：您的项目 ID
    • 区域：us-central1
    • 输入源属性>环境：Development
    • 输入属性>严重程度：Low
  4. 点击创建应用。对于生产部署，您应为“环境”选择“生产”，为“严重程度”选择“高”。这些标记可帮助 SRE 和运营团队对发生的任何问题进行排序并确定处理优先级。
  5. 系统随即会打开包含应用模板的部署详情页面。鉴于这只是一个模板，我们还需要添加特定于我们应用的配置。
  6. 接下来，我们来配置前端。点击前端组件。
    1. 依次点击容器 > 修改容器。
    2. 我们需要将通用容器映像替换为要用于应用的容器映像。
    3. 将容器映像设置为：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. 将容器映像设置为：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. 将容器映像设置为：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. 点击页面右上角的部署按钮以部署应用。
  11. 部署页面会要求您为部署流水线创建服务账号或选择现有服务账号。点击创建服务账号（系统会自动填充名称），然后点击继续。创建新的服务账号需要几秒钟时间。

创建服务账号

  1. 服务账号创建完成后，页面会刷新，您会看到“选择服务账号”旁边显示对勾标记。

创建的服务账号

  1. 然后点击页面底部的部署。
  2. 这需要几分钟才能完成。部署完成后，您会在每个组件旁边看到一个绿色对勾标记。您还可以点击日志链接按钮（这将打开 Cloud Build 日志）来检查部署状态。该按钮可能需要几分钟时间才会显示。
![Deployment Logs](./img/10b_logs.png)
  1. 您可以查看云端 build 日志，了解部署状态或部署应用时可能发生的任何错误。您还可以在 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. 点击在可观测性中查看按钮。这应该会在可观测性控制台中打开应用。
  2. 打开信息中心视图。该信息中心提供请求速率、错误率、延迟时间和饱和度这 4 个黄金信号等指标，让您大致了解应用的性能和健康状况。这种以应用为中心的监控对于保持可靠性至关重要。您还可以查看应用的日志和轨迹，从而关联信号并找出瓶颈。在这样的复杂智能体应用中，这一点尤为重要，因为 Vertex AI 或 Data MCP 服务器的响应速度缓慢会降低用户体验。

信息中心

  1. 引导式探索：在应用中向代理提出具体问题（例如“伦敦有哪些值得一游的地方？”）。然后，返回到可观测性控制台并查看跟踪记录列表。找到与您的请求对应的轨迹。点击该图标即可查看详细的瀑布图。请注意，您可以看到在前端、代理后端和对 Vertex AI 的调用中花费的时间。这样，您就可以准确确定延迟的引入位置。

9. 恭喜

恭喜！您已使用 ADC 部署了三层应用架构。

您学到的内容

  • 如何使用 ADC 直观地组装云架构。
  • 如何通过界面设置 ADC 并启用 API。
  • 如何使用 ADC 部署应用。
  • 如何使用 App Hub 以应用为中心查看资源。
  • 如何使用可观测性信息中心监控应用运行状况。

参考文档