1. 从一次本地能连、容器就崩的 pymysql 报错说起Python 连接 MySQL 这件事看起来就是pymysql.connect()一行代码但真正在项目里跑起来坑基本都集中在几个地方认证插件不匹配、字符集没对齐、超时设置缺失、连接池被打满。我最近就遇到一个特别典型的场景本地开发环境用 pymysql 连 MySQL 8.0 一切正常代码推到容器里跑直接抛pymysql.err.OperationalError: (1045, Access denied for user rootlocalhost (using password: NO))改完认证方式又变成(1043, Bad handshake)来回折腾了很久。这篇文章聚焦的就是 Python pymysql 连接 MySQL 的高频踩坑场景适合正在用 Python 做后端、数据脚本、定时任务或者刚把服务容器化的同学。我会把认证插件、字符集、超时、连接池耗尽这几类问题拆开讲给出可以直接复制的config.toml和settings.json骨架同时演示怎么用 TaoToken 统一 Key/API 通道来集中管理多个工具的凭据避免每个项目里散落一堆明文密码。目标很明确让你一次跑通本地和容器两套环境的连接。先说结论pymysql 本身不复杂复杂的是 MySQL 8.0 默认认证插件、容器网络、连接生命周期这三件事叠在一起。下面按「问题复现 → 统一凭据前置 → 可复制配置 → 验证动作 → 报错排查 → 凭据集中管理」的顺序走一遍。2. 先解决凭据散落问题TaoToken 统一 Key 与 API 通道在讲具体连接代码之前我想先聊一个容易被忽略但很致命的问题凭据管理。你可能有本地脚本、容器服务、CI 流水线、还有几个 AI 编码工具每个地方都写了一份 MySQL 密码或者 API Key。改一次密码要翻五六个文件。更麻烦的是容器里环境变量没注入对就会出现上面那种「using password: NO」的报错——不是密码错是根本没读到密码。TaoToken 在这里的角色是统一 Key/API 通道把多个工具、多个环境要用的凭据集中到一处管理通过统一的 API 通道下发或调用而不是在每个项目里硬编码。它的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你可以把它理解成一个凭据中转层本地、容器、CI 都从同一个地方拿配置减少「这个环境有、那个环境没有」的低级错误。具体操作上先去控制台创建 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 然后在 API Keys 页面生成密钥 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成之后不要直接写进代码而是放进配置文件或环境变量下面会给骨架。如果你只是想先验证模型通道是否通可以用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你是要长期做编码、跑 Agent 任务那更适合用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。ClaudeCode 相关的走这个 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意TaoToken 是凭据与 API 通道的统一管理层不是数据库本身。MySQL 连接还是走 pymysqlTaoToken 负责的是「Key 从哪来、怎么统一管」两者职责别混。3. 可复制的 config.toml 与 settings.json 骨架下面这套配置是我实际在用的结构把数据库连接参数和 TaoToken 凭据分开管理。config.toml放数据库和连接池参数settings.json放凭据引用代码里只读引用名不读明文。先看config.toml# config.toml [mysql] host 127.0.0.1 port 3306 user app_user database stu_system charset utf8mb4 connect_timeout 5 read_timeout 10 write_timeout 10 [mysql.pool] min_size 2 max_size 10 max_idle_seconds 300 acquire_timeout 3 [taotoken] api_base https://taotoken.net/api key_ref TAOTOKEN_API_KEY再看settings.json这里只放引用和环境映射不放真实密钥{ env: local, mysql: { password_ref: MYSQL_APP_PASSWORD, config_path: ./config.toml }, taotoken: { api_base: https://taotoken.net/api, api_key_ref: TAOTOKEN_API_KEY, console_url: https://taotoken.net/console }, container: { mysql_host_override: mysql, mysql_port_override: 3306 } }关键点在于password_ref和api_key_ref都是「引用名」真实值从环境变量或 TaoToken 控制台注入。本地开发时你在.env里填容器里用编排工具的环境变量注入CI 里用 secrets。这样本地和容器用的是同一套配置结构只是环境变量来源不同就不会出现「本地能连、容器报 using password: NO」这种问题。读取配置的代码骨架import os import json import tomllib # Python 3.113.10 及以下用 tomli def load_settings(path./settings.json): with open(path, r, encodingutf-8) as f: return json.load(f) def load_mysql_config(settings): with open(settings[mysql][config_path], rb) as f: cfg tomllib.load(f) mysql cfg[mysql] # 容器环境覆盖 host if os.getenv(APP_ENV) container: mysql[host] settings[container][mysql_host_override] mysql[port] settings[container][mysql_port_override] # 密码从环境变量取不落盘 mysql[password] os.environ[settings[mysql][password_ref]] return mysql这段代码解决了两件事一是容器里 host 自动从127.0.0.1切成服务名mysql二是密码永远从环境变量读配置文件里看不到明文。4. 三步验证从连接、查询到容器环境配置写好了接下来是验证。我把它拆成三步每步都有明确的成功标志出问题也能快速定位是哪一层。4.1 第一步裸连接验证认证插件先不搞连接池直接用 pymysql 连一次确认认证插件和密码没问题import pymysql conn pymysql.connect( host127.0.0.1, port3306, userapp_user, passwordyour_password, databasestu_system, charsetutf8mb4, connect_timeout5, ) with conn.cursor() as cur: cur.execute(SELECT VERSION()) print(MySQL version:, cur.fetchone()) conn.close()成功标志打印出MySQL version: (8.0.x,)。如果这里报1045 Access denied先别改代码去数据库确认两件事用户是否存在、认证插件是什么。查认证插件SELECT user, host, plugin FROM mysql.user WHERE user app_user;如果plugin是caching_sha2_password而你的 pymysql 版本较旧就可能握手失败。两种处理方式升级 pymysql 到较新版本或者把该用户改成mysql_native_password。我实测下来升级驱动是更省事的做法因为新版本 pymysql 已经支持caching_sha2_password。pip install --upgrade pymysql4.2 第二步带连接池和超时的完整验证裸连接通了之后加上连接池和超时参数模拟真实服务import pymysql from dbutils.pooled_db import PooledDB pool PooledDB( creatorpymysql, mincached2, maxcached10, maxconnections10, blockingTrue, ping1, host127.0.0.1, port3306, userapp_user, passwordyour_password, databasestu_system, charsetutf8mb4, connect_timeout5, read_timeout10, write_timeout10, ) conn pool.connection() with conn.cursor() as cur: cur.execute(SELECT 1) print(pool ok:, cur.fetchone()) conn.close()成功标志打印pool ok: (1,)。这里ping1很关键它会在取连接时检查连接是否存活避免拿到已经被 MySQL 断开的死连接。blockingTrue配合maxconnections控制并发上限防止连接池耗尽时直接抛异常。4.3 第三步容器环境验证容器里最容易出问题的是 host 和网络。假设你的 compose 服务名是mysql验证脚本改成从环境变量读import os import pymysql conn pymysql.connect( hostos.environ.get(MYSQL_HOST, mysql), portint(os.environ.get(MYSQL_PORT, 3306)), useros.environ[MYSQL_USER], passwordos.environ[MYSQL_APP_PASSWORD], databaseos.environ[MYSQL_DATABASE], charsetutf8mb4, connect_timeout5, ) with conn.cursor() as cur: cur.execute(SELECT 1) print(container ok:, cur.fetchone()) conn.close()成功标志容器日志里打印container ok: (1,)。如果报2003 Cant connect to MySQL server基本是 host 写成了127.0.0.1容器里的127.0.0.1是容器自己不是宿主机要改成服务名。5. 本篇常见报错对照与排查下面这张表是我踩过的坑和对应处理按报错信息查最快报错信息常见原因处理方式1045 Access denied ... (using password: NO)密码没读到环境变量未注入检查password_ref对应的环境变量是否存在1045 Access denied ... (using password: YES)密码错误或用户 host 不匹配确认用户host字段容器里可能是%而非localhost1043 Bad handshake驱动版本旧不支持caching_sha2_password升级 pymysql或改用户认证插件2003 Cant connect to MySQL serverhost/端口错容器网络不通容器里用服务名不用127.0.0.11366 Incorrect string value字符集不是utf8mb4连接和建表都用utf8mb42013 Lost connection during query超时或连接被服务端断开加read_timeout连接池开pingToo many connections连接池 max 过大或连接未归还限制maxconnections确保conn.close()几个排查要点单独说。第一using password: NO和using password: YES是两回事前者是没读到密码后者是读到了但不对别混着查。第二Bad handshake不一定是认证插件问题也可能是驱动和 MySQL 版本组合问题先升级驱动再改插件顺序别反。第三字符集问题往往在建表时就埋下了连接用utf8mb4但表是utf8存 emoji 就报1366建表语句也要统一。连接池耗尽这个坑比较隐蔽表现是请求变慢然后超时。核心是maxconnections要小于 MySQL 的max_connections并且每个取出的连接都要在finally里归还conn pool.connection() try: with conn.cursor() as cur: cur.execute(SELECT 1) finally: conn.close()6. 用 TaoToken 集中管理多工具凭据的收尾做法回到凭据管理这条线。当你有多个项目、多个环境、多个工具都要用 Key 时散落管理迟早出事。我的做法是所有 Key 统一在 TaoToken 控制台生成和管理项目里只保留引用名。控制台入口 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 生成在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。具体落地时本地.env、容器环境变量、CI secrets 三处都指向同一个引用名值从 TaoToken 拿。这样换 Key 只改一处不用翻代码。接入方式参考文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 长期编码任务用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 模型验证用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个实用技巧把「连接自检」做成服务启动时的一个步骤连不上就直接退出并打印明确原因而不是等第一个请求进来才报错。这样本地和容器环境的问题在启动阶段就暴露了省得后面排查半天。
