Neo4j 数据库连接失败排查与解决指南

Neo4j 数据库连接失败排查与解决指南

在 WSL Ubuntu 环境下使用 Python 连接 Neo4j 时，常遇到 ServiceUnavailable 或 Connection refused 错误。本文提供两种有效的连接解决方案。

常见错误现象

可能出现以下报错：

• neo4j.exceptions.ServiceUnavailable: Unable to retrieve routing information
• Failed to establish connection to ResolvedIPv4Address(('127.0.0.1', 7687)) (reason [Errno 111] Connection refused)

方案一：WSL 网络配置（使用宿主机 IP）

在 WSL 中直接连接 localhost 往往无法访问宿主机的 Neo4j 服务，需使用 Windows 宿主机 IP。

1. 在 Windows PowerShell 中获取 IPv4 地址：

   ipconfig
   

   找到无线局域网适配器 WLAN 下的 IPv4 地址。

2. 在 WSL 中测试连通性：

   nc -zv <Windows_IP> 7687
   

   若显示 succeeded，则网络可达。

3. 修改 Python 脚本中的 URI：

   uri = "bolt://<Windows_IP>:7687"
   

   替换 <Windows_IP> 为实际地址。运行脚本即可连接数据库。

方案二：Docker 部署 Neo4j

若本地安装不完整，可使用 Docker 容器部署 Neo4j 镜像。

1. 执行启动命令：

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

2. 运行 Python 脚本即可连接。注意浏览器访问可能显示旧版界面。

注意事项

1. 安装方式区分：终端指令 neo4j start 需要通过 配置，而非仅通过 pip 安装库。