py2neo连接Neo4j报ConnectionUnavailable连接失败问题

你遇到的IndexError: pop from empty deque、ConnectionRefusedError: [Errno 111] Connection refused、WireError到最终的ConnectionUnavailable是连锁报错，核心原因是py2neo传入的连接参数和Neo4j Desktop实际运行的数据库配置完全不匹配，根本没有建立有效Bolt连接，和你传的name参数、参数顺序之类的细节无关。

第一步：先拿到Neo4j Desktop的真实运行参数 #

你之前踩的第一个坑是直接照搬独立版Neo4j的默认配置，Neo4j Desktop的默认规则和独立安装版完全不一样：

• 打开Neo4j Desktop，找到你用来导入Cora数据的目标数据库实例，先点击Start按钮等实例状态变为Running，未启动的实例不可能连上
• 点击实例卡片的Details选项卡，找到Bolt监听地址：Neo4j Desktop不会固定占用7687端口，会给每个本地实例动态分配可用端口，常见值为7688/7689甚至更高，文档里写的7687是独立版的默认值，Desktop环境下大概率不对
• 同页面找到实例认证信息：Desktop创建实例时会自动生成随机初始密码，根本不是固定值password，如果你没手动改过密码，直接复制页面上显示的初始密码即可
• 确认加密配置：本地运行的Desktop实例默认不开启Bolt TLS加密，你之前开secure=True反而会导致TLS握手失败

第二步：正确的初始化代码 #

不要用参数留空读环境变量、重复传port的冗余写法，直接用从Details页复制的真实参数初始化即可，py2neo v4/v5通用写法：

from py2neo import Graph

# 把下面三个值替换成你从Neo4j Desktop Details页复制的真实值
BOLT_ADDR = "bolt://localhost:替换成实际Bolt端口"
USERNAME = "neo4j"
PASSWORD = "替换成实例实际密码"

graph = Graph(
    BOLT_ADDR,
    auth=(USERNAME, PASSWORD),
    secure=False
)

# 连通性校验，跑通再执行后续Cora导入逻辑
print(graph.run("RETURN 1 AS connect_test").data())

代码执行后如果输出[{'connect_test': 1}]，说明连接已经正常建立。

之前三种初始化方案的具体错误 #

• 方案1：port、user、password参数全留空时，py2neo会尝试读取系统环境变量里的Neo4j连接配置，如果你没提前在系统中配置对应环境变量，参数为空会直接触发内部连接池的空deque弹出错误，属于无效配置
• 方案2：硬编码7687端口、填固定密码password、开启secure=True三个配置全错：端口和密码都是独立版Neo4j的默认值，不符合Desktop的动态配置规则，开加密和本地实例的非加密配置冲突
• 方案3：name参数只是py2neo给本地连接打别名用的标记参数，不参与实际连接逻辑，加了也解决不了基础参数错配的问题

额外避坑 #

• 连接测试前先临时关闭系统代理、全局VPN，这类工具经常会劫持localhost流量导致连接被拒
• 如果py2neo版本低于2021.2.0，先执行pip install --upgrade py2neo升级，老版本对Neo4j 4.x以上版本的Bolt协议兼容性很差，也会报奇奇怪怪的连接错误
• StellarGraph的Cora导入示例是基于独立安装版Neo4j编写的，默认配置和Neo4j Desktop差异很大，不要直接抄示例里的连接参数

内容的提问来源于stack exchange，提问作者Strongshell