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

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

使用 Airflow UI 存取權控管

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本頁說明 Airflow UI 和 DAG UI 的不同存取權控管機制。除了 IAM 提供的存取權控制項，您也可以使用這些機制，在環境的 Airflow UI 和 DAG UI 中區隔使用者。

Cloud Composer 中的 Airflow UI 存取權控管總覽

在 Cloud Composer 中，Airflow UI 和 DAG UI 的存取權，以及這些 UI 中資料和作業的顯示方式，都受到兩個層級的控管：

Cloud Composer 中的 Airflow UI 和 DAG UI 存取權由 IAM 控制。

如果帳戶沒有可查看專案中 Cloud Composer 環境的角色，就無法使用 Airflow UI 和 DAG UI。

IAM 不會在 Airflow UI 或 DAG UI 中提供任何額外的精細權限控管機制。
Apache Airflow 存取權控管模型可根據使用者角色，減少 Airflow UI 和 DAG UI 中的可見度。

Apache Airflow 存取權控管是 Airflow 的一項功能，具有自己的使用者、角色、權限模型，與 IAM 不同。

Apache Airflow 存取權控管機制會使用以資源為準的權限。所有具備特定 Airflow 角色的 Airflow 使用者，都會獲得該角色的權限。舉例來說，如果 Airflow 使用者擁有具備 can delete on Connections 權限的角色，就能在 Airflow UI 的「Connections」頁面刪除連線。

您也可以為個別 DAG 指派 DAG 層級的權限。舉例來說，只有具備特定 Airflow 角色的使用者，才能在 Airflow UI 中查看特定 DAG。在 Cloud Composer 中，您可以自動指派 DAG 層級的權限，依據 DAG 檔案在環境 bucket 中的子資料夾位置。

事前準備

Airflow UI (含存取權控管功能) 適用於 Cloud Composer 版本 1.13.4 以上版本，以及 Airflow 1.10.10 以上版本。環境也必須執行 Python 3。
資料夾專屬角色註冊功能適用於 Airflow 2 的 Cloud Composer 1.18.12 以上版本，以及 Airflow 1 的 Cloud Composer 1.13.4 以上版本。

啟用 Airflow UI 存取權控管機制

Airflow 2

在 Airflow 2 中，Airflow UI 存取控管機制一律會啟用。

Airflow 1

如要啟用 Airflow UI 並搭配存取控管機制，請覆寫下列 Airflow 設定選項：

區段	鍵	值
`webserver`	`rbac`	`True`

您可以為現有環境執行這項操作，也可以在建立新環境時執行。

完成這項設定後，環境會執行具有存取權控管功能的 Airflow UI，而非傳統 Airflow UI。

管理 Airflow 角色和存取權控管設定

具備管理員角色 (或同等角色) 的使用者，可以在 Airflow UI 中查看及修改存取權控管設定。

在 Airflow UI 中，您可以透過「安全性」選單設定存取權控管設定。如要進一步瞭解 Airflow 存取權控管模型、可用權限和預設角色，請參閱 Airflow UI 存取權控管說明文件。

Airflow 1 會將「使用者」角色視為所有自訂角色的範本。Airflow 會持續將使用者角色的權限複製到所有自訂角色，但 all_dags 的權限除外。

Airflow 會維護自己的使用者清單。擁有管理員角色 (或同等角色) 的使用者可以查看已開啟環境的 Airflow UI，並在 Airflow 中註冊的使用者清單。這份清單也包含管理員手動預先註冊的使用者，詳情請見下節。

在 Airflow 使用者介面中註冊使用者

新使用者首次開啟 Cloud Composer 環境的 Airflow UI 時，系統會自動註冊。

註冊時，系統會授予使用者在 Airflow 設定選項中指定的角色。[webserver]rbac_user_registration_role您可以覆寫這個 Airflow 設定選項，並使用不同的值，控管新註冊使用者的角色。

如未指定，在 Airflow 2 環境中，預設的註冊角色為 Op。

