Python 3 執行階段環境

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

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

runtime: pythonVERSION

其中 VERSION 是 Python MAJOR 和 MINOR 版本號碼。舉例來說，如要使用最新的 Python 版本 (Python 3.15 預先發布版)，請指定 315。

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

Python 3 版本

目前支援的最新 Python 版本為 3.15 (預先發布版)。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 檔案。

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

entrypoint: gunicorn -b :$PORT main:app

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

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

• 應用程式目錄的根目錄包含 main.py 檔案，內有與 WSGI 相容的 app 物件。

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

如果您未指定 Python 3 執行階段的進入點，App Engine 會使用 gthread worker 類別 (每個 worker 有 4 個執行緒) 設定及啟動預設的 Gunicorn 網路伺服器。如果是 F1 和 B1 執行個體，gthread worker 類別會使用 4 worker；如果是 F2、B2 和更大的執行個體，則會使用 8 worker。如果指定自訂 entrypoint，但未設定 --workers (-w)，Gunicorn 預設會使用一個 sync worker。

注意：如果指定 entrypoint 欄位，default timeout of gunicorn 為 30 秒。如果 worker 閒置超過這個秒數，就會遭到終止並重新啟動。如果處理常式執行時間超過 30 秒，可能會發生 [CRITICAL] WORKER TIMEOUT 錯誤。為確保要求順利完成，您可以根據用途，在進入點欄位中使用 -- timeout flag 增加逾時時間。

Entrypoint 最佳做法

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

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

• 您可以使用進入點欄位調整應用程式效能。舉例來說，如果您使用 gunicorn 做為網路伺服器，可以在進入點欄位中使用 --workers 旗標，設定為應用程式提供服務的工作站數量。

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

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

  這項指引可做為選取 worker 數量的起點。視應用程式的效能特性而定，您可能需要使用不同數量的 worker。以下範例顯示使用兩個 gunicorn worker 提供應用程式服務的 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。