MariaDB 3306 握手失败时别急着重装数据库或把端口改来改去。先把完整报错原文贴给走 TaoToken 的 Codex让它在本地 SQL 客户端返回的报错上对照 pymysql、asyncmy、SQLAlchemy 连接串和 3306 端口逐项排查。TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 用来创建 KeyAPI 通道是 https://taotoken.net/api。TaoToken 只供 Codex 的 Key 和通道不替 pymysql 建立数据库会话。这篇按排障视角写。你前面在 Vibe Coding 的安装环境里一路装 HBuilder X、微信开发者工具、trae、Python再到 MariaDB默认端口保持 3306也按要求装了 asyncmy、pymysql 等 Python 驱动。结果 SQLAlchemy 一连接就握手失败。这个问题不一定在 MariaDB 本身很多时候出在驱动和连接串不匹配、端口指向了另一个实例、用户授权 host 不对、认证插件不兼容或者 utf8mb4 参数没有按连接层核对。本文不讨论复杂架构只做一件事借助走 TaoToken 的 Codex把报错原文、驱动、端口、参数一条条对齐。一、原问题与场景MariaDB 3306 握手失败SQLAlchemy 先别乱改典型场景是这样的Windows 本地已经安装 MariaDB服务能启动命令行也能用mysql -V看到版本。Python 环境里装了 SQLAlchemy、pymysql、asyncmy。你以为接下来create_engine就能连上但运行时报错例如连接握手阶段失败、连接丢失、SSL 握手异常、认证插件不匹配或者干脆提示驱动加载不到。报错可能长这样sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (2013, Lost connection to MySQL server during query)也可能是(2003, Cant connect to MySQL server on 127.0.0.1)还可能是 asyncmy 或 SSL 相关错误。此时不要先改代码也不要直接怀疑 MariaDB 安装失败。正确顺序是先把报错原文完整复制出来包括 traceback、SQLAlchemy 版本、Python 版本、连接串中隐藏密码后的形式然后贴给走 TaoToken 的 Codex。为什么强调“走 TaoToken 的 Codex”因为 Codex 在这里的角色是排障助手它根据你给出的本地 SQL 客户端报错、驱动版本、连接串和端口信息帮你列出下一步验证命令。它不是数据库驱动不会替你创建 pymysql 会话也不会绕过 MariaDB 的认证。TaoToken 提供的是 Codex 可用的 Key 和 API 通道。把它和 MariaDB 的账号密码区分开后面排查才不会混。你原文安装环境时保持默认 3306并要求安装 asyncmy、pymysql。这个前提很重要同步连接用 pymysql异步连接通常用 asyncmy。SQLAlchemy 连接串前缀必须匹配否则驱动层在握手前就可能报错。再加上 utf8mb4 参数如果连接层没有写 charset或者服务端字符集与客户端不一致也可能出现看似“握手失败”的连锁问题。所以第一段的目标不是立刻修好而是把现场固定下来MariaDB 服务状态、3306 监听情况、命令行能否登录、pymysql 能否单独连接、asyncmy 能否单独连接、SQLAlchemy 用哪个连接串。把这几项结果交给 Codex比反复重装有效。二、TaoToken 前置创建 Key把 https://taotoken.net/api 填进 Codex先处理 Codex 的通道。打开 TaoToken 官网进入控制台创建 API Key。链接是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建后你会拿到类似YOUR_API_KEY的 Key。不要把它写进文章、截图或公开仓库。这个 Key 是给 Codex 请求模型用的不是 MariaDB 的密码。MariaDB 仍然使用你自己的数据库用户名、密码、库名和 3306 端口。Codex 自定义 Base URL 填https://taotoken.net/api注意这个 API 地址不加 UTM 参数。官网入口可以带 UTM但配置进 Codex 的 base_url 保持干净。也就是说base_url 不要写成官网首页不要带?utm_source...也不要自己拼成奇怪的路径。若你的 Codex 版本使用配置文件就写进config.toml。若使用环境变量就把 Key 放进环境变量例如TAOTOKEN_API_KEY。这一步的核心是让 Codex 能正常对话。验证方式很简单配置完成后启动 Codex问一个和数据库排障无关的普通问题看是否能返回内容。如果 Codex 报 401、403、404、model not found那属于 TaoToken 接入问题不要和 MariaDB 握手失败混在一起查。如果 Codex 能正常对话再让它分析 pymysql 和 asyncmy 的报错。还要提醒一次TaoToken 只供 Codex 的 Key 和通道。它能帮你分析“为什么 pymysql 握手失败”但不能替你执行pymysql.connect()也不能替你修改 MariaDB 用户权限。数据库会话仍然由你本地的驱动建立。三、可复制配置Codex config.toml、环境变量与排障提示词下面按 Codex 的config.toml来写。Windows 下常见路径是C:\Users\你的用户名\.codex\config.tomlLinux 或 macOS 常见路径是~/.codex/config.toml先设置环境变量。Windows PowerShell 临时生效$env:TAOTOKEN_API_KEYYOUR_API_KEYWindows 持久化可以用setx TAOTOKEN_API_KEY YOUR_API_KEY设置后需要新开终端。Linux 或 macOSexport TAOTOKEN_API_KEYYOUR_API_KEY然后编辑config.tomlmodel gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat其中model换成 TaoToken 控制台里可用的模型 ID不要照抄一个不可用的名字。base_url保持https://taotoken.net/api。env_key对应你设置的环境变量。若你的 Codex 版本对wire_api有要求按接入文档确认用chat还是responses如果这里填错常见表现是 404 或协议错误不是 MariaDB 握手错误。配置完成后用 Codex 做数据库排障时提示词不要只写“连不上”。建议这样贴你是 Python 数据库连接排障助手。我的环境是 WindowsMariaDB 默认端口 3306Python 已装 SQLAlchemy、pymysql、asyncmy。现在用 SQLAlchemy 连接时报握手失败。完整 traceback 如下 粘贴完整报错 连接串隐藏密码后如下 mysqlpymysql://user:***127.0.0.1:3306/db?charsetutf8mb4 mysqlasyncmy://user:***127.0.0.1:3306/db?charsetutf8mb4 请按顺序让我验证 1. 驱动是否安装、版本是否匹配 2. 连接串前缀和驱动是否匹配 3. 3306 是否被 MariaDB 监听是否被其他 MySQL 实例占用 4. 用户 host 授权和认证插件 5. utf8mb4、SSL 参数 6. 防火墙、多实例、IPv6 与 localhost 差异。 每一步给出 Windows 可执行命令和判断标准先不要让我重装数据库。这个提示词的作用是把 Codex 的输出限制在排障路径上。否则它可能直接给你一大段新代码反而掩盖真正问题。你要的是对照驱动和端口而不是让模型替你猜 MariaDB 密码。四、验证请求与成功结果从 mysql 命令行到 SQLAlchemy 连通先验 MariaDB 本身。命令行执行mysql -V确认你调用的是 MariaDB 客户端而不是另一个 MySQL 实例的客户端。然后检查 3306 监听netstat -ano | findstr 3306Linux 可以用ss -lntp | grep 3306再尝试命令行登录mysql -h 127.0.0.1 -P 3306 -u 你的用户 -p如果这里都连不上先不要碰 SQLAlchemy。如果这里能连上再验驱动。同步 pymysql 单独测试import pymysql conn pymysql.connect( host127.0.0.1, port3306, user你的用户, password你的密码, database你的库, charsetutf8mb4, ) print(conn.ping()) conn.close()不抛异常就说明 pymysql 这一层和 MariaDB 的握手基本正常。异步 asyncmy 单独测试import asyncio import asyncmy async def main(): conn await asyncmy.connect( host127.0.0.1, port3306, user你的用户, password你的密码, db你的库, charsetutf8mb4, ) print(await conn.ping()) conn.close() asyncio.run(main())如果 asyncmy 失败而 pymysql 成功重点查 async 驱动安装、Python 版本、连接串前缀和认证插件。然后测试 SQLAlchemy 同步连接from sqlalchemy import create_engine, text engine create_engine( mysqlpymysql://你的用户:你的密码127.0.0.1:3306/你的库?charsetutf8mb4 ) with engine.connect() as conn: print(conn.execute(text(select version())).scalar())异步 SQLAlchemy 则用from sqlalchemy.ext.asyncio import create_async_engine engine create_async_engine( mysqlasyncmy://你的用户:你的密码127.0.0.1:3306/你的库?charsetutf8mb4 )成功结果不是“Codex 说成功了”而是本地命令真实返回 MariaDB 版本、ping()不抛异常、SQLAlchemy 不再出现握手失败。Codex 正常对话只是前提它能根据你贴的 traceback 指出下一项检查例如让你先看pip list、3306 监听、用户 host、认证插件。最终连库仍然由 pymysql 或 asyncmy 完成。五、本篇常见错排查pymysql、asyncmy、3306、utf8mb4 一项项对第一连接串前缀与驱动不匹配。mysqlpymysql对应 pymysqlmysqlasyncmy对应 asyncmy。同步引擎用异步驱动或异步引擎用同步驱动都会在握手阶段或驱动加载阶段报错。第二只装了 pymysql却在 SQLAlchemy 里写mysqlasyncmy。表现可能是No module named asyncmy也可能被外层包装成连接失败。用pip list看 sqlalchemy、pymysql、asyncmy 是否都在版本是否正常。第三3306 被占用或多实例。你安装 MariaDB 时默认 3306但机器上可能还有 MySQL、XAMPP、Docker 映射的 3306。命令行mysql -V显示 MariaDB不代表你连到的就是 MariaDB。用netstat -ano | findstr 3306看 PID再对应服务。第四localhost和127.0.0.1差异。有的环境里localhost可能走 IPv6 或命名管道127.0.0.1走 IPv4。连接串里写一个命令行里试另一个。MariaDB 的bind-address若只监听某地址也会影响结果。第五用户 host 授权。userlocalhost和user127.0.0.1可能不是同一个授权项。查看mysql.user里的 user 和 host确认当前连接来源有权限。第六认证插件。MariaDB 用户可能使用某种认证插件而当前 pymysql 或 asyncmy 版本不支持。先看报错里有没有 authentication plugin、ed25519、caching_sha2_password 等关键词再决定是否调整用户认证方式。第七utf8mb4 参数。安装时选了 utf8mb4不代表连接层自动使用。连接串里应带charsetutf8mb4并检查服务端character_set_server、collation_server。字符集问题通常表现为乱码但在某些驱动组合下也可能让初始化阶段异常。第八SSL/TLS 握手。如果报错里有 SSL、certificate、TLS先确认 MariaDB 是否配置了对应证书再检查驱动是否默认要求 SSL。不要盲目关闭但可以按文档在测试环境临时调整。第九密码特殊字符。密码里有、#、/、:时连接串需要 URL 编码。否则解析出的 host 或 port 可能完全错误看起来像 3306 握手失败。第十Codex 配置错误。base_url如果填成官网首页或者 Key 没放进环境变量Codex 会报 401、404。这和 MariaDB 握手失败是两类问题。先让 Codex 能正常对话再让它分析数据库报错。第十一防火墙或安全软件拦截 3306。命令行本机可连Python 进程却被拦截这种情况要看防火墙规则和监听地址。第十二安装环境里的多个工具互相干扰。HBuilder X、微信开发者工具、trae 本身不直接改 MariaDB但如果你在 trae 或其他终端里使用了不同 Python 解释器pip install装的 pymysql、asyncmy 可能不在当前解释器里。用python -m pip list确认当前解释器的包。六、语义一致 CTA排障接入先拿 Key再按文档配置这篇的核心是排障和接入让 Codex 通过 TaoToken 拿到可用的 Key 与通道再对照 pymysql、asyncmy、3306、utf8mb4 逐项排查 MariaDB 握手失败。建议先打开 API Keys 创建或管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmaria3306_codexutm_campaignrewrite然后对照接入文档把 Codex 的config.toml、环境变量和base_url配置正确https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentmaria3306_codexutm_campaignrewrite如果你后续要长期用 Codex 做安装环境、数据库连接和工程排障可以再看 Coding Planhttps://taotoken.net/console/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentmaria3306_codexutm_campaignrewrite配置时记住两件事Codex 的 Key 来自 TaoTokenMariaDB 的会话来自 pymysql 或 asyncmy。TaoToken 不替驱动连库但可以让 Codex 在你贴出报错原文后按驱动、端口、认证和 utf8mb4 参数给出更清晰的排查顺序。先把 Key 配好再把报错贴全MariaDB 3306 握手失败就不再是盲猜。