簡(jiǎn)介面向圖數(shù)據(jù)庫(kù)初學(xué)者與需要搭建本地 Neo4j 環(huán)境的開發(fā)者這份 Windows 版 Neo4j 社區(qū)版安裝包提供開箱即用的圖形數(shù)據(jù)庫(kù)運(yùn)行環(huán)境。Neo4j 以節(jié)點(diǎn)和邊建模實(shí)體與關(guān)系配合聲明式查詢語(yǔ)言 Cypher可高效表達(dá)復(fù)雜關(guān)聯(lián)并支持深度查詢與數(shù)據(jù)可視化適合社交網(wǎng)絡(luò)、知識(shí)圖譜、推薦系統(tǒng)等場(chǎng)景的入門實(shí)踐與項(xiàng)目驗(yàn)證。壓縮包共 264 個(gè)文件約 119.26MB以 235 個(gè) jar 依賴庫(kù)為主體輔以 conf 配置、bat 與 ps1 啟動(dòng)腳本、exe 服務(wù)組件及證書、許可等文件目錄結(jié)構(gòu)完整便于直接部署與按需調(diào)整參數(shù)。已有 526 人學(xué)習(xí)下載可作為理解圖數(shù)據(jù)模型、熟悉 Cypher 查詢與服務(wù)啟停流程的實(shí)用起點(diǎn)。1. 從一次解壓即用的誤判說(shuō)起neo4j-chs-community-5.23.0-windows.zip 到底裝的是什么很多人第一次接觸圖數(shù)據(jù)庫(kù)都是被一句「解壓就能跑」帶進(jìn)坑的。我見過(guò)一個(gè)開發(fā)者拿到 neo4j-chs-community-5.23.0-windows.zip雙擊解壓看到 bin 目錄里有個(gè) neo4j.bat順手一跑控制臺(tái)刷了幾行就退了瀏覽器打開 7474 一片空白。他以為是包壞了重新下載了三遍最后發(fā)現(xiàn)問(wèn)題根本不在包而在于沒裝 JDK、沒設(shè) JAVA_HOME、也沒初始化數(shù)據(jù)目錄。圖數(shù)據(jù)庫(kù)這類東西裝不好不是報(bào)個(gè)錯(cuò)就完事而是服務(wù)起不來(lái)、端口占著、日志里全是看不懂的堆棧新手很容易在這里卡一整天。這份 neo4j-chs-community-5.23.0-windows.zip 是 Neo4j 社區(qū)版 5.23.0 的 Windows 發(fā)行包屬于圖數(shù)據(jù)庫(kù)里最常被拿來(lái)入門和做中小規(guī)模關(guān)系建模的一套環(huán)境。它適合兩類人一類是想在本機(jī)把圖數(shù)據(jù)庫(kù)跑起來(lái)、驗(yàn)證 Cypher 查詢和節(jié)點(diǎn)關(guān)系模型的開發(fā)者另一類是要在 Windows 機(jī)器上做離線部署、不想依賴安裝器的運(yùn)維。下面按「先列環(huán)境、再裝、再配、最后驗(yàn)證和救火」的順序走一遍都是我實(shí)際裝過(guò)之后留下的步驟和參數(shù)取舍。2. 裝前把環(huán)境列清JDK 版本與目錄規(guī)劃先定死2.1 Neo4j 5.23.0 對(duì) JDK 的硬性要求Neo4j 5.x 系列運(yùn)行在 Java 17 上這是 5.23.0 這個(gè)版本不能繞過(guò)的前提。社區(qū)版發(fā)行包里不帶 JDKWindows 上必須自己準(zhǔn)備一個(gè) 17 的運(yùn)行時(shí)。常見做法是裝一個(gè) JDK 17 的 LTS 發(fā)行版裝完確認(rèn)java -version輸出里帶17.。這里有個(gè)反直覺的點(diǎn)機(jī)器上如果同時(shí)有 JDK 8 和 JDK 17PATH 里排前面的往往是 8Neo4j 啟動(dòng)時(shí)讀到的就是 8然后直接拋UnsupportedClassVersionError。所以不要只看「裝沒裝 17」要看「默認(rèn) java 是不是 17」。# 確認(rèn)當(dāng)前默認(rèn) JDK 版本輸出必須包含 17 java -version # 如果輸出是 1.8 或 11說(shuō)明 PATH 指向了舊版本 # 臨時(shí)切換當(dāng)前命令行窗口有效路徑按自己實(shí)際安裝位置改 set JAVA_HOMEC:\Program Files\Java\jdk-17 set PATH%JAVA_HOME%\bin;%PATH% # 再確認(rèn)一次 java -version上面這段的關(guān)鍵在JAVA_HOME和PATH的先后順序。Neo4j 的啟動(dòng)腳本會(huì)優(yōu)先讀JAVA_HOME但如果你只在 PATH 里塞了 17 的 bin 而JAVA_HOME還指向舊 JDK腳本仍可能拿錯(cuò)。我一般會(huì)把JAVA_HOME顯式設(shè)成 17 的根目錄再把%JAVA_HOME%\bin放到 PATH 最前面兩個(gè)一起改避免只改一半。臨時(shí)set只對(duì)當(dāng)前窗口生效要長(zhǎng)期生效得進(jìn)系統(tǒng)環(huán)境變量里改改完重開命令行再驗(yàn)證。2.2 目錄規(guī)劃別把數(shù)據(jù)目錄放在解壓目錄里第二個(gè)要提前定的是目錄結(jié)構(gòu)。很多人習(xí)慣把 zip 解壓到桌面或者下載目錄然后直接在里面跑結(jié)果數(shù)據(jù)、日志、配置全混在一起升級(jí)或遷移時(shí)根本分不清哪些是要保留的。我一般會(huì)分成三塊程序目錄、數(shù)據(jù)目錄、日志目錄。程序目錄放解壓出來(lái)的 neo4j-community-5.23.0數(shù)據(jù)目錄單獨(dú)放一個(gè)路徑比如D:\neo4j\data日志同理。這樣以后換版本只換程序目錄數(shù)據(jù)目錄原地不動(dòng)遷移成本最低。目錄用途建議路徑說(shuō)明程序目錄D:\neo4j\neo4j-community-5.23.0解壓后的根目錄升級(jí)時(shí)整體替換數(shù)據(jù)目錄D:\neo4j\data存放圖數(shù)據(jù)遷移時(shí)優(yōu)先保留日志目錄D:\neo4j\logs排查啟動(dòng)失敗的第一現(xiàn)場(chǎng)導(dǎo)入目錄D:\neo4j\importCSV 批量導(dǎo)入時(shí)的默認(rèn)落點(diǎn)路徑里盡量只用英文和數(shù)字不要帶空格和中文。Windows 上帶空格的路徑在腳本拼接時(shí)容易出問(wèn)題尤其是neo4j.conf里寫路徑的時(shí)候空格會(huì)被當(dāng)成參數(shù)分隔符。這一點(diǎn)在后面的配置章節(jié)還會(huì)再提一次。2.3 端口和內(nèi)存的預(yù)判Neo4j 默認(rèn)占兩個(gè)端口7474 是 HTTP 瀏覽器界面7687 是 Bolt 協(xié)議端口應(yīng)用驅(qū)動(dòng)連的就是 7687。裝之前先確認(rèn)這兩個(gè)端口沒被別的服務(wù)占著尤其是本機(jī)已經(jīng)跑過(guò)其他數(shù)據(jù)庫(kù)或者開發(fā)服務(wù)器的情況。查端口占用的命令很直接# 查 7474 和 7687 是否被占用 netstat -ano | findstr :7474 netstat -ano | findstr :7687 # 如果看到 LISTENING記下最后一列的 PID再去任務(wù)管理器對(duì)內(nèi)存方面社區(qū)版默認(rèn)的堆設(shè)置對(duì)開發(fā)機(jī)夠用但如果機(jī)器本身內(nèi)存緊張啟動(dòng)時(shí)可能因?yàn)槎淹鈨?nèi)存分配失敗而退出。這個(gè)不用提前改等真出問(wèn)題再調(diào)neo4j.conf里的server.memory.heap.initial_size和server.memory.heap.max_size后面排錯(cuò)章節(jié)會(huì)講具體怎么改。3. 解壓與首次啟動(dòng)neo4j.bat 的正確打開方式3.1 解壓后的目錄結(jié)構(gòu)確認(rèn)把 neo4j-chs-community-5.23.0-windows.zip 解壓到程序目錄后先別急著跑花一分鐘看一眼結(jié)構(gòu)。根目錄下應(yīng)該有bin、conf、data、import、logs、plugins、labs這幾個(gè)目錄。bin里是啟動(dòng)腳本conf里是neo4j.confplugins是放擴(kuò)展插件的地方。如果解壓出來(lái)多了一層同名目錄比如neo4j-community-5.23.0\neo4j-community-5.23.0\bin那說(shuō)明解壓時(shí)多套了一層啟動(dòng)腳本的相對(duì)路徑會(huì)算錯(cuò)得先把內(nèi)層目錄提上來(lái)。# 進(jìn)入程序目錄確認(rèn) bin 和 conf 在同一層 cd /d D:\neo4j\neo4j-community-5.23.0 dir # 正常應(yīng)該能看到 bin、conf、data、import、logs、plugins # 如果只看到一個(gè)同名文件夾說(shuō)明多套了一層需要把內(nèi)層內(nèi)容移上來(lái)這一步看著瑣碎但多套一層是 Windows 解壓工具最常見的坑之一尤其是用某些壓縮軟件「解壓到當(dāng)前文件夾」的時(shí)候。啟動(dòng)腳本里用的是相對(duì)路徑找conf和data層級(jí)錯(cuò)了就會(huì)報(bào)找不到配置文件而報(bào)錯(cuò)信息往往只寫「config file not found」不會(huì)告訴你是因?yàn)槟夸泴蛹?jí)不對(duì)。3.2 首次啟動(dòng)前先做一次配置檢查在真正neo4j.bat console之前我習(xí)慣先打開conf\neo4j.conf掃一眼幾個(gè)關(guān)鍵項(xiàng)。5.23.0 的配置文件里默認(rèn)的server.default_listen_address是localhost意味著只有本機(jī)能訪問(wèn)server.bolt.listen_address和server.http.listen_address默認(rèn)是:7687和:7474。如果只是本機(jī)開發(fā)這些默認(rèn)值不用動(dòng)。如果要讓局域網(wǎng)內(nèi)其他機(jī)器連才需要把監(jiān)聽地址改成0.0.0.0但那是后面的事首次啟動(dòng)先保持默認(rèn)減少變量。# conf/neo4j.conf 中首次啟動(dòng)需要確認(rèn)的幾項(xiàng)保持默認(rèn)即可 server.default_listen_addresslocalhost server.bolt.listen_address:7687 server.http.listen_address:7474 # 數(shù)據(jù)目錄和日志目錄如果要用自定義路徑在這里改 # server.directories.dataD:/neo4j/data # server.directories.logsD:/neo4j/logs配置項(xiàng)用#注釋掉表示走默認(rèn)值。我建議首次啟動(dòng)時(shí)先不要改數(shù)據(jù)目錄等確認(rèn)能跑起來(lái)之后再遷移否則一旦啟動(dòng)失敗你分不清是路徑寫錯(cuò)還是環(huán)境問(wèn)題。等驗(yàn)證通過(guò)再把server.directories.data指向規(guī)劃好的獨(dú)立目錄重啟一次確認(rèn)數(shù)據(jù)能正常讀寫這樣排錯(cuò)范圍是可控的。3.3 用 console 模式啟動(dòng)并觀察輸出首次啟動(dòng)一定用console模式不要用start后臺(tái)啟動(dòng)。console會(huì)把啟動(dòng)日志直接打在窗口里出問(wèn)題能第一時(shí)間看到start把進(jìn)程丟到后臺(tái)失敗了只能去翻日志文件新手很容易找不到方向。# 在程序目錄下執(zhí)行前臺(tái)啟動(dòng)日志直接輸出到當(dāng)前窗口 bin\neo4j.bat console # 正常啟動(dòng)后窗口里會(huì)看到類似下面的輸出 # Started. # Remote interface available at http://localhost:7474/看到Started.和Remote interface available這兩行說(shuō)明服務(wù)起來(lái)了。這時(shí)候不要關(guān)窗口另開一個(gè)瀏覽器訪問(wèn)http://localhost:7474應(yīng)該能看到 Neo4j Browser 的登錄界面。首次登錄默認(rèn)用戶名和密碼都是neo4j登錄后會(huì)強(qiáng)制要求改密碼改完才算真正可用。如果窗口里刷了一堆異常然后退出先別急著重裝把最后 20 行報(bào)錯(cuò)記下來(lái)對(duì)照后面的排錯(cuò)章節(jié)看大部分是 JDK 版本、端口占用、目錄權(quán)限這三類。4. 配置落地neo4j.conf 里真正要?jiǎng)拥膸讉€(gè)參數(shù)4.1 監(jiān)聽地址與遠(yuǎn)程訪問(wèn)的取舍本機(jī)開發(fā)保持localhost最省事但如果要在虛擬機(jī)、容器或者局域網(wǎng)另一臺(tái)機(jī)器上訪問(wèn)就得改監(jiān)聽地址。這里有個(gè)容易混淆的點(diǎn)server.default_listen_address是總開關(guān)server.bolt.listen_address和server.http.listen_address是分協(xié)議的具體地址。只改分協(xié)議不改總開關(guān)或者反過(guò)來(lái)都可能出現(xiàn)「端口通了但連不上」的情況。我一般兩個(gè)一起改保持一致。# 允許局域網(wǎng)訪問(wèn)時(shí)的配置組合 server.default_listen_address0.0.0.0 server.bolt.listen_address:7687 server.http.listen_address:7474改成0.0.0.0之后防火墻要放行 7474 和 7687否則外部還是連不進(jìn)來(lái)。Windows 防火墻的入站規(guī)則里加兩條 TCP 規(guī)則即可。注意這里說(shuō)的是內(nèi)網(wǎng)開發(fā)環(huán)境公網(wǎng)暴露數(shù)據(jù)庫(kù)端口不是合格做法真要對(duì)外提供服務(wù)前面得有一層反向代理和認(rèn)證這個(gè)不在本次安裝范圍內(nèi)。4.2 內(nèi)存參數(shù)堆大小怎么給才不翻車社區(qū)版默認(rèn)的堆設(shè)置偏保守開發(fā)機(jī)上一般夠用。但如果導(dǎo)入大批量 CSV 或者跑復(fù)雜查詢時(shí)出現(xiàn)OutOfMemoryError就要調(diào)堆。5.23.0 里堆參數(shù)是server.memory.heap.initial_size和server.memory.heap.max_size單位可以是g或m。我一般把初始值和最大值設(shè)成一樣避免運(yùn)行中反復(fù)擴(kuò)容帶來(lái)的抖動(dòng)。# 堆內(nèi)存設(shè)置按機(jī)器實(shí)際內(nèi)存給開發(fā)機(jī) 2g 起步 server.memory.heap.initial_size2g server.memory.heap.max_size2g # 頁(yè)面緩存圖數(shù)據(jù)讀性能相關(guān)開發(fā)機(jī)給 512m 到 1g server.memory.pagecache.size512m堆大小不是越大越好。堆給太大頁(yè)面緩存就被擠占圖遍歷反而變慢堆給太小復(fù)雜查詢直接 OOM。經(jīng)驗(yàn)值是堆不超過(guò)物理內(nèi)存的一半頁(yè)面緩存再分一部分剩下的留給操作系統(tǒng)。改完這些參數(shù)必須重啟服務(wù)才生效console模式下就是 CtrlC 停掉再重新跑。4.3 數(shù)據(jù)目錄遷移的標(biāo)準(zhǔn)動(dòng)作確認(rèn)默認(rèn)配置能跑通之后把數(shù)據(jù)目錄遷到獨(dú)立路徑。動(dòng)作順序是先停服務(wù)再改配置再把原data目錄下的內(nèi)容整體復(fù)制到新路徑最后啟動(dòng)驗(yàn)證。順序錯(cuò)了會(huì)出現(xiàn)「新目錄是空的、舊數(shù)據(jù)還在原地」的尷尬局面。# 遷移數(shù)據(jù)目錄和日志目錄 server.directories.dataD:/neo4j/data server.directories.logsD:/neo4j/logs# 停掉 console 窗口后復(fù)制原數(shù)據(jù)到新目錄 xcopy /E /I /Y D:\neo4j\neo4j-community-5.23.0\data D:\neo4j\data # 重新啟動(dòng)觀察日志里數(shù)據(jù)目錄是否指向新路徑 bin\neo4j.bat console復(fù)制用xcopy /E /I /Y/E包含空目錄/I目標(biāo)不存在時(shí)按目錄處理/Y跳過(guò)覆蓋確認(rèn)。啟動(dòng)后去D:\neo4j\logs下看neo4j.log里面會(huì)打印實(shí)際使用的數(shù)據(jù)目錄路徑確認(rèn)是新的就說(shuō)明遷移成功。這一步做完以后升級(jí)只換程序目錄數(shù)據(jù)原地不動(dòng)。5. 常見問(wèn)題排查啟動(dòng)失敗、連不上、密碼忘了怎么救5.1 啟動(dòng)即退出日志里是 UnsupportedClassVersionError現(xiàn)象是雙擊neo4j.bat或者console啟動(dòng)窗口閃一下就關(guān)日志里出現(xiàn)UnsupportedClassVersionError或者提示 class file version 不匹配。原因基本只有一個(gè)默認(rèn) java 不是 17。解決方式是回到 2.1 節(jié)把JAVA_HOME指向 JDK 17 的根目錄PATH 里%JAVA_HOME%\bin放最前重開命令行再驗(yàn)證java -version。如果機(jī)器上裝了多個(gè) JDK建議直接把舊版本的 PATH 項(xiàng)刪掉減少誤判。5.2 端口被占用啟動(dòng)卡在 Bolt 監(jiān)聽現(xiàn)象是啟動(dòng)日志停在Starting Bolt connector附近然后報(bào)Address already in use。原因是 7687 或 7474 被別的進(jìn)程占了常見的是之前沒退干凈的 Neo4j 進(jìn)程或者本機(jī)其他數(shù)據(jù)庫(kù)服務(wù)。解決方式是netstat -ano | findstr :7687找到 PID任務(wù)管理器里結(jié)束對(duì)應(yīng)進(jìn)程如果確認(rèn)是別的服務(wù)長(zhǎng)期占用就改 Neo4j 的端口把server.bolt.listen_address改成:7688之類同時(shí)應(yīng)用連接串也要跟著改。5.3 瀏覽器能打開但登錄失敗提示認(rèn)證錯(cuò)誤現(xiàn)象是 7474 界面能出來(lái)輸入 neo4j/neo4j 提示認(rèn)證失敗。原因通常是之前改過(guò)密碼但忘了或者數(shù)據(jù)目錄是從別處復(fù)制過(guò)來(lái)的、帶著舊密碼。解決方式分兩種記得密碼就直接用新密碼登錄不記得就走密碼重置流程先停服務(wù)用bin\neo4j.bat配合admin子命令重置或者刪掉data\dbms\auth相關(guān)文件讓系統(tǒng)重新初始化認(rèn)證。后者會(huì)清掉所有用戶只適合本地開發(fā)環(huán)境生產(chǎn)數(shù)據(jù)目錄不要這么干。# 停服務(wù)后用 admin 子命令重置密碼具體參數(shù)以當(dāng)前版本幫助為準(zhǔn) bin\neo4j.bat admin --help # 本地開發(fā)環(huán)境實(shí)在找不回可以備份后清理認(rèn)證文件重新初始化 # 注意這會(huì)清空用戶僅限本地開發(fā)庫(kù)5.4 改了配置不生效服務(wù)還是老樣子現(xiàn)象是neo4j.conf里改了端口或內(nèi)存重啟后行為沒變。原因有兩個(gè)常見方向一是改的不是實(shí)際加載的那份配置文件比如程序目錄多套了一層改的是外層那份二是服務(wù)沒真正重啟start模式下的進(jìn)程還在跑新配置沒被讀取。解決方式是先確認(rèn)neo4j.log里打印的配置路徑再確認(rèn)進(jìn)程確實(shí)停了任務(wù)管理器里沒有殘留的 java 進(jìn)程然后重新console啟動(dòng)看輸出。5.5 導(dǎo)入 CSV 報(bào)路徑錯(cuò)誤現(xiàn)象是用LOAD CSV導(dǎo)入時(shí)報(bào)找不到文件。原因是 Neo4j 默認(rèn)只允許從import目錄讀文件絕對(duì)路徑或者..跳目錄會(huì)被安全策略攔掉。解決方式是把 CSV 放到程序目錄下的import文件夾LOAD CSV里寫相對(duì)路徑的文件名即可。如果確實(shí)要用別的目錄得在neo4j.conf里配server.directories.import指向目標(biāo)目錄但開發(fā)階段沒必要放import最省事。6. 裝完怎么驗(yàn)證跑通三條命令確認(rèn)環(huán)境真的可用裝完不等于跑通我一般用三層驗(yàn)證來(lái)收尾從服務(wù)層到查詢層再到數(shù)據(jù)持久化層逐層確認(rèn)。第一層看服務(wù)狀態(tài)第二層跑一條 Cypher第三層重啟后確認(rèn)數(shù)據(jù)還在。這三步走完這套 neo4j-chs-community-5.23.0-windows.zip 才算真正落地。第一層服務(wù)狀態(tài)。console窗口里看到Started.只是啟動(dòng)成功再用cypher-shell連一下 Bolt 端口確認(rèn)協(xié)議層通。cypher-shell在bin目錄下連的時(shí)候帶上用戶名密碼# 連接本地 Bolt 端口-a 是地址-u 用戶名-p 密碼 bin\cypher-shell.bat -a bolt://localhost:7687 -u neo4j -p 你的密碼 # 連上后執(zhí)行一條最簡(jiǎn)單的查詢 RETURN 1;能返回1就說(shuō)明 Bolt 協(xié)議、認(rèn)證、查詢引擎三層都通了。這一步比瀏覽器登錄更能說(shuō)明問(wèn)題因?yàn)闉g覽器走的是 HTTPBolt 才是應(yīng)用驅(qū)動(dòng)實(shí)際用的通道。第二層建節(jié)點(diǎn)查關(guān)系。在cypher-shell里跑一條帶寫入的語(yǔ)句確認(rèn)圖數(shù)據(jù)能落盤// 建兩個(gè)節(jié)點(diǎn)和一條關(guān)系驗(yàn)證寫入鏈路 CREATE (a:Person {name: A})-[:KNOWS]-(b:Person {name: B}); MATCH (p:Person) RETURN p.name;返回兩行A和B就說(shuō)明寫入和讀取都正常。這里用CREATE而不是MERGE是因?yàn)槭状悟?yàn)證要確認(rèn)寫入一定發(fā)生MERGE在數(shù)據(jù)已存在時(shí)會(huì)跳過(guò)反而看不出問(wèn)題。第三層重啟驗(yàn)證持久化。CtrlC 停掉console重新bin\neo4j.bat console啟動(dòng)再連cypher-shell跑一次MATCH (p:Person) RETURN p.name;。如果還能查到 A 和 B說(shuō)明數(shù)據(jù)目錄配置正確、數(shù)據(jù)確實(shí)落盤了。這一步是很多人漏掉的尤其是把數(shù)據(jù)目錄改到自定義路徑之后不重啟驗(yàn)證就不知道配置有沒有真正生效。驗(yàn)證層命令通過(guò)標(biāo)準(zhǔn)服務(wù)層cypher-shell.bat -a bolt://localhost:7687能連上并返回查詢結(jié)果查詢層CREATEMATCH節(jié)點(diǎn)和關(guān)系能寫入并讀出持久化層重啟后再M(fèi)ATCH數(shù)據(jù)仍在未丟失三層都過(guò)這套環(huán)境就可以放心用了。從那以后我每次裝 Neo4j不管多急都會(huì)把「重啟后再查一次」這步強(qiáng)制走一遍因?yàn)閿?shù)據(jù)目錄配錯(cuò)這種事不重啟根本暴露不出來(lái)等真丟了數(shù)據(jù)再回頭找就晚了。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取