在 Airflow 1.10.* 環境中，預設註冊角色為 Admin。

建議您按照下列步驟，為 Airflow UI 建立基本角色設定：

Airflow 2

環境管理員開啟新建立環境的 Airflow UI。
將 Admin 角色授予管理員帳戶。在 Airflow 2 環境中，新帳戶的預設角色為 Op。如要指派 Admin 角色，請使用 gcloud CLI 執行下列 Airflow CLI 指令：
```
  gcloud composer environments run ENVIRONMENT_NAME \
    --location LOCATION \
    users add-role -- -e USER_EMAIL -r Admin
```
取代：
- 將 ENVIRONMENT_NAME 替換為環境的名稱。
- LOCATION 改成環境所在的地區。
- USER_EMAIL 使用使用者帳戶的電子郵件地址。
管理員現在可以為新使用者設定存取權控管，包括將Admin角色授予其他使用者。

Airflow 1

環境管理員開啟新建立環境的 Airflow UI 後，系統會自動以 Admin角色註冊。
覆寫下列 Airflow 設定選項，為新使用者設定必要角色。舉例來說，如要User。

區段鍵值

webserver rbac_user_registration_role User 或其他非管理員角色
管理員現在可以為新使用者設定 Airflow UI 存取權控制項，包括將 Admin 角色授予其他使用者。

區段	鍵	值
`webserver`	`rbac_user_registration_role`	`User` 或其他非管理員角色

預先註冊使用者

系統會自動以Google 使用者帳戶的數字 ID (而非電子郵件地址) 做為使用者名稱，為使用者註冊帳戶。您也可以手動預先註冊使用者，並為他們指派角色，方法是新增使用者記錄，並將使用者名稱欄位設為使用者的主要電子郵件地址。如果使用者電子郵件地址與預先註冊的使用者記錄相符，首次登入 Airflow UI 時，系統會將使用者名稱替換為目前 (首次登入時) 透過電子郵件地址識別的使用者 ID。Google 身分 (電子郵件地址) 和使用者帳戶 (使用者 ID) 之間的關係並不固定。Google 群組無法預先註冊。

如要預先註冊使用者，可以使用 Airflow UI，或透過 Google Cloud CLI 執行 Airflow CLI 指令。

如要透過 Google Cloud CLI 預先註冊具有自訂角色的使用者，請執行下列 Airflow CLI 指令：

gcloud composer environments run ENVIRONMENT_NAME \
  --location LOCATION \
  users create -- \
  -r ROLE \
  -e USER_EMAIL \
  -u USER_EMAIL \
  -f FIRST_NAME \
  -l LAST_NAME \
  --use-random-password # The password value is required, but is not used

更改下列內容：

ENVIRONMENT_NAME：環境名稱
LOCATION：環境所在的區域
ROLE：使用者的 Airflow 角色，例如 Op
USER_EMAIL：使用者的電子郵件地址
FIRST_NAME 和 LAST_NAME：使用者的名字和姓氏

範例：

gcloud composer environments run example-environment \
  --location us-central1 \
  users create -- \
  -r Op \
  -e "example-user@example.com" \
  -u "example-user@example.com" \
  -f "Name" \
  -l "Surname" \
  --use-random-password

移除使用者

從 Airflow 刪除使用者不會撤銷存取權，因為使用者下次存取 Airflow UI 時，系統會自動重新註冊。如要撤銷整個 Airflow UI 的存取權，請從專案的允許政策中移除 composer.environments.get 權限。

您也可以將使用者的角色變更為「公開」，這樣一來，使用者仍可註冊，但會失去 Airflow UI 的所有權限。

自動設定 DAG 層級權限

「依資料夾註冊角色」功能會自動為 /dags 資料夾內每個子資料夾建立自訂 Airflow 角色，並授予該角色 DAG 層級的存取權，可存取來源檔案儲存在該子資料夾中的所有 DAG。這項功能可簡化自訂 Airflow 角色和 DAG 存取權的管理作業。

