1. Python 連 MySQL 報(bào) Timed out 的真實(shí)場(chǎng)景先說(shuō)結(jié)論Timed out在 Python 操作 MySQL 時(shí)絕大多數(shù)不是網(wǎng)絡(luò)斷了而是事務(wù)邊界沒(méi)管好。你寫(xiě)了一條select覺(jué)得讀操作不需要提交于是cursor.execute()之后直接conn.close()結(jié)果連接池里的連接一直掛著未結(jié)束的事務(wù)下一次復(fù)用就撞上Timed out。這個(gè)坑我在本地腳本和輕量服務(wù)里都踩過(guò)尤其是腳本跑批、定時(shí)任務(wù)這種「連一次、查一批、關(guān)掉」的寫(xiě)法。核心檢索詞先擺出來(lái)Python 操作 MySQL 報(bào) Timed out 怎么排查以及一個(gè)反直覺(jué)的點(diǎn)——select 也需要 commit。這兩件事其實(shí)是同一根繩上的兩端連接沒(méi)回收干凈事務(wù)沒(méi)結(jié)束超時(shí)只是表象。為什么select也要 commit因?yàn)?MySQL 的 InnoDB 默認(rèn)是**可重復(fù)讀REPEATABLE READ**隔離級(jí)別并且驅(qū)動(dòng)比如mysql-connector-python默認(rèn)autocommitFalse。這意味著你執(zhí)行任何 SQL包括select都會(huì)隱式開(kāi)啟一個(gè)事務(wù)。事務(wù)不提交快照就不釋放連接就一直處于「事務(wù)中」?fàn)顟B(tài)。你close()的只是客戶端游標(biāo)和連接對(duì)象服務(wù)端的會(huì)話可能還在Sleep或者持有元數(shù)據(jù)鎖。更隱蔽的是select ... for update。這條語(yǔ)句會(huì)加行鎖如果你不commit鎖一直不放別的連接來(lái)改同一行就卡住卡到innodb_lock_wait_timeout默認(rèn) 50 秒就報(bào)超時(shí)。很多人以為是網(wǎng)絡(luò)問(wèn)題其實(shí)是自己沒(méi)提交。還有一種典型場(chǎng)景DDL 語(yǔ)句ALTER TABLE超時(shí)?？蛻舳藪伭薕perationalError程序捕獲異常后close退出但你去數(shù)據(jù)庫(kù)show processlist一看那條ALTER還在跑狀態(tài)是Waiting for table metadata lock。因?yàn)?DDL 在服務(wù)端是獨(dú)立執(zhí)行的客戶端斷開(kāi)不代表它停了。等持有元數(shù)據(jù)鎖的那個(gè)事務(wù)一commitALTER反而執(zhí)行成功了。這就是 excerpt 里描述的現(xiàn)象本質(zhì)還是事務(wù)邊界問(wèn)題。所以這篇要解決三件事連接參數(shù)怎么配才不容易超時(shí)、autocommit和顯式commit到底怎么選、以及怎么用統(tǒng)一的 API 通道做連通性驗(yàn)證把「是網(wǎng)絡(luò)問(wèn)題還是事務(wù)問(wèn)題」快速區(qū)分開(kāi)。適合寫(xiě)本地腳本、跑定時(shí)任務(wù)、做輕量服務(wù)的同學(xué)不需要你懂 DBA 那套跟著配就行。2. TaoToken 前置統(tǒng)一 Key 與 API 通道做連通性驗(yàn)證排查T(mén)imed out最怕的就是「不知道是網(wǎng)絡(luò)層還是數(shù)據(jù)庫(kù)層」。我的做法是先把「外部 API 通道」這條鏈路單獨(dú)驗(yàn)證一遍確認(rèn)網(wǎng)絡(luò)出口、鑒權(quán)、超時(shí)配置都沒(méi)問(wèn)題再去查 MySQL 本身。這里用 TaoToken 做統(tǒng)一入口把 Key 和 API 通道收斂到一處省得每個(gè)腳本各配一套。TaoToken 是什么、能做什么它是一個(gè)統(tǒng)一的模型與 API 接入通道你申請(qǐng)一個(gè) Key就能通過(guò)統(tǒng)一的 Base URL 調(diào)用后端能力適合做連通性探測(cè)、腳本里的輔助調(diào)用、以及把多個(gè)服務(wù)的鑒權(quán)集中管理。適合誰(shuí)寫(xiě) Python 腳本、做輕量服務(wù)、需要頻繁驗(yàn)證「網(wǎng)絡(luò)通不通、Key 對(duì)不對(duì)」的開(kāi)發(fā)者。官網(wǎng)入口在這里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 這個(gè)不加 UTM。注意TaoToken 是合規(guī)的 API 接入通道不是任何形式的網(wǎng)絡(luò)代理工具我們只用它做接口連通性驗(yàn)證和統(tǒng)一鑒權(quán)。為什么排查 MySQL 超時(shí)要先驗(yàn)證 API 通道因?yàn)槌瑫r(shí)可能來(lái)自三個(gè)層次一是本機(jī)到外部的網(wǎng)絡(luò)出口被限速或阻斷二是鑒權(quán)失敗導(dǎo)致請(qǐng)求被拒三是目標(biāo)服務(wù)本身慢。如果你連一個(gè)簡(jiǎn)單的 API 請(qǐng)求都超時(shí)那 MySQL 的超時(shí)大概率跟數(shù)據(jù)庫(kù)無(wú)關(guān)先修網(wǎng)絡(luò)。反過(guò)來(lái)API 通道秒回MySQL 還超時(shí)那問(wèn)題就鎖定在數(shù)據(jù)庫(kù)連接或事務(wù)上。具體操作先去控制臺(tái)創(chuàng)建 Key。打開(kāi) https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登錄后進(jìn)入 API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 新建一個(gè) Key復(fù)制保存。這個(gè) Key 就是你后面所有腳本統(tǒng)一用的憑證。拿到 Key 之后先別急著寫(xiě) MySQL 代碼用一條最簡(jiǎn)單的請(qǐng)求驗(yàn)證通道。你可以用模型對(duì)話頁(yè)面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 手動(dòng)發(fā)一條消息看是否正常返回。如果這里就超時(shí)說(shuō)明你的網(wǎng)絡(luò)出口有問(wèn)題先解決這個(gè)別去折騰 MySQL。如果你是要做長(zhǎng)期編碼或 Agent 類(lèi)任務(wù)可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它把額度、Key、模型 ID 統(tǒng)一管理適合把驗(yàn)證腳本和業(yè)務(wù)腳本分開(kāi)跑。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到參數(shù)不確定就翻這里。這一步的目的不是讓你把 MySQL 換成 API而是建立一個(gè)「已知可用」的參照系。后面 MySQL 超時(shí)的時(shí)候你可以立刻對(duì)比API 通道正常那問(wèn)題在數(shù)據(jù)庫(kù)側(cè)API 通道也超時(shí)那問(wèn)題在網(wǎng)絡(luò)側(cè)。這個(gè)二分法能省掉大量瞎猜的時(shí)間。3. 可復(fù)制配置連接參數(shù)、autocommit 與顯式 commit這一節(jié)是重點(diǎn)直接給可復(fù)制的配置。先說(shuō)連接參數(shù)再說(shuō)autocommit和commit的選擇最后給一個(gè)完整的settings風(fēng)格片段。先看mysql-connector-python的連接參數(shù)。超時(shí)相關(guān)的關(guān)鍵參數(shù)有三個(gè)connection_timeout建立連接的超時(shí)秒、read_timeout讀超時(shí)、write_timeout寫(xiě)超時(shí)。很多人只配了connection_timeout結(jié)果查詢慢的時(shí)候照樣卡死。建議這樣配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, # 建連超時(shí) read_timeout: 30, # 讀超時(shí)防止查詢卡死 write_timeout: 30, # 寫(xiě)超時(shí) autocommit: False, # 關(guān)鍵默認(rèn)關(guān)閉自動(dòng)提交 charset: utf8mb4, use_pure: True, # 用純 Python 實(shí)現(xiàn)便于排查 } conn mysql.connector.connect(**config)autocommitFalse是默認(rèn)值但顯式寫(xiě)出來(lái)能提醒自己每條 SQL 之后都要考慮提交。如果你寫(xiě)的是只讀腳本最省心的做法是autocommitTrue這樣每條select執(zhí)行完自動(dòng)提交事務(wù)立刻結(jié)束連接不會(huì)掛著。代價(jià)是失去事務(wù)原子性多條寫(xiě)操作無(wú)法回滾。所以選擇邏輯是場(chǎng)景autocommit是否需要顯式 commit純只讀查詢腳本True不需要單條寫(xiě)操作True不需要多條寫(xiě)操作需原子性False需要成功則 commit異常則 rollbackselect ... for updateFalse必須 commit 或 rollback 釋放鎖DDLALTER/CREATE無(wú)所謂服務(wù)端獨(dú)立執(zhí)行客戶端斷開(kāi)也可能繼續(xù)如果你堅(jiān)持autocommitFalse那select之后也要commit。對(duì)讀操作也提交目的是結(jié)束事務(wù)、釋放快照。寫(xiě)法cursor conn.cursor(dictionaryTrue) try: cursor.execute(SELECT id, name FROM users WHERE id %s, (1,)) row cursor.fetchone() conn.commit() # 讀操作也提交結(jié)束事務(wù) print(row) except OperationalError as e: conn.rollback() print(OperationalError:, e) except InterfaceError as e: print(InterfaceError:, e) finally: cursor.close() conn.close()注意異常類(lèi)型的區(qū)別這是排障的關(guān)鍵信號(hào)OperationalError通常是 SQL 執(zhí)行超時(shí)或服務(wù)端問(wèn)題InterfaceError通常是連接被 KILL 或連接已斷開(kāi)。excerpt 里也提到客戶端 SQL 超時(shí)拋OperationalError連接被手動(dòng) KILL 拋InterfaceError。記住這個(gè)對(duì)應(yīng)關(guān)系看異常就知道往哪查。再給一個(gè)settings風(fēng)格的配置片段方便你直接抄進(jìn)項(xiàng)目。假設(shè)你用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 或類(lèi)似工具做輔助開(kāi)發(fā)配置里要寫(xiě)全三件套Base URL Key Model ID。Base URL 用https://taotoken.net/apiKey 用你在控制臺(tái)創(chuàng)建的Model ID 按文檔填。這三樣缺一個(gè)都會(huì)報(bào)鑒權(quán)或路由錯(cuò)誤。Claude Code 的接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的settings示例。最后強(qiáng)調(diào)一個(gè)連接回收的坑不要用全局單例連接跑所有查詢。連接長(zhǎng)時(shí)間Sleep會(huì)被服務(wù)端wait_timeout干掉下次用就報(bào)InterfaceError。正確做法是用連接池或者每次操作「建連-執(zhí)行-提交-關(guān)閉」。輕量腳本用后者更簡(jiǎn)單服務(wù)用連接池比如mysql.connector.pooling.MySQLConnectionPool并設(shè)置pool_reset_sessionTrue讓歸還的連接自動(dòng)重置會(huì)話狀態(tài)。4. 驗(yàn)證請(qǐng)求與成功結(jié)果從連通性到事務(wù)邊界配置寫(xiě)完得驗(yàn)證。驗(yàn)證分兩層先驗(yàn)證 API 通道通不通再驗(yàn)證 MySQL 事務(wù)邊界對(duì)不對(duì)。第一層用 Python 發(fā)一個(gè)請(qǐng)求到 TaoToken確認(rèn)網(wǎng)絡(luò)和 Key 沒(méi)問(wèn)題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 且有內(nèi)容說(shuō)明網(wǎng)絡(luò)出口、鑒權(quán)、超時(shí)都正常。如果這里就Timed out別往下走了先查本機(jī)網(wǎng)絡(luò)和防火墻。如果返回 401說(shuō)明 Key 不對(duì)回控制臺(tái)重新復(fù)制。這一步能幫你排除掉一大半「以為是數(shù)據(jù)庫(kù)問(wèn)題」的誤判。第二層驗(yàn)證 MySQL 事務(wù)邊界。寫(xiě)一個(gè)腳本故意不提交然后另開(kāi)一個(gè)連接看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 秒內(nèi)另開(kāi)窗口 show processlist conn.commit() cursor.close() conn.close()在sleep期間登錄 MySQL 執(zhí)行show processlist;你會(huì)看到這個(gè)連接的狀態(tài)是Sleep或者QueryTime在漲。這就證明了select 之后不 commit事務(wù)一直開(kāi)著。如果你此時(shí)在另一個(gè)連接執(zhí)行ALTER TABLE users ...就會(huì)看到Waiting for table metadata lock和 excerpt 里的現(xiàn)象一模一樣。成功的結(jié)果應(yīng)該是commit之后show processlist里那個(gè)連接的事務(wù)結(jié)束狀態(tài)回到SleepTime歸零。如果你用autocommitTrue則查詢一結(jié)束事務(wù)就沒(méi)了processlist里看不到長(zhǎng)時(shí)間掛著的連接。再驗(yàn)證一個(gè)select ... for update的鎖釋放conn1 mysql.connector.connect(**config) cur1 conn1.cursor() cur1.execute(SELECT * FROM users WHERE id 1 FOR UPDATE) # 此時(shí)不 commit行鎖持有 # 另開(kāi)連接嘗試更新同一行會(huì)阻塞 conn2 mysql.connector.connect(**config) cur2 conn2.cursor() cur2.execute(UPDATE users SET name test WHERE id 1) # 卡住如果你在conn1上commit()conn2的更新立刻通過(guò)。如果不提交conn2會(huì)一直等到innodb_lock_wait_timeout然后報(bào)Lock wait timeout exceeded。這個(gè)實(shí)驗(yàn)?zāi)茏屇阒庇^理解「select 也要 commit」不是玄學(xué)是鎖和事務(wù)的硬約束。驗(yàn)證通過(guò)后你的腳本應(yīng)該具備這些特征連接參數(shù)有超時(shí)、autocommit選擇明確、每條 SQL 后事務(wù)邊界清晰、異常類(lèi)型能區(qū)分OperationalError和InterfaceError。做到這幾點(diǎn)Timed out基本就絕跡了。5. 本篇常見(jiàn)錯(cuò)排查401、local proxy failed、reading choices、OAuth排障這節(jié)按真實(shí)報(bào)錯(cuò)來(lái)每個(gè)都給你定位方法和修復(fù)動(dòng)作。401 Unauthorized。這個(gè)最常見(jiàn)出現(xiàn)在 API 通道驗(yàn)證階段。原因就三個(gè)Key 沒(méi)填、Key 填錯(cuò)、Key 過(guò)期。修復(fù)回 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新復(fù)制注意別把前后空格帶進(jìn)去。如果你用的是 Claude Code 或 Cline 這類(lèi)工具檢查配置里的三件套是否齊全Base URL 是https://taotoken.net/apiKey 是sk-開(kāi)頭那串Model ID 按文檔填。缺 Model ID 有時(shí)也會(huì)報(bào)鑒權(quán)類(lèi)錯(cuò)誤別只盯著 Key。local proxy failed。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在工具嘗試走本地代理但代理沒(méi)起來(lái)的時(shí)候。注意我們這里不涉及任何網(wǎng)絡(luò)代理工具這個(gè)報(bào)錯(cuò)本身是工具配置問(wèn)題。修復(fù)檢查你的工具配置里是否誤填了http_proxy或https_proxy環(huán)境變量把它們清掉讓請(qǐng)求直連。在 Python 里可以這樣確認(rèn)import os print(os.environ.get(http_proxy)) print(os.environ.get(https_proxy))如果有值unset掉再跑。TaoToken 的 API 通道是直連的不需要任何代理配置。reading choices 相關(guān)報(bào)錯(cuò)。這個(gè)一般出現(xiàn)在解析 API 返回時(shí)返回體里沒(méi)有choices字段代碼卻去讀resp[choices][0]于是KeyError或IndexError。根因通常是請(qǐng)求失敗但沒(méi)檢查狀態(tài)碼直接解析了錯(cuò)誤響應(yīng)。修復(fù)先判斷resp.status_code再解析。寫(xiě)法if resp.status_code ! 200: print(請(qǐng)求失敗:, resp.status_code, resp.text) else: data resp.json() if choices in data: print(data[choices][0][message][content]) else: print(返回體無(wú) choices:, data)OAuth 相關(guān)報(bào)錯(cuò)。如果你用 Claude Code 或類(lèi)似工具配置里選了 OAuth 登錄方式但環(huán)境不支持就會(huì)報(bào) OAuth 失敗。修復(fù)改用 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 側(cè)的 Timed out 對(duì)照。如果你 API 通道驗(yàn)證通過(guò)MySQL 還超時(shí)按這個(gè)順序查先看異常類(lèi)型OperationalError查 SQL 是否慢、是否有鎖等待InterfaceError查連接是否被 KILL、是否超過(guò)wait_timeout。再看show processlist有沒(méi)有長(zhǎng)時(shí)間Sleep或Waiting for table metadata lock的連接。最后查事務(wù)邊界是不是select之后沒(méi)commit。這三步走完問(wèn)題基本定位。DDL 超時(shí)但服務(wù)端還在跑。這是 excerpt 里的經(jīng)典場(chǎng)景?？蛻舳薃LTER超時(shí)拋異常程序退出但服務(wù)端還在Waiting for table metadata lock。修復(fù)思路捕獲異常后用新連接找到那個(gè)會(huì)話 ID執(zhí)行KILL id。或者更根本的先確保沒(méi)有長(zhǎng)事務(wù)持有元數(shù)據(jù)鎖再執(zhí)行 DDL。DDL 本身在服務(wù)端是獨(dú)立執(zhí)行的客戶端斷開(kāi)不會(huì)自動(dòng)取消這點(diǎn)要記牢。6. 語(yǔ)義一致 CTA把 Key、通道、事務(wù)邊界一次理清回到開(kāi)頭那個(gè)問(wèn)題Timed out和select 也要 commit其實(shí)是同一件事的兩面。連接沒(méi)回收、事務(wù)沒(méi)結(jié)束超時(shí)只是最后的癥狀。你現(xiàn)在手里應(yīng)該有三樣?xùn)|西一套帶超時(shí)參數(shù)的連接配置、一個(gè)明確的autocommit選擇、以及用 TaoToken 統(tǒng)一 Key 和 API 通道做連通性驗(yàn)證的方法。下一步動(dòng)作按你的場(chǎng)景選如果你還在排障和接入階段先把 Key 建好、通道驗(yàn)證通。API Keys 頁(yè)面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 兩個(gè)頁(yè)面配合看配置不會(huì)錯(cuò)。如果你要驗(yàn)證模型返回、做接口聯(lián)調(diào)用模型對(duì)話頁(yè)面手動(dòng)發(fā)幾條消息確認(rèn)通道穩(wěn)定https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你是要長(zhǎng)期跑編碼任務(wù)或 Agent把額度、Key、模型 ID 統(tǒng)一管理看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后留一個(gè)我自己的習(xí)慣任何連數(shù)據(jù)庫(kù)的腳本第一行日志打印連接參數(shù)里的三個(gè)超時(shí)值第二行日志打印autocommit狀態(tài)。出問(wèn)題的時(shí)候這兩行日志能幫你省掉一半排查時(shí)間。事務(wù)邊界這件事配一次、記一次后面就順了。