Neo4j 数据库连接失败排查与修复指南

Neo4j 数据库连接失败排查与修复指南

在图数据库开发中，常遇到连接失败的问题。常见报错如下：

neo4j.exceptions.ServiceUnavailable: Unable to retrieve routing information

ServiceUnavailable: Couldn't connect to localhost:7687 ...
[Errno 111] Connection refused

针对 WSL Ubuntu 环境，提供以下两种解决方法。

方法一：配置宿主机 IP 连接

1. 在 Windows PowerShell 中执行 ipconfig，找到无线局域网适配器 WLAN 的 IPv4 地址。
2. 在 WSL2 中使用 nc 测试端口连通性：

nc -zv <IPv4 地址> 7687

3. 修改 Python 脚本中的 URI 为宿主机 IP：

uri = "bolt://<IPv4 地址>:7687"

方法二：Docker 部署

使用 Docker 拉取官方镜像运行 Neo4j 容器：

docker run \
  -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:5.21.0

注意：此方法启动后，Neo4j Browser 可能显示旧版界面。

补充说明

• neo4j start 等指令并非通过 pip install neo4j 配置，需通过 sudo apt install -y neo4j 安装系统命令。
• 项目中 import 的 neo4j 方法库与终端指令使用的 neo4j 是不同的组件。