如何註冊每個資料夾的角色

資料夾角色註冊功能可自動設定角色及其 DAG 層級權限。因此，這項功能可能會與其他授予 DAG 層級權限的 Airflow 機制發生衝突：

手動將 DAG 權限指派給角色。
透過 DAG 中的 access_control 屬性，將 DAG 指派給角色。

為避免這類衝突，啟用「每個資料夾的角色註冊」也會改變這些機制的行為。

在 Airflow 1 中，如果啟用「依資料夾註冊角色」，就無法使用這些機制。所有 DAG 層級的權限管理都只能透過「依資料夾角色註冊」進行。

在 Airflow 2 中：

您可以透過 DAG 原始碼中定義的 access_control 屬性，將 DAG 存取權授予角色。
手動授予 DAG 權限 (透過 Airflow UI 或 gcloud CLI) 可能會導致衝突。舉例來說，如果您手動將 DAG 層級的權限授予每個資料夾的角色，DAG 處理器同步處理 DAG 時，這些權限可能會遭到移除或覆寫。建議不要手動授予 DAG 權限。
角色會合併透過「依資料夾註冊角色」註冊的 DAG 存取權限，以及在 DAG 的 access_control 屬性中定義的權限。

位於頂層 /dags 資料夾中的 DAG 不會自動指派給任何資料夾角色。任何資料夾專屬角色都無法存取這些設定。其他角色 (例如管理員、作業人員、使用者，或任何獲授權的自訂角色) 則可透過 Airflow UI 和 DAG UI 存取這些角色。

如果您將 DAG 上傳至名稱與內建 Airflow 角色和 Cloud Composer 建立的角色相符的子資料夾，系統仍會將這些子資料夾中 DAG 的權限指派給這些角色。舉例來說，將 DAG 上傳至 /dags/Admin 資料夾，會將該 DAG 的權限授予管理員角色。內建 Airflow 角色包括管理員、作業人員、使用者、檢視者和公開。啟用「依資料夾註冊角色」功能後，Cloud Composer 會建立 NoDags 和 UserNoDags。

Airflow 在 Airflow 排程器中處理 DAG 時，會為每個資料夾註冊角色。如果環境中有超過一百個 DAG，您可能會發現 DAG 剖析時間變長。如果是這種情況，建議您增加 Airflow 1 環境的 [scheduler]max_threads 參數，或是 Airflow 2 的 [scheduler]parsing_processes 參數。

自動將 DAG 指派給每個資料夾的角色

如要將 DAG 自動指派給每個資料夾的角色，請按照下列步驟操作：

覆寫下列 Airflow 設定選項：

區段鍵值

webserver rbac_autoregister_per_folder_roles True
將新使用者註冊角色變更為無法存取任何 DAG 的角色。這樣一來，管理員為新使用者的帳戶指派具有特定 DAG 權限的角色之前，新使用者都無法存取任何 DAG。

只有在啟用「依資料夾註冊角色」功能時，Cloud Composer 才會建立 UserNoDags 和 NoDags 角色。這類角色與「使用者」角色相同，但無法存取任何 DAG。在 Airflow 2 中建立 UserNoDags 角色，在 Airflow 1 中建立 NoDags 角色。

在 Airflow 2 中，覆寫下列 Airflow 設定選項：

區段鍵值

webserver rbac_user_registration_role UserNoDags

在 Airflow 1 中，覆寫下列 Airflow 設定選項：

區段鍵值

