Airflow执行scheduler命令提示端口占用无法正常启动

这个问题是Airflow本地部署的常见问题，核心是8794（scheduler默认日志服务端口）被残留进程或内核TCP栈占用，按以下步骤逐一排查即可解决：

• 第一步：按端口精准定位占用进程，不要靠进程名搜索
  很多时候异常退出的scheduler会留下僵尸子进程、或者同属Airflow组件的triggerer/worker进程误占端口，这类进程用ps aux | grep scheduler搜不到，必须直接查端口关联的PID：
  • Linux/macOS执行：lsof -i :8794 或 ss -tulpn | grep 8794
  • Windows执行：netstat -ano | findstr :8794
    拿到返回结果里的PID后，直接强制终止进程：
  • Linux/macOS执行：kill -9 <对应PID>
  • Windows执行：taskkill /F /PID <对应PID>
    执行完再重新查询一次端口，确认端口释放后再启动scheduler即可。
• 第二步：处理TCP TIME_WAIT残留问题
  如果查端口时没有查到关联的用户态进程，但启动依然报端口占用，基本是之前scheduler异常崩溃时，TCP连接没有完成正常挥手，内核暂时把端口标记为占用状态（TIME_WAIT状态，默认会保留1-2分钟）：
  • 先验证状态：Linux下执行ss -tan | grep 8794，如果返回结果的状态列为TIME-WAIT即可确认
  • 临时解决可以等待2分钟等内核自动回收端口，也可以直接修改Airflow配置换端口：打开$AIRFLOW_HOME/airflow.cfg，找到[scheduler]配置段，把默认值为8794的serve_logs_port改成其他未占用端口（比如8795），保存后重新启动scheduler即可。
  • 本地开发环境可以通过开启内核端口复用永久规避这个问题：在/etc/sysctl.conf中添加配置net.ipv4.tcp_tw_reuse = 1，执行sysctl -p生效即可，生产环境不建议随意修改该内核参数。
• 第三步：特殊场景排查
  • 如果使用WSL2+Windows本地环境，大概率是WSL实例内部的进程占用了端口、或者WSL做了端口转发，宿主系统直接查进程搜不到，需要进入WSL终端内执行端口查询命令定位进程，临时关闭WSL测试也可以快速验证。
  • 如果本地运行了Docker容器，检查是否有映射了8794端口的容器在后台运行，这类容器进程如果没有挂载到当前终端的进程组，靠常规进程搜索也容易漏查，执行docker ps查看端口映射即可确认。
  • 检查本地安全防护软件、防火墙规则，部分安全工具会预留端口阻止新进程绑定，临时关闭防护软件后重试启动即可定位问题。

注意：不要靠删除scheduler.pid文件尝试解决这个问题，pid文件残留只会触发PID已存在的报错，和端口占用无关。

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