Java-172 Neo4j 访问方式实战：嵌入式 vs 服务器（含 Java 示例与踩坑）

TL;DR

• 场景：在 Java 项目中选择 Neo4j 的访问形态，并完成本地嵌入式与远程 Server 的读写。
• 结论：3.5.x 可用嵌入式；生产推荐 Server + Java Driver（Bolt）；注意驱动与版本强绑定。
• 产出：可复用依赖与示例代码、版本选型矩阵、常见错误速查与修复清单。

版本矩阵

已验证	说明
是（基于文中示例）	Neo4j 3.5.x + 嵌入式：GraphDatabaseFactory().newEmbeddedDatabase(...) 可用；适合单机/工具型；不建议生产。存储目录为库目录（如 graph.db/），非单一文件。
是（基于文中示例）	Neo4j 3.5.x Server + Java 访问：通过 Bolt 访问远端 bolt://host:7687，示例已跑通。建议开启 TLS 并使用参数化查询。
未验证（建议升级）	Neo4j 4.x Server + Java Driver 4.x：推荐生产；不再支持社区嵌入式模式；需使用 neo4j-java-driver（非 OGM 驱动）。
未验证（建议生产）	Neo4j 5.x Server + Java Driver 5.x：长期支持线；协议/驱动强绑定，务必版本匹配；默认走加密通道与连接池配置。
视场景而定	OGM（对象图映射）：便于实体映射但维护成本更高；与纯 Driver 方案二选一，不建议混用。

访问方式

数据库访问

嵌入式数据库

嵌入式 Neo4j 数据库是将数据库引擎直接嵌入到应用程序中的运行模式，无需单独的服务器进程。这种模式通过指定数据库文件存储路径（如 data/graph.db）以编程方式直接访问数据库文件系统。

嵌入式数据库特别适合以下应用场景：

1. Java 技术栈项目

   • Neo4j 本身是用 Java 开发的
   • 嵌入式模式提供原生 Java API（如 GraphDatabaseService）
   • 示例：GraphDatabaseService graphDb = new GraphDatabaseFactory().newEmbeddedDatabase(new File("/path/to/database"));

2. 独立应用程序

   • 不需要网络通信的开销
   • 无需额外安装和管理数据库服务器
   • 打包部署简单（可包含在 JAR/WAR 文件中）
   • 典型用例：桌面应用、移动应用（如 Android）、单机版数据分析工具

3. 高性能需求场景

   • 消除网络延迟（本地直接访问）
   • 减少序列化/反序列化开销
   • 事务处理延迟低（微秒级响应）
   • 适用场景举例：
     • 高频交易系统
     • 实时推荐引擎
     • 大规模图计算任务

嵌入式模式通过以下方式实现高性能：

• 直接操作磁盘存储文件（如 neostore 文件系列）
• 利用 JVM 内存管理优化
• 支持 ACID 事务（通过 Transaction 接口）
• 可配置内存映射缓存策略# 嵌入式数据库详解：Neo4j 嵌入式模式

服务器模式

Neo4j Server 是部署 Neo4j 图数据库的最佳实践方案，特别适合对操作性、安全性和监控有较高要求的应用场景。作为独立运行的数据库服务器，它具有以下显著优势：

1. 跨平台与多语言支持：

• 提供标准的 RESTful API 接口，支持 HTTP/HTTPS 协议
• 兼容所有现代开发平台（Windows/Linux/macOS）
• 支持 30+ 种编程语言，包括 Java、Python、JavaScript、C#、Go 等
• 典型应用场景：Web 应用通过前端 JavaScript 直接调用，或后端服务通过对应语言 SDK 交互

2. 安全特性：

• 独立进程运行，与应用程序隔离，避免嵌入式模式的内存泄漏风险
• 支持基于角色的访问控制 (RBAC)
• 提供 TLS/SSL 加密传输
• 可配置防火墙规则和 IP 白名单
• 审计日志记录所有数据访问操作

3. 运维监控能力：

• 内置 JMX 监控接口
• 支持 Prometheus 指标采集
• 提供可视化监控仪表盘
• 可配置性能告警阈值
• 完善的日志管理系统

Java 访问

<dependency>
  <groupId>org.neo4j</groupId>
  <artifactId>neo4j</artifactId>
  <version>3.5.5</version>
</dependency>

嵌入式访问

package icu.wzk;
public class Demo01 {

    private static final File DATABASE = new File( "target/graph.db" );

    public static void main(String[] args) {
        GraphDatabaseService graphDb = new GraphDatabaseFactory().newEmbeddedDatabase(DATABASE);
        Transaction tx = graphDb.beginTx();
        Node n1 = graphDb.createNode();
        n1.setProperty("name", "wzk1");
        n1.setProperty("age", "18");
        n1.setProperty("money", "99");
        n1.addLabel(Label.label("Person"));
        String cql = "CREATE(person:Person {name: 'wzk2', age: 20, money: 10})";
        graphDb.execute(cql);
        tx.success();
        tx.close();
        System.out.println("Done!");
        graphDb.shutdown();
    }

}

