Python 3 執行階段環境

Python 執行階段是軟體堆疊，負責安裝網路服務的程式碼和其依附元件，並執行 App Engine 服務。

適用於 App Engine 標準環境的 Python 執行階段會在 app.yaml 檔案中宣告：

runtime: pythonVERSION

其中 VERSION 是 Python MAJOR 和 MINOR 版本號碼。舉例來說，如要使用最新 Python 版本 (Python 3.14)，請指定 314。

如要瞭解其他支援的 Python 版本，以及 Python 版本對應的 Ubuntu 版本，請參閱「執行階段支援時間表」。

Python 3 版本

最新支援的 Python 版本為 3.14。Python 執行階段會使用 app.yaml 檔案中指定版本的最新穩定版。App Engine 會自動更新至新的修補程式版本，但不會自動更新子版本。

舉例來說，您的應用程式可能先採用 Python 3.7.0 版進行部署，並在之後自動更新成 Python 3.7.1，但是並不會自動更新至下一個子版本 Python 3.8.0。

App Engine 會在最新版 Ubuntu Linux 發行版本上，透過 gVisor 保護的容器執行 Python 應用程式。

依附元件

部署期間，App Engine 會使用 Python 套件管理工具 pip，安裝專案根目錄中 requirements.txt 中繼資料檔案定義的依附元件。您不需要上傳依附元件，因為 App Engine 會執行全新安裝。

目前，系統並不支援使用 Pipfile/Pipfile.lock 標準指定依附元件，且您的專案不允許存在這些檔案。

啟動應用程式

執行階段會執行 app.yaml 檔案中 entrypoint 欄位指定的指令，啟動應用程式。如果您已在 app.yaml 檔案中設定 Gunicorn 網路伺服器進入點，則也必須將 gunicorn 新增至 requirements.txt 檔案。

entrypoint 應啟動網路伺服器，監聽 PORT 環境變數指定的通訊埠。例如：

entrypoint: gunicorn -b :$PORT main:app

應用程式使用的網路架構負責將要求轉送至應用程式中的適當處理常式。

如果應用程式符合下列規定，且您未指定 entrypoint 欄位，App Engine 就會使用 gunicorn 網路伺服器啟動應用程式：

  • 應用程式的根目錄中包含 main.py 檔案，該檔案擁有與 WSGI 相容且名為 app 的物件。

  • 您的應用程式不包含 Pipfile 或 Pipfile.lock 檔案。

如果沒有為 Python 3 執行階段指定進入點，App Engine 會設定並啟動預設的 Gunicorn 網路伺服器。

Entrypoint 最佳做法

  • 請確認 requirements.txt 檔案中含有在 app.yaml 中執行指定進入點所需的 Python 模組。只有在 app.yaml 檔案中明確指定 gunicorn 端點時，才將 gunicorn 新增至 requirements.txt 檔案。

  • 如要獲得最佳效能，應使用輕量的 entrypoint，因為當您為應用程式建立新的執行個體時，每一次都會執行該項目。

  • 您可以利用 entrypoint 欄位調整應用程式的效能。舉例來說，假設您使用 gunicorn 做為網路伺服器，則可在 entrypoint 欄位中使用 --workers 標記設定提供應用程式的工作站數量。

    您指定的工作站數量應與 App Engine 應用程式的執行個體類別相符：

    執行個體類別 工作站
    F1 2
    F2 4
    F4 8
    F4_1G 8
    B1 2
    B2 4
    B4 8
    B4_1G 8
    B8 8

    這項指引可當成選取工作站數量的起點。根據應用程式的效能特性，您可能需要使用不同數量的工作站。以下範例顯示使用兩個 gunicorn 工作站提供應用程式的 App Engine 部署作業：

    entrypoint: gunicorn -b :$PORT -w 2 main:app

  • 建議您將網路伺服器設為監聽並回應 $PORT 環境變數指定的通訊埠上的 HTTP 要求。使用預設連接埠 8080 可防止 App Engine 使用 NGINX 層壓縮 HTTP 回應。請注意，如果您使用連接埠 8080，應用程式的記錄檔會顯示連接埠 8080 和 NGINX 的相關警告。

其他網頁架構

除了 Django 和 Flask 之外，您也可以搭配 App Engine 使用其他網站架構，例如 uwsgi 和 Tornado。下列範例顯示如何將 uwsgi 與 App Engine 搭配使用：

runtime: python313
entrypoint: uwsgi --http-socket :$PORT --wsgi-file main.py --callable app --master --processes 1 --threads 2
 
uwsgi==2.0.22
Flask==3.1.3; python_version >= '3.9'

環境變數

下列為執行階段設定的環境變數：

環境變數 說明
GAE_APPLICATION App Engine 應用程式的 ID。 這個 ID 的前置字元為「region code~」，例如在歐洲部署的應用程式為「e~」。
GAE_DEPLOYMENT_ID 目前部署的 ID。
GAE_ENV App Engine 環境。設為 standard。
GAE_INSTANCE 服務目前正在執行的執行個體 ID。
GAE_MEMORY_MB 應用程式程序可用的記憶體量，以 MB 為單位。
GAE_RUNTIME 在 app.yaml 檔案中指定的執行階段。
GAE_SERVICE 在 app.yaml 檔案中指定的服務名稱。如果未指定服務名稱，則會設為 default。
GAE_VERSION 服務目前的版本標籤。
GOOGLE_CLOUD_PROJECT 與應用程式相關聯的 Google Cloud 專案 ID。
PORT 接受 HTTP 要求的通訊埠。
NODE_ENV (僅適用於 Node.js 執行階段) 在部署服務時設定為 production。

您可以在 app.yaml 檔案中定義其他環境變數，但無法覆寫上述值 (NODE_ENV 除外)。

HTTPS 和轉送 Proxy

App Engine 會在負載平衡器上終止 HTTPS 連線，並將要求轉送至您的應用程式。部分應用程式需要判斷原始要求 IP 和通訊協定。使用者的 IP 位址會顯示在標準 X-Forwarded-For 標頭中。需要這項資訊的應用程式應設定網路架構，以信任 Proxy。

檔案系統

執行階段包含完整的檔案系統。檔案系統為唯讀狀態，但位置 /tmp 除外。這個位置是在 App Engine 執行個體的 RAM 中儲存資料的虛擬磁碟。

中繼資料伺服器

應用程式的每個執行個體都可以使用 App Engine 中繼資料伺服器來查詢與執行個體和專案相關的資訊。

您可以透過以下端點存取中繼資料伺服器：

  • http://metadata
  • http://metadata.google.internal

傳送至中繼資料伺服器的要求必須包含要求標頭 Metadata-Flavor: Google。此標頭表示要求是為了擷取中繼資料值而傳送。

下表列出可讓您針對特定中繼資料發出 HTTP 要求的端點：

中繼資料端點 說明
/computeMetadata/v1/project/numeric-project-id 指派給專案的專案編號。
/computeMetadata/v1/project/project-id 指派給專案的專案 ID。
/computeMetadata/v1/instance/region 執行個體執行的區域。
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email 指派給專案的預設服務帳戶電子郵件。
/computeMetadata/v1/instance/service-accounts/default/ 列出專案的所有預設服務帳戶。
/computeMetadata/v1/instance/service-accounts/default/scopes 列出預設服務帳戶的所有支援範圍。
/computeMetadata/v1/instance/service-accounts/default/token 傳回可用於向其他 Google Cloud API 驗證應用程式的驗證權杖。

舉例來說，如要擷取專案 ID，請將要求傳送至 http://metadata.google.internal/computeMetadata/v1/project/project-id。