managing-astro-local-env

Astro 本地环境

此技能可帮助你使用 Astro CLI 管理本地 Airflow 环境。

两种模式：Docker（默认，使用容器）和 Standalone（无需 Docker，使用本地 venv — 需要 Airflow 3 + uv）。

要设置新项目，请参阅 setting-up-astro-project 技能。 Airflow 运行时，请使用 authoring-dags 和 testing-dags 技能中的 MCP 工具。

---

启动 / 停止 / 重启（Docker）

# 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 containers
astro dev restart

# Restart specific component
astro dev restart --scheduler
astro dev restart --webserver

默认凭据： admin / admin

修改以下文件后重启： requirements.txt、packages.txt、Dockerfile

使用 Standalone 模式？ 请参阅下一节。

---

Standalone 模式

无需 Docker 的本地开发模式。Airflow 直接在你的计算机上运行，使用由 uv 管理的 .venv/。

要求： Airflow 3（运行时版本为 3.x），PATH 中包含 uv。不支持 Windows。

直接运行 astro dev init 已会固定使用 3.x 运行时镜像，因此无需版本标志。有关项目初始化，请参阅 setting-up-astro-project。

启动

# One-time: set standalone as default mode
astro config set dev.mode standalone

# Or use the flag per invocation
astro dev start --standalone

标志	说明
--foreground / -f	在前台流式输出
--port / -p	覆盖 Web 服务器端口（默认：8080）
--no-proxy	禁用反向代理

停止 / 终止 / 重启

# 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

如果启动时使用了 --standalone，而不是设置配置项，那么后续每条命令也都要传入 --standalone（如 stop、kill、restart、bash、run、logs 等）。

状态位置： venv 位于 .venv/，数据库和日志位于 .astro/standalone/，DAG 来自 dags/。

---

反向代理

在本地运行多个 Airflow 项目且不发生端口冲突。Docker 和 standalone 模式均适用。

每个项目都会获得一个类似 <project-name>.localhost:6563 的主机名。访问 http://localhost:6563 查看所有活动项目。

# Check proxy status and active routes
astro dev proxy status

# Force-stop proxy (auto-restarts on next astro dev start)
astro dev proxy stop

配置	命令
更改代理端口	astro config set proxy.port <port>
每次启动时禁用	astro dev start --no-proxy

默认代理端口：6563

---

检查状态

astro dev ps

---

查看日志

# All logs
astro dev logs

# Specific component
astro dev logs --scheduler
astro dev logs --webserver

# Follow in real-time
astro dev logs -f

Standalone： astro dev logs 的用法相同，但会显示统一日志（不按组件筛选）。

---

运行 Airflow CLI 命令

# Open a shell with Airflow environment
astro dev bash

# Run Airflow CLI commands
astro dev run airflow info
astro dev run airflow dags list

Standalone： 同样适用这些命令 — bash 会打开已激活 venv 的 shell，run 会在 venv 中执行命令。

---

查询 Airflow API

使用 astro api airflow 查询正在运行的本地 Airflow 实例。优先使用操作 ID，而非 URL 路径。

默认值： localhost:8080，admin/admin（自动检测）。使用 --api-url、--username、--password 覆盖。

发现

# List all endpoints
astro api airflow ls

# Filter by keyword
astro api airflow ls dags
astro api airflow ls task

# Show params and schema for an operation
astro api airflow describe get_dag

主要标志

标志	用途
-p key=value	路径参数
-F key=value	请求体 / 查询字段（自动转换布尔值 / 数字）
-q / --jq	对响应应用 jq 筛选器
--paginate	获取所有分页
-X / --method	覆盖 HTTP 方法
--generate	输出 curl 命令，而不执行

DAG

# List all DAGs
astro api airflow get_dags

# Filter by pattern (SQL LIKE — use % wildcards)
astro api airflow get_dags -F dag_id_pattern=%etl%

# Get a specific DAG
astro 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 / unpause
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=true
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=false

# View DAG source code
astro api airflow get_dag_source -p dag_id=my_dag

# Check import errors
astro api airflow get_import_errors

DAG 运行

# List runs for a DAG
astro api airflow get_dag_runs -p dag_id=my_dag

# Trigger a run
astro api airflow trigger_dag_run -p dag_id=my_dag

# Trigger with config
astro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value

# Get a specific run
astro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# Clear (re-run) a DAG run
astro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false

任务实例

# List task instances for a run
astro 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 instance
astro 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 tasks
astro 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 logs
astro 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

配置与连接

astro api airflow get_connections
astro api airflow get_variables
astro api airflow get_config

使用 jq 筛选

# List only DAG IDs
astro api airflow get_dags -q '.dags[].dag_id'

# Get failed task IDs from a run
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \
  -q '[.task_instances[] | select(.state=="failed") | .task_id]'

---

故障排除

问题	解决方案
端口 8080 已被占用	停止其他容器，或编辑 .astro/config.yaml
容器无法启动	运行 astro dev kill，然后运行 astro dev start
安装软件包失败	检查 requirements.txt 语法
DAG 未显示	运行 astro dev parse 检查导入错误
磁盘空间不足	运行 docker system prune
Standalone 无法启动	确保 PATH 中包含 uv，且运行时版本为 3.x
代理端口冲突	运行 astro config set proxy.port <port>
.venv 已损坏	运行 astro dev kill，然后运行 astro dev start --standalone

重置环境

出现问题时：

astro dev kill
astro dev start

---

升级 Airflow

先测试兼容性

astro dev upgrade-test

更改版本

1. 编辑 Dockerfile：

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

2. 重启：

   astro dev kill && astro dev start
   

---

相关技能

• setting-up-astro-project：初始化项目并配置依赖项
• authoring-dags：编写 DAG（使用 MCP 工具，需要运行中的 Airflow）
• testing-dags：测试 DAG（使用 MCP 工具，需要运行中的 Airflow）
• deploying-airflow：将 DAG 部署到生产环境（Astro、Docker Compose、Kubernetes）