1. 长驻线程里的 2013 报错到底卡在哪Django 项目用 pymysql 连 MySQL跑一段时间后定时任务或常驻线程突然抛Lost connection to MySQL server during query错误码 2013。这个报错本身不神秘它说的是你手里这个 TCP 连接在真正发 SQL 的那一刻已经被 MySQL 服务端单方面关掉了客户端却还以为它活着。MySQL 有个wait_timeout默认常见 28800 秒也就是 8 小时和interactive_timeout空闲超过这个时间的连接会被服务端回收。Web 请求场景下 Django 每个请求结束会走close_old_connections连接被及时归还或重建所以很少撞上。但定时任务、threading.Thread起的常驻线程、Celery worker 里的长循环它们不经过请求生命周期连接一挂就是几小时下一次执行 SQL 时直接踩雷。这篇要解决的就是这条链路先讲清close_old_connections和连接池的机制再给一份可复制的settings.json/config.toml骨架把数据库连接配置和 TaoToken 统一 Key 的接入示例放在一起最后用复现报错、验证连接恢复的具体动作帮你建立一条稳定的排查路径。适合正在被 2013 折磨的 Django 后端也适合想把 AI 调用和数据库配置统一管理的团队。2. 先把 TaoToken 的 Key 和接入点准备好排查这类问题经常需要一边翻日志、一边让模型帮你读 traceback、生成修复代码。如果每个工具都单独配一套 Key管理成本会很高。TaoToken 的思路是给你一个统一的 Key兼容 OpenAI 风格的接口模型对话、编码 Agent、控制台管理都走同一个入口。你需要先拿到 Key再决定用在哪。三个入口按用途分模型对话临时问报错、贴 traceback 让模型分析https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan长期在 IDE / Agent 里改 Django 代码https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI Keys 管理生成、轮换 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API 基址是https://taotoken.net/api这个地址不加 UTM 参数直接用于代码里的 base_url。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。注意Key 只放在环境变量或本地配置文件里不要提交进 Git。下面给的config.toml骨架里Key 字段留空用环境变量注入。3. 可复制的配置骨架settings.json 与 config.toml3.1 Django 侧 settings.json 片段把数据库连接参数和连接健康检查相关的配置集中管理避免散落在settings.py各处。下面这份settings.json是给配置加载器读的骨架字段名按你的加载逻辑调整即可。{ database: { ENGINE: django.db.backends.mysql, NAME: your_db, USER: your_user, PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, CONN_MAX_AGE: 0, OPTIONS: { charset: utf8mb4, connect_timeout: 10, read_timeout: 30, write_timeout: 30 } }, taotoken: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model: gpt-4o-mini } }关键点解释CONN_MAX_AGE设为 0 表示每个请求结束后关闭连接这是 Web 请求场景下最省心的做法但常驻线程不吃这套所以还要配合close_old_connections。connect_timeout和read_timeout是 pymysql 支持的参数能避免连接卡死时无限等待。3.2 config.toml 骨架如果你更习惯 TOML这份等价[database] engine django.db.backends.mysql name your_db user your_user password your_password host 127.0.0.1 port 3306 conn_max_age 0 [database.options] charset utf8mb4 connect_timeout 10 read_timeout 30 write_timeout 30 [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini3.3 在 settings.py 里加载并注入import json import os from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent with open(BASE_DIR / settings.json, r, encodingutf-8) as f: _cfg json.load(f) DATABASES { default: { ENGINE: _cfg[database][ENGINE], NAME: _cfg[database][NAME], USER: _cfg[database][USER], PASSWORD: _cfg[database][PASSWORD], HOST: _cfg[database][HOST], PORT: _cfg[database][PORT], CONN_MAX_AGE: _cfg[database][CONN_MAX_AGE], OPTIONS: _cfg[database][OPTIONS], } } TAOTOKEN_BASE_URL _cfg[taotoken][base_url] TAOTOKEN_API_KEY os.environ.get(_cfg[taotoken][api_key_env], )4. 让连接不再失效close_old_connections 与 create_cursor 覆盖4.1 方案一在长驻任务前调用 close_old_connectionsDjango 的close_old_connections会遍历所有数据库连接检查is_usable()不可用就关闭下次用的时候重新建。它不判断空闲多久只判断当前是否还能用所以放在每次数据库操作前调用最稳。from django.db import close_old_connections def long_running_task(): while True: close_old_connections() # 这里再执行 ORM 操作 from myapp.models import Task Task.objects.filter(statuspending).update(statusrunning) time.sleep(60)如果你用的是 Celery可以在task_prerun信号里统一挂上避免每个任务都手写from celery.signals import task_prerun from django.db import close_old_connections task_prerun.connect def _close_old_conn(**kwargs): close_old_connections()4.2 方案二覆盖 create_cursor让每次取 cursor 前 ping 一次Django 所有 model 操作最终都会走到DatabaseWrapper.create_cursor。pymysql 的connection.ping(reconnectTrue)会检测连接断了就重连。把这两件事绑在一起等于给每次查询加了一道保险。在项目某个 App 的__init__.py或专门的db_patch.py里写import pymysql pymysql.version_info (1, 4, 13, final, 0) pymysql.install_as_MySQLdb() from django.db.backends.mysql.base import CursorWrapper, DatabaseWrapper from django.utils import asyncio def create_cursor(self, nameNone): self.connection.ping(reconnectTrue) cursor self.connection.cursor() return CursorWrapper(cursor) DatabaseWrapper.create_cursor asyncio.async_unsafe(create_cursor)然后在settings.py顶部或manage.py里 import 这个模块确保补丁在 Django 初始化数据库前生效。实测下来这个方案对定时任务和常驻线程都有效代价是每次查询多一次 ping 往返QPS 极高的场景要评估。注意ping(reconnectTrue)在连接已断时会重建连接但重建后 Django 的连接状态需要同步所以补丁要放在DatabaseWrapper层面而不是自己另起一个连接。4.3 连接池视角什么时候该上池CONN_MAX_AGE大于 0 时Django 会复用连接但复用的连接同样可能被服务端回收。如果你用django-db-connection-pool或 SQLAlchemy 池要确认池的pool_recycle小于 MySQL 的wait_timeout否则池里拿出来的还是死连接。一个常见配置是pool_recycle28000比默认wait_timeout28800小一点留出安全边界。5. 验证请求复现报错并确认连接恢复5.1 先复现 2013把 MySQL 的wait_timeout临时调小方便快速复现SET GLOBAL wait_timeout 10; SET GLOBAL interactive_timeout 10;然后跑一个不调用close_old_connections的脚本import time import django import os os.environ.setdefault(DJANGO_SETTINGS_MODULE, myproject.settings) django.setup() from myapp.models import Task Task.objects.count() print(first query ok) time.sleep(15) Task.objects.count() print(second query ok)第二次查询大概率抛pymysql.err.OperationalError: (2013, Lost connection to MySQL server during query)。这就是你要的复现。5.2 加上修复后再跑在两次查询之间插入close_old_connections()或者启用create_cursor补丁再跑一遍。第二次查询应该正常返回日志里能看到 pymysql 重连的痕迹。如果还是报错检查补丁是否在django.setup()之前 import 生效。5.3 用 TaoToken 辅助读 traceback把完整 traceback 贴到模型对话里让它帮你定位是哪一层连接失效import os from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是 Django 数据库排障助手只输出可执行的修复步骤。}, {role: user, content: 报错pymysql.err.OperationalError: (2013, Lost connection to MySQL server during query)场景是 Celery 长驻 worker。}, ], ) print(resp.choices[0].message.content)返回结果会给出close_old_connections和ping(reconnectTrue)的具体落点和你上面手动做的对得上相当于多一个交叉验证。6. 本篇常见错排查补丁没生效create_cursor覆盖必须在 Django 加载数据库后端之前执行。放在settings.py里 import 最稳放在manage.py里要注意 import 顺序。ping 太频繁拖慢查询每次取 cursor 都 pingQPS 高时开销明显。折中做法是只在长驻任务入口调用close_old_connectionsWeb 请求路径不动。CONN_MAX_AGE 设太大设成 600 秒以上但 MySQLwait_timeout只有 300 秒连接在池里就死了。让CONN_MAX_AGE或pool_recycle小于wait_timeout。多线程共享连接Django 的数据库连接是线程局部的但如果你手动把 connection 对象传给别的线程会出问题。每个线程自己走 ORM别共享 connection。Key 相关报错如果 TaoToken 调用返回 401先确认TAOTOKEN_API_KEY环境变量已导出再检查 base_url 是不是https://taotoken.net/api。Key 的生成和轮换在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。验证模型是否通想快速确认 Key 能用直接去模型对话页发一条消息比写脚本快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期编码场景如果你要在 IDE 或 Agent 里持续改 Django 代码用 Coding Plan 更合适不用每次手动贴 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个我踩过的坑close_old_connections放在循环里调用时别放在try/except的except分支里否则连接已经坏了才去关等于没关。放在每次数据库操作之前才是正确姿势。
1. 长驻线程里的 2013 报错到底卡在哪Django 项目用 pymysql 连 MySQL跑一段时间后定时任务或常驻线程突然抛Lost connection to MySQL server during query错误码 2013。这个报错本身不神秘它说的是你手里这个 TCP 连接在真正发 SQL 的那一刻已经被 MySQL 服务端单方面关掉了客户端却还以为它活着。MySQL 有个wait_timeout默认常见 28800 秒也就是 8 小时和interactive_timeout空闲超过这个时间的连接会被服务端回收。Web 请求场景下 Django 每个请求结束会走close_old_connections连接被及时归还或重建所以很少撞上。但定时任务、threading.Thread起的常驻线程、Celery worker 里的长循环它们不经过请求生命周期连接一挂就是几小时下一次执行 SQL 时直接踩雷。这篇要解决的就是这条链路先讲清close_old_connections和连接池的机制再给一份可复制的settings.json/config.toml骨架把数据库连接配置和 TaoToken 统一 Key 的接入示例放在一起最后用复现报错、验证连接恢复的具体动作帮你建立一条稳定的排查路径。适合正在被 2013 折磨的 Django 后端也适合想把 AI 调用和数据库配置统一管理的团队。2. 先把 TaoToken 的 Key 和接入点准备好排查这类问题经常需要一边翻日志、一边让模型帮你读 traceback、生成修复代码。如果每个工具都单独配一套 Key管理成本会很高。TaoToken 的思路是给你一个统一的 Key兼容 OpenAI 风格的接口模型对话、编码 Agent、控制台管理都走同一个入口。你需要先拿到 Key再决定用在哪。三个入口按用途分模型对话临时问报错、贴 traceback 让模型分析https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan长期在 IDE / Agent 里改 Django 代码https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI Keys 管理生成、轮换 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API 基址是https://taotoken.net/api这个地址不加 UTM 参数直接用于代码里的 base_url。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。注意Key 只放在环境变量或本地配置文件里不要提交进 Git。下面给的config.toml骨架里Key 字段留空用环境变量注入。3. 可复制的配置骨架settings.json 与 config.toml3.1 Django 侧 settings.json 片段把数据库连接参数和连接健康检查相关的配置集中管理避免散落在settings.py各处。下面这份settings.json是给配置加载器读的骨架字段名按你的加载逻辑调整即可。{ database: { ENGINE: django.db.backends.mysql, NAME: your_db, USER: your_user, PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, CONN_MAX_AGE: 0, OPTIONS: { charset: utf8mb4, connect_timeout: 10, read_timeout: 30, write_timeout: 30 } }, taotoken: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model: gpt-4o-mini } }关键点解释CONN_MAX_AGE设为 0 表示每个请求结束后关闭连接这是 Web 请求场景下最省心的做法但常驻线程不吃这套所以还要配合close_old_connections。connect_timeout和read_timeout是 pymysql 支持的参数能避免连接卡死时无限等待。3.2 config.toml 骨架如果你更习惯 TOML这份等价[database] engine django.db.backends.mysql name your_db user your_user password your_password host 127.0.0.1 port 3306 conn_max_age 0 [database.options] charset utf8mb4 connect_timeout 10 read_timeout 30 write_timeout 30 [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini3.3 在 settings.py 里加载并注入import json import os from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent with open(BASE_DIR / settings.json, r, encodingutf-8) as f: _cfg json.load(f) DATABASES { default: { ENGINE: _cfg[database][ENGINE], NAME: _cfg[database][NAME], USER: _cfg[database][USER], PASSWORD: _cfg[database][PASSWORD], HOST: _cfg[database][HOST], PORT: _cfg[database][PORT], CONN_MAX_AGE: _cfg[database][CONN_MAX_AGE], OPTIONS: _cfg[database][OPTIONS], } } TAOTOKEN_BASE_URL _cfg[taotoken][base_url] TAOTOKEN_API_KEY os.environ.get(_cfg[taotoken][api_key_env], )4. 让连接不再失效close_old_connections 与 create_cursor 覆盖4.1 方案一在长驻任务前调用 close_old_connectionsDjango 的close_old_connections会遍历所有数据库连接检查is_usable()不可用就关闭下次用的时候重新建。它不判断空闲多久只判断当前是否还能用所以放在每次数据库操作前调用最稳。from django.db import close_old_connections def long_running_task(): while True: close_old_connections() # 这里再执行 ORM 操作 from myapp.models import Task Task.objects.filter(statuspending).update(statusrunning) time.sleep(60)如果你用的是 Celery可以在task_prerun信号里统一挂上避免每个任务都手写from celery.signals import task_prerun from django.db import close_old_connections task_prerun.connect def _close_old_conn(**kwargs): close_old_connections()4.2 方案二覆盖 create_cursor让每次取 cursor 前 ping 一次Django 所有 model 操作最终都会走到DatabaseWrapper.create_cursor。pymysql 的connection.ping(reconnectTrue)会检测连接断了就重连。把这两件事绑在一起等于给每次查询加了一道保险。在项目某个 App 的__init__.py或专门的db_patch.py里写import pymysql pymysql.version_info (1, 4, 13, final, 0) pymysql.install_as_MySQLdb() from django.db.backends.mysql.base import CursorWrapper, DatabaseWrapper from django.utils import asyncio def create_cursor(self, nameNone): self.connection.ping(reconnectTrue) cursor self.connection.cursor() return CursorWrapper(cursor) DatabaseWrapper.create_cursor asyncio.async_unsafe(create_cursor)然后在settings.py顶部或manage.py里 import 这个模块确保补丁在 Django 初始化数据库前生效。实测下来这个方案对定时任务和常驻线程都有效代价是每次查询多一次 ping 往返QPS 极高的场景要评估。注意ping(reconnectTrue)在连接已断时会重建连接但重建后 Django 的连接状态需要同步所以补丁要放在DatabaseWrapper层面而不是自己另起一个连接。4.3 连接池视角什么时候该上池CONN_MAX_AGE大于 0 时Django 会复用连接但复用的连接同样可能被服务端回收。如果你用django-db-connection-pool或 SQLAlchemy 池要确认池的pool_recycle小于 MySQL 的wait_timeout否则池里拿出来的还是死连接。一个常见配置是pool_recycle28000比默认wait_timeout28800小一点留出安全边界。5. 验证请求复现报错并确认连接恢复5.1 先复现 2013把 MySQL 的wait_timeout临时调小方便快速复现SET GLOBAL wait_timeout 10; SET GLOBAL interactive_timeout 10;然后跑一个不调用close_old_connections的脚本import time import django import os os.environ.setdefault(DJANGO_SETTINGS_MODULE, myproject.settings) django.setup() from myapp.models import Task Task.objects.count() print(first query ok) time.sleep(15) Task.objects.count() print(second query ok)第二次查询大概率抛pymysql.err.OperationalError: (2013, Lost connection to MySQL server during query)。这就是你要的复现。5.2 加上修复后再跑在两次查询之间插入close_old_connections()或者启用create_cursor补丁再跑一遍。第二次查询应该正常返回日志里能看到 pymysql 重连的痕迹。如果还是报错检查补丁是否在django.setup()之前 import 生效。5.3 用 TaoToken 辅助读 traceback把完整 traceback 贴到模型对话里让它帮你定位是哪一层连接失效import os from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是 Django 数据库排障助手只输出可执行的修复步骤。}, {role: user, content: 报错pymysql.err.OperationalError: (2013, Lost connection to MySQL server during query)场景是 Celery 长驻 worker。}, ], ) print(resp.choices[0].message.content)返回结果会给出close_old_connections和ping(reconnectTrue)的具体落点和你上面手动做的对得上相当于多一个交叉验证。6. 本篇常见错排查补丁没生效create_cursor覆盖必须在 Django 加载数据库后端之前执行。放在settings.py里 import 最稳放在manage.py里要注意 import 顺序。ping 太频繁拖慢查询每次取 cursor 都 pingQPS 高时开销明显。折中做法是只在长驻任务入口调用close_old_connectionsWeb 请求路径不动。CONN_MAX_AGE 设太大设成 600 秒以上但 MySQLwait_timeout只有 300 秒连接在池里就死了。让CONN_MAX_AGE或pool_recycle小于wait_timeout。多线程共享连接Django 的数据库连接是线程局部的但如果你手动把 connection 对象传给别的线程会出问题。每个线程自己走 ORM别共享 connection。Key 相关报错如果 TaoToken 调用返回 401先确认TAOTOKEN_API_KEY环境变量已导出再检查 base_url 是不是https://taotoken.net/api。Key 的生成和轮换在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。验证模型是否通想快速确认 Key 能用直接去模型对话页发一条消息比写脚本快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期编码场景如果你要在 IDE 或 Agent 里持续改 Django 代码用 Coding Plan 更合适不用每次手动贴 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个我踩过的坑close_old_connections放在循环里调用时别放在try/except的except分支里否则连接已经坏了才去关等于没关。放在每次数据库操作之前才是正确姿势。
