1. Python 连 MySQL 报 Timed out 的真实场景先说结论Timed out在 Python 操作 MySQL 时绝大多数不是网络断了而是事务边界没管好。你写了一条select觉得读操作不需要提交于是cursor.execute()之后直接conn.close()结果连接池里的连接一直挂着未结束的事务下一次复用就撞上Timed out。这个坑我在本地脚本和轻量服务里都踩过尤其是脚本跑批、定时任务这种「连一次、查一批、关掉」的写法。核心检索词先摆出来Python 操作 MySQL 报 Timed out 怎么排查以及一个反直觉的点——select 也需要 commit。这两件事其实是同一根绳上的两端连接没回收干净事务没结束超时只是表象。为什么select也要 commit因为 MySQL 的 InnoDB 默认是**可重复读REPEATABLE READ**隔离级别并且驱动比如mysql-connector-python默认autocommitFalse。这意味着你执行任何 SQL包括select都会隐式开启一个事务。事务不提交快照就不释放连接就一直处于「事务中」状态。你close()的只是客户端游标和连接对象服务端的会话可能还在Sleep或者持有元数据锁。更隐蔽的是select ... for update。这条语句会加行锁如果你不commit锁一直不放别的连接来改同一行就卡住卡到innodb_lock_wait_timeout默认 50 秒就报超时。很多人以为是网络问题其实是自己没提交。还有一种典型场景DDL 语句ALTER TABLE超时。客户端抛了OperationalError程序捕获异常后close退出但你去数据库show processlist一看那条ALTER还在跑状态是Waiting for table metadata lock。因为 DDL 在服务端是独立执行的客户端断开不代表它停了。等持有元数据锁的那个事务一commitALTER反而执行成功了。这就是 excerpt 里描述的现象本质还是事务边界问题。所以这篇要解决三件事连接参数怎么配才不容易超时、autocommit和显式commit到底怎么选、以及怎么用统一的 API 通道做连通性验证把「是网络问题还是事务问题」快速区分开。适合写本地脚本、跑定时任务、做轻量服务的同学不需要你懂 DBA 那套跟着配就行。2. TaoToken 前置统一 Key 与 API 通道做连通性验证排查Timed out最怕的就是「不知道是网络层还是数据库层」。我的做法是先把「外部 API 通道」这条链路单独验证一遍确认网络出口、鉴权、超时配置都没问题再去查 MySQL 本身。这里用 TaoToken 做统一入口把 Key 和 API 通道收敛到一处省得每个脚本各配一套。TaoToken 是什么、能做什么它是一个统一的模型与 API 接入通道你申请一个 Key就能通过统一的 Base URL 调用后端能力适合做连通性探测、脚本里的辅助调用、以及把多个服务的鉴权集中管理。适合谁写 Python 脚本、做轻量服务、需要频繁验证「网络通不通、Key 对不对」的开发者。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 这个不加 UTM。注意TaoToken 是合规的 API 接入通道不是任何形式的网络代理工具我们只用它做接口连通性验证和统一鉴权。为什么排查 MySQL 超时要先验证 API 通道因为超时可能来自三个层次一是本机到外部的网络出口被限速或阻断二是鉴权失败导致请求被拒三是目标服务本身慢。如果你连一个简单的 API 请求都超时那 MySQL 的超时大概率跟数据库无关先修网络。反过来API 通道秒回MySQL 还超时那问题就锁定在数据库连接或事务上。具体操作先去控制台创建 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 新建一个 Key复制保存。这个 Key 就是你后面所有脚本统一用的凭证。拿到 Key 之后先别急着写 MySQL 代码用一条最简单的请求验证通道。你可以用模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 手动发一条消息看是否正常返回。如果这里就超时说明你的网络出口有问题先解决这个别去折腾 MySQL。如果你是要做长期编码或 Agent 类任务可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它把额度、Key、模型 ID 统一管理适合把验证脚本和业务脚本分开跑。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数不确定就翻这里。这一步的目的不是让你把 MySQL 换成 API而是建立一个「已知可用」的参照系。后面 MySQL 超时的时候你可以立刻对比API 通道正常那问题在数据库侧API 通道也超时那问题在网络侧。这个二分法能省掉大量瞎猜的时间。3. 可复制配置连接参数、autocommit 与显式 commit这一节是重点直接给可复制的配置。先说连接参数再说autocommit和commit的选择最后给一个完整的settings风格片段。先看mysql-connector-python的连接参数。超时相关的关键参数有三个connection_timeout建立连接的超时秒、read_timeout读超时、write_timeout写超时。很多人只配了connection_timeout结果查询慢的时候照样卡死。建议这样配import mysql.connector from mysql.connector import InterfaceError, OperationalError config { host: 127.0.0.1, port: 3306, user: app_user, password: your_password, database: app_db, connection_timeout: 10, # 建连超时 read_timeout: 30, # 读超时防止查询卡死 write_timeout: 30, # 写超时 autocommit: False, # 关键默认关闭自动提交 charset: utf8mb4, use_pure: True, # 用纯 Python 实现便于排查 } conn mysql.connector.connect(**config)autocommitFalse是默认值但显式写出来能提醒自己每条 SQL 之后都要考虑提交。如果你写的是只读脚本最省心的做法是autocommitTrue这样每条select执行完自动提交事务立刻结束连接不会挂着。代价是失去事务原子性多条写操作无法回滚。所以选择逻辑是场景autocommit是否需要显式 commit纯只读查询脚本True不需要单条写操作True不需要多条写操作需原子性False需要成功则 commit异常则 rollbackselect ... for updateFalse必须 commit 或 rollback 释放锁DDLALTER/CREATE无所谓服务端独立执行客户端断开也可能继续如果你坚持autocommitFalse那select之后也要commit。对读操作也提交目的是结束事务、释放快照。写法cursor conn.cursor(dictionaryTrue) try: cursor.execute(SELECT id, name FROM users WHERE id %s, (1,)) row cursor.fetchone() conn.commit() # 读操作也提交结束事务 print(row) except OperationalError as e: conn.rollback() print(OperationalError:, e) except InterfaceError as e: print(InterfaceError:, e) finally: cursor.close() conn.close()注意异常类型的区别这是排障的关键信号OperationalError通常是 SQL 执行超时或服务端问题InterfaceError通常是连接被 KILL 或连接已断开。excerpt 里也提到客户端 SQL 超时抛OperationalError连接被手动 KILL 抛InterfaceError。记住这个对应关系看异常就知道往哪查。再给一个settings风格的配置片段方便你直接抄进项目。假设你用config/settings.toml[mysql] host 127.0.0.1 port 3306 user app_user password your_password database app_db connection_timeout 10 read_timeout 30 write_timeout 30 autocommit false charset utf8mb4 [taotoken] base_url https://taotoken.net/api api_key sk-你的Key model_id 你的模型ID如果你用 Claude Code 或类似工具做辅助开发配置里要写全三件套Base URL Key Model ID。Base URL 用https://taotoken.net/apiKey 用你在控制台创建的Model ID 按文档填。这三样缺一个都会报鉴权或路由错误。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的settings示例。最后强调一个连接回收的坑不要用全局单例连接跑所有查询。连接长时间Sleep会被服务端wait_timeout干掉下次用就报InterfaceError。正确做法是用连接池或者每次操作「建连-执行-提交-关闭」。轻量脚本用后者更简单服务用连接池比如mysql.connector.pooling.MySQLConnectionPool并设置pool_reset_sessionTrue让归还的连接自动重置会话状态。4. 验证请求与成功结果从连通性到事务边界配置写完得验证。验证分两层先验证 API 通道通不通再验证 MySQL 事务边界对不对。第一层用 Python 发一个请求到 TaoToken确认网络和 Key 没问题import requests resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{ Authorization: Bearer sk-你的Key, Content-Type: application/json, }, json{ model: 你的模型ID, messages: [{role: user, content: ping}], }, timeout15, ) print(resp.status_code) print(resp.json())如果返回 200 且有内容说明网络出口、鉴权、超时都正常。如果这里就Timed out别往下走了先查本机网络和防火墙。如果返回 401说明 Key 不对回控制台重新复制。这一步能帮你排除掉一大半「以为是数据库问题」的误判。第二层验证 MySQL 事务边界。写一个脚本故意不提交然后另开一个连接看processlistimport mysql.connector import time conn mysql.connector.connect( host127.0.0.1, port3306, userapp_user, passwordyour_password, databaseapp_db, autocommitFalse, ) cursor conn.cursor() cursor.execute(SELECT * FROM users LIMIT 1) print(查询完成但先不提交) time.sleep(20) # 这 20 秒内另开窗口 show processlist conn.commit() cursor.close() conn.close()在sleep期间登录 MySQL 执行show processlist;你会看到这个连接的状态是Sleep或者QueryTime在涨。这就证明了select 之后不 commit事务一直开着。如果你此时在另一个连接执行ALTER TABLE users ...就会看到Waiting for table metadata lock和 excerpt 里的现象一模一样。成功的结果应该是commit之后show processlist里那个连接的事务结束状态回到SleepTime归零。如果你用autocommitTrue则查询一结束事务就没了processlist里看不到长时间挂着的连接。再验证一个select ... for update的锁释放conn1 mysql.connector.connect(**config) cur1 conn1.cursor() cur1.execute(SELECT * FROM users WHERE id 1 FOR UPDATE) # 此时不 commit行锁持有 # 另开连接尝试更新同一行会阻塞 conn2 mysql.connector.connect(**config) cur2 conn2.cursor() cur2.execute(UPDATE users SET name test WHERE id 1) # 卡住如果你在conn1上commit()conn2的更新立刻通过。如果不提交conn2会一直等到innodb_lock_wait_timeout然后报Lock wait timeout exceeded。这个实验能让你直观理解「select 也要 commit」不是玄学是锁和事务的硬约束。验证通过后你的脚本应该具备这些特征连接参数有超时、autocommit选择明确、每条 SQL 后事务边界清晰、异常类型能区分OperationalError和InterfaceError。做到这几点Timed out基本就绝迹了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障这节按真实报错来每个都给你定位方法和修复动作。401 Unauthorized。这个最常见出现在 API 通道验证阶段。原因就三个Key 没填、Key 填错、Key 过期。修复回 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新复制注意别把前后空格带进去。如果你用的是 Claude Code 或 Cline 这类工具检查配置里的三件套是否齐全Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 按文档填。缺 Model ID 有时也会报鉴权类错误别只盯着 Key。local proxy failed。这个报错通常出现在工具尝试走本地代理但代理没起来的时候。注意我们这里不涉及任何网络代理工具这个报错本身是工具配置问题。修复检查你的工具配置里是否误填了http_proxy或https_proxy环境变量把它们清掉让请求直连。在 Python 里可以这样确认import os print(os.environ.get(http_proxy)) print(os.environ.get(https_proxy))如果有值unset掉再跑。TaoToken 的 API 通道是直连的不需要任何代理配置。reading choices 相关报错。这个一般出现在解析 API 返回时返回体里没有choices字段代码却去读resp[choices][0]于是KeyError或IndexError。根因通常是请求失败但没检查状态码直接解析了错误响应。修复先判断resp.status_code再解析。写法if resp.status_code ! 200: print(请求失败:, resp.status_code, resp.text) else: data resp.json() if choices in data: print(data[choices][0][message][content]) else: print(返回体无 choices:, data)OAuth 相关报错。如果你用 Claude Code 或类似工具配置里选了 OAuth 登录方式但环境不支持就会报 OAuth 失败。修复改用 API Key 方式把 Base URL、Key、Model ID 三件套填全。Claude Code 的接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有 API Key 模式的完整配置照着填就行。别混用 OAuth 和 Key二选一。MySQL 侧的 Timed out 对照。如果你 API 通道验证通过MySQL 还超时按这个顺序查先看异常类型OperationalError查 SQL 是否慢、是否有锁等待InterfaceError查连接是否被 KILL、是否超过wait_timeout。再看show processlist有没有长时间Sleep或Waiting for table metadata lock的连接。最后查事务边界是不是select之后没commit。这三步走完问题基本定位。DDL 超时但服务端还在跑。这是 excerpt 里的经典场景。客户端ALTER超时抛异常程序退出但服务端还在Waiting for table metadata lock。修复思路捕获异常后用新连接找到那个会话 ID执行KILL id。或者更根本的先确保没有长事务持有元数据锁再执行 DDL。DDL 本身在服务端是独立执行的客户端断开不会自动取消这点要记牢。6. 语义一致 CTA把 Key、通道、事务边界一次理清回到开头那个问题Timed out和select 也要 commit其实是同一件事的两面。连接没回收、事务没结束超时只是最后的症状。你现在手里应该有三样东西一套带超时参数的连接配置、一个明确的autocommit选择、以及用 TaoToken 统一 Key 和 API 通道做连通性验证的方法。下一步动作按你的场景选如果你还在排障和接入阶段先把 Key 建好、通道验证通。API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 两个页面配合看配置不会错。如果你要验证模型返回、做接口联调用模型对话页面手动发几条消息确认通道稳定https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你是要长期跑编码任务或 Agent把额度、Key、模型 ID 统一管理看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后留一个我自己的习惯任何连数据库的脚本第一行日志打印连接参数里的三个超时值第二行日志打印autocommit状态。出问题的时候这两行日志能帮你省掉一半排查时间。事务边界这件事配一次、记一次后面就顺了。