如何正确调试docker-compose部署的Apache Airflow初始化故障

你之前用docker-compose up -d看不到有效报错的核心原因很明确：-d是后台运行参数，启动后容器内部所有的标准输出、错误输出都不会直接打印到当前终端；加--verbose参数只会打印Docker Compose本身的调度逻辑日志，根本不会输出容器内应用、命令的执行报错，自然拿不到有效调试信息。
Airflow部署后Webserver看不到DAG，90%以上的根因在Scheduler服务——DAG的解析、加载逻辑全由Scheduler负责，只要Scheduler启动失败、依赖没装完、DAG解析报错，Webserver端就不会展示任何DAG。按以下步骤排查即可：

1. 第一时间获取容器运行日志，不要用后台模式排查问题 #

排查阶段先停掉所有运行中的服务：

docker-compose down

直接以前台模式启动你怀疑异常的服务，所有运行日志、报错会直接打印在终端，比如你当前把pip依赖安装逻辑写在了Scheduler的启动命令里，直接前台启动Scheduler看实时输出：

docker-compose up scheduler

如果要同时看所有服务的启动输出，直接执行不带-d参数的docker-compose up即可，pip安装的报错、Airflow初始化的异常、数据库连接问题都会直接打印出来。
如果不想停掉已经后台启动的服务，用logs命令跟踪对应容器的输出即可，加-f参数实时刷新日志：

# 跟踪Scheduler实时日志
docker-compose logs -f scheduler
# 查看Scheduler最后100行日志，避免日志太多刷不到重点
docker-compose logs --tail=100 -f scheduler
# 先确认初始化服务有没有正常跑完，初始化失败后续所有服务都会异常
docker-compose logs init

2. 进入容器手动复现异常步骤 #

如果日志里看不到明确的报错点，直接进入运行中的容器手动执行对应命令复现问题：

1. 先查Scheduler的容器ID：docker ps
2. 进入容器交互终端：docker exec -it <替换成你的Scheduler容器ID> /bin/bash
3. 手动执行你写在启动命令里的依赖安装步骤，看具体报错：

   pip install -r /opt/airflow/env/requirements.txt
   

依赖安装失败的常见原因包括：pip源网络不通、依赖版本和当前Airflow版本冲突、容器内缺少对应系统编译依赖（比如安装MySQL Python驱动需要libmysqlclient-dev系统包）、requirements.txt路径挂载错误找不到文件。

3. 检查Airflow落盘的业务日志 #

你在配置里已经挂载了logs卷，Airflow运行时DAG解析报错、任务执行报错都会存在容器内/opt/airflow/logs/目录下，对应会映射到你宿主机的挂载路径。重点看scheduler子目录下最新的日志文件，里面会明确记录DAG解析失败的具体原因，比如依赖缺失、DAG语法错误、导入包失败等。

4. 优化启动逻辑减少黑盒问题 #

你当前把pip依赖安装和Scheduler启动拼在同一个启动命令的写法很容易增加排查难度：只要pip安装步骤失败，后续的Scheduler命令根本不会执行，容器会直接退出，而且pip的输出很容易被后续Airflow的日志冲掉。建议做如下调整：

• 尽量把依赖安装步骤放到镜像构建阶段，写自定义Dockerfile提前把所有依赖预装到镜像里，不要放在容器启动命令里执行。既可以避免每次启动容器重复装依赖，也能在镜像构建阶段就提前发现依赖安装错误，不会拖到服务启动时才出问题。
• 如果一定要在启动阶段装依赖，把安装日志单独输出到固定文件，安装完成后加pip check做依赖兼容性校验，校验失败直接打印明确错误再退出容器。
• 启动Scheduler前先执行airflow dags list做DAG解析校验，解析失败直接打印报错，不要静默启动。

高频初始化问题排查点 #

• 目录权限问题：Airflow官方镜像默认用UID为50000的非root用户运行，如果宿主机挂载的dags、logs、env目录权限配置不对，会出现读不到requirements.txt、读不到DAG文件、写不了日志的问题，直接表现就是服务启动异常、DAG不显示。
• 初始化服务未完成：Docker Compose部署栈里的init服务负责执行数据库迁移、创建默认账户、初始化连接信息，如果init服务异常退出，后续Webserver、Scheduler都会运行异常，优先排查init服务的日志确认初始化完成。
• 数据库连接异常：Scheduler和Webserver都需要正常连接Postgres元数据库，如果数据库连接不通，服务会一直处于重试状态，不会加载任何DAG。

内容的提问来源于stack exchange，提问作者kkpalczewski