4. 迁移任务启动失败：连接超时、驱动不兼容、配置错误排查

迁移任务在启动阶段即告失败，是 Development 环境中最常见的阻塞性问题。这类故障通常表现为任务进程刚启动就抛出异常、连接池初始化失败或长时间无响应。根据生产环境与开发环境的统计，启动失败的原因高度集中在网络连接超时、驱动版本不匹配和配置参数错误三个维度。本章将逐一拆解这三类问题的根因定位方法与修复步骤。

4.1 连接超时：网络层与连接池的常见陷阱

连接超时是启动失败中占比最高的原因，通常并非数据库不可达，而是异步迁移框架在初始化连接池时对超时参数的敏感度高于普通客户端。

超时类型	典型表现	常见根因
TCP 连接超时	任务日志中报 connect timed out 或 Connection refused	防火墙规则、安全组未放行端口；数据库监听地址绑定在 127.0.0.1
连接池获取超时	报 Connection pool exhausted 或 Timeout waiting for idle object	连接池最大连接数设置过小；异步任务并发数超过池容量
握手/认证超时	报 Authentication failed 或 SSL handshake timeout	数据库用户密码过期；SSL 证书配置错误；TLS 版本不匹配

4.2 驱动不兼容：版本、方言与异步适配

数据库驱动（JDBC / ODBC / 原生驱动）是迁移框架与数据库之间的桥梁。驱动不兼容在 Development 阶段尤为隐蔽，因为本地开发环境与 CI/CD 环境的驱动版本可能不一致。

错误日志关键字	可能原因	修复方案
No suitable driver	驱动 JAR 未加载或 SPI 注册失败	检查 classpath；确认驱动类名正确；使用 Class.forName() 手动注册
Unsupported authentication plugin	驱动版本不支持数据库认证协议	升级驱动至与数据库大版本匹配；或修改数据库用户认证插件为 mysql_native_password
Dialect class not found	方言配置错误或缺少方言依赖	在配置中指定正确的方言全限定类名；引入对应数据库的方言包
Failed to create async connection	异步驱动未引入或版本冲突	确认使用了 vertx-mysql-client / r2dbc 等异步驱动；排除同步驱动冲突

4.3 配置错误：从连接串到参数校验

配置错误是启动失败中排查成本最高的类别，因为错误信息往往不够直观。常见的配置错误包括连接字符串格式错误、参数拼写错误、以及异步框架特有的配置缺失。

4.3.1 连接字符串（JDBC URL）常见错误

-- 错误示例 1：缺少数据库名称
jdbc:mysql://localhost:3306?useSSL=false

-- 错误示例 2：参数分隔符错误（应为 & 而非 ?）
jdbc:mysql://localhost:3306/mydb?useSSL=false?serverTimezone=UTC

-- 错误示例 3：异步驱动 URL 前缀错误
# 错误：使用 jdbc:mysql 前缀连接 R2DBC 驱动
r2dbc:mysql://localhost:3306/mydb

-- 正确示例
jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC
r2dbc:mysql://localhost:3306/mydb

4.3.2 异步框架特有配置项

异步迁移框架（如 Flyway 异步扩展、Liquibase 异步模式、自定义 Vert.x 迁移器）在启动时对以下配置项敏感：

配置项	作用	错误值示例	正确值示例
spring.flyway.async.enabled	启用异步迁移模式	false（默认值）	true
vertx.pool.maxSize	异步连接池最大连接数	0 或 -1	10
r2dbc.pool.initial-size	连接池初始连接数	100（过大导致启动慢）	2
liquibase.parameters.async	Liquibase 异步执行参数	未配置	true

4.4 综合排查清单与快速定位表

当迁移任务启动失败时，建议按照以下优先级顺序进行排查，避免在非根因上浪费时间。

优先级	排查项	验证命令 / 方法	预期结果
P0	网络连通性	telnet host port 或 nc -zv host port	连接成功
P0	驱动版本兼容性	检查 pom.xml / build.gradle 中驱动版本与数据库版本对应关系	版本匹配
P1	连接字符串格式	在数据库客户端工具中直接使用该 URL 测试连接	连接成功
P1	异步配置开关	检查配置文件中 async.enabled 或类似属性	已启用
P2	连接池参数	检查 maxTotal、maxWaitMillis、initialSize	值合理且大于 0
P2	SSL/TLS 配置	检查证书路径、密码、TLS 版本	证书有效且路径正确
P3	数据库用户权限	SHOW GRANTS FOR 'user'@'host';	拥有迁移所需 DDL 权限