简介neo4j-chs-community-5.23.0-windows.zip 是面向图数据库初学者、应用开发者与运维人员的 Windows 社区版压缩包用于在本地搭建 Neo4j 图数据库环境理解节点、关系及属性构成的图模型并用 Cypher 完成图数据查询与可视化探索。压缩包共 264 个文件约 119.26MB以 235 个 jar 运行库为核心配合 bat 与 ps1 启停和管理脚本、conf 配置、exe 服务组件及证书和说明文本构成较完整的 Windows 运行目录。已有 527 人学习下载。借助其中的依赖库、管理脚本与配置样例读者可完成本地部署、服务启停、连接配置和基础查询练习并对照浏览器组件观察图数据结果适合作为图数据库入门、课程实验与小型项目验证的环境底包。1. 从一张关系表到图查询为什么 Windows 上要备一个 Neo4j 5.23 社区版做权限校验或反欺诈关系链时用关系型数据库写三度好友查询SQL 里叠三层 JOIN索引一多优化器就开始摆烂。Neo4j 数据库这类图数据库把关系存成指针多跳遍历不用回头扫表。这个 zip 包是 Neo4j 5.23.0 社区版的 Windows 构建解压后 bin、conf、data、import 都在不写注册表适合在本地开发机快速铺一套图环境做知识图谱、组织关系、商品关联的验证。社区版不含集群和企业级热备单机开发和小数据量验证够用如果你正在 Windows 上找一套能直接跑 Cypher 的图数据库这个包就是冲这个场景来的。2. 解压即用之前Windows 下的目录、JDK 与启动参数2.1 zip 包和 installer 的差别以及目录里哪些东西不能删Windows 上装 Neo4j 常见两条路installer 和 zip。installer 会注册系统服务、写注册表、开机自启适合长期挂在一台机器上跑zip 包解压就能用卸载就是删目录同一个盘里放两个版本也不会打架。做开发验证、临时压测、给同事演示我一般选 zip因为不污染系统环境出问题直接删掉重来不用去服务列表里清残留。这个包的顶层目录不是随便摆的删错一个文件可能启动不了或者丢数据。下面这张表是实际拆包后最该先认的几项目录/文件作用能不能删常见误操作bin启动脚本neo4j.bat、管理工具neo4j-admin.bat不能删把neo4j.bat单独拷走路径找不到confneo4j.conf、日志配置不能删改端口拼错参数启动直接退出datadatabases图数据、transactions事务日志、dbms/auth密码文件不能删只备份databases恢复后密码对不上importLOAD CSV默认根目录可以清空CSV 放在桌面报找不到文件pluginsAPOC 等插件 jar可以空着插件版本和 5.23 不匹配启动报类冲突logsneo4j.log、debug.log可以清排查时只看控制台不看日志尾巴licenses许可文件别动无data/dbms/auth是密码文件data/databases是图数据本体data/transactions是事务日志。备份的时候这三个要一起带走只拷databases恢复出来可能登录不了或者事务状态不一致。这是血泪经验后面第 6 章还会落到具体命令。2.2 配 JDK 17 与两个必须改的 conf 参数Neo4j 5 跑在 Java 17 上机器上如果同时有 Java 8 或 11最容易翻车的是JAVA_HOME指错。先开 PowerShell 确认java -version echo $env:JAVA_HOME第一行输出必须是 17.x如果输出 1.8 或 11说明 Path 里排在前面的不是 JDK 17。JAVA_HOME要指向 JDK 根目录不是bin目录。临时切一下$env:JAVA_HOME C:\Program Files\Java\jdk-17 $env:Path $env:JAVA_HOME\bin; $env:Path java -version这三行的逻辑是先把JAVA_HOME指到 JDK 17 根目录再把它的bin插到 Path 最前面最后重新检查版本。永久生效就去系统环境变量里改不要写注册表脚本后面换 JDK 21 也方便。参数上唯一要注意的是路径里不要有中文和空格之外的奇怪符号Program Files的空格是允许的但手写引号别丢。接着改conf/neo4j.conf。开发机最少改这几行server.default_listen_address127.0.0.1 server.bolt.listen_address:7687 server.http.listen_address:7474 server.memory.heap.initial_size2G server.memory.heap.max_size2G server.memory.pagecache.size1Gserver.default_listen_address127.0.0.1表示只监听本机局域网里其它机器连不上开发环境这样最省心。如果你确实要让同事连再改成0.0.0.0并配好防火墙别一上来就全网开放。server.bolt.listen_address是驱动走的 7687server.http.listen_address是 Browser 走的 7474。内存三行后面第 4 章会展开这里先给一个能跑的起步值heap 初始和最大设成一样避免运行时反复伸缩pagecache 先给 1G数据量大了再按实际 store 大小加。启动用前台模式日志直接打屏第一次排错最直观cd D:\neo4j-chs-community-5.23.0 .\bin\neo4j.bat consoleconsole是前台启动关掉窗口就停start是后台启动stop是停止。启动成功的标志是日志最后出现Started。如果报Unable to find any JVMs matching version回到JAVA_HOME检查如果报Address already in use说明 7474 或 7687 被占了排查方法在第 5 章。再开一个 PowerShell 确认端口真的在听netstat -ano | findstr :7474 netstat -ano | findstr :7687输出里出现LISTENING才算起来最后一列是 PID可以用tasklist /FI PID eq 那个PID看是不是java.exe。如果 7474 没有但 7687 有说明 HTTP 被别的服务占了改server.http.listen_address:7475再重启。2.3 首次登录与 Browser 里的三个自检命令浏览器打开http://localhost:7474默认用户名neo4j初始密码neo4j。第一次登录会强制改密改完记牢。登录进去先别急着建数据跑三个自检命令确认版本、库状态和内存参数CALL dbms.components() YIELD name, versions, edition RETURN name, versions, edition; SHOW DATABASES; CALL dbms.listConfig() YIELD name, value WHERE name CONTAINS memory RETURN name, value;dbms.components()看版本号和edition是不是community确认拿到的是社区版SHOW DATABASES看默认库neo4j是否online社区版通常只有system和neo4j两个库别去执行CREATE DATABASE会报权限或版本限制dbms.listConfig()过滤memory看刚才改的 heap 和 pagecache 有没有生效。三条都正常这套环境就算铺好了接下来才轮到图模型和数据导入。3. 图模型落地从 CSV 到节点、关系和约束3.1 先定标签和关系类型再写 LOAD CSV图建模不是把关系表原样搬进来。标签表达实体类别关系类型用动词属性只放过滤和返回会用到的字段。比如用户关注用户User是标签FOLLOWS是关系类型用户买商品如果订单本身要被售后、物流引用就把订单建成节点如果只是连接建成关系更轻。下面这张表是常见拆法业务对象标签/关系关键属性建模理由用户:Userid、name、cityid做唯一约束city做过滤索引商品:Productid、title、price商品独立查询多建节点关注(:User)-[:FOLLOWS]-(:User)since关系本身带时间不需要中间节点购买(:User)-[:BUY]-(:Product)count、last_time轻量关系避免订单节点膨胀先把这张表写在纸上再决定 CSV 的列。很多导入失败不是 Cypher 写错是 CSV 列名和row.xxx对不上或者关系两头的主键在节点文件里不存在。常见做法是节点 CSV 和关系 CSV 分开节点先导关系后导关系文件只放from_id、to_id和关系属性。3.2 约束和索引先建再灌数据约束不只是防重复它会在背后建索引MERGE能不能走索引全看这一步。导入前先跑CREATE CONSTRAINT user_id_unique IF NOT EXISTS FOR (u:User) REQUIRE u.id IS UNIQUE; CREATE CONSTRAINT product_id_unique IF NOT EXISTS FOR (p:Product) REQUIRE p.id IS UNIQUE; CREATE INDEX user_city_idx IF NOT EXISTS FOR (u:User) ON (u.city);IF NOT EXISTS让脚本可以重复执行不会因为约束已存在而中断。唯一约束会自动附带索引所以MERGE (u:User {id: row.id})才能按 id 直接定位而不是全表扫。user_city_idx是给WHERE u.city 城市A这种过滤用的低基数字段比如性别、布尔标记不建议建优化器大概率不用反而增加写入开销。建完用SHOW CONSTRAINTS;和SHOW INDEXES;确认状态是ONLINE。3.3 LOAD CSV 的两段式导入与分批提交CSV 必须放在import目录下file:///users.csv这个写法里的/是相对import的根不是 Windows 盘符。准备一个节点文件id,name,city u001,用户A,城市A u002,用户B,城市B导入节点LOAD CSV WITH HEADERS FROM file:///users.csv AS row MERGE (u:User {id: row.id}) ON CREATE SET u.name row.name, u.city row.city ON MATCH SET u.name row.name, u.city row.city RETURN count(u);WITH HEADERS表示第一行是列名后面用row.id取值MERGE依赖唯一约束走索引存在就匹配、不存在就创建ON CREATE和ON MATCH分开写重复导入时只更新属性不会造出第二个节点。别用CREATE同一个文件跑两遍就会多出一倍节点。RETURN count(u)是确认这次实际处理了多少行数字对不上先查 CSV 有没有空行。关系文件from_id,to_id,since u001,u002,2024-01-01导入关系LOAD CSV WITH HEADERS FROM file:///follows.csv AS row MATCH (a:User {id: row.from_id}) MATCH (b:User {id: row.to_id}) MERGE (a)-[r:FOLLOWS]-(b) ON CREATE SET r.since row.since RETURN count(r);关系导入必须先MATCH两端节点再MERGE关系不能直接MERGE (a:User {id: row.from_id})-[r:FOLLOWS]-(b:User {id: row.to_id})否则两端主键不存在时会凭空造出只有 id 的空节点。since现在按字符串存要做日期范围查询就用date(row.since)转一下或者导入时直接SET r.since date(row.since)。数据量上一万行以后单条LOAD CSV默认一个事务提交堆会抖日志里能看到 GC 字样。用 Neo4j 5 的子查询事务分批LOAD CSV WITH HEADERS FROM file:///users.csv AS row CALL { WITH row MERGE (u:User {id: row.id}) SET u.name row.name, u.city row.city } IN TRANSACTIONS OF 1000 ROWS;IN TRANSACTIONS OF 1000 ROWS表示每 1000 行提交一次降低单事务内存压力。注意子查询里不要写RETURN外层也不要再包RETURN count分批提交的计数要看日志或导入后自己MATCH统计。首次全量导入如果数据量很大更稳的是停库后用neo4j-admin database import做离线导入这个放在第 6 章一起说。导入完做两个验证MATCH (n) RETURN labels(n) AS label, count(*) AS cnt ORDER BY cnt DESC; MATCH ()-[r]-() RETURN type(r) AS rel, count(*) AS cnt ORDER BY cnt DESC;第一条看各标签节点数第二条看各关系类型数量。再跑一个两跳查询确认连通MATCH (a:User {id: u001})-[:FOLLOWS*1..2]-(b:User) RETURN a.id, b.id;如果这里返回空先查关系 CSV 的from_id、to_id是不是和节点文件里的 id 完全一致大小写、前后空格都算差异。4. 查询计划与内存参数把慢查询钉在 EXPLAIN 上4.1 EXPLAIN 和 PROFILE 的差别先看计划再跑数EXPLAIN只编译不执行适合看优化器选了哪个索引PROFILE会真的跑一遍给出每个算子的实际行数和 db hits。两个都跑同一个查询EXPLAIN MATCH (u:User {id: u001})-[:FOLLOWS*1..3]-(v:User) RETURN v.id, v.name; PROFILE MATCH (u:User {id: u001})-[:FOLLOWS*1..3]-(v:User) RETURN v.id, v.name;看计划时重点盯三类算子AllNodesScan表示全表扫节点说明过滤字段没索引NodeIndexSeek才是走索引Expand(All)是沿关系扩展行数突然变大说明路径爆炸。可变长度路径一定要写上上限*1..3比*安全后者在稠密图里可能把内存打满。PROFILE的 db hits 高不一定是内存不够先看是不是扫了太多节点补索引比加堆更有效。4.2 索引怎么选单属性、复合、全文单属性索引适合等值、范围过滤复合索引的顺序很关键(city, age)能服务city和city age但服务不了单独age全文索引给CONTAINS或模糊检索用和普通 B 树索引不是一回事。CREATE INDEX user_name_idx IF NOT EXISTS FOR (u:User) ON (u.name); CREATE INDEX user_city_age_idx IF NOT EXISTS FOR (u:User) ON (u.city, u.age); CREATE FULLTEXT INDEX user_name_fulltext IF NOT EXISTS FOR (u:User) ON EACH [u.name, u.bio];前两个是普通索引第三个是全文索引。全文索引查询要换写法CALL db.index.fulltext.queryNodes(user_name_fulltext, 用户A) YIELD node, score RETURN node.id, node.name, score ORDER BY score DESC;queryNodes第一个参数是索引名第二个是检索词score是相关度。普通索引对CONTAINS不生效别看到CONTAINS慢就怪索引没建先确认建的是全文索引。低基数字段比如gender不要单独建索引优化器可能直接忽略写入反而多一层维护。4.3 neo4j.conf 里三个内存参数与 memory-recommendationNeo4j 5 自带内存建议命令先让工具按机器内存给个数.\bin\neo4j-admin.bat server memory-recommendation --memory8G--memory8G是给 Neo4j 进程的总内存上限不是物理内存总量。输出会分别给 heap 和 pagecache 的建议值把结果写回conf/neo4j.conf。Windows 下用neo4j-admin.batLinux 下才是无后缀的neo4j-admin。三个参数的关系server.memory.heap.initial_size2G server.memory.heap.max_size2G server.memory.pagecache.size1Gheap 初始和最大设成一样避免运行中反复扩缩pagecache 尽量覆盖data/databases下 store 文件的大小图数据全在内存里遍历才快heap 不要超过物理内存的 70%留空间给操作系统文件缓存。改完重启用下面这条确认生效CALL dbms.listConfig() YIELD name, value WHERE name STARTS WITH server.memory RETURN name, value;如果查询慢但 db hits 不高再看是不是 pagecache 太小导致频繁读盘如果 db hits 很高回到PROFILE补索引别一味加堆。正在跑的慢查询可以用CALL dbms.listQueries()看必要时CALL dbms.killQuery(query-id)杀掉但生产环境别随手杀先确认它是不是在写数据。5. 避坑与排查Windows 下跑 Neo4j 最常翻车的五件事5.1 启动类端口占用、JAVA_HOME 指错、服务重复注册现象一启动日志报Address already in use: bindBrowser 打不开。原因通常是上一次console窗口没关或者 7474/7687 被别的服务占了。先查端口netstat -ano | findstr :7474 netstat -ano | findstr :7687 tasklist /FI PID eq 1234最后一列 PID 拿去tasklist确认是不是java.exe。如果是残留的 Neo4jtaskkill /PID 1234 /F杀掉再启动如果是别的服务改conf里的端口比如server.http.listen_address:7475别硬杀不认识的进程。现象二启动报UnsupportedClassVersionError或Unable to find any JVMs matching version。原因是JAVA_HOME指向 Java 8/11或者指向了bin目录。解决就是第 2 章那三行JAVA_HOME指 JDK 17 根目录Path 里%JAVA_HOME%\bin放最前面重开 PowerShell 再java -version。现象三neo4j.bat start报服务已存在或者启动后两个实例抢端口。原因是之前用 installer 装过或者多次执行过neo4j.bat install-service。先清旧服务.\bin\neo4j.bat uninstall-service .\bin\neo4j.bat console开发机我一般不用 Windows 服务直接console前台跑关窗口就停省得服务列表里留一堆同名项。5.2 数据类LOAD CSV 找不到文件、约束冲突、导入事务过大现象四LOAD CSV报Couldnt load the external resource at: file:///xxx.csv。原因有两个CSV 没放import目录或者写了C:\Users\...这种 Windows 绝对路径。file:///后面跟的是相对import的路径把文件放到import/users.csv用file:///users.csv。确实要读绝对路径得在conf里开dbms.security.allow_csv_import_from_file_urlstrue开发环境不建议开容易把整盘暴露给 Cypher。现象五导入报Node already exists with label User and property id。原因是唯一约束已经存在CSV 里同一个 id 出现多次或者你先CREATE再MERGE混用了。先查重MATCH (u:User {id: u001}) RETURN u;清洗 CSV 保证 id 唯一导入语句统一用MERGE更新属性用ON MATCH SET不要用CREATE硬怼。现象六导入几万行后卡住日志出现 GC overhead 甚至 OOM。原因是单条LOAD CSV默认一个事务所有行一次提交。改成子查询分批LOAD CSV WITH HEADERS FROM file:///users.csv AS row CALL { WITH row MERGE (u:User {id: row.id}) SET u.name row.name, u.city row.city } IN TRANSACTIONS OF 1000 ROWS;首次全量数据更大就停库走离线导入.\bin\neo4j.bat stop .\bin\neo4j-admin.bat database import full --nodesimport/users.csv --relationshipsimport/follows.csv neo4j .\bin\neo4j.bat start离线导入要求目标库为空导入前确认data/databases/neo4j没有旧数据或者换一个库名。命令里的full表示全量导入CSV 表头要符合neo4j-admin的格式约定和在线LOAD CSV的列名不完全一样第一次跑先用小文件试。5.3 运维类忘记密码、备份文件锁、配置改错启动失败现象七登录一直提示 unauthorized密码想不起来。停库后删掉data/dbms/auth重启会恢复默认neo4j/neo4j再改新密码.\bin\neo4j.bat stop Remove-Item .\data\dbms\auth .\bin\neo4j.bat console删auth会丢所有用户和角色只适合本地开发库。更稳的做法是首次启动前用neo4j-admin dbms set-initial-password设初始密码但已经跑起来的库还是得走删除重置。现象八neo4j-admin database dump报数据库正在使用。原因是数据库没停文件被 java 进程占着。先neo4j.bat stop用tasklist | findstr java确认没有残留再 dump。dump 完再start。冷备必须停库社区版没有企业级在线热备别在跑着写入的时候拷data/databases拷出来大概率不一致。现象九改完conf启动直接退出日志报Unrecognized setting。原因是参数名拼错或者把 4.x 的旧参数抄进来了。Neo4j 5 的连接器参数是server.bolt.listen_address不是 4.x 的dbms.connector.bolt.listen_address。改配置前先备份neo4j.conf启动失败看logs/neo4j.log第一行报错回滚到上一版再逐项加。6. 冷备份验证别等数据丢了才第一次跑 dump备份这件事最怕的是“文件生成了但没验证过”。我习惯在每次改完conf或者导完一批数据之后做一次停机冷备然后立刻 load 到临时目录验证确认文件不是空的、能恢复。命令不复杂顺序不能错.\bin\neo4j.bat stop .\bin\neo4j-admin.bat database dump neo4j --to-path.\backup .\bin\neo4j.bat startdatabase dump第一个参数是库名社区版默认库叫neo4j--to-path是备份输出目录执行前先建好。dump 要求数据库停止跑完看backup下有没有.dump文件大小是否和data/databases/neo4j的量级匹配。恢复验证用.\bin\neo4j.bat stop .\bin\neo4j-admin.bat database load neo4j --from-path.\backup --overwrite-destinationtrue .\bin\neo4j.bat start--overwrite-destinationtrue会覆盖当前库所以验证时要么确认当前库可以丢要么先把当前库再 dump 一份。load 同样要求停库。恢复后进 Browser 跑一句MATCH (n) RETURN count(n);数字和备份前对得上才算过。检查项备份前恢复后节点总数MATCH (n) RETURN count(n);数字一致关系总数MATCH ()-[r]-() RETURN count(r);数字一致约束/索引SHOW CONSTRAINTS;状态ONLINE登录密码当前密码可用同一密码可登录从那以后我每次动完配置或导完数据都强制跑一遍 dump load 到临时目录确认备份文件不是黑匣子。希望帮到你。本文还有配套的精品资源点击获取
简介neo4j-chs-community-5.23.0-windows.zip 是面向图数据库初学者、应用开发者与运维人员的 Windows 社区版压缩包用于在本地搭建 Neo4j 图数据库环境理解节点、关系及属性构成的图模型并用 Cypher 完成图数据查询与可视化探索。压缩包共 264 个文件约 119.26MB以 235 个 jar 运行库为核心配合 bat 与 ps1 启停和管理脚本、conf 配置、exe 服务组件及证书和说明文本构成较完整的 Windows 运行目录。已有 527 人学习下载。借助其中的依赖库、管理脚本与配置样例读者可完成本地部署、服务启停、连接配置和基础查询练习并对照浏览器组件观察图数据结果适合作为图数据库入门、课程实验与小型项目验证的环境底包。1. 从一张关系表到图查询为什么 Windows 上要备一个 Neo4j 5.23 社区版做权限校验或反欺诈关系链时用关系型数据库写三度好友查询SQL 里叠三层 JOIN索引一多优化器就开始摆烂。Neo4j 数据库这类图数据库把关系存成指针多跳遍历不用回头扫表。这个 zip 包是 Neo4j 5.23.0 社区版的 Windows 构建解压后 bin、conf、data、import 都在不写注册表适合在本地开发机快速铺一套图环境做知识图谱、组织关系、商品关联的验证。社区版不含集群和企业级热备单机开发和小数据量验证够用如果你正在 Windows 上找一套能直接跑 Cypher 的图数据库这个包就是冲这个场景来的。2. 解压即用之前Windows 下的目录、JDK 与启动参数2.1 zip 包和 installer 的差别以及目录里哪些东西不能删Windows 上装 Neo4j 常见两条路installer 和 zip。installer 会注册系统服务、写注册表、开机自启适合长期挂在一台机器上跑zip 包解压就能用卸载就是删目录同一个盘里放两个版本也不会打架。做开发验证、临时压测、给同事演示我一般选 zip因为不污染系统环境出问题直接删掉重来不用去服务列表里清残留。这个包的顶层目录不是随便摆的删错一个文件可能启动不了或者丢数据。下面这张表是实际拆包后最该先认的几项目录/文件作用能不能删常见误操作bin启动脚本neo4j.bat、管理工具neo4j-admin.bat不能删把neo4j.bat单独拷走路径找不到confneo4j.conf、日志配置不能删改端口拼错参数启动直接退出datadatabases图数据、transactions事务日志、dbms/auth密码文件不能删只备份databases恢复后密码对不上importLOAD CSV默认根目录可以清空CSV 放在桌面报找不到文件pluginsAPOC 等插件 jar可以空着插件版本和 5.23 不匹配启动报类冲突logsneo4j.log、debug.log可以清排查时只看控制台不看日志尾巴licenses许可文件别动无data/dbms/auth是密码文件data/databases是图数据本体data/transactions是事务日志。备份的时候这三个要一起带走只拷databases恢复出来可能登录不了或者事务状态不一致。这是血泪经验后面第 6 章还会落到具体命令。2.2 配 JDK 17 与两个必须改的 conf 参数Neo4j 5 跑在 Java 17 上机器上如果同时有 Java 8 或 11最容易翻车的是JAVA_HOME指错。先开 PowerShell 确认java -version echo $env:JAVA_HOME第一行输出必须是 17.x如果输出 1.8 或 11说明 Path 里排在前面的不是 JDK 17。JAVA_HOME要指向 JDK 根目录不是bin目录。临时切一下$env:JAVA_HOME C:\Program Files\Java\jdk-17 $env:Path $env:JAVA_HOME\bin; $env:Path java -version这三行的逻辑是先把JAVA_HOME指到 JDK 17 根目录再把它的bin插到 Path 最前面最后重新检查版本。永久生效就去系统环境变量里改不要写注册表脚本后面换 JDK 21 也方便。参数上唯一要注意的是路径里不要有中文和空格之外的奇怪符号Program Files的空格是允许的但手写引号别丢。接着改conf/neo4j.conf。开发机最少改这几行server.default_listen_address127.0.0.1 server.bolt.listen_address:7687 server.http.listen_address:7474 server.memory.heap.initial_size2G server.memory.heap.max_size2G server.memory.pagecache.size1Gserver.default_listen_address127.0.0.1表示只监听本机局域网里其它机器连不上开发环境这样最省心。如果你确实要让同事连再改成0.0.0.0并配好防火墙别一上来就全网开放。server.bolt.listen_address是驱动走的 7687server.http.listen_address是 Browser 走的 7474。内存三行后面第 4 章会展开这里先给一个能跑的起步值heap 初始和最大设成一样避免运行时反复伸缩pagecache 先给 1G数据量大了再按实际 store 大小加。启动用前台模式日志直接打屏第一次排错最直观cd D:\neo4j-chs-community-5.23.0 .\bin\neo4j.bat consoleconsole是前台启动关掉窗口就停start是后台启动stop是停止。启动成功的标志是日志最后出现Started。如果报Unable to find any JVMs matching version回到JAVA_HOME检查如果报Address already in use说明 7474 或 7687 被占了排查方法在第 5 章。再开一个 PowerShell 确认端口真的在听netstat -ano | findstr :7474 netstat -ano | findstr :7687输出里出现LISTENING才算起来最后一列是 PID可以用tasklist /FI PID eq 那个PID看是不是java.exe。如果 7474 没有但 7687 有说明 HTTP 被别的服务占了改server.http.listen_address:7475再重启。2.3 首次登录与 Browser 里的三个自检命令浏览器打开http://localhost:7474默认用户名neo4j初始密码neo4j。第一次登录会强制改密改完记牢。登录进去先别急着建数据跑三个自检命令确认版本、库状态和内存参数CALL dbms.components() YIELD name, versions, edition RETURN name, versions, edition; SHOW DATABASES; CALL dbms.listConfig() YIELD name, value WHERE name CONTAINS memory RETURN name, value;dbms.components()看版本号和edition是不是community确认拿到的是社区版SHOW DATABASES看默认库neo4j是否online社区版通常只有system和neo4j两个库别去执行CREATE DATABASE会报权限或版本限制dbms.listConfig()过滤memory看刚才改的 heap 和 pagecache 有没有生效。三条都正常这套环境就算铺好了接下来才轮到图模型和数据导入。3. 图模型落地从 CSV 到节点、关系和约束3.1 先定标签和关系类型再写 LOAD CSV图建模不是把关系表原样搬进来。标签表达实体类别关系类型用动词属性只放过滤和返回会用到的字段。比如用户关注用户User是标签FOLLOWS是关系类型用户买商品如果订单本身要被售后、物流引用就把订单建成节点如果只是连接建成关系更轻。下面这张表是常见拆法业务对象标签/关系关键属性建模理由用户:Userid、name、cityid做唯一约束city做过滤索引商品:Productid、title、price商品独立查询多建节点关注(:User)-[:FOLLOWS]-(:User)since关系本身带时间不需要中间节点购买(:User)-[:BUY]-(:Product)count、last_time轻量关系避免订单节点膨胀先把这张表写在纸上再决定 CSV 的列。很多导入失败不是 Cypher 写错是 CSV 列名和row.xxx对不上或者关系两头的主键在节点文件里不存在。常见做法是节点 CSV 和关系 CSV 分开节点先导关系后导关系文件只放from_id、to_id和关系属性。3.2 约束和索引先建再灌数据约束不只是防重复它会在背后建索引MERGE能不能走索引全看这一步。导入前先跑CREATE CONSTRAINT user_id_unique IF NOT EXISTS FOR (u:User) REQUIRE u.id IS UNIQUE; CREATE CONSTRAINT product_id_unique IF NOT EXISTS FOR (p:Product) REQUIRE p.id IS UNIQUE; CREATE INDEX user_city_idx IF NOT EXISTS FOR (u:User) ON (u.city);IF NOT EXISTS让脚本可以重复执行不会因为约束已存在而中断。唯一约束会自动附带索引所以MERGE (u:User {id: row.id})才能按 id 直接定位而不是全表扫。user_city_idx是给WHERE u.city 城市A这种过滤用的低基数字段比如性别、布尔标记不建议建优化器大概率不用反而增加写入开销。建完用SHOW CONSTRAINTS;和SHOW INDEXES;确认状态是ONLINE。3.3 LOAD CSV 的两段式导入与分批提交CSV 必须放在import目录下file:///users.csv这个写法里的/是相对import的根不是 Windows 盘符。准备一个节点文件id,name,city u001,用户A,城市A u002,用户B,城市B导入节点LOAD CSV WITH HEADERS FROM file:///users.csv AS row MERGE (u:User {id: row.id}) ON CREATE SET u.name row.name, u.city row.city ON MATCH SET u.name row.name, u.city row.city RETURN count(u);WITH HEADERS表示第一行是列名后面用row.id取值MERGE依赖唯一约束走索引存在就匹配、不存在就创建ON CREATE和ON MATCH分开写重复导入时只更新属性不会造出第二个节点。别用CREATE同一个文件跑两遍就会多出一倍节点。RETURN count(u)是确认这次实际处理了多少行数字对不上先查 CSV 有没有空行。关系文件from_id,to_id,since u001,u002,2024-01-01导入关系LOAD CSV WITH HEADERS FROM file:///follows.csv AS row MATCH (a:User {id: row.from_id}) MATCH (b:User {id: row.to_id}) MERGE (a)-[r:FOLLOWS]-(b) ON CREATE SET r.since row.since RETURN count(r);关系导入必须先MATCH两端节点再MERGE关系不能直接MERGE (a:User {id: row.from_id})-[r:FOLLOWS]-(b:User {id: row.to_id})否则两端主键不存在时会凭空造出只有 id 的空节点。since现在按字符串存要做日期范围查询就用date(row.since)转一下或者导入时直接SET r.since date(row.since)。数据量上一万行以后单条LOAD CSV默认一个事务提交堆会抖日志里能看到 GC 字样。用 Neo4j 5 的子查询事务分批LOAD CSV WITH HEADERS FROM file:///users.csv AS row CALL { WITH row MERGE (u:User {id: row.id}) SET u.name row.name, u.city row.city } IN TRANSACTIONS OF 1000 ROWS;IN TRANSACTIONS OF 1000 ROWS表示每 1000 行提交一次降低单事务内存压力。注意子查询里不要写RETURN外层也不要再包RETURN count分批提交的计数要看日志或导入后自己MATCH统计。首次全量导入如果数据量很大更稳的是停库后用neo4j-admin database import做离线导入这个放在第 6 章一起说。导入完做两个验证MATCH (n) RETURN labels(n) AS label, count(*) AS cnt ORDER BY cnt DESC; MATCH ()-[r]-() RETURN type(r) AS rel, count(*) AS cnt ORDER BY cnt DESC;第一条看各标签节点数第二条看各关系类型数量。再跑一个两跳查询确认连通MATCH (a:User {id: u001})-[:FOLLOWS*1..2]-(b:User) RETURN a.id, b.id;如果这里返回空先查关系 CSV 的from_id、to_id是不是和节点文件里的 id 完全一致大小写、前后空格都算差异。4. 查询计划与内存参数把慢查询钉在 EXPLAIN 上4.1 EXPLAIN 和 PROFILE 的差别先看计划再跑数EXPLAIN只编译不执行适合看优化器选了哪个索引PROFILE会真的跑一遍给出每个算子的实际行数和 db hits。两个都跑同一个查询EXPLAIN MATCH (u:User {id: u001})-[:FOLLOWS*1..3]-(v:User) RETURN v.id, v.name; PROFILE MATCH (u:User {id: u001})-[:FOLLOWS*1..3]-(v:User) RETURN v.id, v.name;看计划时重点盯三类算子AllNodesScan表示全表扫节点说明过滤字段没索引NodeIndexSeek才是走索引Expand(All)是沿关系扩展行数突然变大说明路径爆炸。可变长度路径一定要写上上限*1..3比*安全后者在稠密图里可能把内存打满。PROFILE的 db hits 高不一定是内存不够先看是不是扫了太多节点补索引比加堆更有效。4.2 索引怎么选单属性、复合、全文单属性索引适合等值、范围过滤复合索引的顺序很关键(city, age)能服务city和city age但服务不了单独age全文索引给CONTAINS或模糊检索用和普通 B 树索引不是一回事。CREATE INDEX user_name_idx IF NOT EXISTS FOR (u:User) ON (u.name); CREATE INDEX user_city_age_idx IF NOT EXISTS FOR (u:User) ON (u.city, u.age); CREATE FULLTEXT INDEX user_name_fulltext IF NOT EXISTS FOR (u:User) ON EACH [u.name, u.bio];前两个是普通索引第三个是全文索引。全文索引查询要换写法CALL db.index.fulltext.queryNodes(user_name_fulltext, 用户A) YIELD node, score RETURN node.id, node.name, score ORDER BY score DESC;queryNodes第一个参数是索引名第二个是检索词score是相关度。普通索引对CONTAINS不生效别看到CONTAINS慢就怪索引没建先确认建的是全文索引。低基数字段比如gender不要单独建索引优化器可能直接忽略写入反而多一层维护。4.3 neo4j.conf 里三个内存参数与 memory-recommendationNeo4j 5 自带内存建议命令先让工具按机器内存给个数.\bin\neo4j-admin.bat server memory-recommendation --memory8G--memory8G是给 Neo4j 进程的总内存上限不是物理内存总量。输出会分别给 heap 和 pagecache 的建议值把结果写回conf/neo4j.conf。Windows 下用neo4j-admin.batLinux 下才是无后缀的neo4j-admin。三个参数的关系server.memory.heap.initial_size2G server.memory.heap.max_size2G server.memory.pagecache.size1Gheap 初始和最大设成一样避免运行中反复扩缩pagecache 尽量覆盖data/databases下 store 文件的大小图数据全在内存里遍历才快heap 不要超过物理内存的 70%留空间给操作系统文件缓存。改完重启用下面这条确认生效CALL dbms.listConfig() YIELD name, value WHERE name STARTS WITH server.memory RETURN name, value;如果查询慢但 db hits 不高再看是不是 pagecache 太小导致频繁读盘如果 db hits 很高回到PROFILE补索引别一味加堆。正在跑的慢查询可以用CALL dbms.listQueries()看必要时CALL dbms.killQuery(query-id)杀掉但生产环境别随手杀先确认它是不是在写数据。5. 避坑与排查Windows 下跑 Neo4j 最常翻车的五件事5.1 启动类端口占用、JAVA_HOME 指错、服务重复注册现象一启动日志报Address already in use: bindBrowser 打不开。原因通常是上一次console窗口没关或者 7474/7687 被别的服务占了。先查端口netstat -ano | findstr :7474 netstat -ano | findstr :7687 tasklist /FI PID eq 1234最后一列 PID 拿去tasklist确认是不是java.exe。如果是残留的 Neo4jtaskkill /PID 1234 /F杀掉再启动如果是别的服务改conf里的端口比如server.http.listen_address:7475别硬杀不认识的进程。现象二启动报UnsupportedClassVersionError或Unable to find any JVMs matching version。原因是JAVA_HOME指向 Java 8/11或者指向了bin目录。解决就是第 2 章那三行JAVA_HOME指 JDK 17 根目录Path 里%JAVA_HOME%\bin放最前面重开 PowerShell 再java -version。现象三neo4j.bat start报服务已存在或者启动后两个实例抢端口。原因是之前用 installer 装过或者多次执行过neo4j.bat install-service。先清旧服务.\bin\neo4j.bat uninstall-service .\bin\neo4j.bat console开发机我一般不用 Windows 服务直接console前台跑关窗口就停省得服务列表里留一堆同名项。5.2 数据类LOAD CSV 找不到文件、约束冲突、导入事务过大现象四LOAD CSV报Couldnt load the external resource at: file:///xxx.csv。原因有两个CSV 没放import目录或者写了C:\Users\...这种 Windows 绝对路径。file:///后面跟的是相对import的路径把文件放到import/users.csv用file:///users.csv。确实要读绝对路径得在conf里开dbms.security.allow_csv_import_from_file_urlstrue开发环境不建议开容易把整盘暴露给 Cypher。现象五导入报Node already exists with label User and property id。原因是唯一约束已经存在CSV 里同一个 id 出现多次或者你先CREATE再MERGE混用了。先查重MATCH (u:User {id: u001}) RETURN u;清洗 CSV 保证 id 唯一导入语句统一用MERGE更新属性用ON MATCH SET不要用CREATE硬怼。现象六导入几万行后卡住日志出现 GC overhead 甚至 OOM。原因是单条LOAD CSV默认一个事务所有行一次提交。改成子查询分批LOAD CSV WITH HEADERS FROM file:///users.csv AS row CALL { WITH row MERGE (u:User {id: row.id}) SET u.name row.name, u.city row.city } IN TRANSACTIONS OF 1000 ROWS;首次全量数据更大就停库走离线导入.\bin\neo4j.bat stop .\bin\neo4j-admin.bat database import full --nodesimport/users.csv --relationshipsimport/follows.csv neo4j .\bin\neo4j.bat start离线导入要求目标库为空导入前确认data/databases/neo4j没有旧数据或者换一个库名。命令里的full表示全量导入CSV 表头要符合neo4j-admin的格式约定和在线LOAD CSV的列名不完全一样第一次跑先用小文件试。5.3 运维类忘记密码、备份文件锁、配置改错启动失败现象七登录一直提示 unauthorized密码想不起来。停库后删掉data/dbms/auth重启会恢复默认neo4j/neo4j再改新密码.\bin\neo4j.bat stop Remove-Item .\data\dbms\auth .\bin\neo4j.bat console删auth会丢所有用户和角色只适合本地开发库。更稳的做法是首次启动前用neo4j-admin dbms set-initial-password设初始密码但已经跑起来的库还是得走删除重置。现象八neo4j-admin database dump报数据库正在使用。原因是数据库没停文件被 java 进程占着。先neo4j.bat stop用tasklist | findstr java确认没有残留再 dump。dump 完再start。冷备必须停库社区版没有企业级在线热备别在跑着写入的时候拷data/databases拷出来大概率不一致。现象九改完conf启动直接退出日志报Unrecognized setting。原因是参数名拼错或者把 4.x 的旧参数抄进来了。Neo4j 5 的连接器参数是server.bolt.listen_address不是 4.x 的dbms.connector.bolt.listen_address。改配置前先备份neo4j.conf启动失败看logs/neo4j.log第一行报错回滚到上一版再逐项加。6. 冷备份验证别等数据丢了才第一次跑 dump备份这件事最怕的是“文件生成了但没验证过”。我习惯在每次改完conf或者导完一批数据之后做一次停机冷备然后立刻 load 到临时目录验证确认文件不是空的、能恢复。命令不复杂顺序不能错.\bin\neo4j.bat stop .\bin\neo4j-admin.bat database dump neo4j --to-path.\backup .\bin\neo4j.bat startdatabase dump第一个参数是库名社区版默认库叫neo4j--to-path是备份输出目录执行前先建好。dump 要求数据库停止跑完看backup下有没有.dump文件大小是否和data/databases/neo4j的量级匹配。恢复验证用.\bin\neo4j.bat stop .\bin\neo4j-admin.bat database load neo4j --from-path.\backup --overwrite-destinationtrue .\bin\neo4j.bat start--overwrite-destinationtrue会覆盖当前库所以验证时要么确认当前库可以丢要么先把当前库再 dump 一份。load 同样要求停库。恢复后进 Browser 跑一句MATCH (n) RETURN count(n);数字和备份前对得上才算过。检查项备份前恢复后节点总数MATCH (n) RETURN count(n);数字一致关系总数MATCH ()-[r]-() RETURN count(r);数字一致约束/索引SHOW CONSTRAINTS;状态ONLINE登录密码当前密码可用同一密码可登录从那以后我每次动完配置或导完数据都强制跑一遍 dump load 到临时目录确认备份文件不是黑匣子。希望帮到你。本文还有配套的精品资源点击获取
