Neo4j Python驱动连接失败：无握手响应问题排查求助

问题概述 #

Ubuntu 22.04.3 LTS服务器的Jenkins环境中，使用官方neo4j:latest Docker镜像时，Python驱动（5.10.0版本，Python 3.10.12）抛出neo4j.exceptions.ServiceUnavailable错误，提示Connection to 127.0.0.1:7687 closed without handshake response。但7687端口检测可用，Neo4j Web界面（7474）能正常连接7687，且GitHub CI测试无此问题，仅Jenkins环境出现故障。

核心排查方向与解决方法 #

1. 排查Jenkins网络隔离问题 #

这是最常见的原因，尤其是当Jenkins本身以容器形式部署时：

• 验证方式：在Jenkins构建步骤中执行以下命令：

  # 测试本地回环地址连通性
  nc -zv 127.0.0.1 7687
  # 测试宿主机实际IP的连通性（替换为你的服务器IP）
  nc -zv 192.168.x.x 7687
  

• 解决方法：将Python驱动的连接地址从127.0.0.1改为宿主机实际IP；或确保Jenkins与Neo4j容器处于同一Docker自定义网络（通过docker network create创建网络，启动容器时加入该网络，使用容器名作为连接地址）。

2. 检查Neo4j容器的监听配置 #

• 验证方式：进入Neo4j容器执行：

  docker exec -it <你的neo4j容器ID> bash
  netstat -tulpn | grep 7687
  

  确认输出为0.0.0.0:7687，而非仅127.0.0.1:7687。
• 解决方法：启动Neo4j容器时添加环境变量，强制监听所有地址：

  docker run -d --name neo4j-test \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/yourpassword \
    -e NEO4J_dbms_default_listen_address=0.0.0.0 \
    neo4j:latest
  

3. 调整Python驱动的加密配置 #

Neo4j 5.x默认开启加密连接，若驱动未匹配配置会导致握手失败：

• 解决方法：在驱动初始化时显式关闭加密（或根据实际配置开启）：

  from neo4j import GraphDatabase
  
  class Neo4jWrapper:
      def __init__(self, uri="bolt://<宿主机IP>:7687", user="neo4j", password="yourpassword"):
          self.driver = GraphDatabase.driver(uri, auth=(user, password), encrypted=False)
          # 若需开启加密，可设置encrypted=True并配置信任证书
  

  也可尝试使用neo4j://协议替代bolt://（Neo4j 5.x推荐的路由协议）。

4. 排查Jenkins的防火墙/权限限制 #

• 验证方式：在Jenkins构建步骤中执行telnet 127.0.0.1 7687，若提示拒绝连接，检查服务器iptables规则：

  sudo iptables -L -n | grep 7687
  

• 解决方法：添加iptables规则允许Jenkins用户/进程访问7687端口，或临时关闭防火墙测试（仅用于排查）。

5. 锁定Neo4j镜像版本避免兼容性问题 #

neo4j:latest会自动拉取最新版本，可能与Python驱动5.10.0存在兼容性差异：

• 解决方法：修改启动脚本使用与驱动版本匹配的Neo4j镜像：

  docker run -d --name neo4j-test \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/yourpassword \
    neo4j:5.10
  

额外验证步骤 #

在Jenkins构建中添加单元测试前的预检查步骤，输出网络状态和Neo4j配置信息，帮助定位问题：

# 查看本地端口占用
netstat -tulpn | grep 7687
# 检查Neo4j容器日志
docker logs <neo4j容器ID> | grep -i "listen"

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