Fly.io部署Ktor应用时Flyway Postgres Jar类加载失败问题

可能的原因 #

• 类加载器层级不匹配
  你打印的类加载器（Application::class.java.classLoader或系统类加载器）和Flyway实际使用的上下文类加载器不是同一个。Flyway通常通过线程上下文类加载器加载数据库驱动实现，而Fly.io环境中这个类加载器的路径配置和本地存在差异。

• Fat Jar打包的SPI文件合并错误
  虽然Manifest中包含依赖，但打包插件（如maven-shade-plugin）可能未正确合并Flyway的SPI注册文件META-INF/services/org.flywaydb.core.api.database.DatabaseType，导致PostgreSQL驱动的实现条目丢失。本地运行时依赖单独Jar，SPI文件可正常读取，但Fat Jar中合并不当就会出现问题。

• Fly.io运行环境的类路径配置问题
  即使Jar内包含依赖，Fly.io的启动命令或容器环境可能未正确将Fat Jar中的嵌套Jar加入类路径，或者存在类加载隔离的隐性配置。

排查与解决步骤 #

1. 检查SPI文件完整性
   解压Fat Jar，查看META-INF/services/org.flywaydb.core.api.database.DatabaseType文件，确认是否包含org.flywaydb.database.postgresql.PostgreSQLDatabaseType条目。如果缺失，需调整maven-shade-plugin配置，添加SPI合并转换器：

   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-shade-plugin</artifactId>
     <version>3.5.1</version>
     <executions>
       <execution>
         <phase>package</phase>
         <goals>
           <goal>shade</goal>
         </goals>
         <configuration>
           <transformers>
             <!-- 合并SPI服务文件 -->
             <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
             <!-- 指定主类 -->
             <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
               <mainClass>你的应用主类全限定名</mainClass>
             </transformer>
           </transformers>
         </configuration>
       </execution>
     </executions>
   </plugin>
   

2. 显式指定Flyway使用的类加载器
   在初始化Flyway时，强制传入正确的类加载器，确保驱动能被加载：

   val targetClassLoader = Thread.currentThread().contextClassLoader ?: Flyway::class.java.classLoader
   val flyway = Flyway.configure(targetClassLoader)
     .dataSource(你的数据库连接配置)
     .load()
   flyway.migrate()
   

3. 验证Fly.io启动命令
   确认Fly.io的启动命令为直接运行Fat Jar：java -jar 你的应用jar包名.jar，避免使用java -cp方式启动，后者可能无法自动加载Jar内的嵌套依赖。

4. 替换打包插件（可选）
   如果maven-shade-plugin的SPI合并问题无法解决，可尝试使用maven-assembly-plugin打包，确保所有依赖和配置文件被完整包含。

额外验证操作 #

• 在Fly.io的VM中执行jar tf 你的应用jar包名.jar | grep PostgreSQLDatabaseType，确认类文件确实存在于Fat Jar内。
• 在应用初始化时打印上下文类加载器信息：println("Context ClassLoader: ${Thread.currentThread().contextClassLoader}")，对比本地与Fly.io环境的输出差异。

内容的提问来源于stack exchange，提问作者evegul