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 中直接连接 localhost 往往无法访问宿主机的 Neo4j 服务，需使用 Windows 宿主机 IP。

在 Windows PowerShell 中获取 IPv4 地址：
```
ipconfig
```
找到无线局域网适配器 WLAN 下的 IPv4 地址。
在 WSL 中测试连通性：
```
nc -zv <Windows_IP> 7687
```
若显示 succeeded，则网络可达。
修改 Python 脚本中的 URI：
```
uri = "bolt://<Windows_IP>:7687"
```
替换 <Windows_IP> 为实际地址。运行脚本即可连接数据库。

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

执行启动命令：

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

安装方式区分：终端指令 neo4j start 需要通过 sudo apt install -y neo4j 配置，而非仅通过 pip 安装库。
库与指令区别：项目中 import 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 中直接连接 localhost 往往无法访问宿主机的 Neo4j 服务，需使用 Windows 宿主机 IP。

在 Windows PowerShell 中获取 IPv4 地址：
```
ipconfig
```
找到无线局域网适配器 WLAN 下的 IPv4 地址。
在 WSL 中测试连通性：
```
nc -zv <Windows_IP> 7687
```
若显示 succeeded，则网络可达。
修改 Python 脚本中的 URI：
```
uri = "bolt://<Windows_IP>:7687"
```
替换 <Windows_IP> 为实际地址。运行脚本即可连接数据库。

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

执行启动命令：

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

安装方式区分：终端指令 neo4j start 需要通过 sudo apt install -y neo4j 配置，而非仅通过 pip 安装库。
库与指令区别：项目中 import neo4j 的方法库与终端使用的 neo4j 指令属于不同组件，请勿混淆。

更多推荐文章