Django异步查询MySQL触发[4031]超时断开问题求助

问题背景 #

低流量站点采用Django 4.2 + MySQL 8.0.30，Nginx+Gunicorn（3 Worker）WSGI架构，在同步视图中通过asyncio.run调用异步ORM的afirst()方法，初始运行正常，但站点闲置约8小时后触发MySQL错误：[4031] The client was disconnected by the server because of inactivity，重启Nginx可临时恢复，已尝试多种Django/MySQL层面的配置调整但无效。

核心原因分析 #

WSGI是同步架构，直接用asyncio.run调用Django异步ORM时，会绕过Django原生的连接生命周期管理——同步连接管理逻辑（如close_old_connections()）无法作用于异步连接池，低流量下长期闲置的异步连接被MySQL主动回收，但Django未感知到连接失效，导致下次查询时报错。

解决方案 #

1. 异步上下文内手动管理连接 #

将连接健康检查、关闭/重建逻辑放到异步函数内部，直接操作异步连接对象：

import asyncio
from django.db import connections
from myapp.models import ModelExample

async def make_query(name):
    conn = connections['default']
    # 强制建立异步连接并检查可用性
    async with conn.async_connect():
        if not conn.is_usable():
            await conn.close()
            await conn.async_connect()
        obj = await ModelExample.objects.filter(name=name).afirst()
        return obj

example_object = asyncio.run(make_query(name))

说明：异步ORM使用独立的连接池，必须在异步上下文内手动处理连接健康，同步代码中的连接管理逻辑无法覆盖异步连接。

2. 使用Django官方同步转异步工具 #

替换asyncio.run为django.utils.asyncio.async_to_sync，它会自动适配Django的连接生命周期管理：

from django.utils.asyncio import async_to_sync
from myapp.models import ModelExample

async def make_query(name):
    obj = await ModelExample.objects.filter(name=name).afirst()
    return obj

# 用官方工具包装异步调用
example_object = async_to_sync(make_query)(name)

说明：async_to_sync是Django为WSGI环境适配异步代码的官方方案，会自动处理连接的打开、健康检查与关闭。

3. 禁用异步连接持久化 #

在数据库配置中强制关闭连接持久化，避免闲置连接被MySQL回收：

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'your_db',
        'USER': 'your_user',
        'PASSWORD': 'your_pwd',
        'HOST': 'localhost',
        'PORT': '3306',
        # 关闭持久连接，每次请求新建
        'CONN_MAX_AGE': 0,
        'OPTIONS': {
            'async': True,
            'connect_timeout': 10,
        },
    }
}

4. 配置Gunicorn自动重启Worker #

低流量下Gunicorn Worker可能长期持有无效连接，配置Worker自动重启机制：

# Gunicorn启动命令添加参数
gunicorn --workers 3 --max-requests 100 --max-requests-jitter 20 your_project.wsgi:application

说明：让Worker处理一定请求后自动重启，避免长期持有闲置连接。

调试思路 #

1. 追踪异步连接状态日志 #

在异步函数内添加连接状态日志，同时开启MySQL通用日志对比连接生命周期：

import logging
logger = logging.getLogger(__name__)

async def make_query(name):
    conn = connections['default']
    logger.info(f"异步连接ID: {conn.connection_id}, 是否可用: {conn.is_usable()}")
    # 执行查询前打印会话级超时配置
    timeout_result = await conn.execute("SHOW SESSION VARIABLES LIKE 'wait_timeout'")
    logger.info(f"会话wait_timeout: {timeout_result.fetchone()[1]}")
    # ... 查询逻辑

MySQL开启通用日志：在my.cnf中添加general_log = 1，重启MySQL后查看general_log_file记录的连接建立/断开时间，确认是否为MySQL主动回收连接。

2. 测试异步视图模式（若业务允许） #

将视图改为Django异步视图，让框架自动管理连接：

from django.http import HttpResponse
from myapp.models import ModelExample

async def my_view(request, name):
    obj = await ModelExample.objects.filter(name=name).afirst()
    return HttpResponse(f"查询结果: {obj}")

说明：Django 4.2支持WSGI环境下运行异步视图（通过线程池调度），连接管理会更规范。

3. 验证MySQL会话级超时配置 #

有些MySQL驱动会覆盖会话级的wait_timeout，需在Django异步代码中直接查询会话变量，确认是否与全局配置一致。

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