最近在实践 GraphRAG 架构时,图数据库 Neo4j 的连接问题成了拦路虎。常见报错如 ServiceUnavailable: Unable to retrieve routing information 或 Connection refused,往往让人排查一整晚。针对 WSL2 (Ubuntu) 环境下的连接失败,主要有两种行之有效的解决方案。
方案一:使用宿主机 IP 直连
在 WSL2 中,localhost 指向的是虚拟机内部,而非 Windows 宿主机。因此直接连接 localhost:7687 通常会失败。
- 获取宿主机 IP
在 Windows PowerShell 中运行
ipconfig,找到无线局域网适配器 WLAN 下的 IPv4 地址(例如192.168.1.105)。

-
测试连通性 切换到 WSL2 终端,使用
nc命令验证端口是否开放:nc -zv 192.168.1.105 7687若显示
Connection succeeded,则网络层正常。 -
修改 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。注意部分旧版镜像可能界面风格较老,但不影响功能使用。

补充说明
这里容易混淆两个概念:
- 命令行工具:通过
sudo apt install -y neo4j安装的neo4j指令,用于管理服务端进程。 - :通过 安装的库,用于应用层连接。

