Docker中gunicorn运行的Flask应用挂死、报WORKER TIMEOUT如何解决？

一、优先修复脚本隐性错误 #

你当前boot.sh首行声明为#!/bin/sh，但脚本中使用了仅bash支持的[[ ]]条件判断语法，Alpine默认的sh解释器为ash，存在隐性兼容问题，修改首行：

#!/bin/bash

同时移除启动脚本中不必要的数据库迁移操作：flask db init仅首次初始化数据库需要执行，flask db migrate用于本地生成迁移文件，不应该在容器启动阶段执行，会导致重复操作数据库引发连接异常，修改后的启动阶段数据库逻辑为：

while true; do
    flask db upgrade
    if [[ "$?" == "0" ]]; then
        break
    fi
    echo Deploy command failed, retrying in 5 secs...
    sleep 5
done

二、解决Gunicorn worker超时核心问题 #

1. 修复数据库/缓存长连接僵死问题 #

该问题是闲置超时的最常见诱因：闲置阶段数据库、Redis等服务端主动断开了空闲的长连接，应用侧连接池未配置自动重连逻辑，新请求到来时worker会阻塞等待僵死的连接返回，最终触发Gunicorn超时。

• 若使用SQLAlchemy，配置以下参数：

  SQLALCHEMY_ENGINE_OPTIONS = {
      "pool_pre_ping": True,
      "pool_recycle": 300, # 小于数据库的wait_timeout配置，通常MySQL默认是8小时
      "pool_size": 10,
      "max_overflow": 20
  }
  

• Redis、MongoDB、BigTable等其他存储客户端，统一配置连接心跳、自动重连参数，开启socket保活。

2. 更换Gunicorn异步worker模型 #

默认同步worker在遇到IO密集型请求时极易被阻塞，更换为gevent异步worker：

• 修改Dockerfile中Gunicorn安装语句，新增gevent依赖：

  RUN venv/bin/pip install gunicorn gevent pymysql
  

• 修改boot.sh中Gunicorn启动参数，调整超时时间、worker数量和worker类型：

  exec gunicorn -b 0.0.0.0:5000 \
    --worker-class gevent \
    --workers $((2*$(nproc)+1)) \ # 按CPU核心数自动计算worker数量，也可手动指定固定值
    --timeout 120 \
    --access-logfile - \
    --error-logfile - \
    main:app
  

3. 修复Docker网络保活问题 #

bridge网络默认会清理长时间无流量的连接，配置容器TCP保活参数：

• 容器启动命令新增sysctl参数：

  docker run --sysctl net.ipv4.tcp_keepalive_time=120 \
    --sysctl net.ipv4.tcp_keepalive_intvl=30 \
    --sysctl net.ipv4.tcp_keepalive_probes=3 \
    --network diagnosticator-net \
    # 其他原有启动参数
  

  也可临时用--network=host启动测试，如果host网络下无超时问题即可确认是bridge网络的保活问题。

4. 排查资源占用问题 #

执行docker stats查看容器运行时CPU、内存占用，执行docker inspect <容器ID> | grep OOM确认是否存在OOM杀掉进程的情况，如果是资源不足导致的超时，扩容容器资源或优化应用内存占用即可。

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