Python 运行时

Python 运行时是负责安装应用代码和依赖项，然后在柔性环境中运行该应用的软件栈。

Python 版本

Python 3.14（预览版）使用 buildpack。如需查看受支持的 Python 版本及其对应 Ubuntu 版本的完整列表，��参阅运行时支持时间表。

如需使用支持的 Python 版本，您必须：

• 将 runtime_config 和 operating_system 设置添加到 app.yaml 文件中以指定操作系统。

• 安装 gcloud CLI 420.0.0 或更高版本。您可以通过运行 gcloud components update 命令来更新 CLI 工具。如需查看已安装的版本，请运行 gcloud version 命令。

• （可选）您可以通过在 app.yaml 文件中添加 runtime_version 设置来指定运行时版本。默认情况下，如果未指定 runtime_version 设置，则使用最新的 Python 版本。

示例

• 在 Ubuntu 24 上指定 Python 3.14（预览版）：

  runtime: python
  env: flex
  entrypoint: gunicorn -b :$PORT main:app
  
  runtime_config:
      operating_system: "ubuntu24"
      runtime_version: "3.14"
  

• 如需在 Ubuntu 24 上指定支持的最新 Python 版本，请执行以下操作：

    runtime: python
    env: flex
    entrypoint: gunicorn -b :$PORT main:app
  
    runtime_config:
        operating_system: "ubuntu24"
  

如需了解详情，请参阅 app.yaml 参考页面。

过往运行时版本

对于 Python 3.7 版及更低版本，您可以在应用的 app.yaml 文件中使用 runtime_config 和 python_version 设置来指定版本。

示例

runtime: python
env: flex
entrypoint: gunicorn -b :$PORT main:app

runtime_config:
    python_version: 3.7

对于 Python 3.7 版及更早版本，如果省略 runtime_config 或 python_version，则默认解释器为 Python 2.7.12。例如，您可以通过在 app.yaml 文件中指定 runtime: python 来使用默认运行时：

runtime: python
env: flex

如需了解详情，请参阅 app.yaml 参考页面。

为每个版本设置部署的解释器如下表所示：

对其他 Python 运行时的支持

如果您需要使用不受支持的 Python 版本，可以创建自定义运行时，并选择带有所需 Python 版本的有效基础映像。

对于 Google 提供的基础映像或 Docker Python 基础映像，请参阅构建自定义运行时。

如需进一步了解适用于 Cloud Run 的 App Engine 应用容器化，请参阅迁移指南。

依赖项

在启动应用之前，运行时会在应用的源代码目录中查找 requirements.txt 文件，并使用 pip 安装所有依赖项。如需详细了解如何声明和管理软件包，请参阅使用 Python ��。

如果您的应用需要专用依赖项，您将需要使用基于 Python 运行时的自定义运行时来安装相应的软件包。

应用启动

运行时使用 app.yaml 文件中定义的 entrypoint 来启动应用。entrypoint 应启动一个进程，以响应环境变量 PORT 所定义端口上的 HTTP 请求。

大多数 Web 应用都使用 WSGI 服务器，例如 Gunicorn、uWSGI 或 Waitress。

如需使用其中一个服务器，您必须将其作为依赖项添加到应用的 requirements.txt 文件中。 如果您将 gunicorn 用于 Flask 应用，请确保应用的 Python 版本与 gunicorn 兼容。

运行时会确保所有依赖项均在 entrypoint 调用之前安装完毕。

Flask==2.0.2
gunicorn==20.1.0

在 Flask 应用中使用 gunicorn 时对应的 entrypoint 示例：

entrypoint: gunicorn -b :$PORT main:app

在 Django 应用中使用 gunicorn 时对应的 entrypoint 示例：

entrypoint: gunicorn -b :$PORT mydjangoapp:wsgi

建议您使用 Gunicorn 作为 WSGI 服务器，但您完全可以使用任何其他 WSGI 服务器。下面提供了一个将 uWSGI 与 Flask 搭配使用的 entrypoint 示例：

