Managing Astro Local Env

作者 astronomercbe1141f547b無授權條款451 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫今天更新

Manage local Airflow environment with Astro CLI (Docker and standalone modes). Use when the user wants to start, stop, or restart Airflow, view logs, query the Airflow API, troubleshoot, or fix environment issues. For project setup, see setting-up-astro-project.

僅含說明DevOps & Cloud
AI 產生的概覽

使用 Astro CLI 管理本機 Airflow 環境：啟動、停止、重新啟動、查看日誌、查詢 API 與疑難排解。

功能
此技能提供透過 Astro CLI 在 Docker 或獨立模式下操作本機 Airflow 環境的說明。內容涵蓋啟動、停止、重新啟動與銷毀環境，查看狀態與日誌，執行 Airflow CLI 指令，以及透過 Airflow API 查詢 DAG、DAG 執行、任務執行個體、連線、變數與設定。也包含疑難排解與重置指引、反向代理設定，以及 Airflow 版本升級步驟。此技能僅為說明文件，未附帶指令碼。
適用情境
當使用者需要啟動、停止或重新啟動本機 Airflow，查看日誌或狀態，查詢本機 Airflow API，或診斷並修復本機環境問題時使用。它不用於初始專案建置，後者由另一個技能負責。
執行需求
需要 Astro CLI；預設模式需要 Docker；獨立模式需要 Airflow 3 執行環境以及 PATH 中的 uv（不支援 Windows）。需要存取本機 Airflow 網頁服務與 API 的網路；預設認證為 admin/admin。未包含指令碼。

Astro Local Environment

This skill helps you manage your local Airflow environment using the Astro CLI.

Two modes: Docker (default, uses containers) and Standalone (Docker-free, uses a local venv — requires Airflow 3 + uv).

To set up a new project, see the setting-up-astro-project skill. When Airflow is running, use MCP tools from authoring-dags and testing-dags skills.

Start / Stop / Restart (Docker)

bash
# Start local Airflow (webserver at http://localhost:8080)astro dev start
# Stop containers (preserves data)astro dev stop
# Kill and remove volumes (clean slate)astro dev kill
# Restart all containersastro dev restart
# Restart specific componentastro dev restart --schedulerastro dev restart --webserver

Default credentials: admin / admin

Restart after modifying: requirements.txt, packages.txt, Dockerfile

Standalone mode? See the next section.

Standalone Mode

Docker-free local development. Runs Airflow directly on your machine in a .venv/ managed by uv.

Requirements: Airflow 3 (runtime 3.x), uv on PATH. Not supported on Windows.

Plain astro dev init already pins a runtime 3.x image, so no version flag is needed. See setting-up-astro-project for project initialization.

Start

bash
# One-time: set standalone as default modeastro config set dev.mode standalone
# Or use the flag per invocationastro dev start --standalone
FlagDescription
--foreground / -fStream output in foreground
--port / -pOverride webserver port (default: 8080)
--no-proxyDisable reverse proxy

Stop / Kill / Restart

bash
# Stop (preserves .venv)astro dev stop
# Kill (removes .venv and .astro/standalone/ — clean slate)astro dev kill
# Restart (preserves .venv for fast restart, use -k to kill first)astro dev restart

If you used --standalone on start instead of setting the config, pass --standalone on every subsequent command too (stop, kill, restart, bash, run, logs, etc.).

State locations: venv in .venv/, database and logs in .astro/standalone/, DAGs from dags/.

Reverse Proxy

Run multiple Airflow projects locally without port conflicts. Works in both Docker and standalone modes.

Each project gets a hostname like <project-name>.localhost:6563. Visit http://localhost:6563 to see all active projects.

bash
# Check proxy status and active routesastro dev proxy status
# Force-stop proxy (auto-restarts on next astro dev start)astro dev proxy stop
ConfigCommand
Change proxy portastro config set proxy.port <port>
Disable per-startastro dev start --no-proxy

Default proxy port: 6563

Check Status

bash
astro dev ps

View Logs

bash
# All logsastro dev logs
# Specific componentastro dev logs --schedulerastro dev logs --webserver
# Follow in real-timeastro dev logs -f

Standalone: astro dev logs works the same but shows a unified log (no per-component filtering).

Run Airflow CLI Commands

bash
# Open a shell with Airflow environmentastro dev bash
# Run Airflow CLI commandsastro dev run airflow infoastro dev run airflow dags list

Standalone: Same commands work — bash opens a venv-activated shell, run executes in the venv.

Querying the Airflow API

Use astro api airflow to query a running local Airflow instance. Prefer operation IDs over URL paths.

Defaults: localhost:8080, admin/admin (auto-detected). Override with --api-url, --username, --password.

Discovery

bash
# List all endpointsastro api airflow ls
# Filter by keywordastro api airflow ls dagsastro api airflow ls task
# Show params and schema for an operationastro api airflow describe get_dag

Key Flags

FlagPurpose
-p key=valuePath parameters
-F key=valueBody/query fields (auto-converts booleans/numbers)
-q / --jqjq filter on response
--paginateFetch all pages
-X / --methodOverride HTTP method
--generateOutput curl command instead of executing

DAGs

