1. Linux 下 Python 连 MySQL 的真实痛点在 Linux 上写 Python 操作 MySQL本身并不复杂装个pymysqlconnect()一下cursor()一开SQL 一执行数据就回来了。真正让人头疼的是工程化落地这一步。你本地可能同时跑着好几个 AI 工具一个用来补全代码一个用来做代码审查还有一个 Agent 在后台跑任务。每个工具都要配 Key、配 Base URL、配模型名散落在.bashrc、.env、IDE 插件设置、项目config.toml里改一次要翻五个地方。更麻烦的是数据库连接信息也在到处复制。host、port、user、password写死在脚本里换台机器就得重新改一遍密码还容易跟着代码提交到仓库。这篇就聚焦 Linux 环境下 Python 连接 MySQL 的工程化落地用一份可复制的config.toml配置骨架把数据库连接参数和 AI 工具的 Key 统一收口再通过 TaoToken 的统一 Key 接入让多工具共用一套凭证。适合需要统一管理多 AI 工具 Key、又想让 Python 脚本干净可维护的开发者。下面从配置骨架开始一步步跑通最小验证脚本最后给一份报错排查清单。2. TaoToken 前置统一 Key 与配置骨架设计TaoToken 在这里扮演的角色是统一凭证入口。你不需要给每个 AI 工具单独申请一套 Key而是用同一个 Key 去访问不同的模型能力。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。注意TaoToken 是正规的 API 聚合服务不是所谓的中转所有请求都走标准 HTTP 接口。配置骨架的核心思路是把「连接什么」和「用什么凭证」分开。数据库连接参数放[mysql]段AI 工具凭证放[taotoken]段Python 脚本只读配置不硬编码任何敏感信息。这样你在 Linux 上换环境、换机器只需要替换config.toml一个文件。先看目录结构建议这样组织project/ ├── config.toml ├── db.py ├── verify.py └── requirements.txtconfig.toml的骨架如下可以直接复制# config.toml —— 统一配置骨架 [mysql] host 127.0.0.1 port 3306 database jing_dong user root password your_mysql_password charset utf8mb4 [taotoken] api_key sk-你的TaoTokenKey base_url https://taotoken.net/api model claude-3-5-sonnet [app] debug true timeout 10这里有几个设计点值得说明。charset用utf8mb4而不是utf8因为 MySQL 的utf8实际只支持三字节存 emoji 或部分生僻字会报错utf8mb4才是真正的四字节 UTF-8。base_url指向 TaoToken 的 API 入口后面 Python 侧调用模型时直接读这个值。api_key单独放一段方便你后续换成环境变量注入。注意config.toml不要提交到 Git。在.gitignore里加上config.toml或者用config.example.toml做模板真实文件本地保留。如果你还没有 Key可以去 API Keys 页面创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后把 Key 填进config.toml的api_key字段。想先确认模型通道是否正常可以用模型对话页面发一条测试消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。3. 可复制配置Python 读取 config.toml 并连接 MySQLPython 3.11 之后标准库自带tomllib可以直接解析 TOML不需要额外装toml包。先确认你的 Python 版本python3 --version如果低于 3.11用pip install tomli并import tomli as tomllib。下面写一个db.py负责读配置和建立连接# db.py import tomllib from pathlib import Path import pymysql CONFIG_PATH Path(__file__).parent / config.toml def load_config(): with open(CONFIG_PATH, rb) as f: return tomllib.load(f) def get_connection(): cfg load_config()[mysql] return pymysql.connect( hostcfg[host], portcfg[port], databasecfg[database], usercfg[user], passwordcfg[password], charsetcfg[charset], cursorclasspymysql.cursors.DictCursor, )注意tomllib.load需要二进制模式打开文件所以是rb而不是r这是新手最容易踩的坑之一。cursorclass设成DictCursor后查询结果返回字典而不是元组字段名直接可读调试时省事很多。安装依赖pip install pymysql如果你在 Linux 上遇到pymysql装不上通常是 pip 版本太旧先python3 -m pip install --upgrade pip。MySQL 服务端本身不需要额外 Python 驱动pymysql是纯 Python 实现不依赖 C 库这也是它在 Linux 上比mysqlclient更好装的原因。接下来写最小验证脚本verify.py把「连数据库」和「读 TaoToken 配置」两件事都验证一遍# verify.py from db import get_connection, load_config def main(): # 1. 验证 MySQL 连接 conn get_connection() try: with conn.cursor() as cur: cur.execute(SELECT VERSION() AS v) row cur.fetchone() print(MySQL 版本:, row[v]) cur.execute(SHOW DATABASES) dbs [list(r.values())[0] for r in cur.fetchall()] print(数据库列表:, dbs) finally: conn.close() # 2. 验证 TaoToken 配置读取 cfg load_config()[taotoken] print(TaoToken base_url:, cfg[base_url]) print(TaoToken model:, cfg[model]) print(Key 前缀:, cfg[api_key][:6] ****) if __name__ __main__: main()运行python3 verify.py预期输出类似MySQL 版本: 8.0.36 数据库列表: [information_schema, jing_dong, mysql, performance_schema, sys] TaoToken base_url: https://taotoken.net/api TaoToken model: claude-3-5-sonnet Key 前缀: sk-abc****看到 MySQL 版本号和数据库列表说明数据库通道通了看到 TaoToken 的base_url和 Key 前缀说明配置读取正常。这两步都过配置骨架就算跑通了。4. 验证请求参数化查询与事务提交配置通了之后重点看 Python 操作 MySQL 的几个关键动作。先建一张测试表# create_table.py from db import get_connection conn get_connection() try: with conn.cursor() as cur: cur.execute( CREATE TABLE IF NOT EXISTS goods_cates ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64) NOT NULL ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 ) conn.commit() print(建表完成) finally: conn.close()插入数据时一定要用参数化不要用字符串拼接。下面是对比# 错误示范字符串拼接有 SQL 注入风险 name 硬盘 sql fINSERT INTO goods_cates(name) VALUES({name}) # 正确示范参数化%s 占位 sql INSERT INTO goods_cates(name) VALUES(%s) cur.execute(sql, [name])参数化查询的%s是pymysql的占位符不是 Python 的字符串格式化。多个参数就传列表cur.execute(sql, [v1, v2])。这样 MySQL 驱动会把参数和 SQL 分开传输从根本上杜绝注入。插入、更新、删除之后必须commit()否则数据不会真正落库。Python 的数据库操作默认开启事务pymysql也一样。查询则不需要 commit直接fetchone()或fetchall()# query_demo.py from db import get_connection conn get_connection() try: with conn.cursor() as cur: cur.execute(INSERT INTO goods_cates(name) VALUES(%s), [机械硬盘]) cur.execute(INSERT INTO goods_cates(name) VALUES(%s), [固态硬盘]) conn.commit() print(受影响行数:, cur.rowcount) cur.execute(SELECT id, name FROM goods_cates WHERE id %s, [1]) rows cur.fetchall() for r in rows: print(r[id], r[name]) finally: conn.close()rowcount是只读属性表示最近一次execute()影响的行数做批量操作时很有用。fetchone()取一行返回字典fetchall()取全部返回字典列表。数据量大时不要一次fetchall()用游标迭代或分页查询避免内存爆掉。如果你想把 TaoToken 的模型能力也接进来比如让脚本自动生成 SQL 注释可以读[taotoken]段的配置去调 API。长期做编码和 Agent 任务的话Coding Plan 页面有更完整的接入说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例。5. 本篇常见错排查清单跑不通的时候按下面顺序排查基本能覆盖九成问题。报错ModuleNotFoundError: No module named pymysql说明依赖没装到当前 Python 环境。Linux 上常有系统 Python 和虚拟环境两套确认你pip install和python3用的是同一个。用python3 -m pip install pymysql更稳。报错Access denied for user rootlocalhost密码错了或者用户没有从localhost连接的权限。检查config.toml里的user和password。MySQL 8 默认认证插件是caching_sha2_password老版本pymysql可能不兼容升级pip install --upgrade pymysql即可。报错Cant connect to MySQL server on 127.0.0.1MySQL 服务没启动或者端口不对。Linux 上用systemctl status mysql看服务状态ss -tlnp | grep 3306看端口监听。如果 MySQL 装在容器里host要改成容器映射的地址。报错Unknown database jing_dong数据库不存在。先CREATE DATABASE jing_dong DEFAULT CHARSET utf8mb4;或者把config.toml里的database改成已存在的库。中文乱码或 emoji 报错Incorrect string valuecharset没设成utf8mb4或者建表时没指定字符集。连接参数和建表语句都要用utf8mb4两处缺一不可。tomllib.load报TypeError文件没用二进制模式打开。确认是open(path, rb)不是r。数据插入后查不到忘了commit()。查询前先确认上一次写操作有没有提交或者把连接设成autocommitTrue不推荐事务控制会变粗。TaoToken 请求返回 401Key 填错或过期。去 API Keys 页面重新生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。确认base_url是https://taotoken.net/api不要多加斜杠或路径。配置读取到旧值config.toml改了但脚本没重启或者读的是缓存。Python 每次load_config()都重新读文件如果还不对检查是不是有多个config.tomlPath(__file__).parent定位的是脚本所在目录。6. 把配置收口让脚本可迁移这套骨架跑通后你在 Linux 上换机器只需要带走config.toml一个文件代码原样复制就能跑。数据库参数和 AI 工具 Key 都收口在配置里脚本本身不碰敏感信息提交到仓库也放心。我试过把这套结构用在几个小工具上从本地开发机迁到测试服务器改一下host和password就完事不用翻代码找硬编码。后续要扩展的话[taotoken]段可以加temperature、max_tokens这些参数Python 侧读出来直接传给 API。数据库侧可以加连接池配置比如pymysql配合DBUtils做PooledDB高并发场景下比每次新建连接省资源。控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 可以看调用量和 Key 状态。Claude Code 相关的接入说明在 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 如果你用 Anthropic 系模型做编码那边有更细的配置示例。最后留一个实用习惯在verify.py里加一行print(load_config()[mysql][host])每次改完配置先跑验证脚本确认读到的是新值再跑业务逻辑。这个动作花三秒能省掉大量「改了没生效」的排查时间。