troubleshooting-astro-deployments

Astro 部署故障排查

此技能可帮助你使用 Astro CLI 诊断和排查生产环境中的 Astronomer 部署问题。

有关部署管理，请参阅 managing-astro-deployments 技能。 有关本地开发，请参阅 managing-astro-local-env 技能。

---

快速健康检查

先运行以下命令，了解整体情况：

# 1. List deployments to find target
astro deployment list

# 2. Get deployment overview
astro deployment inspect <DEPLOYMENT_ID>

# 3. Check for errors
astro deployment logs <DEPLOYMENT_ID> --error -c 50

---

查看部署日志

使用 -c 控制日志数量（默认值：500）。日志标志不能组合使用——每条命令只能使用一个组件标志或级别标志。

组件特定日志

查看特定 Airflow 组件的日志：

# Scheduler logs (DAG processing, task scheduling)
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 50

# Worker logs (task execution)
astro deployment logs <DEPLOYMENT_ID> --workers -c 30

# Webserver logs (UI access, health checks)
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30

# Triggerer logs (deferrable operators)
astro deployment logs <DEPLOYMENT_ID> --triggerer -c 30

日志级别筛选

按严重性筛选：

# Error logs only (most useful for troubleshooting)
astro deployment logs <DEPLOYMENT_ID> --error -c 30

# Warning logs
astro deployment logs <DEPLOYMENT_ID> --warn -c 50

# Info-level logs
astro deployment logs <DEPLOYMENT_ID> --info -c 50

搜索日志

搜索特定关键词：

# Search for specific error
astro deployment logs <DEPLOYMENT_ID> --keyword "ConnectionError"

# Search for specific DAG
astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100

# Find import errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"

# Find task failures
astro deployment logs <DEPLOYMENT_ID> --error --keyword "Task failed"

---

完整排查工作流

步骤 1：确定问题

# List deployments with status
astro deployment list

# Get deployment details
astro deployment inspect <DEPLOYMENT_ID>

请检查：

• 状态：HEALTHY 还是 UNHEALTHY
• 运行时版本兼容性
• 资源限制（CPU、内存）
• 最近的部署时间戳

步骤 2：检查错误日志

# Start with errors
astro deployment logs <DEPLOYMENT_ID> --error -c 50

请检查：

• 重复出现的错误模式
• 反复失败的特定 DAG
• 导入错误或语法错误
• 连接或凭据错误

步骤 3：查看调度器日志

# Check DAG processing
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 30

请检查：

• DAG 解析错误
• 调度延迟
• 任务排队问题

步骤 4：检查 Worker 日志

# Check task execution
astro deployment logs <DEPLOYMENT_ID> --workers -c 30

请检查：

• 任务执行失败
• 资源耗尽
• 超时错误

步骤 5：验证配置

# Check environment variables
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# Verify deployment settings
astro deployment inspect <DEPLOYMENT_ID>

请检查：

• 缺失或不正确的环境变量
• 密钥配置（AIRFLOW__SECRETS__BACKEND）
• 连接配置

---

常见排查模式

DAG 反复失败

按照上述完整排查工作流操作，然后将范围缩小到特定 DAG：

astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100

资源问题

# 1. Check deployment resource allocation
astro deployment inspect <DEPLOYMENT_ID>
# Look for: resource_quota_cpu, resource_quota_memory
# Worker queue: max_worker_count, worker_type

# 2. Check for worker scaling issues
astro deployment logs <DEPLOYMENT_ID> --workers -c 50

# 3. Look for out-of-memory errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "memory"

配置问题

# 1. Review environment variables
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# 2. Check for secrets backend configuration
# Look for: AIRFLOW__SECRETS__BACKEND, AIRFLOW__SECRETS__BACKEND_KWARGS

# 3. Verify deployment settings
astro deployment inspect <DEPLOYMENT_ID>

# 4. Check webserver logs for auth issues
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30

导入错误

# 1. Find import errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"

# 2. Check scheduler for parse failures
astro deployment logs <DEPLOYMENT_ID> --scheduler --keyword "Failed to import" -c 50

# 3. Verify dependencies were deployed
astro deployment inspect <DEPLOYMENT_ID>
# Check: current_tag, last deployment timestamp

---

环境变量管理

列出变量

# List all variables for deployment
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# Find specific variable
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --key AWS_REGION

# Export variables to file
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --save --env .env.backup

创建变量

# Create regular variable
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
  --key API_ENDPOINT \
  --value https://api.example.com

# Create secret (masked in UI and logs)
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
  --key API_KEY \
  --value secret123 \
  --secret

更新变量

# Update existing variable
astro deployment variable update --deployment-id <DEPLOYMENT_ID> \
  --key API_KEY \
  --value newsecret

删除变量

# Delete variable
astro deployment variable delete --deployment-id <DEPLOYMENT_ID> --key OLD_KEY

注意：DAG 可将变量用作环境变量。更改无需重新部署。

---

deployment inspect 中的关键指标

排查问题时，请重点关注以下字段：

• status：HEALTHY 还是 UNHEALTHY
• runtime_version：Airflow 版本兼容性
• scheduler_size/scheduler_count：调度器容量
• executor：CELERY、KUBERNETES 或 LOCAL
• worker_queues：Worker 扩缩容限制和类型
  • min_worker_count、max_worker_count
  • worker_concurrency
  • worker_type（资源类别）
• resource_quota_cpu/memory：总体资源限制
• dag_deploy_enabled：是否支持仅部署 DAG
• current_tag：上次部署的版本
• is_high_availability：是否启用冗余

---

排查最佳实践

1. 始终从错误日志开始——最明显的故障通常会显示在这里
2. 检查错误日志中的模式——同一个 DAG 是否反复失败？是否存在时间规律？
3. 按组件进行故障排查：
   • Worker 日志 → 任务执行详情
   • 调度器日志 → DAG 处理和调度
   • Webserver 日志 → UI 问题和健康检查
   • Triggerer 日志 → 可延迟操作符问题
4. 使用 --keyword 进行定向搜索——比阅读所有日志更高效
5. 将 inspect 命令用作健康状况仪表板——先检查它
6. 查看 inspect 输出中的环境变量——它们可能揭示配置问题
7. 日志数量默认值为 500——根据需要使用 -c 调整
8. 别忘了检查部署时间——最近的部署可能引入了问题

---

故障排查速查表

症状	命令
部署显示为 UNHEALTHY	astro deployment inspect <ID> + --error 日志
DAG 未显示	查看 --error 日志中的导入错误，并检查 --scheduler 日志
任务失败	查看 --workers 日志 + 使用 --keyword 搜索 DAG
调度缓慢	查看 --scheduler 日志 + 使用 inspect 检查调度器资源
UI 无响应	查看 --webserver 日志
连接问题	检查变量，并在日志中搜索连接名称
导入错误	--error --keyword "ImportError" + 查看 --scheduler 日志
内存不足	使用 inspect 检查资源 + 使用 --workers --keyword "memory" 搜索

---

相关技能

• managing-astro-deployments：创建、更新和删除部署，部署代码
• managing-astro-local-env：管理本地 Airflow 开发环境
• setting-up-astro-project：初始化和配置 Astro 项目