用 Astro CLI 管理本地 Airflow…

当需要启动、停止、重启本地 Airflow、查看日志、调用 Airflow API 或排查本地环境问题时使用。

适用场景

解决思路

1. 启动本地 Airflow（Webserver 位于 http://localhost:8080）：`astro dev start`
2. 停止容器但保留数据：`astro dev stop`
3. 彻底删除容器与卷（干净重置）：`astro dev kill`
4. 重启所有容器：`astro dev restart`
5. 只重启特定组件：`astro dev restart --scheduler` 或 `astro dev restart --webserver`
6. 默认凭据为 admin / admin
7. 修改 `requirements.txt`、`packages.txt`、`Dockerfile` 后需重启
8. Standalone 模式（无 Docker，使用 uv 管理的 `.venv/`）要求 Airflow 3（runtime 3.x）且 `uv` 在 PATH 中，不支持 Windows
9. 一次性将 standalone 设为默认模式：`astro config set dev.mode standalone`；或每次启动时加 `--standalone`
10. Standalone 启动可用标志：`--foreground`/`-f` 前台流式输出、`--port`/`-p` 覆盖 webserver 端口（默认 8080）、`--no-proxy` 禁用反向代理
11. Standalone 停止保留 `.venv`：`astro dev stop`；彻底删除 `.venv` 与 `.astro/standalone/`：`astro dev kill`；重启保留 `.venv` 以加快速度，加 `-k` 可先 kill
12. 若启动时用 `--standalone` 而非设置 config，则后续所有命令（stop、kill、restart、bash、run、logs 等）都要加 `--standalone`
13. Standalone 状态位置：venv 在 `.venv/`，数据库与日志在 `.astro/standalone/`，DAG 来自 `dags/`
14. 反向代理可在本地运行多个 Airflow 项目而不冲突（Docker 与 standalone 均可用），每个项目获得 `<project-name>.localhost:6563` 主机名，访问 http://localhost:6563 查看所有活跃项目
15. 查看代理状态与活跃路由：`astro dev proxy status`；强制停止代理（下次 `astro dev start` 自动重启）：`astro dev proxy stop`
16. 修改代理端口：`astro config set proxy.port <port>`；单次启动禁用：`astro dev start --no-proxy`；默认代理端口为 6563
17. 查看状态：`astro dev ps`
18. 查看全部日志：`astro dev logs`；查看特定组件：`astro dev logs --scheduler` 或 `astro dev logs --webserver`；实时跟踪：`astro dev logs -f`
19. Standalone 下 `astro dev logs` 行为相同但显示统一日志，无法按组件过滤
20. 打开带 Airflow 环境的 shell：`astro dev bash`
21. 运行 Airflow CLI 命令：`astro dev run airflow info`、`astro dev run airflow dags list`
22. Standalone 下 `bash` 打开已激活 venv 的 shell，`run` 在 venv 中执行
23. 用 `astro api airflow` 查询运行中的本地 Airflow，优先使用 operation ID 而非 URL 路径；默认 localhost:8080、admin/admin（自动检测），可用 `--api-url`、`--username`、`--password` 覆盖
24. 发现端点：`astro api airflow ls`；按关键词过滤：`astro api airflow ls dags`、`astro api airflow ls task`；查看操作的参数与 schema：`astro api airflow describe get_dag`
25. 关键标志：`-p key=value` 路径参数、`-F key=value` body/query 字段（自动转换布尔/数字）、`-q`/`--jq` 对响应做 jq 过滤、`--paginate` 获取所有页、`-X`/`--method` 覆盖 HTTP 方法、`--generate` 输出 curl 命令而不执行
26. DAG 操作：`astro api airflow get_dags` 列出所有 DAG；`astro api airflow get_dags -F dag_id_pattern=%etl%` 用 SQL LIKE 通配符过滤；`astro api airflow get_dag -p dag_id=my_dag` 获取特定 DAG；`astro api airflow get_dag_details -p dag_id=my_dag` 获取完整详情；`astro api airflow patch_dag -p dag_id=my_dag -F is_paused=true`（或 false）暂停/恢复；`astro api airflow get_dag_source -p dag_id=my_dag` 查看源码；`astro api airflow get_import_errors` 检查导入错误
27. DAG Run 操作：`astro api airflow get_dag_runs -p dag_id=my_dag` 列出运行；`astro api airflow trigger_dag_run -p dag_id=my_dag` 触发运行；加 `-F conf[key]=value` 带配置触发；`astro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07` 获取特定运行；`astro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false` 清除（重跑）
28. Task Instance 操作：`astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=manual__2026-04-07` 列出任务实例；用 `~` 作为通配符（所有 DAG 或所有运行）；`astro api airflow get_task_instance -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -p task_id=extract` 获取特定任务实例；`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` 清除/重试失败任务；`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` 获取任务日志
29. 配置与连接：`astro api airflow get_connections`、`astro api airflow get_variables`、`astro api airflow get_config`
30. 用 jq 过滤：`astro api airflow get_dags -q '.dags[].dag_id'` 只列 DAG ID；`astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ -q '[.task_instances[] | select(.state=="failed") | .task_id]'` 获取失败任务 ID
31. 排障：端口 8080 被占用则停止其他容器或编辑 `.astro/config.yaml`；容器无法启动则 `astro dev kill` 后 `astro dev start`；包安装失败检查 `requirements.txt` 语法；DAG 不出现运行 `astro dev parse` 检查导入错误；磁盘空间不足运行 `docker system prune`；Standalone 无法启动确保 `uv` 在 PATH 且 runtime 为 3.x；代理端口冲突用 `astro config set proxy.port <port>`；`.venv` 损坏则 `astro dev kill` 后 `astro dev start --standalone`
32. 环境损坏时重置：`astro dev kill` 然后 `astro dev start`
33. 升级 Airflow 前先测试兼容性：`astro dev upgrade-test`
34. 更改版本：编辑 `Dockerfile` 中的 `FROM quay.io/astronomer/astro-runtime:13.0.0`，然后 `astro dev kill && astro dev start`

适用边界 · 注意事项

• 项目初始化/依赖配置请用 setting-up-astro-project 技能
• 编写或测试 DAG 请用 authoring-dags / testing-dags 技能（需 Airflow 运行中）
• Standalone 模式不支持 Windows，且需要 Airflow 3 与 uv