Neo4j 数据库连接失败排查与解决方案

Neo4j 数据库连接失败排查与解决方案

在开发 GraphRAG 等项目时，常需使用 Neo4j 图数据库。若遇到连接失败报错（如 ServiceUnavailable），可参考以下排查方案。

方法一：WSL 连接 Windows 宿主机

针对 WSL Ubuntu 环境，可通过获取 Windows 宿主机 IP 进行连接。

1. 在 Windows PowerShell 中执行以下命令查看 IPv4 地址：

ipconfig

找到无线局域网适配器 WLAN 下的 IPv4 地址（示例：192.168.1.105）。

2. 在 WSL 中测试端口连通性：

nc -zv <宿主机 IP> 7687

若显示 succeeded，则网络层正常。

3. 修改 Python 脚本中的 URI 配置：

uri = "bolt://<宿主机 IP>:7687"

运行脚本即可连接数据库。

方法二：使用 Docker 部署

若本地安装不完整，可使用 Docker 拉取镜像运行。

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

此方法启动后，Python 脚本可对数据库进行修改。注意进入 Neo4j Browser 时可能为旧版界面。

注意事项

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

通过以上步骤，通常可解决常见的连接拒绝或服务不可用问题。