Gunicorn 返回 502 问题解析

Gunicorn 返回 502

在使用以下命令启动 Django 应用时，应用某些接口出现了 502：

gunicorn --workers=3 --worker-class=gevent --bind=0.0.0.0:80 xxx.wsgi:application

可能导致 502 错误的原因

0. Worker 超时：

   • Gunicorn 工作进程处理请求时间超过配置的超时时间
   • 默认超时是 30 秒，可以通过 --timeout 参数调整

1. Worker 异常崩溃：

   • Python 代码抛出未捕获的异常
   • 内存泄漏导致 worker 进程被操作系统终止
   • 特别是使用 gevent 作为 worker 类时，某些阻塞操作可能导致问题

2. Worker 进程重启期间：

   • 当所有 worker 进程同时重启或不可用时
   • 特别是只有 3 个 worker 的情况下，负载高时更容易发生

3. 上游服务问题：

   • Django 应用依赖的其他服务（数据库、Redis、外部 API）响应超时
   • 数据库连接池耗尽

4. 资源限制：

   • 服务器 CPU 或内存资源不足
   • 文件描述符限制达到上限

排查方法

添加以下配置检查 502 错误：

gunicorn --workers=3 --worker-class=gevent --bind=0.0.0.0:80 \
  --timeout=60 \
  --log-level=debug \
  --error-logfile=gunicorn-error.log \
  --access-logfile=gunicorn-access.log \
  --capture-output \
  xxx.wsgi:application

检查是否存在代码中长时间运行的操作，尤其是在 Django 视图或中间件中，可能会超出 worker 超时限制。

可以考虑增加 worker 数量（建议为 CPU 核心数的 2-4 倍）以提高并发处理能力。

建议尝试：使用监控工具如 Prometheus + Grafana 监控 Gunicorn 的性能指标，及早发现潜在问题。

如何开启 Gunicorn debug 模式

方法 1: 使用 --log-level=debug 参数

gunicorn --workers=3 --worker-class=gevent --bind=0.0.0.0:80 \
  --log-level=debug \
  xxx.wsgi:application

方法 2: 启用详细日志和错误输出

gunicorn --workers=3 --worker-class=gevent --bind=0.0.0.0:80 \
  --log-level=debug \
  --access-logfile=- \
  --error-logfile=- \
  --capture-output \
  xxx.wsgi:application

方法 3: 使用配置文件

创建 gunicorn_config.py 文件:

# gunicorn_config.py
bind = "0.0.0.0:80"
workers = 3
worker_class = "gevent"
loglevel = "debug"
accesslog = "-"
errorlog = "-"
capture_output = True
spew = True  # 非常详细的调试输出，生产环境慎用

然后使用配置文件启动:

gunicorn -c gunicorn_config.py xxx.wsgi:application

方法 4: 开启重载功能以便开发调试

gunicorn --workers=3 --worker-class=gevent --bind=0.0.0.0:80 \
  --log-level=debug \
  --reload \
  xxx.wsgi:application

--reload 参数会在代码变更时自动重启 workers，适合开发环境使用。

注意事项

0. 调试模式会产生大量日志，生产环境谨慎使用
1. 对于 502 错误特别关注，可以添加 --timeout 参数增加请求超时时间
2. 使用 --access-logfile 和 --error-logfile 将日志保存到文件便于分析

Gunicorn 异步工作方式与超时机制解析

异步工作机制详解

0. 阻塞 I/O vs 非阻塞 I/O:

   • 当使用 gevent 工作类时，Gunicorn 会通过猴子补丁(monkey patching)将标准库中的阻塞 I/O 操作替换为非阻塞版本
   • gevent 基于协程，通过事件循环来管理 I/O 操作

1. 超时判定条件:

   • Gunicorn 不是简单地计算请求总处理时间
   • 它监控的是"工作线程没有向事件循环让出控制权"的时间

技术原理

当使用 gevent，Gunicorn 的超时计时器会在以下情况重置:

• 每当工作协程让出控制权给事件循环
• 网络 I/O 操作自动让出控制权
• CPU 密集操作不会自动让出，需手动使用 gevent.sleep(0) 让出