跑起第一個 Airflow:Docker 環境 + 你的第一個 DAG

· tech

#airflow#data-engineering#docker

上一篇把 Airflow 的概念與架構講清楚了;這篇動手把它在本機跑起來,寫出第一個 DAG,並在 Web UI 上看著它跑完。目標很單純:從零到「我親眼看到自己的 DAG 在介面上變綠」。

兩種起法:先選一個

方式指令適合
airflow standalonepip install apache-airflow 後一行啟動只想快速摸 DAG、不在意元件
官方 Docker Compose一份 compose 檔起整套想看到真實多元件架構(scheduler / worker / DB)

學習階段我推薦直接用 Docker Compose —— 它把 上一篇講的 Scheduler、Worker、Metadata DB 全變成你看得到、摸得到的容器,概念才會落地。

用 Docker Compose 起 Airflow

# 1. 抓官方 compose 檔
curl -LfO 'https://airflow.apache.org/docs/apache-airflow/stable/docker-compose.yaml'

# 2. 建掛載資料夾,並設定 UID(Linux/macOS)
mkdir -p ./dags ./logs ./plugins ./config
echo "AIRFLOW_UID=$(id -u)" > .env

# 3. 初始化:建 metadata DB、建 admin 帳號
docker compose up airflow-init

# 4. 起整套(背景執行)
docker compose up -d

跑完打開 http://localhost:8080,用預設帳密 airflow / airflow 登入,就看到 Airflow 的 Web UI 了。這份 compose 會起這些服務:

./dags/*.py 你寫的 DAG Scheduler Web UI :8080 Worker 瀏覽器 你 掛載/解析 顯示 派送任務
你本機的 ./dags 資料夾被掛載進容器;Scheduler 解析它、派任務給 Worker;你用瀏覽器連 :8080 操作

(背後還有 Postgres 當 metadata DB、Redis 當 Celery 的 broker —— 這份官方 compose 用的是 CeleryExecutor,所以多了 worker 與 redis。)

踩到 env file … /.env not found? 多半是 docker-compose.yaml、.env、dags/ 沒放在同一層。docker compose 在當前資料夾找不到 compose 檔時會往上層找,並把專案目錄設成上層,連帶去上層找 .env(於是錯誤裡的路徑會是你上一層的目錄)。解法:確保三者都在同一個資料夾,而且從那個資料夾執行 docker compose。另外,FERNET_KEY … not set 只是警告 —— 官方 compose 寫死空字串,本機學習可忽略。

寫你的第一個 DAG

在剛剛建的 ./dags/ 裡新增 hello_airflow.py:

from datetime import datetime
from airflow.decorators import dag, task


@dag(
    schedule=None,                 # 先不排程,純手動觸發
    start_date=datetime(2026, 1, 1),
    catchup=False,                 # 別自動回補過去(學習期務必設 False)
    tags=["tutorial"],
)
def hello_airflow():

    @task
    def say_hello() -> str:
        return "hello"

    @task
    def shout(word: str) -> None:
        print(f"{word.upper()}!")   # 在 task log 裡會看到 HELLO!

    shout(say_hello())


hello_airflow()

存檔後什麼都不用做 —— Scheduler 每隔一小段時間會掃 ./dags/,大約 30 秒內,hello_airflow 就會自己出現在 Web UI 的 DAG 列表裡。這個「改檔案 → 自動出現」的瞬間,就是 Airflow 從抽象變具體的時刻。

在 Web UI 跑一輪

放進 dags/ UI 自動出現 ▶ 觸發 看 Graph/Log
第一個 DAG 的完整一輪:存檔 → 自動出現 → 手動觸發 → 看執行圖與 log
  1. 打開開關:DAG 列表左邊有個 toggle,新 DAG 預設是暫停的,點亮它。
  2. 手動觸發:右邊的 ▶(Trigger DAG)按下去。
  3. 看 Graph / Grid:點進 DAG,Graph 檢視會看到 say_hello → shout 兩個方塊依序變綠。
  4. 看 log:點任一個 task → Logs,會看到 shout 印出的 HELLO!。
  5. 重跑:對 task 按 Clear,它會重新跑一次 —— 這就是 上一篇說的「可重試」最直觀的體驗。

反思

docker-compose 很適合「學」,但它不是 production

官方那份 compose 檔開頭就寫明 “not suitable for production”。它的價值是讓你一次看到所有元件(scheduler、worker、redis、postgres 全在那),對理解架構很棒;但它也很重,而且預設配置不是拿來上線的。我的建議:用它來「看懂整套怎麼運作」,真要部署再走 managed(MWAA / Astronomer)或正式的 K8s 部署 —— 別把學習用的 compose 直接搬上 production。

第一個坑幾乎都是「DAG 沒出現」

新手最常卡在「我存檔了,UI 卻沒出現我的 DAG」。九成是 DAG 檔本身有 parse error —— Scheduler 匯入失敗,DAG 自然不會出現。解法很固定:看 UI 上方的 Import Errors,或去翻 scheduler 的 log。記住 上一篇提過的:DAG 檔的 top-level 會被反覆 import,所以那層不要放會出錯或很慢的程式碼。

catchup=False 是學習期的保命符

start_date 設在過去 + catchup=True(預設)會讓 Airflow 一啟用就狂補跑從 start_date 到現在的每一個排程,瞬間塞爆。學習階段一律先 schedule=None 或 catchup=False,等真的搞懂 排程模型再開 —— 這也正好是下一篇要拆解的主題。