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

Managed Airflow (第 3 代) | Managed Airflow (第 2 代) | Managed Airflow (舊版第 1 代)

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

如果您想執行 Managed Airflow 環境來開發，建議建立開發模式環境，在不使用時休眠。

關於 Composer 本機開發 CLI 工具

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

您可以根據現有的 Managed Airflow 環境建立本機 Airflow 環境。在本例中，本機 Airflow 環境會從 Managed Airflow 環境，取得已安裝的 PyPI 套件清單和環境變數名稱。

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

警告： 請僅將本機 Airflow 環境用於測試和開發。Managed Airflow 不支援使用本機部署的 Airflow 建構映像檔進行生產。

事前準備

• Composer 本機開發 CLI 工具支援 Airflow 3 建構作業，如下所示：

  • 自 composer-3-airflow-3.3.1-build.0 起，支援 Airflow 3.3.1 以上版本。
  • composer-3-airflow-3.2.2-build.3 以上版本支援 Airflow 3.2.2。
  • 不支援 Airflow 3.1.8。
  • 從 composer-3-airflow-3.1.0-build.8 開始，系統支援較舊的 Airflow 3 版本。

• Composer Local Development CLI 工具會在您執行 composer-dev create 指令的目錄中，建立本機 Airflow 環境。如要稍後存取本機 Airflow 環境，請在您最初建立本機環境的路徑中執行工具指令。本機環境的所有資料都會儲存在您建立本機環境的路徑子目錄中：./composer/<local_environment_name>。

• 電腦必須有足夠的磁碟空間，才能儲存 Airflow 建構映像檔。Composer Local Development CLI 工具會為每個 Airflow 建構作業儲存一個映像檔。舉例來說，如果您有兩個本機 Airflow 環境，且 Airflow 建構版本不同，則 Composer Local Development CLI 工具會儲存兩個 Airflow 建構映像檔。

• Composer Local Development CLI 工具會使用彩色輸出內容。你可以使用 NO_COLOR=1 變數停用彩色輸出：NO_COLOR=1 composer-dev <other commands>。

• 如果只有一個本機環境，除了 run-airflow-cmd 之外，您可以從所有 composer-dev 指令中省略本機環境的名稱。

• 安裝 Composer 本機開發 CLI 工具依附元件：

  • Python 3.8 至 3.11 版，搭配 pip
  • Google Cloud CLI

• 電腦上必須安裝並執行 Docker (Linux/macOS/Windows) 或 Podman (Linux 或 Windows)。

  如要確認 Docker 或 Podman 是否正在運作，請執行任何 Docker CLI 或 Podman CLI 指令，例如 docker ps 或 podman ps。除非另有說明，否則所有指令都適用於 Docker 和 Podman，且任何 Docker 指令都可以替換為對應的 Podman 指令。

設定憑證

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

gcloud auth application-default login

使用 Google 帳戶登入 gcloud CLI：

gcloud auth login

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

安裝 Composer Local Development CLI 工具

複製 Composer Local Development CLI 存放區：

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

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

pip install .

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

(Podman) 設定 Podman

如果您使用的是 Podman，請按照下列步驟設定：

Linux

1. 啟用 Podman 使用者服務通訊端。

   composer-dev CLI 會透過標準 Docker API 呼叫進行通訊。您必須在使用者層級啟用 Podman 的背景服務通訊端包裝函式，才能模擬 Docker Daemon。

   首先，請確認使用者層級的插座是否已啟用：

   systemctl --user is-active podman.socket
   

   如果指令傳回 inactive 或 failed，請啟用並啟動通訊端：

   # Enable and start Podman's user-level systemd socket
   systemctl --user enable --now podman.socket
   

2. 設定 Podman 的環境變數。

   在殼層設定檔 (例如 .bashrc 或 .zshrc) 中新增下列指令：

   export DOCKER_HOST="unix:///run/user/$UID/podman/podman.sock"
   

Windows

1. 設定 WSL 2 (.wslconfig)。初始化 Podman 機器前，請先檢查 WSL 2 是否已定義記憶體和交換邊界。如果沒有這項功能，多容器部署作業可能會在映像檔擷取期間導致記憶體用量激增。此外，設定並行下載限制也很重要。

   變更或建立 %USERPROFILE%\.wslconfig 檔案：

   [wsl2]
   memory=4GB
   swap=2GB
   
   [registry]
   max_concurrent_downloads = 2
   

2. 在 PowerShell 中，初始化 Podman 電腦：

   podman machine init
   

3. 啟動機器：

   podman machine start
   

完成這些步驟後，您就可以使用 composer-dev CLI 指令。這項工具會自動偵測 Windows 上的 Podman 環境，並調整架構對應。

