使用Python Driver无法连接Neo4j，但Neo4j Browser可正常连接

环境与问题概述 #

• 部署架构：私有子网内的EC2实例通过Docker容器运行Neo4j，由应用负载均衡（ALB）对外提供服务
• ALB配置：设置两个监听器，分别对应Neo4j Browser（7474端口）和Bolt协议（7687端口），绑定了带ACM SSL证书的自定义域名
• 异常现象：可正常访问Neo4j Browser UI，且在Browser内能成功连接Bolt服务，但使用Python Driver连接Bolt端点时失败

错误日志 #

Traceback (most recent call last):
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_async_compat/network/_bolt_socket.py", line 694, in connect
    return BoltSocket._handshake(s, resolved_address, deadline)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_async_compat/network/_bolt_socket.py", line 641, in _handshake
    raise ServiceUnavailable(
neo4j.exceptions.ServiceUnavailable: Cannot to connect to Bolt service on ResolvedIPv4Address(('18.194.47.191', 7687)) (looks like HTTP)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/Downloads/neo.py", line 12, in <module>
    result = session.run("MATCH (n) RETURN n LIMIT 5")
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/work/session.py", line 302, in run
    self._connect(self._config.default_access_mode)
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/work/session.py", line 130, in _connect
    super()._connect(
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/work/workspace.py", line 182, in _connect
    self._connection = self._pool.acquire(**acquire_kwargs_)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/io/_pool.py", line 526, in acquire
    return self._acquire(
           ^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/io/_pool.py", line 313, in _acquire
    return connection_creator()
           ^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/io/_pool.py", line 163, in connection_creator
    connection = self.opener(
                 ^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/io/_pool.py", line 500, in opener
    return Bolt.open(
           ^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_sync/io/_bolt.py", line 403, in open
    BoltSocket.connect(
  File "/opt/homebrew/lib/python3.11/site-packages/neo4j/_async_compat/network/_bolt_socket.py", line 718, in connect
    raise ServiceUnavailable(
neo4j.exceptions.ServiceUnavailable: Couldn't connect to neo.mydomain.com:7687 (resolved to ()):
Cannot to connect to Bolt service on ResolvedIPv4Address(('18.456.47.191', 7687)) (looks like HTTP)
Cannot to connect to Bolt service on ResolvedIPv4Address(('52.456.141.61', 7687)) (looks like HTTP)

连接代码 #

from neo4j import GraphDatabase

uri = "bolt+s://neo.mydomain.com:7687"
username = "neo4j"
password = "password"

# Initialize the driver with SSL encryption
driver = GraphDatabase.driver(uri, auth=(username, password))

# Optional: Create a session to interact with the database
with driver.session() as session:
    result = session.run("MATCH (n) RETURN n LIMIT 5")
    for record in result:
        print(record)

# Remember to close the driver when done
driver.close() 

Docker Compose配置 #

services:
  neo4j:
    image: neo4j:5.18
    ports:
      - "7474:7474"
      - "7687:7687"
    restart: always
    environment:
      NEO4J_AUTH: "neo4j/password"
      NEO4J_PLUGINS: '["apoc"]'
      NEO4J_dbms_security_procedures_unrestricted: "apoc.*,gds.*"
      NEO4J_dbms_security_procedures_allowlist: "apoc.*,gds.*"
      NEO4J_apoc_export_file_enabled: "true"
      NEO4J_apoc_import_file_enabled: "true"
      NEO4J_server_bolt_listen__address: 0.0.0.0:7687
      NEO4J_server_default__listen__address: 0.0.0.0
      NEO4J_server_bolt_advertised__address: :7687
    volumes:
      - /neo4j_data/data:/data 
      - /neo4j_data/logs:/logs

解决方案 #

核心问题分析 #

错误提示looks like HTTP说明Python Driver连接7687端口时，收到的是HTTP响应而非Bolt协议握手数据——ALB的7687端口监听器配置错误，将Bolt流量当作HTTP处理。

具体修复步骤 #

1. 调整ALB监听器配置

   • 7687端口的监听器不能使用HTTP/HTTPS协议，需选择TCP协议（Bolt是基于TCP的自定义协议）
   • 目标组协议设置为TCP，端口映射到EC2的7687端口
   • ACM证书仅适用于HTTPS监听器，TCP监听器无需配置SSL；若需加密Bolt流量，可在Neo4j侧启用SSL，或使用ALB的TCP+SSL模式

2. 修正Neo4j配置

   • 更新NEO4J_server_bolt_advertised__address为自定义域名+端口：neo.mydomain.com:7687，确保客户端能正确识别Bolt服务地址
   • 若启用Bolt SSL，添加以下环境变量：

     NEO4J_server_bolt_enabled: "true"
     NEO4J_server_bolt_tls_level: "REQUIRED"
     NEO4J_server_ssl_certificate_file: "/path/to/certificate.crt"
     NEO4J_server_ssl_private_key_file: "/path/to/private.key"
     

3. 调整Python Driver连接参数

   • 若ALB使用TCP+SSL（ALB终止SSL），URI使用bolt+s://neo.mydomain.com:7687，并添加SSL验证参数：

     driver = GraphDatabase.driver(uri, auth=(username, password), encrypted=True, trust_all_certificates=True)
     

   • 若ALB仅转发TCP（Neo4j自身处理SSL），确保URI与Neo4j的SSL配置匹配

验证步骤 #

• 用telnet neo.mydomain.com 7687测试端口连通性
• 用openssl s_client -connect neo.mydomain.com:7687查看SSL握手情况（若启用SSL）
• 重新运行Python代码测试连接

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