App Engine app.yaml 参考文档

区域 ID

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

详细了解区域 ID。

您可以在 app.yaml 配置文件中配置 App Engine 应用的设置。您的配置文件必须至少指定一个 runtime 条目。

应用中的每项服务都有其专属的 app.yaml 文件，该文件充当其部署的描述符。您必须先为 default 服务创建 app.yaml 文件，然后才能为应用中的其他服务创建和部署 app.yaml 文件。如需详细了解如何在应用中设计多项服务的结构，请参阅在 App Engine 中设计 Web 服务的结构。

语法

app.yaml 的语法采用 YAML 格式。

YAML 格式支持注释。系统会忽略以井号 (#) 字符开头的行：

# This is a comment.

网址和文件路径格式使用 POSIX 扩展正则表达式语法，但排序元素和排序类除外。支持对分组匹配项的反向引用（例如 \1），另外还支持以下 Perl 扩展：\w \W \s \S \d \D。

示例

下面是一个 app.yaml 文件示例：

runtime: python312

instance_class: F2

env_variables:
  BUCKET_NAME: "example-gcs-bucket"

handlers:
# Matches requests to /images/... to files in static/images/...
- url: /images
  static_dir: static/images

- url: /.*
  secure: always
  redirect_http_response_code: 301
  script: auto

运行时和应用元素

元素 说明
app_engine_apis

可选。如果要使用适用于第二代运行时的 App Engine 旧版捆绑服务，请将此字段设置为 true。
build_env_variables

可选。如果您使用的是支持 buildpack 的运行时，则可以在 app.yaml 文件中定义构建环境变量。

如需了解详情，请参阅使用构建环境变量。
default_expiration

可选。为应用的所有静态文件处理程序设置全局默认缓存期限。您还可以配置特定静态文件处理程序的缓存时长。该值是一个由数字和单位组成并以空格分隔的字符串，其中，单位可以是 d（表示天）、h（表示小时）、m（表示分钟）和 s（表示秒）。例如，"4d 5h" 表示将缓存到期时间设置为首次请求文件后的 4 天 5 小时。如未设置，生产服务器会将到期时间设置为 10 分钟。

Python 示例： 
runtime: python312

default_expiration: "4d 5h"

handlers:
# ...

如需了解详情，请参阅缓存到期时间。

entrypoint

可选。通过在应用启动时执行 entrypoint 命令来替换默认启动行为。为了让您的应用接收 HTTP 请求，entrypoint 元素应包含一个命令，用于启动监听端口 8080 的 Web 服务器。

如果您没有为 Python 运行时指定 entrypoint，则 App Engine 会配置并启动 Gunicorn 网络服务器。

如需了解详情，请参阅应用启动。
env_variables

可选。您可以在 app.yaml 文件中定义环境变量供您的应用使用。请确保环境变量中的键与表达式“[a-zA-Z_][a-zA-Z0-9_]*”（以字母或“_”开头，后跟任何字母数字或“_”）匹配。

以 GAE 作为前缀的环境变量会保留给系统使用，因此不允许在 app.yaml 文件中出现。

对于 Python，os.environ 字典中提供了这些变量：

env_variables:
          DJANGO_SETTINGS_MODULE: "myapp.settings"

另请参阅不能覆盖的运行时环境变量列表。
error_handlers

可选。用于配置针对不同错误类型返回的自定义错误页面。

此元素可以包含以下元素：

error_code
可选。error_code 可以是下列选项之一：
over_quota
表示应用已超出资源配额
timeout
如果截止时间已到而应用未响应，则提供此错误代码。

error_code 是可选的；如果省略，则指定文件便会成为应用的默认错误响应。

file
每个 file 条目都表示一个用于代替一般错误响应而传送的静态文件。如果指定不带相应 error_code 元素的 file 元素，则静态文件将作为应用的默认错误页面。自定义错误数据不得超过 10 千字节。
示例
error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

可选。一组网址格式及其处理方式说明。App Engine 可以通过执行应用代码，或通过传送与代码一起上传的静态文件（例如图片、CSS 或 JavaScript）来处理网址。

请参阅处理程序和子元素语法。

inbound_services

可选。应用必须先启用这些服务，然后才能接收入站请求。如需为应用启用该服务，您可以在 app.yaml 文件中包含 inbound_services 部分。

warmup
启用预热请求。请参阅配置预热请求。
示例： 
inbound_services:
- warmup
instance_class

可选。此服务的实例类。

根据服务的扩缩设置，可用的值如下：

自动扩缩
F1、F2、F4、F4_1G
默认值：F1

（可选）使用 automatic_scaling 元素更改自动扩缩的默认设置，例如最小和最大实例数、延迟时间和并发连接数。

注意：如果 instance_class 设置为 F2 或更高级别，您可以将 max_concurrent_requests 设置为大于 10（默认值）的值来优化实例。要确定最佳值，请逐渐增加值，同时监控应用的性能。

基本扩缩和手动扩缩
B1、B2、B4、B4_1G、B8
默认值：B2

基本实例类和手动实例类要求您指定 basic_scaling 元素或 manual_scaling 元素。
runtime

必需。应用使用的运行时环境的名称。例如，如需指定运行时环境，请使用：

runtime: python312
service

如果创建服务，此元素是必需的。 对于 default 服务，此元素为可选元素。每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。在柔性环境中，VERSION-dot-SERVICE-dot-PROJECT_ID 的组合长度（其中 VERSION 是版本名称，SERVICE 是服务名称） PROJECT_ID 是项目 ID）不得超过 63 个字符，且首尾不能使用连字符。请为每项服务和每个版本选择唯一的名称。服务名称和版本名称不得重复。

例如： 
service: service-name
service_account

可选。借助 service_account 元素，您可以将特定于版本的服务账号指定为版本的身份。访问其他 Google Cloud 服务和执行任务时会使用指定的服务账号。

示例： 
service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
vpc_access_connector

可选。 将应用配置为使用 Serverless VPC Access 连接器，使应用能够将请求发送到 VPC 网络中的内部资源。如需了解详情，请参阅连接到 VPC 网络。

name
字符串字面量。在引号内指定无服务器 VPC 访问通道连接器的完全限定名称：
"projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
egress_setting
可选。默认值为 private-ranges-only。egress_setting 可以是下列选项之一：
private-ranges-only
默认值。对内部 IP 地址的请求会通过无服务器 VPC 访问通道连接器发送到连接的 VPC 网络。对外部 IP 地址的请求会发送到公共互联网。
all-traffic
所有请求都通过无服务器 VPC 访问通道连接器发送到连接的 VPC 网络。
示例 
vpc_access_connector:
  name: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
  egress_setting: all-traffic

处理程序元素

handlers 元素提供了一组网址格式及其处理方式的说明。App Engine 可以通过执行应用代码，或通过提供与代码一起上传的静态文件（例如图片、CSS 或 JavaScript）来处理网址。

格式评估按照格式在 app.yaml 文件中出现的顺序（即从上到下）依次进行。格式与网址匹配的第一个映射将用于处理请求。

下表列出了 handlers 元素的子元素，这些可以控制静态文件、静态目录、除 Node.js 以外的运行时中的脚本和其他设置的行为。

元素 说明
auth_fail_action

如需使用此元素，必须将 app_engine_apis 设置为 true。

可选。说明为处理程序指定 login 元素且用户未登录时所执行的操作。有两个可能的值：

redirect
默认值。用户会被重定向到 Google 登录页面，或者如果使用 OpenID 身份验证，则被重定向至 /_ah/login_required。用户在登录或创建账号后，会被重定向回应用的网址。
unauthorized
如果请求被拒绝，服务器将返回一个 HTTP 401 状态代码以及一条错误消息。

如果应用需要其他行为，则该应用自身可以实现对用户登录的处理方法。例如，需要登录 /profile/ 目录或以管理员身份登录 /admin/ 目录。如需了解详情，请参阅 Users API。

通过将 auth_fail_action: unauthorized 添加到处理程序的配置中，您可以配置处理程序，以便在用户未登录时拒绝访问受保护的网址，而不是将用户重定向到登录页面。

expiration 可选。Web 代理和浏览器应缓存由此处理程序传送的静态文件的时长。该值是一个用空格分隔的数字和单位字符串，其中，单位可以是 d（表示天）、h（表示小时）、m（表示分钟）和 s（表示秒）。例如，"4d 5h" 表示将缓存到期时间设置为首次请求文件后的 4 天 5 小时。如果省略此元素，则系统会使用应用的 default_expiration。如需了解详情，请参阅缓存到期时间。
http_headers

可选。您可以设置静态文件或目录处理程序响应的 HTTP 标头。

如果您需要在 script 处理程序中设置 HTTP 标头，您应该在应用的代码中执行此操作。如需了解哪些响应标头会影响缓存，请参阅缓存静态内容。

如需详细了解 App Engine 特定标头，请参阅请求标头和响应。

示例 
handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value
    vary: Accept-Encoding
  # ...

CORS 支持

此功能的一个重要用途是支持跨域资源共享 (CORS)，例如，访问由其他 App Engine 应用托管的文件。

例如，假设您有一个游戏应用 mygame.uc.r.appspot.com 需访问由 myassets.uc.r.appspot.com 托管的资源。但是，如果 mygame 尝试向 myassets 发出 JavaScript XMLHttpRequest 请求，则除非 myassets 的处理程序返回一个包含 http://mygame.uc.r.appspot.com 值的 Access-Control-Allow-Origin: 响应标头，否则尝试将失败。

下面演示了如何让静态文件处理程序返回这个必需的响应标头值： 

handlers:
- url: /images
  static_dir: static/images
  http_headers:
    Access-Control-Allow-Origin: https://mygame.uc.r.appspot.com
  # ...

提示：如需允许任何人访问您的资源，您可以使用通配符 '*'（而非 https://mygame.uc.r.appspot.com）。
login

如需使用此元素，必须将 app_engine_apis 设置为 true。

可选。确定网址处理程序是否要求用户登录。

该元素可用的值有以下三个：

optional
默认值。不要求用户已登录。
required
如果用户已登录，则处理程序正常运行。否则，将执行 auth_fail_action 中指定的操作。
admin
与 required 一样，如果用户未登录，则执行auth_fail_action。此外，如果用户不是应用的管理员，则无论 auth_fail_action 设置为何值，用户都会收到错误消息。如果用户是管理员，处理程序将继续运行。

如果 login 设置设为非 optional 值的网址处理程序与某个网址匹配，则处理程序首先会使用其身份验证选项检查用户是否已登录应用。如果用户未登录，则默认将其重定向到登录页面。您还可以使用 auth_fail_action 将应用配置为仅拒绝未正确进行身份验证的用户对处理程序的请求，而不是将用户重定向到登录页面。

注意：如果 App Engine 为内部请求设置了合适的 X-Appengine 特殊标头，该内部请求也满足 admin 登录限制。例如，cron 计划任务满足 admin 限制，因为 App Engine 为相应请求设置了 HTTP 标头 X-Appengine-Cron: true。但是，这些请求并不满足 required 登录限制，因为并非任何用户都可以运行 Cron 计划任务。
mime_type

可选。如果指定此元素，则由此处理程序传送的所有文件均将使用指定的 MIME 类型进行传送。如果未指定，将根据文件的文件扩展名确定文件的 MIME 类型。如果上传多个扩展名不同的同一文件，则生成的扩展名可能由上传的顺序决定。

如需详细了解可能的 MIME 媒体类型，请参阅 IANA MIME 媒体类型网站。
redirect_http_response_code

可选。redirect_http_response_code 与 secure 设置搭配使用，用于设置按照 secure 设置的配置执行重定向时返回的 HTTP 响应代码。redirect_http_response_code 元素可用的值如下：

301
Moved Permanently 响应代码。
302
Found 响应代码。
303
See Other 响应代码。
307
Temporary Redirect 响应代码。

重定向用户请求时，HTTP 状态代码将设置为 redirect_http_response_code 参数的值。如果该参数不存在，系统将返回 302。

script

可选。指定发送到特定处理程序的请求应以您的应用为目标。script 元素唯一接受的值是 auto，因为所有流量都使用 entrypoint 命令进行传送。如需使用静态处理程序，至少一个处理程序必须包含 script: auto 行或定义 entrypoint 元素才能成功部署。
secure 可选。任何网址处理程序都可使用 secure 设置，包括静态文件处理程序。secure 元素可用的值如下：
optional
与处理程序相匹配的 HTTP 和 HTTPS 网址请求都会成功执行，而不会发生重定向。应用可以检查请求以确定请求使用了哪个协议，并相应地做出响应。如果没有为处理程序提供 secure，默认将使用此值。
never
与处理程序匹配且使用 HTTPS 的网址请求会被自动重定向到等效的 HTTP 网址。如果用户的 HTTPS 请求被重定向为 HTTP 请求，查询参数将会从该请求中移除。这可以防止用户意外地通过非安全连接提交本应通过安全连接传输的查询数据。
always
与此处理程序匹配的非 HTTPS 网址请求会自动重定向到路径相同的 HTTPS 网址。重定向时会保留查询参数。
Python 示例 
handlers:
- url: /youraccount/.*
  secure: always
  script: auto

如需使用 REGION_ID.r.appspot.com 网域来定位应用的特定版本，请将英文句点（通常用来分隔网址的子网域组成部分）替换为字符串“-dot-”，例如：
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

如需将自定义网域与 HTTPS 搭配使用，您必须先为该网域激活并配置 SSL 证书。

Google 账号的登录和退出始终是通过安全连接执行的，与应用网址配置为何种格式无关。
static_dir

可选。应用根目录中包含静态文件的目录的路径。所匹配的 url 格式结尾字符后面的所有内容都会附加到 static_dir 中，以构成所请求文件的完整路径。

静态目录中的每个文件都使用与其文件扩展名对应的 MIME 类型提供，除非被目录的 mime_type 设置替换。指定目录中的所有文件都会作为静态文件上传，并且它们都不能作为脚本运行。

示例： 
handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
  static_dir: stylesheets
  # ...
static_files

可选。静态文件格式处理程序会将网址格式与随应用一并上传的静态文件的路径相关联。网址格式正则表达式可以定义用来构建文件路径的正则表达式分组。您可以使用它而非 static_dir 来映射到目录结构中的特定文件，而不是映射整个目录。

示例：
handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$
  # ...

静态文件不能与应用代码文件相同。

upload

可选。一个正则表达式，它会与将由此处理程序引用的所有文件的文件路径进行匹配。系统必须执行此操作，否则处理程序将无法确定应用目录中的哪些文件与指定的 url 和 static_files 格式相对应。静态文件与应用文件的上传和处理是分开进行的。上面的示例可能使用以下 upload 格式：archives/(.*)/items/(.*)
url

handlers 下的必需元素。网址格式正则表达式，可以包含分组方式。 例如，/profile/(.*)/(.*) 可能与网址 /profile/edit/manager 匹配，并使用 edit 和 manager 作为第一个和第二个分组。

与以下元素一起使用时，网址格式在行为上有一些差异：

static_dir
使用网址前缀。与 static_dir 元素搭配使用时，此正则表达式格式不应包含分组方式。以该前缀开头的所有网址都由此处理程序处理，且前缀后面的网址部分用作文件路径的一部分。
static_files
静态文件格式处理程序会将网址格式与随应用一并上传的静态文件的路径相关联。网址格式正则表达式可以定义用来构建文件路径的正则表达式分组。您可以使用它而非 static_dir 来映射到目录结构中的特定文件，而不是映射整个目录。

扩缩元素

下表中的元素用于配置应用的扩缩方式。如果未指定扩缩类型，则默认设置自动扩缩。

如需详细了解 App Engine 应用的扩缩方式，请参阅扩缩类型。

元素 说明
automatic_scaling

可选。仅适用于使用 F1 或更高级别的实例类的应用。

指定此元素可以更改自动扩缩的默认设置，例如设置最小和最大实例数、延迟时间和服务的并发连接数。

此元素可以包含以下元素：

max_instances
可选。指定 0 至 2147483647 之间的值，其中 0 表示停用该设置。

此参数用来指定 App Engine 可为此模块版本创建的最大实例数。这对限制模块费用非常有用。

min_instances
可选。App Engine 可为此模块版本创建的最小实例数。这些实例在请求到达时处理流量，即便在必要时启动了其他实例来处理流量，这些实例也会继续处理流量。

指定 0 至 1000 之间的值。您可以将此参数的值设置为 0，以允许扩缩到 0 个实例，这样可以在未处理任何请求时降低费用。请注意，您需要为指定的实例数支付费用，无论这些实例是否接收流量。

max_idle_instances

可选。App Engine 应为此版本保留的最大空闲实例数。指定一个介于 1 到 1000 之间的值。如果未指定，则默认值为 automatic，这意味着 App Engine 将管理空闲实例数。

请注意以下几点：

  • 如果设置的最大值较高，那么当负载水平在峰值后恢复正常时，空闲实例数会较为平缓地逐渐减少。这有助于您的应用在请求负载发生波动期间保持稳定的性能，但也会增加负载繁重时段的空闲实例数（从而增加运行费用）。
  • 设置较低的最大值有助于保持较低的运行费用，但在负载水平波动期间可能会降低性能。

注意：当负载水平在峰值过后恢复到正常水平时，空闲实例数可能会暂时超出您指定的最大值。不过，对于这些多出的实例，您不需要支付费用。

min_idle_instances

可选：需要保持运行并准备好为此版本处理流量的其他实例数。

App Engine 根据 target_cpu_utilization 和 target_throughput_utilization 等扩缩设置计算处理当前应用流量所需的实例数。设置 min_idle_instances 指定除此计算数量之外要运行的实例数。例如，如果 App Engine 计算出将 5 个实例用于处理流量，并且 min_idle_instances 设置为 2，则 App Engine 将运行 7 个实例（根据流量计算得出 5 个实例，以及每 min_idle_instances 额外 2 个实例）。

请注意，您需要为指定数量的实例支付费用，无论这些实例是否正在接收流量。请谨记以下内容：

  • 较低的最小值有助于在空闲期间降低您的运行费用，但也意味着突然发生负载峰值时可立即使用的实例会更少。

  • 设置较高的最小值有助于应用自如应对突然出现的请求负载峰值。App Engine 会保持运行该最小数量的实例来处理传入请求。您需要为指定数量的实例支付费用，无论这些实例是否正在处理请求。

    如果您设置了最小空闲实例数，则等待延迟时间对应用性能的影响会更小。

target_cpu_utilization
可选。指定 0.5 至 0.95 之间的值。默认值为 0.6。

此参数指定需要启动新实例来处理流量时的 CPU 使用率阈值，使您能够在性能和费用之间取得平衡，较低的值表示性能提升和费用增加，而较高的值表示性能和费用下降。例如，0.7 表示 CPU 使用率达到 70% 后会启动新实例。

target_throughput_utilization
可选。指定 0.5 至 0.95 之间的值。默认值为 0.6。

与 max_concurrent_requests 搭配使用，用于指定何时因并发请求而启动新实例。当并发请求数达到 max_concurrent_requests 乘以 target_throughput_utilization 的值时，调度器会尝试启动一个新实例。

max_concurrent_requests

可选。在调度程序生成新实例之前，自动扩缩实例可以接受的并发请求数（默认值：10，最大值：1000）。

与 target_throughput_utilization 搭配使用，用于指定何时因并发请求而启动新实例。当并发请求数达到 max_concurrent_requests 乘以 target_throughput_utilization 的值时，调度器会尝试启动一个新实例。

除非您需要单线程，否则我们建议您不要将 max_concurrent_requests 设置为小于 10 的值。小于 10 的值可能会导致创建的实例数多于线程安全应用所需的数量，从而产生不必要的费用。

如果此设置过高，则 API 延迟时间可能会增加。请注意，调度程序可能会在达到实际最大请求数之前生成新实例。

max_pending_latency

在启动额外的实例处理请求以缩短等待延迟时间之前，App Engine 允许请求在待处理队列中等待的最长时间。当达到此阈值时，即表示需要纵向扩容，这会导致实例数增加。

如果未指定，则默认值为 automatic。这意味着请求可在待处理队列中最长保留 10 秒（即待处理请求时间上限），超过此时间才会触发新实例启动。

设置较低的最大值意味着，App Engine 将更早地为待处理请求启动新实例，这有助于提高性能，但会增加运行费用。

设置较高的最大值意味着，用户可能需要花费更长时间来等待其请求得到处理（如果有待处理请求且没有空闲实例来处理这些请求），不过，这有助于降低应用的运行费用。

min_pending_latency

您可以设置一个可选元素，以指定在启动新实例来处理请求之前，App Engine 应允许请求在待处理队列中等待的最短时间。指定值可降低运行费用，但会增加用户必须等待处理请求的时间。

对于免费应用，默认值为 500ms。对于付费应用，默认值为 0。

此元素可以与 max_pending_latency 元素搭配使用，以确定 App Engine 何时创建新实例。如果待处理请求在队列中的时间：

  • 短于您指定的 min_pending_latency，App Engine 将不会创建新实例。
  • 长于 max_pending_latency，App Engine 将会尝试创建新实例。
  • 介于 min_pending_latency 和 max_pending_latency 指定的时间之间，则 App Engine 将尝试重复使用现有的实例。如果没有实例能够在 max_pending_latency 之前处理请求，则 App Engine 将创建新实例。
示例 
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

使用 B1 或更高级别的实例类的应用必须指定此元素或 manual_scaling。

此元素用于启用实例类 B1 及更高级别的基本扩缩，并且可以包含以下元素：

max_instances
必需。App Engine 可为此服务版本创建的最大实例数。这对限制服务费用非常有用。
idle_timeout
可选。实例在收到最后一个请求后，再经过该值指定的时间即会关停。默认值为 5 分钟 (5m)。
示例 
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

使用 B1 或更高级别的实例类的应用必须指定此元素或 basic_scaling。

此元素用于启用实例类 B1 及更高级别的手动扩缩，并且可以包含以下元素：

instances
在开始时分配给服务的实例数。
示例 
manual_scaling:
  instances: 5