2026 年 9 月 15 日，所有 Cloud Composer 1 和 Cloud Composer 2 2.0.x 版環境將達到預計的生命週期終止日，屆時您將無法使用這些環境。建議您規劃遷移至 Cloud Composer 3。

本頁面由 Cloud Translation API 翻譯而成。

使用 Composer Local Development CLI 工具執行本機 Airflow 環境

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本節說明如何使用 Composer Local Development CLI 工具，建立、設定及執行本機 Airflow 環境。

關於 Composer 本機開發 CLI 工具

Composer Local Development CLI 工具可在本機執行 Airflow 環境，簡化 Cloud Composer 的 Apache Airflow DAG 開發作業。這個本機 Airflow 環境會使用特定 Cloud Composer 版本所用的 Airflow 建構映像檔。

您可以根據現有的 Cloud Composer 環境建立本機 Airflow 環境。在這種情況下，本機 Airflow 環境會從 Cloud Composer 環境取得已安裝的 PyPI 套件清單和環境變數名稱。

您可以將這個本機 Airflow 環境用於測試和開發，例如測試新的 DAG 程式碼、PyPI 套件或 Airflow 設定選項。

事前準備

Composer Local Development CLI 工具會在您執行 composer-dev create 指令的目錄中，建立本機 Airflow 環境。如要稍後存取本機 Airflow 環境，請在您最初建立本機環境的路徑中執行工具指令。本機環境的所有資料都會儲存在您建立本機環境的路徑 (./composer/<local_environment_name>) 中的子目錄。
電腦必須有足夠的磁碟空間，才能儲存 Airflow 建構映像檔。Composer 本機開發 CLI 工具會為每個 Airflow 建構作業儲存一個映像檔。舉例來說，如果您有兩個 Airflow 本機環境，且 Airflow 建構版本不同，則 Composer Local Development CLI 工具會儲存兩個 Airflow 建構映像檔。
Composer Local Development CLI 工具會使用彩色輸出內容。你可以使用 NO_COLOR=1 變數停用彩色輸出：NO_COLOR=1 composer-dev <other commands>。
如果只有一個本機環境，可以從所有 composer-dev 指令中省略本機環境名稱，但 run-airflow-cmd 除外。
安裝 Composer Local Development CLI 工具依附元件：
- 使用 pip 的 Python 版本 3.8 至 3.11
- Google Cloud CLI
安裝 Docker。本機系統必須安裝並執行 Docker。如要確認 Docker 是否正在執行，可以執行任何 Docker CLI 指令，例如 docker ps。

設定憑證

如果尚未完成，請取得新的使用者憑證，以便用於應用程式預設憑證：

gcloud auth application-default login

使用 Google 帳戶登入 gcloud CLI：

gcloud auth login

Composer Local Development CLI 工具和 DAG 執行的所有 API 呼叫，都是透過您在 gcloud CLI 中使用的帳戶執行。舉例來說，如果本機 Airflow 環境中的 DAG 會讀取 Cloud Storage 值區的內容，這個帳戶就必須具備存取該值區的權限。這與 Cloud Composer 環境不同，後者是由環境的服務帳戶發出呼叫。

安裝 Composer Local Development CLI 工具

複製 Composer Local Development CLI 存放區：

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

在複製存放區的頂層目錄中，執行下列指令：

pip install .

根據 pip 設定，工具的安裝路徑可能不在 PATH 變數中。如果發生這種情況，pip 會顯示警告訊息。您可以根據這則警告訊息中的資訊，將這個目錄新增至作業系統的 PATH 變數。

使用 Airflow 建構映像檔建立本機 Airflow 環境

如要列出可用的 Airflow 建構映像檔，請執行：

composer-dev list-available-versions --include-past-releases --limit 10

如要使用預設參數建立本機 Airflow 環境，請執行下列指令：

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

其他參數：

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

取代：

IMAGE_VERSION 改為 Airflow 建構映像檔的名稱。
將 PROJECT_ID 替換為專案 ID。
WEB_SERVER_PORT，並指定 Airflow 網路伺服器必須監聽的通訊埠。
LOCAL_DAGS_PATH，其中包含 DAG 檔案所在的本機目錄路徑。
將 LOCAL_ENVIRONMENT_NAME 替換為這個本機 Airflow 環境的名稱。

