1. 从 2003 和 1045 说起py3 连 MySQL 到底卡在哪如果你用 Python3 连 MySQL十有八九见过这两个错误码(2003, Cant connect to MySQL server on xxx)和(1045, Access denied for user xxxxxx (using password: YES))。前者是网络层根本没握上手后者是握手成功但身份没通过。很多人第一反应是改密码、换端口、关防火墙折腾一圈还是原地打转因为问题往往不在 MySQL 本身而在连接参数的组织方式上。这篇内容面向正在用 pymysql 或 mysql-connector-python 做数据读写、被 2003/1045 反复打断的 Python 开发者。核心思路是把散落在代码里的 host、port、user、password 这些连接参数收敛到 TaoToken 统一 Key/API 通道来管理让连接配置有单一可信来源排查路径也从猜变成对照。TaoToken 在这里扮演的是统一接入与凭据管理入口官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先说清楚 2003 和 1045 的本质区别这决定了你该往哪个方向查。2003 属于连接建立阶段失败TCP 三次握手都没完成常见原因是 host 写错、端口不对、目标机器没监听、网络策略拦截。1045 属于认证阶段失败TCP 已经通了MySQL 服务也响应了但用户名密码或授权主机不匹配。把这两类错误混在一起查是最常见的踩坑方式。我试过在一个内网项目里代码里 host 写的是192.168.1.6、port 写的是3307本地跑没问题一上测试机就 2003。后来发现是测试机的网络策略只放通了标准端口非标端口被拦。这类问题靠改代码解决不了得靠统一的连接参数管理来暴露差异。所以本文的路线是先讲清楚问题场景和错误码语义再引入 TaoToken 统一通道做参数收敛然后给出可直接复制的配置片段接着用三步验证动作确认连通性、错误码对照和连接池复用最后把常见报错逐条对照排查末尾给出语义一致的入口分流。全程围绕 py3 连 mysql 这个具体动作不空谈架构。2. TaoToken 统一通道把连接参数从代码里抽出来2.1 为什么连接参数要统一管理传统写法是把 host、port、user、password 硬编码在pymysql.connect()里或者塞进一个config.py。项目小的时候没问题一旦有多套环境本地、测试、预发、生产、多个服务共用同一个数据库、多人协作参数就会散落各处。改一次密码要翻五个文件2003 和 1045 就会在不同环境里轮流出现。TaoToken 统一通道的价值在于把连哪个地址、用哪个凭据、走哪个模型或服务这件事集中到一个 Key 和一套 API 入口上。对于数据库连接场景你可以把连接参数的来源统一到 TaoToken 管理的配置里代码只负责读取不负责硬编码。这样排查 2003 时你只需要确认一件事TaoToken 通道里的 host/port 是不是当前环境该用的那一套。需要说明的是TaoToken 不是数据库本身也不替代 MySQL。它是一个统一接入与凭据管理通道帮你把连接参数、API Key、模型 ID 这些东西管起来。数据库还是你自己的 MySQL只是连接参数的来源变了。2.2 前置准备拿到统一 Key 和 API 入口在开始改代码之前你需要先准备好三样东西TaoToken 的 API Key、API 入口地址、以及你要连接的目标服务标识比如模型 ID 或数据库连接标识。API Key 的获取入口在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 控制台在 https://taotoken.net/console 。拿到 Key 之后不要直接写进代码。正确做法是放进环境变量或本地配置文件代码通过读取环境变量来获取。这样做的直接好处是2003 报错时你可以快速确认当前进程读到的 host 到底是什么而不是靠猜。# 把统一 Key 放进环境变量避免硬编码 export TAOTOKEN_API_KEY你的统一Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Windows PowerShell写法是$env:TAOTOKEN_API_KEY你的统一Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api2.3 连接参数收敛的三种落地方式第一种是环境变量方式适合容器和 CI 环境。第二种是本地配置文件方式适合开发机。第三种是配置中心方式适合多服务共用。三种方式的核心都是代码里不出现明文 host 和 password只出现从哪读。以本地配置文件为例你可以建一个taotoken.toml[mysql] host 192.168.1.6 port 3307 user root database hxjxequities # password 不写在这里从环境变量注入 [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY代码里用tomllibPython 3.11或tomli读取import tomllib import os with open(taotoken.toml, rb) as f: cfg tomllib.load(f) mysql_cfg cfg[mysql] password os.environ.get(MYSQL_PASSWORD)这样做的意义在于当 2003 出现时你可以直接打开taotoken.toml确认 host 和 port而不是在几百行代码里搜索connect(。当 1045 出现时你可以确认 password 环境变量是否注入成功而不是怀疑 MySQL 用户表。2.4 统一通道和数据库连接的关系这里要澄清一个容易混淆的点TaoToken 统一通道管理的是接入凭据和入口不是数据库连接池。你的 pymysql 连接依然直连你的 MySQL只是连接参数的来源被统一了。如果你用的是 TaoToken 提供的模型对话或 Coding Plan 能力那是另一条链路走的是 https://taotoken.net/api 下的模型接口。对于本文聚焦的 py3 连 mysql 场景TaoToken 的作用是让你有一个统一的 Key 和入口来管理连什么、用什么凭据从而在 2003/1045 出现时排查范围从整个项目缩小到统一配置里的几个字段。3. 可复制配置pymysql 与 mysql-connector 双版本3.1 pymysql 版本配置片段先给出一份可直接复制的 pymysql 连接配置。注意 host、port、user、password、database 全部从统一配置读取代码里不出现明文。# -*- coding: UTF-8 -*- import os import tomllib import pymysql from pymysql import err # 读取统一配置 with open(taotoken.toml, rb) as f: cfg tomllib.load(f) mysql_cfg cfg[mysql] # 从环境变量注入密码避免硬编码 password os.environ.get(MYSQL_PASSWORD) if not password: raise RuntimeError(MYSQL_PASSWORD 未注入请检查环境变量) try: db pymysql.connect( hostmysql_cfg[host], portmysql_cfg[port], usermysql_cfg[user], passwordpassword, databasemysql_cfg[database], charsetutf8mb4, connect_timeout5, read_timeout10, write_timeout10, ) except err.OperationalError as e: code e.args[0] if code 2003: print(2003连接建立失败检查 host/port/网络策略) elif code 1045: print(1045认证失败检查 user/password/授权主机) else: print(f其他错误码{code}详情{e}) raise else: with db.cursor() as cursor: cursor.execute(SELECT VERSION()) data cursor.fetchone() print(mysqldb version : %s % data) db.close()这份配置的关键点有三个connect_timeout显式设置避免 2003 卡住不返回错误码分支处理2003 和 1045 分开提示密码从环境变量读取不写进文件。3.2 mysql-connector-python 版本配置片段如果你用的是官方 mysql-connector-python配置结构略有不同但参数来源一致。# -*- coding: UTF-8 -*- import os import tomllib import mysql.connector from mysql.connector import errorcode with open(taotoken.toml, rb) as f: cfg tomllib.load(f) mysql_cfg cfg[mysql] password os.environ.get(MYSQL_PASSWORD) config { host: mysql_cfg[host], port: mysql_cfg[port], user: mysql_cfg[user], password: password, database: mysql_cfg[database], charset: utf8mb4, connection_timeout: 5, } try: cnx mysql.connector.connect(**config) except mysql.connector.Error as err: if err.errno errorcode.ER_ACCESS_DENIED_ERROR: print(1045用户名或密码错误) elif err.errno errorcode.ER_BAD_DB_ERROR: print(1049数据库不存在) elif err.errno 2003: print(2003无法连接检查 host/port) else: print(f错误码 {err.errno}{err.msg}) raise else: cursor cnx.cursor() cursor.execute(SELECT VERSION()) print(mysql-connector version : %s % cursor.fetchone()) cursor.close() cnx.close()3.3 连接池复用配置单次连接没问题不代表连接池没问题。连接池复用不当会引发连接已断开类错误表现上有时会被误判成 2003。下面给出 DBUtils 的 PooledDB 配置。# -*- coding: UTF-8 -*- import os import tomllib from dbutils.pooled_db import PooledDB import pymysql with open(taotoken.toml, rb) as f: cfg tomllib.load(f) mysql_cfg cfg[mysql] password os.environ.get(MYSQL_PASSWORD) pool PooledDB( creatorpymysql, maxconnections10, mincached2, maxcached5, blockingTrue, ping1, hostmysql_cfg[host], portmysql_cfg[port], usermysql_cfg[user], passwordpassword, databasemysql_cfg[database], charsetutf8mb4, connect_timeout5, ) def query_version(): conn pool.connection() try: with conn.cursor() as cursor: cursor.execute(SELECT VERSION()) return cursor.fetchone() finally: conn.close() if __name__ __main__: print(pooled version : %s % query_version())ping1是关键参数它让连接池在取连接时先 ping 一次避免拿到已断开的连接。blockingTrue保证池满时等待而不是直接抛异常。3.4 配置片段对照表参数pymysqlmysql-connector作用hosthosthost目标地址2003 首要排查项portportport目标端口非标端口易被拦useruseruser认证用户1045 首要排查项passwordpasswordpassword认证密码建议环境变量注入databasedatabasedatabase目标库不存在报 1049超时connect_timeoutconnection_timeout避免 2003 长时间挂起字符集charsetcharset建议 utf8mb4保活ping池需手动 ping避免复用断开连接4. 三步验证连通性、错误码、连接池复用4.1 第一步本地连通性测试在跑 Python 代码之前先用系统工具确认网络层通不通。这一步能直接把 2003 的范围缩小。# 测试端口是否可达Linux/macOS nc -zv 192.168.1.6 3307 # Windows 用 Test-NetConnection Test-NetConnection -ComputerName 192.168.1.6 -Port 3307如果这一步就失败说明 2003 是网络层问题跟 Python 代码无关。如果这一步成功但 Python 还是 2003那问题在 Python 进程的网络环境比如容器网络、代理设置。再用 MySQL 客户端确认认证层mysql -h 192.168.1.6 -P 3307 -u root -p -e SELECT VERSION();如果客户端能连上Python 连不上那问题在 Python 的驱动或参数。如果客户端也报 1045那问题在 MySQL 用户授权。4.2 第二步错误码对照把捕获到的错误码和含义对照避免误判。下面这张表覆盖了 py3 连 mysql 最常见的几个错误码。错误码含义首要排查方向2003无法连接到 MySQL 服务器host、port、网络策略、服务是否启动1045访问被拒绝user、password、授权主机userhost1049未知数据库database 名称拼写、库是否存在2006MySQL 服务器已断开连接空闲超时、wait_timeout 设置2013查询期间丢失连接网络抖动、max_allowed_packet 过小2059认证插件不兼容caching_sha2_password 与旧驱动2003 和 1045 的区别再强调一次2003 是门都没敲开1045 是门开了但你不让进。把这两个混在一起查是最浪费时间的做法。4.3 第三步连接池复用确认连接池的问题往往在运行一段时间后才暴露。验证方法是连续取多次连接确认每次都能正常查询。# -*- coding: UTF-8 -*- import time def verify_pool(pool, rounds5): for i in range(rounds): conn pool.connection() try: with conn.cursor() as cursor: cursor.execute(SELECT 1) result cursor.fetchone() print(f第 {i1} 次取连接结果{result}) finally: conn.close() time.sleep(1) if __name__ __main__: verify_pool(pool)如果某一次取连接报 2006 或 2013说明连接池保活没做好需要调大ping或检查 MySQL 的wait_timeout。如果每次都报 2003说明池配置里的 host/port 和单次连接不一致回到统一配置里核对。4.4 验证结果说明三步验证都通过后你应该看到nc返回 succeededmysql客户端返回版本号Python 单次连接返回版本号连接池连续 5 次返回(1,)。任何一步失败都对应到上面的错误码表按方向排查。这套验证动作的价值在于它把连不上这个模糊描述拆成了网络层、认证层、复用层三个可独立确认的环节。2003 和 1045 不再是黑盒而是有明确归属的故障点。5. 常见报错逐条排查401、local proxy failed、reading choices、OAuth5.1 401 与 1045 的区别401 是 HTTP 语义的未授权通常出现在调用 TaoToken API 或模型接口时不是 MySQL 的错误码。如果你在 py3 连 mysql 的过程中看到 401说明你的代码里混入了 HTTP 请求逻辑比如用 requests 调了某个接口。排查方法是确认报错来自哪一行如果是pymysql.connect()那不会出现 401如果是requests.post()那要检查 API Key 是否正确注入。import os import requests api_key os.environ.get(TAOTOKEN_API_KEY) if not api_key: raise RuntimeError(TAOTOKEN_API_KEY 未注入) headers {Authorization: fBearer {api_key}} resp requests.get(https://taotoken.net/api, headersheaders, timeout10) print(resp.status_code)如果这里返回 401说明 Key 无效或格式不对。注意 Bearer 后面有一个空格这是最常见的低级错误。5.2 local proxy failed 的排查local proxy failed通常出现在本地代理配置异常时。如果你在环境变量里设置了HTTP_PROXY或HTTPS_PROXY而代理进程没启动就会出现这个报错。排查方法是检查环境变量# Linux/macOS env | grep -i proxy # Windows PowerShell Get-ChildItem Env: | Where-Object { $_.Name -like *PROXY* }如果发现代理变量指向一个不存在的地址清掉它unset HTTP_PROXY unset HTTPS_PROXY然后重新跑连接测试。注意这里说的是清理无效的本地代理配置不是让你去配置任何网络工具。保持环境干净让连接直连目标地址。5.3 reading choices 报错的定位reading choices这类报错通常出现在解析 API 响应时比如期望 JSON 但拿到了 HTML 错误页。如果你在调用模型接口时看到它说明响应体不是预期的结构。排查方法是打印原始响应resp requests.post( https://taotoken.net/api, headersheaders, json{model: your-model-id, messages: [{role: user, content: hi}]}, timeout30, ) print(status:, resp.status_code) print(content-type:, resp.headers.get(content-type)) print(body:, resp.text[:500])先看 status 和 content-type再看 body 前 500 字符。如果 content-type 是 text/html说明请求打到了错误的地址检查 Base URL 是否写成了https://taotoken.net/api而不是其他路径。5.4 OAuth 相关报错OAuth 报错通常出现在使用 Claude Code 或类似工具时凭据过期或未登录。如果你在 py3 项目里集成了这类工具报错信息里会出现 OAuth 字样。排查方法是确认凭据文件是否存在且未过期。对于 Claude Code 场景配置需要写全三件套Base URL、Key、Model ID。Base URL 用https://taotoken.net/apiKey 用你的统一 KeyModel ID 用你在控制台看到的模型标识。三者缺一不可缺任何一个都会导致认证类报错。5.5 CC Switch / Cline MCP / Codex auth.json 三件套如果你用 CC Switch 或 Cline MCP 这类工具配置里必须写全 Base URL、Key、Model ID。以 Codex 的auth.json为例结构大致如下{ base_url: https://taotoken.net/api, api_key: 你的统一Key, model: your-model-id }注意base_url不要带末尾斜杠api_key不要带 Bearer 前缀具体以工具文档为准model要和你在控制台看到的标识一致。三件套写全之后OAuth 类报错通常会消失。5.6 排查顺序建议遇到报错时按这个顺序排查先看错误码是 2003 还是 1045确定是网络层还是认证层再看是不是混入了 HTTP 请求导致的 401然后检查环境变量里有没有无效代理最后确认三件套是否写全。这个顺序能覆盖绝大多数 py3 连 mysql 场景下的报错。6. 按场景分流排障、验证、长期编码各走各的入口6.1 排障和接入场景如果你正在被 2003 或 1045 卡住需要的是 API Key 和接入文档。API Key 入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。先把 Key 拿到再对照文档把 Base URL 和 Model ID 填对三件套齐了再跑连接测试。6.2 验证模型场景如果你已经配好了连接想确认模型能不能正常响应用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。在这里发一条测试消息确认返回正常再回到代码里跑。6.3 长期编码和 Agent 场景如果你是要长期做编码、跑 Agent 任务用 Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这个入口适合需要持续调用、有配额管理需求的场景。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以在这里查看用量和 Key 状态。6.4 一个实用技巧把连接参数统一到 TaoToken 通道之后建议在项目里加一个启动自检脚本每次启动时先跑一遍三步验证。这样 2003 和 1045 会在启动阶段就暴露而不是等到业务逻辑跑到一半才报错。自检脚本可以直接复用第 4 节的代码加一个if __name__ __main__入口即可。最后提醒一点连接参数的统一管理核心目的是让排查有据可依。2003 查 host/port1045 查 user/password401 查 Key各归各的。把这条线理清楚py3 连 mysql 的报错就不再是玄学。
