Docker环境下Spring后端项目执行Liquibase:diff时无法加载Hibernate实体类

看起来你在Docker多服务环境里跑Liquibase diff的时候踩了实体类加载的坑，我之前在类似的微服务+Docker场景里也碰到过类似问题，结合你的日志和操作步骤，给你几个排查和解决的方向：

1. 先确保实体类已经被编译为class文件 #

你当前的Docker命令是直接挂载本地项目目录到容器里执行liquibase:diff，但如果本地还没编译项目，target/classes目录里就没有实体类的.class文件，容器里的Maven自然找不到实体类。

解决方法二选一：

• 先在本地执行编译：

  mvn clean compile
  

  再重新执行你的Docker Liquibase命令
• 或者在Docker的Maven命令里加入编译步骤，让容器里先编译再执行diff：

  docker run --rm -it -v ${PWD}:/app -w /app --network central-server_central-net maven:3.9.0 mvn compile "-Dliquibase.classpath=target/classes:target/dependency" liquibase:diff
  

2. 给Liquibase明确指定Hibernate实体扫描路径 #

Liquibase执行diff依赖Hibernate解析实体类，必须明确告诉它去哪里找你的实体。你可以通过两种方式配置：

方式一：在pom.xml的Liquibase插件里配置 #

打开项目的pom.xml，找到liquibase-maven-plugin的配置块，添加实体包扫描和Hibernate配置文件的指定：

<plugin>
  <groupId>org.liquibase</groupId>
  <artifactId>liquibase-maven-plugin</artifactId>
  <version>4.27.0</version>
  <configuration>
    <!-- 指向你的liquibase配置文件 -->
    <propertyFile>src/main/resources/liquibase.properties</propertyFile>
    <!-- 指定实体类所在的包 -->
    <hibernatePackageName>com.starcrest.backend_primary.entity</hibernatePackageName>
    <!-- 指向你的Spring JPA配置文件，让Liquibase能读取Hibernate配置 -->
    <hibernateConfiguration>src/main/resources/application.yml</hibernateConfiguration>
  </configuration>
  <dependencies>
    <!-- 确保加入Hibernate和Postgres驱动依赖，让Liquibase能调用Hibernate -->
    <dependency>
      <groupId>org.hibernate.orm</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>你的Hibernate版本，比如6.1.7.Final</version>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>42.6.0</version>
    </dependency>
  </dependencies>
</plugin>

方式二：在liquibase.properties里配置 #

如果用单独的liquibase.properties文件，加入以下配置：

# 数据库连接配置（注意用Docker容器名作为主机名，不是localhost）
url=jdbc:postgresql://postgres-primary:5432/你的数据库名称
username=数据库用户名
password=数据库密码
driver=org.postgresql.Driver

# Hibernate实体扫描配置
hibernate.package.name=com.starcrest.backend_primary.entity
hibernate.configuration.file=src/main/resources/application.yml

3. 修复数据库JDBC URL undefined的问题 #

从你的日志里看到Database JDBC URL [undefined/unknown]，这说明Liquibase根本没正确连接到数据库，这也会间接导致实体类加载失败——因为Hibernate需要数据库元数据来对比实体和库表结构。

重点注意：不要用localhost作为数据库主机名，因为Docker容器里的localhost是容器自身，不是宿主机。你应该用Docker网络里的postgres-primary容器名作为主机名，这样Liquibase容器才能通过Docker内部网络访问到Postgres服务。

4. 确保Liquibase能拿到所有依赖 #

你指定的liquibase.classpath=target/classes:target/dependency，但如果target/dependency目录是空的，Liquibase就找不到Hibernate、Spring JPA这些依赖。可以先在本地执行：

mvn dependency:copy-dependencies

把所有依赖下载到target/dependency目录，再执行Docker里的diff命令。

按照上面的步骤一步步排查，应该能解决实体类加载的问题。

内容来源于stack exchange