Docker FastAPI连接Mac本地Neo4j报Connection Unavailable问询

Docker容器拥有独立的网络命名空间，代码中配置的bolt://127.0.0.1:7687在容器语境下指向的是容器自身的回环地址，而非Mac宿主机上运行的Neo4j服务，因此触发连接拒绝错误。

• 替换连接目标地址
  • 将原连接串中的127.0.0.1替换为Mac Docker内置的特殊域名host.docker.internal，最终连接地址为bolt://host.docker.internal:7687
  • 该域名会自动映射到宿主机的内网可达地址，无需手动查询、硬编码Mac的局域网IP，可避免Mac切换网络导致IP变动引发的连接失效
  • 推荐通过容器环境变量传入该配置，不要将地址硬编码到镜像内，减少后续调整配置时重新打包的成本
• 调整Neo4j监听规则
  • 打开Mac本地Neo4j的配置文件conf/neo4j.conf，将Bolt服务的监听地址从默认的127.0.0.1:7687修改为0.0.0.0:7687
  • 重启本地Neo4j服务让配置生效，默认的回环地址监听只会接受宿主机本地的连接请求，会拒绝Docker网段的访问
• 容器启动参数配置
  • 较新版本的Mac Docker Desktop已默认支持host.docker.internal的解析，直接运行原镜像即可
  • 旧版本Docker可在启动命令中补充host映射参数：

    docker run --add-host=host.docker.internal:host-gateway e7bf302e02ec
    

• 不要尝试使用Linux环境常用的--network=host模式启动容器：Mac版Docker的host网络实现和Linux原生环境不同，该模式无法让容器直接复用Mac的网络栈，无法解决连通性问题
• 检查Mac系统防火墙规则：如果开启了系统防火墙，需要放行Neo4j的7687端口的入站连接，否则即使网络配置正确，依然会被防火墙拦截请求
• 无需调整Neo4j的7474 Web端口配置，容器与Neo4j的通信仅依赖Bolt协议的7687端口即可

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