entrypoint: uwsgi --http :$PORT --wsgi-file main.py --callable app

对于可以在没有 WSGI 服务器的情况下处理请求的应用，您只需执行 Python 脚本：

entrypoint: python main.py

推荐的 Gunicorn 配置

上面所示的基本 entrypoint 示例只是个学习起点，可能适用于您的 Web 应用，但是，大多数应用将需要进一步配置 WSGI 服务器。在项目的 app.yaml 文件所在的根目录中创建 gunicorn.conf.py 文件（而不是在入口点指定所有设置），并在入口点中指定它：

entrypoint: gunicorn -c gunicorn.conf.py -b :$PORT main:app

如需了解 Gunicorn 的所有配置值，您可以阅读其文档。

工作器

Gunicorn 使用工作器来处理请求。默认情况下，Gunicorn 使用同步工作器。此类工作器与所有 Web 应用都兼容，但每个工作器一次只能处理一个请求。默认情况下，gunicorn 只使用其中一个工作器。这通常会导致您的实例得不到充分利用，并且可能会增加高负载应用的延迟时间。

我们建议您将工作器数量设置为实例的 CPU 核心数的 2 至 4 倍再加一。您可以在 gunicorn.conf.py 中将此字段指定为：

import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1

另外，一些主要受 I/O 约束的 Web 应用可以通过使用不同的工作器类别来实现性能的提升。 如果您的工作器类需要其他依赖项（例如 gevent 或 tornado），则需要在应用的 requirements.txt 中声明这些依赖项。

HTTPS 和转发代理

App Engine 在负载均衡器上终止 HTTPS 连接，并将请求转发给应用。大多数应用不需要知道请求是否通过 HTTPS 发送，但需要此信息的应用应将 Gunicorn 配置为信任其 gunicorn.conf.py 中的 App Engine 代理：

forwarded_allow_ips = '*'
secure_scheme_headers = {'X-FORWARDED-PROTO': 'https'}

Gunicorn 现在将确保 wsgi.url_scheme 到 'https'（大多数网络框架将使用该标志来指示请求是安全的）。如果您的 WSGI 服务器或框架不支持此功能，只需手动检查X-Forwarded-Proto标头的值即可。

某些应用还需要确定用户的 IP 地址。该地址可在 X-Forwarded-For 标头中获取。

请注意，gunicorn.conf.py 中的 secure_scheme_headers 设置应为大写（如X-FORWARDED-PROTO），但您的代码可以读取的标头将为混合大小写（如 X-Forwarded-Proto）。

扩展运行时

柔性环境 Python 运行时可用于创建自定义运行时。如需了解详情，请参阅自定义 Python。

环境变量

以下环境变量由运行时环境设置：

您可以在 app.yaml 文件中设置其他环境变量。

元数据服务器

应用的每个实例都可以使用 Compute Engine 元数据服务器来查询实例的相关信息，包括实例的主机名、外部 IP 地址、实例 ID、自定义元数据和服务账号信息。App Engine 不支持设置每个实例的自定义元数据，但您可以设置项目级的自定义元数据，并从 App Engine 和 Compute Engine 实例中读取这些数据。

此示例函数使用元数据服务器来获取实例的外部 IP 地址：

METADATA_NETWORK_INTERFACE_URL = (
    "http://metadata/computeMetadata/v1/instance/network-interfaces/0/"
    "access-configs/0/external-ip"
)


def get_external_ip():
    """Gets the instance's external IP address from the Compute Engine metadata
    server.

    If the metadata server is unavailable, it assumes that the application is running locally.

    Returns:
        The instance's external IP address, or the string 'localhost' if the IP address
        is not available.
    """
    try:
        r = requests.get(
            METADATA_NETWORK_INTERFACE_URL,
            headers={"Metadata-Flavor": "Google"},
            timeout=2,
        )
        return r.text
    except requests.RequestException:
        logging.info("Metadata server could not be reached, assuming local.")
        return "localhost"