使用 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 LOCAL_ENVIRONMENT_NAME \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  --plugins-path LOCAL_PLUGINS_PATH \
  --database DATABASE_ENGINE \
  --editable-dependencies EDITABLE_DEPENDENCY_PATH

更改項目：

• LOCAL_ENVIRONMENT_NAME：這個本機 Airflow 環境的名稱。
• IMAGE_VERSION：Airflow 建構映像檔的名稱。
• PROJECT_ID，並提供專案 ID。
• WEB_SERVER_PORT：Airflow 網路伺服器必須監聽的通訊埠。
• LOCAL_DAGS_PATH 替換為 DAG 檔案所在本機目錄的路徑。
• 將 LOCAL_PLUGINS_PATH 替換為外掛程式檔案所在本機目錄的路徑。

• DATABASE_ENGINE，並選擇要使用的資料庫引擎。可能的值為 postgresql (預設) 和 sqlite。

  注意： 如要使用 LocalExecutor 做為 Airflow 的核心執行器，請將 DATABASE_ENGINE 設為 postgresql。LocalExecutor 必須有這項權限才能正常運作。

• (僅限 Linux/macOS) EDITABLE_DEPENDENCY_PATH，其中包含要在可編輯模式下安裝的 Python 套件所在本機目錄的路徑。Windows 不支援這個引數。

  路徑可以是絕對路徑或相對路徑 (相對路徑會根據目前使用的目錄解析)。容器引擎必須可存取這個目錄。

  如要指定多個可編輯套件，請重複使用這個選項。例如：--editable-dependencies ./pkg1 --editable-dependencies ./pkg2。

  使用 pip install -e 安裝套件後，系統會立即將變更套用至專案中的這些套件。

範例：

composer-dev create \
  --from-image-version composer-3-airflow-2.11.1-build.20 \
  example-local-environment

從 Managed Airflow 環境建立本機 Airflow 環境

注意： Composer 本機開發 CLI 工具不會產生 Managed Airflow 環境的本機副本。

系統只會從 Managed Airflow 環境擷取下列資訊：

• 環境使用的特定 Airflow 建構版本。

• 環境中安裝的自訂 PyPI 套件清單。

• 環境中設定的環境變數名稱註解清單。

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

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

如要從現有的 Managed Airflow 環境建立本機 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 \
    --plugins-path LOCAL_PLUGINS_PATH \
    --database DATABASE_ENGINE \
    --editable-dependencies EDITABLE_DEPENDENCY_PATH

更改項目：

• LOCAL_ENVIRONMENT_NAME，並為本機 Airflow 環境命名。
• ENVIRONMENT_NAME：Managed Airflow 環境的名稱。
• LOCATION：Managed Airflow 環境所在的區域。
• PROJECT_ID，並提供專案 ID。
• WEB_SERVER_PORT，並指定本機 Airflow 網路伺服器的通訊埠。
• LOCAL_DAGS_PATH，並提供 DAG 所在本機目錄的路徑。
• 將 LOCAL_PLUGINS_PATH 替換為外掛程式檔案所在本機目錄的路徑。

• DATABASE_ENGINE 替換為要使用的資料庫引擎。可能的值為 postgresql (預設) 和 sqlite。

  注意： 如要使用 LocalExecutor 做為 Airflow 的核心執行器，請將 DATABASE_ENGINE 設為 postgresql。LocalExecutor 必須有這項權限才能正常運作。

• (僅限 Linux/macOS) EDITABLE_DEPENDENCY_PATH，其中包含要在可編輯模式下安裝的 Python 套件所在本機目錄的路徑。Windows 不支援這個引數。

  路徑可以是絕對路徑或相對路徑 (相對路徑會根據目前使用的目錄解析)。容器引擎必須可存取這個目錄。

  如要指定多個可編輯套件，請重複使用這個選項。例如：--editable-dependencies ./pkg1 --editable-dependencies ./pkg2。

  使用 pip install -e 安裝套件後，系統會立即將變更套用至專案中的這些套件。

範例：

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path ./example_directory/dags \
  --plugins-path ./example_directory/plugins \
  --database postgresql \
  --editable-dependencies ./pkg1

啟動本機 Airflow 環境

如要啟動本機 Airflow 環境，請執行：

composer-dev start LOCAL_ENVIRONMENT_NAME

更改項目：

• LOCAL_ENVIRONMENT_NAME：本機 Airflow 環境的名稱。

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

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

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

composer-dev restart LOCAL_ENVIRONMENT_NAME

更改項目：

• LOCAL_ENVIRONMENT_NAME：本機 Airflow 環境的名稱。

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

