Neo4j 数据库连接失败排查与解决方案
在使用 Python 连接 Neo4j 图数据库时,常遇到 ServiceUnavailable 或 Connection refused 错误。以下提供两种针对 WSL Ubuntu 环境的解决方案。
方案一:配置网络与 URI
-
获取宿主机 IP 在 Windows PowerShell 中执行以下命令,找到无线局域网适配器 WLAN 的 IPv4 地址:
ipconfig -
测试端口连通性 在 WSL2 终端中使用
nc命令测试 Neo4j 默认端口(7687)是否可达:nc -zv <宿主机 IP> 7687若显示
succeeded,则网络层面正常。 -
修改 Python 脚本 URI 将项目中的连接 URI 更新为宿主机 IP:
uri = "bolt://<宿主机 IP>: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)需通过sudo apt install -y neo4j配置,而非仅通过pip install neo4j。 - 库与工具差异:项目中导入的
neo4jPython 库与终端使用的neo4j命令行工具是两个不同的组件,请根据需求分别配置。

