测试和部署应用

区域 ID

REGION_ID 是 Google 根据您在创建应用时选择的区域分配的缩写代码。此代码不对应于国家/地区或省，尽管某些区域 ID 可能类似于常用国家/地区代码和省代码。对于 2020 年 2 月以后创建的应用，REGION_ID.r 包含在 App Engine 网址中。对于在此日期之前创建的现有应用，网址中的区域 ID 是可选的。

详细了解区域 ID。

确定

Go Java Node.js PHP Python Ruby .NET 自定义

了解如何在本地运行您的应用，以及如何在 App Engine 上部署和测试应用。

在本地运行

如需在部署之前测试应用，请使用您常用的开发工具在本地环境中运行应用。 例如，您通常可以使用以下命令在 Flask 开发服务器上运行 Flask 应用：

python main.py

使用以下命令启动 Django 应用：

python manage.py runserver

如需模拟 App Engine 生产环境，您可以在本地运行完整的 Web 服务器网关接口 (WSGI) 服务器。使用 app.yaml 文件中指定为 entrypoint 的同一命令，例如：

gunicorn -b :$PORT main:app

部署应用

使用 gcloud app deploy 命令将应用部署到 App Engine。

Cloud Build 服务会自动将您的部署构建到容器映像中，并将该映像部署到 App Engine 柔性环境。这个容器包含您对运行时映像所做的全部本地修改。

如需以编程方式部署应用，请使用 Admin API。

准备工作

在部署应用之前，请做好以下准备：

• Google Cloud 项目的所有者必须为 App Engine 设置 Google Cloud 项目。

• 确保您的用户账号具备所需的权限。

确保成功部署

如果您启用新版健康检查，但应用未达到健康状况良好状态，则系统将回滚部署。在将第一个应用部署到柔性环境时，可能会出现延迟，原因是需要设置虚拟机 (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 项目，并将所有流量路由到新版本。新版本将成为默认版本。

注意：建议您查看 Google Cloud 控制台中的 App Engine 版本页面或在运行 gcloud app deploy 命令后运行 gcloud app versions list，以验证接收流量的版本。

您可以通过指定特定文件、指定版本或添加其他参数来更改部署命令的默认行为：

• 您可以通过分布定位并部署每个文件来部署服务的其他配置文件，例如：

  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 等标志。

部署多项服务

您可以使用相同的部署命令来部署或更新应用中包含的多项服务。

须知事项：

• 您必须先将应用的某个版本部署到 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 文件，则无法在 app.yaml 文件中指定 skip_files 字段。

如需详细了解 .gcloudignore 文件的语法，请参阅 gcloud 参考文档。

手动构建容器以进行部署

注意：Container Registry 已被弃用，并已安排关停。2024 年 1 月 8 日之前未使用 Container Registry 的组织默认在 Artifact Registry 上托管新的 gcr.io 制品库。自 2024 年 5 月 15 日起， Google Cloud 之前未使用 Container Registry 的项目将仅支持托管和管理 Artifact Registry 中 gcr.io 网域的映像。

Container Registry 计划于 2025 年 3 月 18 日关停。如需详细了解弃用情况，请参阅 Container Registry 弃用。

如需在 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. 部署新版本 同时添加 --no-promote 标志：

   gcloud app deploy --no-promote

2. 转到以下网址以访问新版本：

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

   注意：您可以在 Google Cloud 控制台中找到版本 ID，也可以在部署时使用 version 参数指定版本 ID。

   现在，您可以在 App Engine 运行时环境中测试新版本。如需对应用进行调试，您可以在 Google Cloud 控制台的日志浏览器中查看其日志。如需了解详情，请参阅写入应用日志。

   发送到 https://PROJECT_ID.REGION_ID.r.appspot.com 的请求仍将路由到先前配置为接收流量的版本。

3. 如需将流量发送到新版本，请使用 Google Cloud 控制台迁移流量：

   管理版本

   选择刚部署的版本，然后点击迁移流量。

如需使用相同的流程来测试其他服务的新版本，您可以将网址中的 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
• 您可以使用 Buildpack 支持的任何密钥。

如需将环境变量与 Buildpack 搭配使用，请在 app.yaml 文件中指定 build_env_variables 字段。

详细了解 Buildpack。

使用 Cloud Trace

Cloud Trace 对于了解请求如何在您的应用中传播非常有用。您可以检查单个请求的详细延迟时间信息，也可以查看整个应用的总体延迟时间。

您可以查看跟踪记录详情。在 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 命令时可能会失败。只有拥有 Owner 角色的账号才具备创建 App Engine 应用所需的权限。

502 Bad Gateway

如果 app.yaml 配置错误，则 Google Cloud 项目可能无法启动。检查应用日志，了解更详细的错误消息。

[13] An internal error occurred while creating a Cloud Storage bucket.

App Engine 会代表您在创建应用的同一区域中创建默认的 Cloud Storage 多区域存储桶。它需要使用此存储桶来存储应用的内容。当无法创建此存储桶时，系统会返回此错误，例如在以下情况下：

• App Engine 柔性环境服务代理在您的项目中不存在，或者它没有 App Engine flexible environment Service Agent 角色。您可以将代理的服务账号重新添加到项目中，只需向其授予正确的 IAM 权限即可。请参阅恢复已删除的服务代理。

• 默认 App Engine 服务账号在您的项目中不存在。如果 App Engine 服务账号已在删除后 30 天内移除，您可以将其恢复。

• 您的项目隶属于执行 constraints/gcp.resourceLocations 政策的组织，并且该组织不允许在创建您的 App Engine 的同一区域上创建资源。您必须替换针对您的项目强制执行的 constraints/gcp.resourceLocations 政策，并允许在创建您的 App Engine 应用的同一区域中使用多区域位置。

例如，如果您的 App Engine 应用是在 europe-west 区域中创建的，即使该区域映射到 europe-west1 位置，您也必须修改限制条件以允许 in:eu-locations（包括所有 EU 区域）中的资源。这是必要的操作，因为 App Engine 创建的存储桶是多区域资源。如果您的 App Engine 应用是在 US 区域中创建的，您必须允许 in:us-locations；如果您的应用是在 ASIA 区域中创建的，则必须允许 in:asia-locations。

[13] An internal error occurred.

如果您通过使用共享 VPC 设置的网络配置来部署服务，则可能会发生此错误。请尝试以下操作：

1. 确保您的 app.yaml 配置有效。
2. 确保您的 App Engine 柔性环境满足共享 VPC 设置的所有要求。请参阅在共享 VPC 网络中使用 App Engine 柔性环境。
3. 确保您的项目中存在已配置的服务账号。如果没有，您必须恢复账号。共享 VPC 宿主项目中的子网区域必须与创建 App Engine 环境的位置相匹配。

如果问题仍然存在，请使用 Google Cloud SDK 重新部署您的服务。确保添加 --verbosity=debug 标志。请与 Google Cloud Support 团队联系，并提供命令的输出。

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

如果部署失败并显示此错误消息，则表示为 App Engine 服务配置的网络没有剩余地址可分配给服务的新实例。如需解决此问题，请在为 App Engine 柔性环境服务配置的子网上扩展 VPC 范围。