composer-dev stop LOCAL_ENVIRONMENT_NAME

注意： stop 指令不會刪除本機 Airflow 環境。

新增及更新 DAG

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

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

查看本機 Airflow 環境記錄

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

注意： Composer Local Development CLI 工具不會將 DAG 執行和工作記錄寫入檔案。您可以在本機 Airflow 環境的 Airflow UI 中查看這些記錄。

如要查看執行本機 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 指令的 Google Cloud 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 本機開發 CLI 工具會儲存本機 Airflow 環境的設定參數，例如本機環境目錄 (./composer/<local_environment_name>) 中的環境變數和 PyPI 套件需求。

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

重要事項： Composer 本機開發 CLI 工具不會將 airflow.cfg 檔案儲存在這個目錄中。這個檔案位於環境的 Docker 映像檔中。您可以設定環境變數，變更 Airflow 設定選項。

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

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

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

composer-dev list

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

composer-dev describe LOCAL_ENVIRONMENT_NAME

更改項目：

• LOCAL_ENVIRONMENT_NAME，並將其替換為本機 Airflow 環境的名稱。

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

如要列出 Composer 本機開發 CLI 工具使用的所有映像檔，請執行下列指令：

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

安裝外掛程式及變更資料

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

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

Composer 本機開發 CLI 工具不支援為資料和外掛程式指定其他目錄。

設定環境變數

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

注意： 為安全起見，系統不會從 Managed Airflow 環境複製環境變數的值，且變數名稱清單會加上註解。舉例來說，您可能想指定不同的值，避免 DAG 與正式環境互動，或省略設定部分變數。

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 本機開發 CLI 工具，並在映像檔之間切換。這種做法與升級 Managed Airflow 環境不同，因為本機 Airflow 環境啟動時，會套用該環境的設定參數。

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

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

1. 編輯本機環境設定檔：./composer/<local_environment_name>/config.json。

2. 變更 composer_image_version 參數的值。如要查看可用值，請列出可用映像檔。

3. 如要套用變更，請重新啟動本機 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)

額外設定和疑難排解

本節提供常見問題的解決方案，以及設定 Composer Local Development CLI 工具與其他工具和服務互動時的額外設定步驟。

Shell Tab 鍵完成

composer-dev CLI 支援 Bash、Zsh 和 Fish 殼層的 Tab 鍵完成功能。您可以使用 Tab 鍵完成功能，探索可用的子指令和選項，不必查閱說明文字。

Zsh

產生完成指令碼，並在 ~/.zshrc 中提供來源：

_COMPOSER_DEV_COMPLETE=zsh_source composer-dev > ~/.composer-dev-complete.zsh

然後將其新增至 ~/.zshrc：

echo 'source ~/.composer-dev-complete.zsh' >> ~/.zshrc

Bash

產生完成指令碼，並在 ~/.bashrc 中提供來源：

_COMPOSER_DEV_COMPLETE=bash_source composer-dev > ~/.composer-dev-complete.bash

然後將其新增至 ~/.bashrc：

echo 'source ~/.composer-dev-complete.bash' >> ~/.bashrc

魚

產生完成指令碼，並儲存至 Fish completions 目錄：

_COMPOSER_DEV_COMPLETE=fish_source composer-dev > ~/.config/fish/completions/composer-dev.fish

與 Kubernetes 叢集互動

根據預設，系統不會掛接 ~/.kube/config 檔案。在啟動環境前，您可以匯出 KUBECONFIG 環境變數，指定 Kubernetes 設定檔的路徑。

export KUBECONFIG=~/.kube/config

與主機上的其他服務互動

由於 Docker 或 Podman 容器的網路運作方式，Managed Airflow 環境中的 localhost 會指向容器本身，而非主機。為方便起見，composer-dev CLI 工具會設定容器的網路，透過 host.docker.internal 網域別名存取機器。範例：

• Redis：如果 Redis 在通訊埠 6379 上執行，請使用 host.docker.internal:6379，而非 localhost:6379。
• PostgreSQL： 如果 PostgreSQL 在通訊埠 25432 上執行，請使用 host.docker.internal:25432，而非 localhost:25432。
• 任何其他服務： 請按照以下模式：host.docker.internal:<PORT>

注意： 如果目標服務是在其他 Docker 容器中執行，請確保該連接埠也已向主機公開。

無法在 macOS 上啟動本機環境

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

舉例來說，如果 Python 安裝在 /opt 目錄中 (例如在 macOS 上使用預設 Homebrew 設定安裝)，則 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。

容器使用者存取主機掛接的檔案和目錄

