在 Docker 中執行 Airflow¶
本快速入門指南將協助您快速啟動並執行在 Docker 中使用 CeleryExecutor 的 Airflow。
注意
此程序可能適用於學習和探索。然而，將其調整為在真實世界情況中使用可能會很複雜，而且 docker compose 檔案並未提供生產系統所需的任何安全性保證。對此程序進行變更將需要 Docker 和 Docker Compose 方面的專業知識，而 Airflow 社群可能無法協助您。
基於這個原因，當您準備好在生產環境中執行 Airflow 時，我們建議使用 Kubernetes 和 官方 Airflow 社群 Helm Chart。
開始之前¶
此程序假設您已熟悉 Docker 和 Docker Compose。如果您之前未使用過這些工具，您應該花一些時間瀏覽 Docker 快速入門 (尤其是關於 Docker Compose 的章節)，以便您熟悉它們的運作方式。
如果您尚未安裝必要的工具，請依照下列步驟進行安裝。
在您的工作站上安裝 Docker Community Edition (CE)。根據您的作業系統，您可能需要設定 Docker 以使用至少 4.00 GB 的記憶體，Airflow 容器才能正常執行。如需更多資訊，請參閱 Docker for Windows 或 Docker for Mac 文件中的「資源」章節。
在您的工作站上安裝 Docker Compose v2.14.0 或更新版本。
舊版本的 docker-compose 不支援 Airflow docker-compose.yaml 檔案所需的所有功能，因此請仔細檢查您的版本是否符合最低版本需求。
提示
macOS 上 Docker 的預設可用記憶體量通常不足以啟動並執行 Airflow。如果未分配足夠的記憶體，可能會導致 Web 伺服器持續重新啟動。您應該為 Docker Engine 分配至少 4GB 的記憶體 (理想情況下為 8GB)。
您可以執行此命令來檢查您是否有足夠的記憶體
docker run --rm "debian:bookworm-slim" bash -c 'numfmt --to iec $(echo $(($(getconf _PHYS_PAGES) * $(getconf PAGE_SIZE))))'
警告
某些作業系統 (Fedora、ArchLinux、RHEL、Rocky) 最近引入了核心變更，導致在 OS 團隊維護的社群 Docker 實作中執行時，Docker Compose 中的 Airflow 會消耗 100% 的記憶體。
這是 containerd 設定向後不相容的問題，某些 Airflow 相依性與其存在問題，並且已在一些問題中追蹤
containerd 團隊目前尚未提出解決方案，但似乎安裝 Linux 上的 Docker Desktop 可以解決問題，如 此評論 中所述，並且允許 Breeze 無問題執行。
取得 docker-compose.yaml¶
若要在 Docker Compose 上部署 Airflow，您應該取得 docker-compose.yaml。
curl -LfO 'https://airflow.dev.org.tw/docs/apache-airflow/2.10.4/docker-compose.yaml'
重要事項
自 2023 年 7 月起，Compose V1 停止接收更新。我們強烈建議升級至較新版本的 Docker Compose，提供的 docker-compose.yaml 可能無法在 Compose V1 中準確運作。
此檔案包含數個服務定義
airflow-scheduler- scheduler 監控所有任務和 DAG，然後在其相依性完成後觸發任務執行個體。airflow-webserver- Web 伺服器可在https://127.0.0.1:8080上使用。airflow-worker- 執行 scheduler 給定任務的 worker。airflow-triggerer- triggerer 執行可延遲任務的事件迴圈。airflow-init- 初始化服務。postgres- 資料庫。redis- Redis - 將訊息從 scheduler 轉發至 worker 的訊息佇列代理程式。
您可以選擇性地透過新增 --profile flower 選項來啟用 flower，例如 docker compose --profile flower up，或透過在命令列上明確指定它，例如 docker compose up flower。
flower- Flower 應用程式，用於監控環境。它可在https://127.0.0.1:5555上使用。
所有這些服務都可讓您使用 CeleryExecutor 執行 Airflow。如需更多資訊，請參閱 架構總覽。
容器中的某些目錄已掛載，這表示它們的內容會在您的電腦和容器之間同步。
./dags- 您可以將您的 DAG 檔案放在這裡。./logs- 包含來自任務執行和 scheduler 的日誌。./config- 您可以新增自訂日誌剖析器，或新增airflow_local_settings.py以設定叢集原則。./plugins- 您可以將您的自訂外掛程式放在這裡。
此檔案使用最新的 Airflow 映像檔 (apache/airflow)。如果您需要安裝新的 Python 程式庫或系統程式庫，您可以建置您的映像檔。
初始化環境¶
第一次啟動 Airflow 之前，您需要準備您的環境，即建立必要檔案、目錄並初始化資料庫。
設定正確的 Airflow 使用者¶
在 Linux 上，快速入門需要知道您的主機使用者 ID，並且需要將群組 ID 設定為 0。否則，在 dags、logs 和 plugins 中建立的檔案將會以 root 使用者擁有權建立。您必須確保為 docker-compose 設定它們
mkdir -p ./dags ./logs ./plugins ./config
echo -e "AIRFLOW_UID=$(id -u)" > .env
對於其他作業系統，您可能會收到 AIRFLOW_UID 未設定的警告，但您可以安全地忽略它。您也可以在與 docker-compose.yaml 相同的資料夾中手動建立 .env 檔案，並包含此內容以消除警告
AIRFLOW_UID=50000
初始化資料庫¶
在所有作業系統上，您都需要執行資料庫遷移並建立第一個使用者帳戶。若要執行此操作，請執行。
docker compose up airflow-init
初始化完成後，您應該會看到類似這樣的訊息
airflow-init_1 | Upgrades done airflow-init_1 | Admin user airflow created airflow-init_1 | 2.10.4 start_airflow-init_1 exited with code 0
建立的帳戶具有登入名稱 airflow 和密碼 airflow。
清理環境¶
我們準備的 docker-compose 環境是「快速入門」環境。它並非設計用於生產環境，並且存在許多注意事項 - 其中之一是從任何問題中復原的最佳方法是清理它並從頭開始重新啟動。
最好的方法是
在您下載
docker-compose.yaml檔案的目錄中執行docker compose down --volumes --remove-orphans命令移除您下載
docker-compose.yaml檔案的整個目錄rm -rf '<DIRECTORY>'從頭開始瀏覽本指南，從重新下載
docker-compose.yaml檔案開始
執行 Airflow¶
現在您可以啟動所有服務
docker compose up
注意
docker-compose 是舊語法。請查看 Stackoverflow。
在第二個終端機中，您可以檢查容器的狀況，並確保沒有容器處於不健康的狀況
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
247ebe6cf87a apache/airflow:2.10.4 "/usr/bin/dumb-init …" 3 minutes ago Up 3 minutes (healthy) 8080/tcp compose_airflow-worker_1
ed9b09fc84b1 apache/airflow:2.10.4 "/usr/bin/dumb-init …" 3 minutes ago Up 3 minutes (healthy) 8080/tcp compose_airflow-scheduler_1
7cb1fb603a98 apache/airflow:2.10.4 "/usr/bin/dumb-init …" 3 minutes ago Up 3 minutes (healthy) 0.0.0.0:8080->8080/tcp compose_airflow-webserver_1
74f3bbe506eb postgres:13 "docker-entrypoint.s…" 18 minutes ago Up 17 minutes (healthy) 5432/tcp compose_postgres_1
0bd6576d23cb redis:latest "docker-entrypoint.s…" 10 hours ago Up 17 minutes (healthy) 0.0.0.0:6379->6379/tcp compose_redis_1
存取環境¶
啟動 Airflow 後，您可以透過 3 種方式與其互動
執行 CLI 命令¶
您也可以執行 CLI 命令，但您必須在定義的 airflow-* 服務之一中執行。例如，若要執行 airflow info，請執行下列命令
docker compose run airflow-worker airflow info
如果您有 Linux 或 Mac OS，您可以讓您的工作更輕鬆，並下載選用的包裝函式腳本，讓您可以使用更簡單的命令來執行命令。
curl -LfO 'https://airflow.dev.org.tw/docs/apache-airflow/2.10.4/airflow.sh'
chmod +x airflow.sh
現在您可以更輕鬆地執行命令。
./airflow.sh info
您也可以使用 bash 作為參數，在容器中輸入互動式 bash shell，或使用 python 輸入 python 容器。
./airflow.sh bash
./airflow.sh python
存取 Web 介面¶
叢集啟動後，您可以登入 Web 介面並開始試用 DAG。
Web 伺服器可在：https://127.0.0.1:8080 上使用。預設帳戶具有登入名稱 airflow 和密碼 airflow。
傳送請求至 REST API¶
REST API 目前支援基本使用者名稱密碼驗證，這表示您可以使用常用工具來傳送請求至 API。
Web 伺服器可在：https://127.0.0.1:8080 上使用。預設帳戶具有登入名稱 airflow 和密碼 airflow。
以下是範例 curl 命令，它會傳送請求以擷取集區清單
ENDPOINT_URL="https://127.0.0.1:8080/"
curl -X GET \
--user "airflow:airflow" \
"${ENDPOINT_URL}/api/v1/pools"
使用自訂映像檔¶
當您想要在本機執行 Airflow 時，您可能會想要使用擴充的映像檔，其中包含一些額外的相依性 - 例如，您可能會新增新的 python 套件，或將 airflow providers 升級至較新版本。這可以透過在您的 docker-compose.yaml 中指定 build: . 並將自訂 Dockerfile 與您的 docker-compose.yaml 放在一起來輕鬆完成。然後您可以使用 docker compose build 命令來建置您的映像檔 (您只需要執行一次)。您也可以將 --build 旗標新增至您的 docker compose 命令，以便在您執行其他 docker compose 命令時即時重建映像檔。
有關如何使用自訂 providers、python 套件、apt 套件等擴充映像檔的範例，請參閱 建置映像檔。
注意
建立自訂映像檔表示您也需要維護一定程度的自動化，因為當您想要安裝的套件或 Airflow 升級時，您需要重新建立映像檔。請不要忘記保留這些腳本。另請記住，在您執行純 Python 任務的情況下，您可以使用 Python Virtualenv 函數，它會在執行階段動態地尋找和安裝 python 相依性。透過 Airflow 2.8.0，Virtualenvs 也可以快取。
特殊情況 - 透過 requirements.txt 檔案新增相依性¶
自訂映像檔的常見情況是當您想要將一組需求新增至其中時 - 通常儲存在 requirements.txt 檔案中。對於開發，您可能會想要在啟動原始 airflow 映像檔時動態新增它，但這會產生許多副作用 (例如，您的容器啟動速度會慢得多 - 每個額外的相依性都會進一步延遲您的容器啟動時間)。而且這完全沒有必要，因為 docker compose 具有內建的開發工作流程。您可以 - 依照前一章的說明，在您在本機使用 docker compose 迭代時，自動建置和使用您的自訂映像檔。具體而言，當您想要新增您自己的需求檔案時，您應該執行這些步驟
註解掉
image: ...行，並移除docker-compose.yaml檔案中build: .行的註解。您的 docker-compose 檔案的相關部分應如下所示 (使用正確的映像檔標籤)
#image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:2.10.4}
build: .
在您的
docker-compose.yaml檔案所在的相同資料夾中建立Dockerfile，其內容類似於
FROM apache/airflow:2.10.4
ADD requirements.txt .
RUN pip install apache-airflow==${AIRFLOW_VERSION} -r requirements.txt
最佳實務是在安裝 apache-airflow 時使用與原始映像檔相同的版本。這樣您可以確保 pip 不會在安裝其他需求時嘗試降級或升級 apache airflow，如果您嘗試新增與您正在使用的 apache-airflow 版本衝突的相依性，則可能會發生這種情況。
將
requirements.txt檔案放在相同的目錄中。
執行 docker compose build 以建置映像檔，或將 --build 旗標新增至 docker compose up 或 docker compose run 命令，以便在需要時自動建置映像檔。
特殊情況 - 新增自訂設定檔¶
如果您有自訂設定檔並希望在您的 Airflow 執行個體中使用它，您需要執行下列步驟
移除
docker-compose.yaml檔案中AIRFLOW_CONFIG: '/opt/airflow/config/airflow.cfg'行的註解。將您的自訂
airflow.cfg檔案放在本機 config 資料夾中。如果您的設定檔名稱與
airflow.cfg不同，請在AIRFLOW_CONFIG: '/opt/airflow/config/airflow.cfg'中調整檔案名稱
網路¶
一般而言，如果您想要在本機使用 Airflow，您的 DAG 可能會嘗試連線至在主機上執行的伺服器。為了達成此目的，必須在 docker-compose.yaml 中新增額外的設定。例如，在 Linux 上，設定必須在 services: airflow-worker 區段中新增 extra_hosts: - "host.docker.internal:host-gateway"；並使用 host.docker.internal 而不是 localhost。此組態在不同平台中有所不同。請查看 Docker 文件以取得 Windows 和 Mac 的更多資訊。
使用 PyCharm 在 Docker 容器內偵錯 Airflow¶
先決條件：在 PyCharm 中建立專案並下載 (docker-compose.yaml)。
步驟
修改
docker-compose.yaml在
services區段下新增下列區段
airflow-python:
<<: *airflow-common
profiles:
- debug
environment:
<<: *airflow-common-env
user: "50000:0"
entrypoint: [ "/bin/bash", "-c" ]
注意
此程式碼片段會建立一個名為 “airflow-python” 的新服務，專門用於 PyCharm 的 Python 直譯器。在 Linux 系統上，如果您已執行命令 echo -e "AIRFLOW_UID=$(id -u)" > .env，您需要在 airflow-python 服務中設定 user: "50000:0"，以避免 PyCharm 的 Unresolved reference 'airflow' 錯誤。
設定 PyCharm 直譯器
開啟 PyCharm 並導覽至 Settings > Project: <您的專案名稱> > Python Interpreter。
按一下 “Add Interpreter” 按鈕，然後選擇 “On Docker Compose”。
在 Configuration file 欄位中，選取您的
docker-compose.yaml檔案。在 Service field 中，選擇新新增的
airflow-python服務。按一下 “Next” 並依照提示完成組態。
建置直譯器索引可能需要一些時間。3) 將 exec 新增至 docker-compose/command 和 python 服務中的 actions
設定完成後，您可以在容器環境中偵錯您的 Airflow 程式碼，模擬您的本機設定。
FAQ：常見問題¶
ModuleNotFoundError: No module named 'XYZ'¶
Docker Compose 檔案使用最新的 Airflow 映像檔 (apache/airflow)。如果您需要安裝新的 Python 程式庫或系統程式庫，您可以自訂和擴充它。
Docker Compose 支援的環境變數¶
不要將此處的變數名稱與建置映像檔時設定的建置引數混淆。AIRFLOW_UID 建置引數在建置映像檔時預設為 50000，因此它會「烘烤」到映像檔中。另一方面，以下環境變數可以在容器執行時設定，例如使用 id -u 命令的結果，這允許使用在建置映像檔時未知的動態主機執行階段使用者 ID。
變數 |
描述 |
預設值 |
|---|---|---|
|
要使用的 Airflow 映像檔。 |
apache/airflow:2.10.4 |
|
執行 Airflow 容器的使用者 UID。如果您想要使用非預設的 Airflow UID (例如，當您從主機對應資料夾時，應將其設定為 |
|
注意
在 Airflow 2.2 之前，Docker Compose 也曾有 AIRFLOW_GID 參數，但它沒有提供任何額外功能，反而造成混淆，因此已被移除。
這些額外的變數在您嘗試/測試透過 Docker Compose 安裝 Airflow 時非常有用。它們不適用於生產環境，但對於首次使用者進行最常見的客製化設定時，它們可以加速環境的啟動。
變數 |
描述 |
預設值 |
|---|---|---|
|
管理員 UI 帳戶的使用者名稱。如果指定此值，將自動建立管理員 UI 使用者。這僅在您想要試用 Airflow 並希望啟動包含嵌入式開發資料庫的容器時才有用。 |
airflow |
|
管理員 UI 帳戶的密碼。僅在設定 |
airflow |
|
如果非空值，airflow 容器將嘗試安裝變數中指定的套件需求。範例： |