简介面向图数据库初学者、后端开发者及知识图谱课程实验的 Neo4j 5.23.0 Windows 社区版中文发行包可用于在本地搭建图数据存储、关系建模与 Cypher 查询环境。压缩包共 264 个文件、约 119.26MB以 235 个 jar 依赖为主体并配有 conf 配置、bat 与 ps1 启停管理脚本、exe 服务组件、txt 说明及证书等目录组织较完整便于直接部署和按需调整。已有 527 人学习下载。内容涵盖节点、边及属性构成的图模型Cypher 声明式查询与可视化浏览以及管理命令、服务注册脚本和浏览器组件等使用支撑对课程演示、开发测试、知识图谱原型和关系数据分析较为适用也可通过配置文件与脚本了解 Neo4j 在 Windows 下的运行方式。1. 从一次双击闪退说起Neo4j 5.23.0 Windows 版装不上多半是 JDK 没对上解压neo4j-chs-community-5.23.0-windows.zip双击bin\neo4j.bat黑窗口闪一下就没了——这是我在 Windows 上见过最多的 Neo4j 安装翻车现场。十有八九不是包坏了而是机器上躺着的还是 JDK 8 或 JDK 11。Neo4j 5.x 的编译目标是 Java 17class 文件版本 61旧 JVM 打开直接抛Unsupported class file major version脚本还没来得及写日志就退出了所以你连报错都看不见。图数据库这种要长期挂在后台、随时接 Cypher 查询的服务第一遍装歪了后面每次建模、每次导数据都要先跟环境打架。这篇记录面向在本机或测试机上落地 Neo4j 5.23.0 社区版的开发者想跑图数据建模、做关系分析、带学生做 Cypher 练习或者只是想把一个图库安安稳稳跑起来。下面按装前清单、配置文件、启动服务、排错、验证的顺序走一遍。2. 装前把基础条件准备好JDK 17、目录规划和端口预检装 Neo4j 之前先把三件事定下来用哪个 JDK、解压到哪个目录、端口有没有被占。这三件事任何一件没定好后面改配置都是白费功夫。这一章做完你应该有一个干净的、待启动的 Neo4j 目录还没有敲过任何一条启动命令。2.1 JDK 17 的版本选择与 JAVA_HOME 落点Neo4j 5.23 的运行前提是 Java 17。机器上装着 JDK 8 不代表不能装 JDK 17两个版本可以共存关键在于JAVA_HOME指向谁。我的习惯是单独建一个目录放 JDK比如C:\Java\jdk-17不要塞进Program Files下面那些带空格的路径里Windows 上带空格的路径在批处理脚本里是经典的翻车点。版本上选 17 的任意一个 LTS 小版本都行不用纠结 17.0.x 的最后一位。Java 21 在 5.23 上也能跑起来但如果后面打算接 APOC 之类的插件先按 17 走插件生态对 17 的兼容验证最充分。装完先确认版本java -version输出里应该看到openjdk version 17.0.x这样的字样。如果这里显示的是 1.8 或者 11说明 PATH 里的 java 还是老的先把 JDK 17 的bin挪到 PATH 前面或者干脆只靠JAVA_HOME让 Neo4j 脚本自己去拼路径。设置JAVA_HOME用系统属性对话框最稳此电脑右键 → 属性 → 高级系统设置 → 环境变量 → 系统变量 → 新建变量名JAVA_HOME值填C:\Java\jdk-17不带\bin后缀。这一点很多人写错写成C:\Java\jdk-17\binNeo4j 启动脚本会拼成...\bin\bin\java.exe然后报找不到 java。命令行方式也可以但要注意setx的坑:: 以管理员身份打开 CMD写入系统级变量 setx JAVA_HOME C:\Java\jdk-17 /M setx PATH %PATH%;%JAVA_HOME%\bin /M逻辑说明/M表示写进系统变量而不是当前用户变量服务方式启动 Neo4j 时读的是系统变量。参数说明第二条把 JDK 的 bin 追加进 PATH。这里有个血泪经验——setx对超过 1024 字符的变量值会静默截断PATH 本来就很长的机器上执行完可能丢掉一截路径。所以 PATH 我一般只在图形界面里改setx只用来设JAVA_HOME这种短变量。提示改完环境变量已经打开的 CMD 窗口不会生效必须关掉重开一个echo %JAVA_HOME%能看到值再往下走。2.2 解压位置与目录结构别放在下载目录和中文路径下把 zip 解压到一个短路径、纯英文、无空格的目录比如D:\neo4j\neo4j-chs-community-5.23.0。我见过把 Neo4j 解压到「桌面\新建文件夹\图数据库」下面的启动时日志路径拼不出来服务注册也失败排查半天最后发现是路径问题。解压完先认一下目录后面所有操作都在这个结构里转目录/文件作用会不会被我改动bin启动脚本、neo4j-admin、cypher-shell不动confneo4j.conf主配置重点改data数据库文件、事务日志、认证文件由程序写logsneo4j.log、debug.log、query.log排错必看importLOAD CSV和批量导入的默认输入目录放数据文件plugins插件 jar 存放位置需要时放这份 chs 包在官方社区版基础上做了中文界面和中文提示的适配bin、conf、data的目录结构与官方社区版一致所以下面所有命令对两边通用。解压后不要急着双击 bat先把NEO4J_HOME也设上很多脚本和第三方工具会读这个变量setx NEO4J_HOME D:\neo4j\neo4j-chs-community-5.23.0 /M设完同样要重开终端。这里不要图省事直接把bin加进 PATHNeo4j 的bin下有一堆同名脚本neo4j.bat、neo4j-admin.bat、cypher-shell.bat全局暴露出去以后机器上再装第二个版本就会互相打架。要用的时候进目录或者写个cd /d %NEO4J_HOME%的快捷方式。2.3 端口 7474 和 7687 的预检Neo4j 默认占两个端口7474 是 HTTP浏览器界面走这个7687 是 Bolt 协议驱动和cypher-shell走这个。装之前先查一遍装完再查一遍能省掉一大半「启动了但连不上」的误会。netstat -ano | findstr :7474 netstat -ano | findstr :7687有输出就说明被占了最后一列是 PID用tasklist | findstr PID看看是哪个进程。常见情况是上一次的 Neo4j 没停干净java.exe还挂着也可能是别的开发工具占了 7474。确认是残留进程就直接结束掉是别的服务就改 Neo4j 的端口改法在下一章。顺便把防火墙也想一下。只在本机用监听地址保持localhost就行不涉及放行如果要在局域网里让另一台机器连过来才需要放行 7474 和 7687。:: 仅在本机使用时不用执行需要局域网访问再放行 netsh advfirewall firewall add rule nameNeo4j HTTP 7474 dirin actionallow protocolTCP localport7474 netsh advfirewall firewall add rule nameNeo4j Bolt 7687 dirin actionallow protocolTCP localport7687参数说明dirin是入站方向localport指定端口protocolTCP。这两条命令要在管理员 CMD 里跑。放行之前想清楚图库一旦对外认证就是唯一一道门密码强度别凑合。3. 改 neo4j.conf内存、监听地址和认证三项先落地conf\neo4j.conf是这套环境里唯一必须动脑子的文件。它有几万行注释但真正需要改的就那么几项剩下的保持默认。改之前先备份一份出问题能立刻回滚copy conf\neo4j.conf conf\neo4j.conf.bak3.1 5.23 里被改名的配置项从 dbms.* 到 server.*如果你手上还有 Neo4j 4.x 的配置笔记直接抄过来会踩坑。5.x 把连接器相关的配置整体从dbms.connector.*挪到了server.*命名空间下内存配置也从dbms.memory.*挪到了server.memory.*。旧键名在新版本里要么被忽略要么直接让启动失败而启动失败的提示往往藏在logs\debug.log里neo4j.log只给你一句「启动失败」。对应关系记一下4.x 旧键5.23 新键dbms.connector.bolt.listen_addressserver.bolt.listen_addressdbms.connector.http.listen_addressserver.http.listen_addressdbms.connector.https.enabledserver.https.enableddbms.memory.heap.max_sizeserver.memory.heap.max_sizedbms.memory.pagecache.sizeserver.memory.pagecache.sizedbms.default_listen_addressserver.default_listen_address改配置时用文本编辑器打开定位到对应段落把行首的#去掉再改值。不要整段复制粘贴容易把注释里的示例行也一起激活产生重复配置。Neo4j 对重复键的处理是后者覆盖前者但日志里会给你一堆警告看着心烦。3.2 堆内存与页缓存按物理内存给一个能跑的数这是最容易配错、也最容易让服务起不来的一项。Neo4j 的两块内存是分开算的堆内存给查询执行、事务和 Java 对象用页缓存用来缓存磁盘上的图数据让遍历不用每次都读盘。两者相加不能超过物理内存还要给操作系统留一截。我的经验值按机器物理内存直接对照物理内存heap.max_sizepagecache.size适用场景8G2g1g本机学习、小图16G4g2g常规开发、几十万节点32G8g8g中等数据集、需要常驻64G 以上16g视数据量给数据能全量进缓存最好页缓存的原则是「能装下整个 store 最好」装不下就按可用内存给剩下的靠磁盘。堆不要给太大堆越大 GC 停顿越明显图查询这种大量对象创建的负载对 GC 很敏感给到物理内存的四分之一到三分之一就够了。打开conf\neo4j.conf找到内存段落改成这样# 堆内存初始值和最大值设成一样避免运行期扩容带来的抖动 server.memory.heap.initial_size4g server.memory.heap.max_size4g # 页缓存缓存图数据用按物理内存给 server.memory.pagecache.size2g逻辑说明initial_size和max_size设成相同值是常见做法JVM 启动时就申请到位不用在中途扩容。单位可以用g、mNeo4j 认这两个后缀。参数说明这两个值写错成4G大写也能识别但别写成4096那是 MB 的意思等于 4G容易和字节混淆统一用带单位的写法最不容易出错。注意如果启动时报内存分配失败先确认不是把 pagecache 给超了。Windows 上还有虚拟内存的因素物理内存 8G 的机器给 1g 页缓存是安全的。3.3 监听地址与 Bolt/HTTP 端口这一段决定服务对外暴露到什么程度。只在本机开发监听localhost最省事也最安全要让虚拟机或同事的机器连进来才改成0.0.0.0。默认配置里server.default_listen_address是注释掉的等同于只监听本机回环地址。# 只监听本机需要局域网访问改成 0.0.0.0 server.default_listen_addresslocalhost # Bolt 协议驱动和 cypher-shell 走这里 server.bolt.enabledtrue server.bolt.listen_address:7687 # HTTP浏览器界面走这里 server.http.enabledtrue server.http.listen_address:7474 # 本机开发不需要 HTTPS关掉省一个端口 server.https.enabledfalse逻辑说明listen_address:7687前面的冒号是「地址留空用 default_listen_address」的意思这是 Neo4j 的写法习惯。如果写成localhost:7687就覆盖了默认监听地址两者效果在单机场景下一样。参数说明server.https.enabledfalse关掉之后7473端口不再监听浏览器走http://localhost:7474就行如果哪天要接反向代理再打开。端口冲突的情况下直接改冒号后面的数字比如把 HTTP 改成:7475Bolt 改成:7688然后防火墙和客户端连接串同步改。3.4 初始密码与认证开关Neo4j 首次启动会生成neo4j用户默认密码也是neo4j第一次登录强制改。这个流程在浏览器里走没问题但如果打算用脚本初始化环境最好提前把初始密码设好省得自动化流程卡在改密码那一步。:: 在 Neo4j 未启动的状态下执行 bin\neo4j-admin.bat dbms set-initial-password YourStrongPass123逻辑说明这条命令直接写认证文件所以必须在数据库停止时跑服务运行中执行会被拒绝。参数说明密码至少 8 位太短会报Invalid password而且这个校验在设置阶段就拦下来。密码里别用需要转义的特殊字符CMD 下引号转义很容易出错字母数字加一两个符号足够。认证开关这一项除非是纯离线的一次性演示环境否则不要关dbms.security.auth_enabledtrue关掉认证意味着任何能连上 7687 的人都能读写全库图数据库里往往存的是关系数据泄露的后果比一张普通业务表严重得多。这条保持true没有例外。顺手把查询日志打开后面排查慢查询用得上dbms.logs.query.enabledtrue dbms.logs.query.threshold500ms逻辑说明超过阈值的查询会写进logs\query.log包含执行计划和耗时。参数说明500ms对开发环境够用生产上一般调低到100ms日志会占磁盘定期清理或关掉。配置改完先别急着启动服务用前台方式跑一遍看日志这就是下一章的内容。4. 启动与注册 Windows 服务console 试跑、服务常驻配置写完之后有两个选择前台跑一次确认没问题或者直接注册成 Windows 服务。我的顺序是先用console模式跑通确认能正常启动、能连上、日志没报错再注册服务。跳过这一步直接装服务出错时你面对的是「服务启动失败错误 1067」这种没有任何信息量的提示。4.1 先用 neo4j.bat console 前台跑一遍打开一个 CMD进到 Neo4j 根目录执行cd /d D:\neo4j\neo4j-chs-community-5.23.0 bin\neo4j.bat consoleconsole参数的意思是前台运行日志直接打到当前窗口。正常的话滚动输出里会出现类似这样的几行加载配置、初始化数据库、启动 Bolt 连接器、启动 HTTP 连接器最后一行是Started。看到Started就说明服务起来了这个窗口不要关另开一个 CMD 去做后面的验证。如果窗口一闪就退或者卡在某一步不动先看这个窗口里最后几行输出再看logs\neo4j.log和logs\debug.log。neo4j.log只有摘要真正的堆栈在debug.log里这一点很多人不知道只看前者会以为日志是空的。启动过程里有几行是关于数据库的第一次启动会创建neo4j和system两个库前者是你的业务库后者存用户、角色、权限这些元数据。等这两行过去再操作别在初始化过程中就去连。提示console模式下按CtrlC是优雅停止会先刷盘再退出。直接点窗口的叉会把进程杀掉下次启动要做恢复第一次遇到会以为数据库坏了。4.2 注册成 Windows 服务neo4j windows-service install确认console模式能正常启动之后CtrlC停掉再注册服务。注意 5.x 的服务命令跟 4.x 不一样4.x 是neo4j install-service5.x 改成了带子命令的形式用老命令会提示未知参数。以管理员身份打开 CMD执行cd /d D:\neo4j\neo4j-chs-community-5.23.0 bin\neo4j.bat windows-service install逻辑说明这条命令把 Neo4j 注册成一个名为neo4j的 Windows 服务启动类型默认是自动。参数说明必须用管理员权限否则会报权限不足服务注册时会把当前的JAVA_HOME和安装路径写进注册表所以以后挪动目录之前必须先卸载服务。安装完之后的启停命令:: 启动服务 bin\neo4j.bat windows-service start :: 查看状态 bin\neo4j.bat status :: 停止服务 bin\neo4j.bat windows-service stop :: 卸载服务挪目录或换版本前必须执行 bin\neo4j.bat windows-service uninstallstatus输出Neo4j is running就说明服务在跑。也可以用services.msc图形界面里找到neo4j服务右键启停效果一样。服务方式跑起来后控制台不会再有输出所有信息都进日志文件。这里有个关键差异要说清楚服务是以LocalSystem账户运行的它读的是系统级环境变量不是当前用户的。所以如果你只在「用户变量」里设了JAVA_HOMEconsole能跑服务启动会失败——这是第 5 章要展开的头号坑。4.3 日志落在哪出问题先看哪个服务模式下排查全靠日志位置记牢文件内容什么时候看logs\neo4j.log启动摘要、正常关闭、错误摘要第一步logs\debug.log完整堆栈、配置加载细节摘要不够时logs\query.log慢查询和执行计划调性能时logs\http.logHTTP 请求记录浏览器访问异常时logs\security.log认证失败、权限拒绝连不上、登不进时看日志有个技巧用 PowerShell 跟踪末尾输出比反复打开文件快得多。powershell Get-Content logs\neo4j.log -Wait -Tail 30参数说明-Wait持续监听新内容-Tail 30先显示最后 30 行。服务重启的时候盯着这个窗口能第一时间看到是哪一步失败的。4.4 数据目录搬迁与版本升级前的准备开发到一半想换机器或者想把data挪到另一块盘上不是复制粘贴就完事。Neo4j 的data目录里除了数据库文件还有事务日志运行中复制会拿到不一致的快照。正确做法是先停服务再整体搬:: 停服务后执行 bin\neo4j.bat windows-service stop robocopy data D:\neo4j-data /E /COPYALL逻辑说明robocopy比xcopy稳/E包含空目录/COPYALL保留权限和时间戳。搬完之后要在neo4j.conf里把server.directories.data指到新位置否则服务还会去读老目录server.directories.dataD:/neo4j-data参数说明路径用正斜杠或者双反斜杠单反斜杠在 properties 文件里会被当转义符吃掉一个。改完启动服务看日志里有没有报「目录不存在」或者「权限拒绝」。升级版本的时候顺序反过来先windows-service uninstall再换目录再install。直接把新版本解压覆盖旧目录bin下的脚本和服务注册信息会对不上服务启动失败还不容易想到原因。5. 避坑排查五条血泪记录每条都有解这一章是我自己踩过、也帮别人处理过的五类问题。写法统一成「现象 → 原因 → 解决」遇到问题时按现象对号入座比从头读配置快得多。判断的第一步永远是看logs\debug.log的最后一段堆栈别猜。5.1 双击 bat 闪退报 Unsupported class file major version现象双击bin\neo4j.bat黑窗口一闪就消失在 CMD 里执行能看到Unsupported class file major version 61或者Could not find or load main class。原因JVM 版本低于 17。Neo4j 5.23 编译产物是 Java 17 字节码class 文件版本 61JDK 8 只认到 52JDK 11 只认到 55加载阶段直接拒绝。机器上装着多个 JDK 时PATH 里排前面的那个说了算JAVA_HOME反而可能被忽略。解决先java -version确认当前生效的是哪个版本不是 17 就去改JAVA_HOME和 PATH 的顺序。改完必须重开 CMD 窗口。如果java -version显示 17 但 Neo4j 还报同样的错说明 Neo4j 脚本读到的JAVA_HOME和你终端里的不是同一个——检查是不是设成了用户变量而脚本在服务上下文里跑。5.2 console 能启动注册成服务后启动失败现象bin\neo4j.bat console一切正常Started也出来了注册服务后windows-service start报错或者服务状态是「已停止」日志里没有新的启动记录。原因服务以LocalSystem账户运行读的是系统级环境变量。如果JAVA_HOME只设在用户变量里服务进程找不到 JDK另一种情况是NEO4J_HOME指向了别的目录服务加载的是另一份配置。解决把JAVA_HOME和NEO4J_HOME都改成系统变量setx ... /M或在图形界面里加到「系统变量」区域然后卸载服务重新注册让注册表里的路径刷新bin\neo4j.bat windows-service uninstall bin\neo4j.bat windows-service install重新注册前确认当前 CMD 是管理员权限且echo %JAVA_HOME%有输出。5.3 启动卡住或报内存分配失败现象console模式跑到一半停住日志里出现Cannot allocate memory或者OutOfMemoryError机器本身内存看着还很富裕。原因server.memory.heap.max_size加server.memory.pagecache.size超过了可用物理内存或者堆设得太大导致 JVM 启动时申请连续内存失败。Windows 上 32 位进程还有 2G 地址空间限制虽然现在基本都是 64 位但 JDK 装成 32 位的情况依然存在。解决先按 3.2 的表把两个值降下来堆和页缓存之和控制在物理内存的 70% 以内。然后确认 JDK 是 64 位java -version输出里带64-Bit字样。降完还起不来把 pagecache 先注释掉让它用默认值排除是这一项的问题。5.4 浏览器打不开 7474或者能开但连不上 7687现象服务状态是 runninglogs\neo4j.log里有Started但浏览器访问http://localhost:7474转圈或拒绝连接或者浏览器能进驱动连 7687 报连接被拒。原因三种可能——端口被占导致 Neo4j 实际没绑上server.default_listen_address设成了localhost而你从另一台机器访问防火墙拦了入站。解决netstat -ano | findstr :7474看端口到底有没有被监听、被谁监听。本机访问不通先换127.0.0.1:7474试排除 hosts 解析问题。跨机器访问就把监听地址改成0.0.0.0并按 2.3 放行防火墙改完重启服务。还有一种隐蔽情况浏览器缓存了旧的登录态换无痕窗口再试一次。5.5 密码改了但登录被拒或者认证被意外关掉现象用neo4j-admin设了新密码浏览器登录还是提示认证失败或者反过来的情况——没输密码就进了库。原因设密码时数据库没停干净认证文件被运行中的进程覆盖或者dbms.security.auth_enabled被改成了false这个配置在有些教程里被建议关掉「方便调试」。解决先停服务确认没有残留的java.exe进程再执行bin\neo4j-admin.bat dbms set-initial-password 新密码。注意set-initial-password只在认证文件不存在时生效如果之前已经初始化过要么删掉data\dbms\auth下的认证文件重来要么用cypher-shell登录后执行ALTER CURRENT USER SET PASSWORD FROM 旧密码 TO 新密码。认证开关一律保持true这条不接受「先关掉方便调试」的说法。6. 装完怎么验证从 cypher-shell 到浏览器跑通一条最小链路服务起来了不等于装好了得证明它能读能写能查。我一般用cypher-shell做命令行验证再用浏览器做一次可视化确认两步都过才算收工。第一步用cypher-shell连上去。它在bin目录下参数和常见的数据库客户端类似bin\cypher-shell.bat -a bolt://localhost:7687 -u neo4j -p YourStrongPass123参数说明-a是连接地址必须写bolt://前缀-u和-p是用户名密码。连上之后提示符会变成neo4jlocalhost:7687说明 Bolt 通道是通的。连不上先回到 5.4 排查。第二步建两个节点一条边再查回来CREATE (a:Person {name: 示例节点A, city: 示例城市}) CREATE (b:Person {name: 示例节点B, city: 示例城市}) CREATE (a)-[:KNOWS {since: 2024}]-(b); MATCH (a:Person)-[r:KNOWS]-(b:Person) RETURN a.name AS 起点, b.name AS 终点, r.since AS 起始年;逻辑说明前三条语句建了两个带Person标签的节点和一条KNOWS关系最后一条用模式匹配把整条路径查回来。参数说明标签和关系类型用英文属性值用中文没问题这也顺便验证了中文写入和读取。查询结果能返回三列一行说明写入、索引、读取整条链路都是通的。第三步浏览器打开http://localhost:7474用同一套账号登录。左边栏能看到Person标签和节点数量在查询框里敲MATCH (n) RETURN n LIMIT 25图上能画出那两个节点和一条连线。可视化出来这一套环境就算真正跑通了。留一张自检表装完逐项对一遍检查项期望结果不通过时先看java -version17.x64-Bit5.1neo4j.bat statusNeo4j is running5.2netstat查 7474/7687两个端口都在监听5.4cypher-shell连接出现neo4jlocalhost:7687提示符5.4、5.5写入并查回节点返回一行三列结果3.2 内存配置浏览器 7474能登录并画出图5.3、5.4logs\debug.log尾部没有 ERROR 堆栈逐条对照现象从那以后我每次装完 Neo4j不管多急都强制把这七项走一遍尤其是debug.log尾部那一项——很多问题在启动时就已经埋下只是neo4j.log里被摘要盖住了等到跑数据才炸出来就得多花几倍时间。希望帮到你。本文还有配套的精品资源点击获取