Spring Boot连接Neo4j报Connection to the database terminated错误怎么解决

错误提示：org.neo4j.driver.v1.exceptions.ServiceUnavailableException: Connection to the database terminated.

第一步：排查Neo4j本地服务状态 #

• 确认Neo4j服务已正常启动，可通过Neo4j Desktop查看运行状态，或直接访问Neo4j浏览器端http://localhost:7474 验证服务可用性
• 验证7687端口未被其他进程占用，且本地防火墙未拦截该端口的通信
• 使用cypher-shell或Neo4j浏览器端，输入配置中的账号密码（neo4j/neo4j）测试登录，确认账号密码正确、认证功能正常

第二步：排查版本兼容性问题 #

该错误90%以上由版本不匹配导致，Spring Boot、Spring Data Neo4j、Neo4j数据库三者版本必须严格对应：

• Spring Boot 2.6.x ~ 2.7.x：对应Spring Data Neo4j 6.x，支持Neo4j 3.5、4.x版本，配置前缀为spring.neo4j.*
• Spring Boot 3.0+：对应Spring Data Neo4j 7.x，支持Neo4j 5.x版本，配置前缀为spring.neo4j.*
• 旧版本Spring Boot 2.4以下：配置前缀为spring.data.neo4j.*，仅支持Neo4j 3.x版本

第三步：修复现有代码/配置错误 #

1. 配置文件修正：如果使用Spring Boot 2.4+版本，将配置改为：

spring.neo4j.uri=bolt://localhost:7687
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=neo4j

2. 实体类修正

• 给Actor类添加@Node（旧版用@NodeEntity）注解
• 废弃@GraphId注解，改用@Id + @GeneratedValue声明主键，主键类型统一用Long，避免类型不匹配
• Movie类的id类型从int改为Long，和Neo4jRepository的泛型参数保持一致

3. 依赖修正：确认pom.xml中已正确引入starter依赖，无需单独引入neo4j驱动：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-neo4j</artifactId>
</dependency>

1. 版本匹配优先 #

正式开发前先确认三者版本对应关系，避免版本不兼容导致的无意义报错

2. 实体类编写规则 #

• 节点实体必须加@Node注解
• 主键必须用Long类型，添加@Id @GeneratedValue注解
• 关系映射通过@Relationship注解指定类型和方向，双向关系需添加@JsonIgnoreProperties避免循环序列化

3. Repository编写规则 #

• 继承Neo4jRepository<实体类, 主键类型>，主键类型必须和实体类的id类型完全一致
• 自定义Cypher查询时，返回结果结构必须和实体类的映射关系匹配

内容的提问来源于stack exchange，提问作者许瀚洋