Python 執行階段

Python 執行階段是軟體堆疊，負責安裝應用程式程式碼和依附元件，然後在彈性環境中執行該應用程式。

Python 版本

Python 3.13 使用Buildpack。如需支援的 Python 版本完整清單及其對應的 Ubuntu 版本，請參閱執行階段支援時間表。

如要使用支援的 Python 版本，您必須：

• 在 app.yaml 檔案中加入 runtime_config 和 operating_system 設定，以便指定作業系統。

• 安裝 gcloud CLI 420.0.0 以上版本。您可以執行 gcloud components update 指令來更新 CLI 工具。如要查看已安裝的版本，請執行 gcloud version 指令。

• 您也可以在 app.yaml 檔案中加入 runtime_version 設定，以便指定執行階段版本。根據預設，如果未指定 runtime_version 設定，系統會使用最新的 Python 版本。

範例

• 如要在 Ubuntu 22 上指定 Python 3.13：

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

• 如要在 Ubuntu 22 上指定最新支援的 Python 版本，請按照下列步驟操作：

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

詳情請參閱 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

如果省略 runtime_config 或 python_version，Python 3.7 以下版本的預設解譯器為 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 啟動應用程式。此進入點應啟動程序，在 PORT 環境變數定義的通訊埠回應 HTTP 要求。

網頁應用程式大多使用 WSGI 伺服器，例如 Gunicorn、uWSGI 或 Waitress。

您必須先在應用程式的 requirements.txt 中將這些伺服器新增為依附元件，才能使用上述任一伺服器。如果您為 Flask 應用程式使用 gunicorn，請確認應用程式的 Python 版本與 gunicorn 相容。

在呼叫進入點之前，執行階段會確保已安裝所有依附元件。

Flask==2.0.2
gunicorn==20.1.0

以下為使用 gunicorn 的 Flask 應用程式進入點範例：

entrypoint: gunicorn -b :$PORT main:app

以下為使用 gunicorn 的 Django 應用程式進入點範例：

entrypoint: gunicorn -b :$PORT mydjangoapp:wsgi

建議使用的 WSGI 伺服器為 gunicorn，不過若您想要使用任何其他的 WSGI 伺服器也絕對不成問題。例如，以下就是一個使用 uWSGI 的 Flask 應用程式進入點：

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

如果應用程式不需要 WSGI 伺服器即可處理要求，您可以直接執行 Python 指令碼：

entrypoint: python main.py

建議的 Gunicorn 設定

上方所示的進入點基本範例皆可做為起點，並可直接用於您的網路應用程式。然而，大多數的應用程式都需要進一步設定 WSGI 伺服器。請在專案根目錄中建立 gunicorn.conf.py 檔案 (app.yaml 檔案所在位置)，並在進入點中指定該檔案，而非在進入點上指定所有設定：

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

如果想要瞭解 Gunicorn 的所有設定值，請參閱其說明文件。

工作站

Gunicorn 使用工作站來處理要求。根據預設，Gunicorn 會使用 sync 工作站。這個類別的工作站與所有網路應用程式相容，但每個工作站一次只能處理一個要求。在預設情況下，Gunicorn 只會使用當中的一個工作站來處理要求。這通常會導致執行個體使用率過低，並使高負載應用程式的延遲情況加重。

我們建議將工作站的數量設為執行個體 CPU 核心數量的 2 至 4 倍再加 1。您可以在 gunicorn.conf.py 中進行如下指定：

import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1

此外，一些 I/O 傾向的網頁應用程式也能因為使用其他的工作站類別而獲得效能提升。如果您的工作站類別需要其他的依附元件 (如 gevent 或 tornado)，您必須在應用程式的 requirements.txt 中宣告這些依附元件。

HTTPS 和轉送 Proxy

App Engine 會在負載平衡器上終止 HTTPS 連線，並將要求轉送至您的應用程式。大多數應用程式不需要知道要求是否透過 HTTPS 傳送，但如果應用程式需要這項資訊，則應將 Gunicorn 設為信任 gunicorn.conf.py 中的 App Engine Proxy：

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"