webserver rbac_user_registration_role NoDags
確認使用者已在 Airflow 中註冊。
使用下列其中一種方法指派角色給使用者：
- 讓 Airflow 根據 DAG 子資料夾自動建立角色，然後將使用者指派給這些角色。
- 預先為 DAG 子資料夾建立空白角色，角色名稱須與子資料夾名稱相符，然後將使用者指派給這些角色。舉例來說，針對 /dags/CustomFolder 資料夾，建立名為 CustomFolder 的角色。
注意： 建立含有 DAG 的資料夾後，使用者不會自動取得對應的資料夾角色。舉例來說，如果使用者建立名為 CustomFolder 的子資料夾，帳戶不會取得 CustomFolder 角色。管理員必須在 Airflow 使用者介面中授予這個角色。
將 DAG 上傳至子資料夾，並以指派給使用者的角色命名。這些子資料夾必須位於環境值區的 /dags 資料夾內。Airflow 會在子資料夾中為 DAG 新增權限，因此只有具備相應角色的使用者，才能透過 Airflow UI 和 DAG UI 存取這些 DAG。

區段	鍵	值
`webserver`	`rbac_autoregister_per_folder_roles`	`True`

區段	鍵	值
`webserver`	`rbac_user_registration_role`	`UserNoDags`

區段	鍵	值
`webserver`	`rbac_user_registration_role`	`NoDags`

手動設定 DAG 層級權限

您可以為自訂角色設定 DAG 層級權限，指定特定使用者群組可查看的 DAG。

如要在 Airflow UI 中設定 DAG 層級的權限，請按照下列步驟操作：

管理員會建立空白角色，用於分組 DAG。
管理員會為使用者指派適當的角色。
管理員或使用者將 DAG 指派給角色。
在 Airflow UI 中，使用者只能看到指派給自己群組的 DAG。

您可以透過 DAG 屬性或 Airflow UI，將 DAG 指派給角色。

在 Airflow UI 中將 DAG 指派給角色

管理員可以在 Airflow UI 中，將必要的 DAG 層級權限指派給適當的角色。

DAG UI 不支援這項作業。

在 DAG 屬性中將 DAG 指派給角色

您可以在 DAG 上設定 access_control DAG 參數，指定 DAG 指派的 DAG 分組角色。

Airflow 2

dag = DAG(
  access_control={
    'DagGroup': {'can_edit', 'can_read'},
  },
  ...
  )

Airflow 1

dag = DAG(
  access_control={
    'DagGroup': {'can_dag_edit', 'can_dag_read'},
  },
  ...
  )

在 Airflow 使用者介面中將稽核記錄對應至使用者

Airflow UI 中的稽核記錄會對應至Google 使用者帳戶的數字 ID。舉例來說，如果使用者暫停 DAG，系統就會在記錄中新增項目。

Airflow 2

在 Airflow 2 中，您可以在 Airflow UI 的「Browse」(瀏覽) >「Audit Logs」(稽核記錄) 頁面中查看稽核記錄。

Airflow 1

在 Airflow 1 中，您可以在「Browse」>「Logs」頁面查看稽核記錄。

一般項目會在「擁有者」欄位中列出數字 ID： accounts.google.com:NUMERIC_ID. 您可以在「安全性」>「列出使用者」頁面，將數字 ID 對應至使用者電子郵件。只有具備 Admin 角色的使用者才能存取這個頁面。

請注意，Google 身分 (電子郵件地址) 和使用者帳戶 (使用者 ID) 之間的關係並非固定。

使用 Airflow UI 存取權控管 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Cloud Composer 中的 Airflow UI 存取權控管總覽

事前準備

啟用 Airflow UI 存取權控管機制

Airflow 2

Airflow 1

管理 Airflow 角色和存取權控管設定

在 Airflow 使用者介面中註冊使用者

Airflow 2

Airflow 1

預先註冊使用者

移除使用者

自動設定 DAG 層級權限

如何註冊每個資料夾的角色

自動將 DAG 指派給每個資料夾的角色

手動設定 DAG 層級權限

在 Airflow UI 中將 DAG 指派給角色

在 DAG 屬性中將 DAG 指派給角色

Airflow 2

Airflow 1

在 Airflow 使用者介面中將稽核記錄對應至使用者

Airflow 2

Airflow 1

後續步驟

使用 Airflow UI 存取權控管