WSL 环境下 Neo4j 连接失败排查与修复指南

最近在实践 GraphRAG 架构时，图数据库 Neo4j 的连接问题成了拦路虎。常见报错如 ServiceUnavailable: Unable to retrieve routing information 或 Connection refused，往往让人排查一整晚。针对 WSL2 (Ubuntu) 环境下的连接失败，主要有两种行之有效的解决方案。

方案一：使用宿主机 IP 直连

在 WSL2 中，localhost 指向的是虚拟机内部，而非 Windows 宿主机。因此直接连接 localhost:7687 通常会失败。

1. 获取宿主机 IP 在 Windows PowerShell 中运行 ipconfig，找到无线局域网适配器 WLAN 下的 IPv4 地址（例如 192.168.1.105）。

2. 测试连通性 切换到 WSL2 终端，使用 nc 命令验证端口是否开放：

   nc -zv 192.168.1.105 7687
   

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

3. 修改 Python 脚本 将项目中的连接 URI 从 bolt://localhost:7687 改为实际 IP：

   uri = "bolt://192.168.1.105:7687"
   

   重新运行脚本即可建立连接。

方案二：Docker 部署

如果本地安装版本不稳定，推荐使用 Docker 容器化部署。这能避免依赖冲突，且启动更规范。

执行以下命令拉取镜像并启动服务：

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

启动后，访问 http://localhost:7474 进入 Browser。注意部分旧版镜像可能界面风格较老，但不影响功能使用。

补充说明

这里容易混淆两个概念：

1. 命令行工具：通过 sudo apt install -y neo4j 安装的 neo4j 指令，用于管理服务端进程。
2. ：通过 安装的库，用于应用层连接。