执行结果如下：

查询数据如下：

package icu.wzk;
public class Demo02 {

    private static final File DATABASE = new File( "target/graph.db" );

    public static void main(String[] args) {
        GraphDatabaseService graphDb = new GraphDatabaseFactory().newEmbeddedDatabase(DATABASE);
        String cql = "MATCH(person:Person) return person";
        Transaction tx = graphDb.beginTx();
        Result result = graphDb.execute(cql);
        while (result.hasNext()) {
            Map<String, Object> row = result.next();
            for (String key : result.columns()) {
                Node nd = (Node) row.getOrDefault(key, null);
                System.out.println(key + " : " + nd.getProperty("money"));
            }
        }
        tx.success();
        tx.close();
        System.out.println("Done!");
        graphDb.shutdown();
    }

}

执行结果如下所示：

服务端访问

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-bolt-driver</artifactId>
    <version>3.2.10</version>
</dependency>

编写代码进行访问：

package icu.wzk;
import org.neo4j.driver.*;
import static org.neo4j.driver.Values.parameters;
public class Demo03 {

    public static void main(String[] args) {
        Config config = Config.builder()
                .withoutEncryption()
                .build();
        Driver driver = GraphDatabase.driver(
                "bolt://10.10.52.38:7687",
                AuthTokens.basic("neo4j", "123123"),
                config
        );
        Session session = driver.session();
        String cql = "MATCH(person:Person) where person.money > $money return person.name as name, person.money as money";
        Result result = session.run(cql, parameters("money", 3000));
        while (result.hasNext()) {
            Record record = result.next();
            System.out.println("name: " + record.get("name") + ", money: " + record.get("money"));
        }
    }

}

执行结果如下所示：

错误速查

症状	根因	定位	修复
ClientException: Unsupported protocol	驱动与 Server 主次版本不匹配	查看驱动/Server 版本与 Bolt 协议握手日志	统一到同代（4.x↔4.x、5.x↔5.x），升级 neo4j-java-driver
AuthenticationException	账户/密码错误或变更	:server user list、审计日志	正确配置 AuthTokens.basic；重置密码；避免明文写死
ServiceUnavailable / Connection refused	地址/端口或防火墙问题	ss -lntp、安全组/白名单	开放 7687/7474；VPC 与安全组放行；本机先 nc -vz host 7687
Neo4j is running with db lock	重复进程或崩溃遗留锁	进程列表、data/databases//neostore.	关闭所有进程；备份后清理锁；异常关闭后做一致性校验
嵌入式启动报"找不到存储文件/库结构不兼容"	指向了错误路径或版本跨读	校验存储目录层级与 store_id	使用对应版本的二进制；避免跨大版本直接打开旧库
NoSuchMethodError GraphDatabaseFactory	SDK 与核心包版本冲突	Maven 依赖树 mvn dependency:tree	锁定版本并排除传递冲突；保持 3.5.x 依赖一致
运行正常但查询结果为空/类型异常	属性类型不一致（字符串 vs 数值）	打印 result.columns() 与 record.get().type()	统一属性类型；写入时数值用数值类型，避免后续比较失败
明文 withoutEncryption() 存在风险	生产未启用 TLS	neo4j.conf 与驱动配置	打开 TLS（证书/信任策略），或至少内网专线并加 ACL
OGM 类缺失或映射失败	OGM 与 Java Driver 混用/注解缺失	运行时 ClassNotFound、扫描日志	二选一：全 OGM 或全 Driver；补齐实体注解与 SessionFactory

其他系列

🚀 AI篇持续更新中（长期更新）

AI炼丹日志-29 - 字节跳动 DeerFlow 深度研究框斜体样式架 私有部署 测试上手 架构研究 ，持续打造实用AI工具指南！
AI-调查研究-108-具身智能 机器人模型训练全流程详解：从预训练到强化学习与人类反馈
🔗 AI模块直达链接

💻 Java篇持续更新中（长期更新）

Java-154 深入浅出 MongoDB 用Java访问 MongoDB 数据库 从环境搭建到CRUD完整示例

MyBatis 已完结，Spring 已完结，Nginx已完结，Tomcat已完结，分布式服务正在更新！深入浅出助你打牢基础！
🔗 Java模块直达链接

📊 大数据板块已完成多项干货更新（300篇）：

包括 Hadoop、Hive、Kafka、Flink、ClickHouse、Elasticsearch 等二十余项核心组件，覆盖离线+实时数仓全栈！
大数据-278 Spark MLib - 基础介绍 机器学习算法 梯度提升树 GBDT案例 详解
🔗 大数据模块直达链接