範例：

composer-dev create \
  --from-image-version composer-3-airflow-2.10.5-build.12 \
  example-local-environment

從 Cloud Composer 環境建立本機 Airflow 環境

系統只會從 Cloud Composer 環境擷取下列資訊：

環境使用的特定 Airflow 建構版本。
環境中安裝的自訂 PyPI 套件清單。
在環境中設定的環境變數名稱註解清單。

重要事項： Cloud Composer 不會複製環境變數的值。您可以手動取消設定檔中環境變數的註解，並視需要設定值。

環境中的其他資訊和設定參數 (例如 DAG 檔案、DAG 執行記錄、Airflow 變數和連線) 不會從 Cloud Composer 環境複製。

如要從現有 Cloud Composer 環境建立本機 Airflow 環境，請按照下列步驟操作：

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

取代：

LOCAL_ENVIRONMENT_NAME，並為本機 Airflow 環境命名。
ENVIRONMENT_NAME，並將其替換為 Cloud Composer 環境的名稱。
LOCATION，其中 LOCATION 是 Cloud Composer 環境所在的地區。
將 PROJECT_ID 替換為專案 ID。
WEB_SERVER_PORT，並指定本機 Airflow 網路伺服器的通訊埠。
LOCAL_DAGS_PATH，並提供 DAG 所在本機目錄的路徑。

範例：

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

啟動本機 Airflow 環境

如要啟動本機 Airflow 環境，請執行下列指令：

composer-dev start LOCAL_ENVIRONMENT_NAME

取代：

將 LOCAL_ENVIRONMENT_NAME 替換為本機 Airflow 環境的名稱。

停止或重新啟動本機 Airflow 環境

重新啟動本機 Airflow 環境時，Composer Local Development CLI 工具會重新啟動執行環境的 Docker 容器。所有 Airflow 元件都會停止並重新啟動。因此，重新啟動期間執行的所有 DAG 執行作業都會標示為失敗。

如要重新啟動或啟動已停止的本機 Airflow 環境，請執行下列指令：

composer-dev restart LOCAL_ENVIRONMENT_NAME

取代：

將 LOCAL_ENVIRONMENT_NAME 替換為本機 Airflow 環境的名稱。

如要停止本機 Airflow 環境，請執行：

composer-dev stop LOCAL_ENVIRONMENT_NAME

新增及更新 DAG

DAG 會儲存在您建立本機 Airflow 環境時，在 --dags-path 參數中指定的目錄。根據預設，這個目錄為 ./composer/<local_environment_name>/dags。您可以使用 describe 指令取得環境使用的目錄。

如要新增及更新 DAG，請變更這個目錄中的檔案。您不需要重新啟動本機 Airflow 環境。

查看本機 Airflow 環境記錄

您可以查看執行本機 Airflow 環境的 Docker 容器最近的記錄。這樣一來，您就能監控容器相關事件，並檢查 Airflow 記錄檔是否有錯誤，例如因安裝 PyPI 套件而導致的依附元件衝突。

如要查看執行本機 Airflow 環境的 Docker 容器記錄，請執行下列指令：

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

如要追蹤記錄串流，請省略 --max-lines 引數：

composer-dev logs LOCAL_ENVIRONMENT_NAME

執行 Airflow CLI 指令

您可以在本機 Airflow 環境中執行 Airflow CLI 指令。

如要執行 Airflow CLI 指令，請按照下列步驟操作：

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

範例：

composer-dev run-airflow-cmd example-local-environment dags list -o table

設定本機 Airflow 環境

Composer Local Development CLI 工具會儲存本機 Airflow 環境的設定參數，例如本機環境目錄 (./composer/<local_environment_name>) 中的環境變數和 PyPI 套件需求。

啟動本機 Airflow 環境時，系統會套用設定。舉例來說，如果您新增衝突的 PyPI 套件需求，啟動本機環境時，Composer 本機開發 CLI 工具就會回報錯誤。

Airflow 連線會儲存在本機 Airflow 環境的資料庫中。您可以執行 Airflow CLI 指令，或將連線參數儲存在環境變數中，藉此設定這些參數。如要進一步瞭解如何建立及設定連線，請參閱 Airflow 說明文件的「管理連線」。

