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 Web 服务和 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今天更新