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