bash
# List all DAGsastro api airflow get_dags
# Filter by pattern (SQL LIKE — use % wildcards)astro api airflow get_dags -F dag_id_pattern=%etl%
# Get a specific DAGastro api airflow get_dag -p dag_id=my_dag
# Get full details (schedule, params, etc.)astro api airflow get_dag_details -p dag_id=my_dag
# Pause / unpauseastro api airflow patch_dag -p dag_id=my_dag -F is_paused=trueastro api airflow patch_dag -p dag_id=my_dag -F is_paused=false
# View DAG source codeastro api airflow get_dag_source -p dag_id=my_dag
# Check import errorsastro api airflow get_import_errors

DAG Runs

bash
# List runs for a DAGastro api airflow get_dag_runs -p dag_id=my_dag
# Trigger a runastro api airflow trigger_dag_run -p dag_id=my_dag
# Trigger with configastro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value
# Get a specific runastro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07
# Clear (re-run) a DAG runastro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false

Task Instances

bash
# List task instances for a runastro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=manual__2026-04-07
# Use ~ as wildcard (all DAGs or all runs)astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~
# Get a specific task instanceastro api airflow get_task_instance -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -p task_id=extract
# Clear/retry failed tasksastro api airflow post_clear_task_instances -p dag_id=my_dag \  -F dag_run_id=manual__2026-04-07 -F only_failed=true -F dry_run=false
# Get task logsastro api airflow get_log -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 \  -p task_id=extract -p try_number=1

Config & Connections

bash
astro api airflow get_connectionsastro api airflow get_variablesastro api airflow get_config

Filtering with jq

bash
# List only DAG IDsastro api airflow get_dags -q '.dags[].dag_id'
# Get failed task IDs from a runastro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \  -q '[.task_instances[] | select(.state=="failed") | .task_id]'

Troubleshooting

IssueSolution
Port 8080 in useStop other containers or edit .astro/config.yaml
Container won't startastro dev kill then astro dev start
Package install failedCheck requirements.txt syntax
DAG not appearingRun astro dev parse to check for import errors
Out of disk spacedocker system prune
Standalone won't startEnsure uv is on PATH and runtime is 3.x
Proxy port conflictastro config set proxy.port <port>
.venv corruptedastro dev kill then astro dev start --standalone

Reset Environment

When things are broken:

bash
astro dev killastro dev start

Upgrade Airflow

Test compatibility first

bash
astro dev upgrade-test

Change version

  1. Edit Dockerfile:

    dockerfile
    FROM quay.io/astronomer/astro-runtime:13.0.0

  2. Restart:

    bash
    astro dev kill && astro dev start

Related Skills

  • setting-up-astro-project: Initialize projects and configure dependencies
  • authoring-dags: Write DAGs (uses MCP tools, requires running Airflow)
  • testing-dags: Test DAGs (uses MCP tools, requires running Airflow)
  • deploying-airflow: Deploy DAGs to production (Astro, Docker Compose, Kubernetes)

來源與署名

來源：astronomer/agents位於skills/managing-astro-local-env提交cbe1141

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 astronomer/agents 的技能

Warehouse Init

astronomer

探索資料倉庫的結構描述中繼資料，並產生可共用的 .astro/warehouse.md 參考檔案，以便快速進行概念對應資料表的查詢。

Data & Analytics451今天更新

Tracing Upstream Lineage

astronomer

Trace upstream data lineage. Use when the user asks where data comes from, what feeds a table, upstream dependencies, data sources, or needs to understand data origins.

待分類451今天更新

Tracing Downstream Lineage

astronomer

追蹤下游資料血緣，評估表或 DAG 變更會造成哪些影響。

Data & Analytics451今天更新

Testing Dags

astronomer

指導使用 af 命令列工具對 Airflow DAG 進行迭代式測試、除錯與修復。

Software Development451今天更新

Setting Up Astro Project

astronomer

使用 Astro CLI 初始化並設定 Astro/Airflow 專案，涵蓋相依套件、連線與變數。

DevOps & Cloud451今天更新

Profiling Tables

astronomer

透過 SQL 統計、基數分析、樣本資料與資料品質評估，對資料庫資料表進行剖析。

Data & Analytics451今天更新

更多DevOps & Cloud技能

Amazon Location Service

awslabs

指導在 AWS 應用中整合 Amazon Location Service API，實現地圖、地理編碼、路線、地點搜尋、地理圍籬與追蹤。

DevOps & Cloud915今天更新

Managing Astro Deployments

astronomer

指導使用 Astro CLI 進行身分驗證、管理工作區，以及建立、更新、刪除和部署 Astronomer 正式環境部署。

DevOps & Cloud451今天更新

Deploying Airflow

astronomer

指導如何透過 Astro、Docker Compose 或 Kubernetes Helm 將 Airflow DAG 與專案部署到正式環境。

DevOps & Cloud451今天更新

Airflow State Store

astronomer

說明 Airflow 3.3 的工作與資產狀態儲存、防崩潰的可續跑作業提交，以及提交加輪詢 DAG 的檢視。

DevOps & Cloud451今天更新

Airflow

astronomer

透過 af 命令列工具操作與排查 Apache Airflow 執行個體，涵蓋 DAG、執行、任務、日誌、設定與健康狀態。

包含腳本
DevOps & Cloud451今天更新

Monitor Reliability

amplitude

根據 Amplitude 的錯誤、網路與錯誤點擊資料，產出主動式的產品可靠性健康檢查報告。

DevOps & Cloud42今天更新