根據預設，Managed Airflow 環境的容器會以 UID 999 的 airflow 使用者身分執行。使用者必須能存取從主機掛接的檔案和目錄，例如 ~/.config/gcloud/application_default_credentials.json。

已知問題：

• google.auth.exceptions.DefaultCredentialsError: Your default credentials were not found：使用預設使用者 airflow (999) 執行容器，且主機目錄 ~/.config/gcloud/ 缺少該使用者的執行權限時，可能會產生這個錯誤。
• [Errno 13] Permission denied: '/home/airflow/.config/gcloud/application_default_credentials.json'：如果使用預設使用者 airflow (999) 執行容器，且主機檔案 ~/.config/gcloud/application_default_credentials.json 缺少使用者的讀取權限，就可能產生這個問題。

在 Linux 或 macOS 上，建議您將 COMPOSER_CONTAINER_RUN_AS_HOST_USER=True 新增至 composer/<LOCAL_ENVIRONMENT_NAME>/variables.env，以目前主機使用者的身分執行容器。這項功能不適用於 Windows，因此您可能需要更新主機上掛接檔案和目錄的權限，允許容器內的使用者存取。

(Podman) 修正企業使用者的權限或 lchown 錯誤

為避免無根 Podman 自動分配與主要公司使用者 ID 重疊的使用者命名空間 (導致 lchown: invalid argument 或權限錯誤)，您必須手動將從屬範圍推送至 400 萬區塊以上。

1. 使用根權限開啟 /etc/subuid 和 /etc/subgid (例如：sudo nano /etc/subuid)。

2. 更新或新增使用者名稱項目，使其與下列內容完全相同：

   YOUR_USERNAME:4000000:3000000
   

3. 儲存這兩個檔案，然後執行下列指令，將新的命名空間對應規則套用至 Podman：

   podman system migrate
   

(Podman) 移除卡住的檔案和權限遭拒錯誤

如果您在舊容器存在時更新 subuid 範圍，目前的命名空間將無法存取自己的資料快取。

警告： 執行下列指令會移除所有磁碟區。 如果還有其他工作內容，請務必謹慎。

使用主機層級的根權限，強制清除本機儲存空間圖表：

podman rm -fa
podman volume rm --all --force
podman system migrate

(Podman) 修正 DNS 故障 (「Name or service not known」)

如果 Airflow 容器產生 psycopg2.OperationalError，指出無法轉譯或解析資料庫容器的主機名稱 (your-environment-name)，則表示 Podman 的內部虛擬橋接網路未同步。

清除執行階段狀態，並強制 netavark 和 aardvark-dns 重新產生乾淨的轉送表。

警告： 下列指令會移除所有網路。如果儲存了其他工作，請謹慎操作。

podman rm -fa
podman network prune --force

rm -rf /run/user/$UID/containers/*
rm -rf /run/user/$UID/netavark/*
rm -rf COMPOSER_LOCAL_DEV_PATH/composer/*

podman system migrate

(Podman) 驗證引擎狀態

如要確認 Podman 是以無根模式管理工作流程，且不會將設定略過並傳送至系統 Docker，請執行下列操作：

1. 驗證網路 DNS 後端：

   podman info | grep -A 3 -i "dns"
   

   輸出內容必須包含 backend: netavark，以及 aardvark-dns 的有效可執行檔路徑。

2. 驗證程序擁有權對應。環境執行時，請檢查主機程序擁有者：

   ps -ef | grep -i "postgres"
   

   最左側的欄應會顯示高 UID 號碼 (例如 4000069)，對應至 subuid 對應範圍，證明完全以無根模式執行。

(Podman、Windows) 修正部署期間的管道錯誤

如果在部署期間，資料庫或 Airflow 容器立即結束並出現管道錯誤，則 Podman 可能已達到記憶體上限。如要修正這個問題，請嘗試在 .wslconfig 檔案中提高記憶體和交換空間上限：

1. 在 PowerShell 中執行下列指令，停止 Podman 電腦和 WSL 2 虛擬機器：

   podman machine stop
   wsl --shutdown
   

2. 在 %USERPROFILE%\.wslconfig 檔案中進行變更，調整交換和記憶體限制。如需參考資料，請參閱「WSL 設定參考資料」。

3. 執行下列指令，啟動 Podman 機器：

   podman machine start
   

如果發生錯誤，可以嘗試對 Windows 虛擬化和網路堆疊執行恢復原廠設定。請以管理員身分開啟 PowerShell，然後執行下列指令：

Restart-Service -Name vmms -Force
Restart-Service -Name hns -Force
wsl --shutdown

後續步驟

• 編寫 DAG
• 從 GitHub 測試、同步及部署 DAG