取得本機 Airflow 環境的清單和狀態

如要列出所有可用的本機 Airflow 環境並顯示其狀態，請執行下列指令：

composer-dev list

如要說明特定環境，並取得環境的映像檔版本、DAG 路徑和網頁伺服器網址等詳細資料，請執行下列操作：

composer-dev describe LOCAL_ENVIRONMENT_NAME

取代：

將 LOCAL_ENVIRONMENT_NAME 替換為本機 Airflow 環境的名稱。

列出本機 Airflow 環境使用的映像檔

如要列出 Composer Local Development CLI 工具使用的所有映像檔，請執行：

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

安裝外掛程式及變更資料

本機 Airflow 環境的外掛程式和資料取自本機環境的目錄：./composer/<local_environment_name>/data 和 ./composer/<local_environment_name>/plugins。

如要變更 /data 和 /plugins 目錄的內容，請在這些目錄中新增或移除檔案。Docker 會自動將檔案變更傳播至本機 Airflow 環境。

Composer Local Development CLI 工具不支援為資料和外掛程式指定其他目錄。

設定環境變數

如要設定環境變數，請編輯環境目錄中的 variables.env 檔案：./composer/<local_environment_name>/variables.env。

variables.env 檔案必須包含鍵值定義，每個環境變數各佔一行。如要變更 Airflow 設定選項，請使用 AIRFLOW__SECTION__KEY 格式。如要進一步瞭解可用的環境變數，請參閱「Airflow 設定參考資料」。

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

如要套用變更，請重新啟動本機 Airflow 環境。

安裝或移除 PyPI 套件

如要安裝或移除 PyPI 套件，請修改環境目錄中的 requirements.txt 檔案：./composer/<local_environment_name>/requirements.txt。

需求必須遵循 PEP-508 中指定的格式，其中每項需求都要以小寫指定，且包含套件名稱和選用的額外項目和版本指定碼。

如要套用變更，請重新啟動本機 Airflow 環境。

切換至其他 Airflow 建構映像檔

您可以使用任何 Airflow 建構映像檔搭配 Composer Local Development CLI 工具，並在映像檔之間切換。這與升級 Cloud Composer 環境不同，因為本機 Airflow 環境的設定參數會在啟動時套用。

舉例來說，在發布新的 Airflow 建構版本後，您可以切換環境來使用該版本，並保留現有的本機 Airflow 環境設定。

如要變更本機 Airflow 環境使用的環境映像檔，請按照下列步驟操作：

編輯本機環境設定檔： ./composer/<local_environment_name>/config.json。
變更 composer_image_version 參數的值。如要查看可用值，可以列出可用映像檔。
如要套用變更，請重新啟動本機 Airflow 環境。

刪除本機 Airflow 環境

注意：請務必儲存環境中的所有必要資料，例如記錄和設定。

如要刪除本機 Airflow 環境，請執行下列指令：

composer-dev remove LOCAL_ENVIRONMENT_NAME

如果環境正在執行，請加上 --force 旗標強制移除。

刪除 Docker 映像檔

如要刪除 Composer Local Development CLI 工具下載的所有映像檔，請執行下列指令：

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

疑難排解

本節提供常見問題的解決方案。

無法在 macOS 上啟動本機環境

如果您將 composer-dev 套件安裝到 Docker 無法存取的目錄，本機環境可能無法啟動。

舉例來說，如果 Python 安裝在 /opt 目錄中 (例如在 MacOS 上使用預設的 Homebrew 設定安裝 Python 時)，composer-dev 套件也會安裝在 /opt 目錄中。由於 Docker 遵守 Apple 的沙箱規則，因此預設無法使用 /opt 目錄。此外，您無法透過使用者介面新增 (依序前往「設定」>「資源」>「檔案共用」)。

在這個情況下，Composer Local Development CLI 工具會產生類似下列範例的錯誤訊息：

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

您可以採用下列其中一種解決方案：

將 Python 或 composer-dev 套件安裝到其他目錄，讓 Docker 可以存取該套件。
手動編輯 ~/Library/Group\ Containers/group.com.docker/settings.json 檔案，並將 /opt 新增至 filesharingDirectories。