Docker部署 Neo4j 及集成 APOC 插件：分步驟指南

摘要

：本文將分兩部分詳細介紹相關內容。第一部分講解如何使用 Docker Compose 部署 Neo4j 圖數據庫，提供完整配置文件及常見問題解決方案；第二部分在前者基礎上，介紹 APOC 插件的集成方法，幫助開發者從零開始搭建完善的 Neo4j 環境。

---

第一部分：Docker Compose 部署 Neo4j 圖數據庫

一、前言

Neo4j 作為主流圖數據庫，在眾多領域有著廣泛應用。采用 Docker 部署能簡化流程、避免環境沖突，讓開發者快速搭建可用的 Neo4j 環境。本部分將聚焦于 Neo4j 本身的 Docker Compose 安裝方法。

二、環境準備

確保系統已安裝以下工具：

• Docker（建議 20.10+）

• Docker Compose（建議 v2.0+）

驗證安裝：

docker --versiondocker-compose --version

Ubuntu 系統快速安裝命令：

sudo apt-get updatesudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

三、項目結構創建

\# 創建項目目錄mkdir neo4j\_docker && cd neo4j\_docker\# 創建數據、日志、導入、插件目錄mkdir -p neo4j/{data,logs,import,plugins}

各目錄作用：

• data：存儲數據庫數據，保障數據持久化

• logs：存放日志，便于排查問題

• import：用于數據導入，Neo4j 可直接訪問

• plugins：預留用于存放擴展插件

四、編寫 Neo4j 基礎 docker-compose.yml 文件

在項目根目錄創建文件，內容如下：

version: '3.9'services:neo4j:image: neo4j:5.12.0container_name: neo4jports:- "18801:7474"- "18802:7687"volumes:- ./neo4j/data:/data- ./neo4j/logs:/logs- ./neo4j/import:/import- ./neo4j/plugins:/pluginsenvironment:# 認證配置NEO4J_AUTH: neo4j/neo4jrag# 內存配置NEO4J_dbms_memory_pagecache_size: 1GNEO4J_dbms_memory_heap_initial__size: 1GNEO4J_dbms_memory_heap_max__size: 1G# 時區配置NEO4J_db_temporal_timezone: Asia/Shanghai

五、關鍵配置解析

1. 基礎配置

• 密碼設置：NEO4J_AUTH 需使用 8 位以上密碼，格式為 “用戶名 / 密碼”，默認用戶名為 neo4j，首次登錄會強制修改密碼。

• 端口映射：7474 對應瀏覽器界面，7687 為 Bolt 協議端口，分別映射到宿主機 18801 和 18802 端口。

• 數據卷掛載：實現數據持久化，容器刪除后數據不丟失，且方便在宿主機操作文件。

2. 內存配置（易錯點）

配置項	說明	配置原則
NEO4J_dbms_memory_pagecache_size	緩存磁盤數據，影響查詢性能	建議為系統可用內存的 50% 左右
NEO4J_dbms_memory_heap_initial__size	JVM 堆初始大小	與堆最大大小一致，避免動態調整損耗性能
NEO4J_dbms_memory_heap_max__size	JVM 堆最大大小	建議為系統可用內存的 25%-30%

?? 注意：

pagecache_size

用單下劃線，

heap.initial_size

和

heap.max_size

因原配置有小數點，在環境變量中用雙下劃線代替，這是 Neo4j 5.x 的特殊規則。

六、啟動 Neo4j 服務及驗證

1. 啟動容器

docker-compose up -d

2. 查看狀態與日志

docker-compose ps  # 查看狀態，顯示 Up 則啟動成功docker-compose logs -f  # 查看日志，出現 Started. 表示啟動完成

3. 訪問驗證

打開瀏覽器訪問 http://localhost:18801，輸入用戶名 neo4j 和密碼 neo4jrag 登錄，首次登錄按提示修改密碼后進入界面。

最終安裝成功構建知識圖譜結果如下：

---

第二部分：在 Neo4j 基礎上集成 APOC 插件

一、APOC 插件簡介

APOC（Awesome Procedures On Cypher）是 Neo4j 強大的擴展插件，提供數百個存儲過程和函數，彌補 Cypher 在復雜數據處理、導入導出等方面的不足，能顯著提升開發效率。

二、修改 docker-compose.yml 集成 APOC

在第一部分基礎配置上，添加 APOC 相關配置，完整文件如下：

version: '3.9'services:neo4j:image: neo4j:5.12.0container_name: neo4jports:- "18801:7474"- "18802:7687"volumes:- ./neo4j/data:/data- ./neo4j/logs:/logs- ./neo4j/import:/import- ./neo4j/plugins:/pluginsenvironment:# 認證配置NEO4J_AUTH: neo4j/neo4jrag# 內存配置NEO4J_dbms_memory_pagecache_size: 1GNEO4J_dbms_memory_heap_initial__size: 1GNEO4J_dbms_memory_heap_max__size: 1G# 時區配置NEO4J_db_temporal_timezone: Asia/Shanghai# APOC插件配置 - 新增部分NEO4J_PLUGINS: '["apoc"]'  # 自動安裝APOC插件NEO4J_dbms_security_procedures_unrestricted: apoc.*  # 允許APOC執行所有操作NEO4J_apoc_export_file_enabled: "true"  # 啟用文件導出NEO4J_apoc_import_file_enabled: "true"  # 啟用文件導入NEO4J_apoc_import_file_use_neo4j_config: "true"  # 使用Neo4j配置的導入路徑

三、APOC 配置詳解

• NEO4J_PLUGINS: '["apoc"]'：容器啟動時自動下載安裝與 Neo4j 版本匹配的 APOC 插件，無需手動下載 JAR 包。

• NEO4J_dbms_security_procedures_unrestricted: apoc.*：解除 APOC 的安全限制，因其包含部分系統級操作功能。

• NEO4J_apoc_export_file_enabled 和 NEO4J_apoc_import_file_enabled：啟用文件導入導出功能，方便批量處理數據。

• NEO4J_apoc_import_file_use_neo4j_config: "true"：讓 APOC 遵循 Neo4j 配置的導入目錄，確保能讀取 import 目錄文件。

四、重啟服務及驗證 APOC 安裝

1. 重啟容器

docker-compose down  # 停止并刪除當前容器docker-compose up -d  # 啟動新配置的容器

2. 驗證 APOC 安裝

在 Neo4j 瀏覽器中執行：

RETURN apoc.version()

若返回版本號（如 5.12.0），則安裝成功；若提示函數不存在，需排查問題。

五、APOC 常用功能示例

1. 數據導入

導入 JSON 數據：

CALL apoc.load.json('import/data.json') YIELD valueCREATE (n:Node) SET n = value

2. 字符串處理

RETURN apoc.text.upper("hello world")  // 輸出 "HELLO WORLD"

3. 日期時間處理

RETURN apoc.date.format(timestamp(), 'ms', 'yyyy-MM-dd HH:mm:ss')  // 格式化當前時間

4. 路徑處理

MATCH (start:Node {name: 'Start'}), (end:Node {name: 'End'})CALL apoc.algo.allSimplePaths(start, end, '', 10) YIELD pathRETURN path

六、APOC 安裝常見問題與解決方案

? 問題：APOC 安裝失敗，提示函數不存在

原因及解決：

• 版本不匹配：通過 NEO4J_PLUGINS: '["apoc"]' 自動匹配版本，無需手動指定。

• 網絡問題：下載失敗時，手動下載對應版本帶 -all 后綴的 APOC JAR 包，放入 neo4j/plugins 目錄后重啟容器。

• 配置錯誤：檢查 NEO4J_dbms_security_procedures_unrestricted 是否包含 apoc.*。

第三部分：根據APOC示例–保存實體

我不解釋這個函數具體用法，我直接給出如何使用APOC將其保存到neo4j數據庫中，其中entities就是一個字典理解就夠了。

 def _create_entities(self, tx, entities):"""創建或合并實體節點。- 若實體不存在：創建并設置所有屬性。- 若實體存在：- 與舊值拼接（用 '; ' 分隔，自動去重空值）使用APOC庫的apoc.create.setProperty處理動態屬性設置"""cypher = """MERGE (e:Entity {name: $name})WITH e, $props AS propsUNWIND keys(props) AS keyWITH e, key, props[key] AS new_val, properties(e)[key] AS old_valWHERE key <> 'name'  // name 不參與合并// 處理空值和修剪空格WITH e, key, old_val, trim(new_val) AS trimmed_new_val, trim(COALESCE(old_val, '')) AS trimmed_old_val// 拆分舊值為數組用于去重檢查WITH e, key, trimmed_new_val, trimmed_old_val,split(trimmed_old_val, '#; ') AS old_vals_array// 計算最終值WITH e, key,CASE // 舊值不存在或為空時，直接使用新值WHEN trimmed_old_val = '' THEN trimmed_new_val// 舊值存在且新值已在舊值中，保持舊值WHEN trimmed_new_val IN old_vals_array THEN trimmed_old_val// 舊值存在且新值不在舊值中，進行合并ELSE apoc.text.join([trimmed_old_val, trimmed_new_val], '#; ')END AS final_val// 使用APOC設置屬性，處理動態屬性名更可靠CALL apoc.create.setProperty(e, key, final_val) YIELD nodeSET e = node  // 將更新后的節點屬性寫回原節點"""for entity in entities:# 提取 entity_ 前綴屬性（去掉前綴）props = {k[7:]: v for k, v in entity.items() if k.startswith("entity_")}if "name" not in props:raise ValueError(f"實體缺少必填主鍵 'name'：{entity}")# 處理可能的None值，轉換為空字符串for key, value in props.items():if value is None:props[key] = ""# 執行合并邏輯tx.run(cypher, name=props["name"], props=props)

總結

本文第一部分詳細介紹了 Neo4j 的 Docker Compose 部署流程，包括環境準備、配置編寫、啟動驗證及問題解決；第二部分在其基礎上，講解了 APOC 插件的集成方法、配置解析、功能示例及相關問題處理。通過這種分步方式，開發者可先搭建基礎的 Neo4j 環境，再根據需求集成 APOC 插件，逐步構建完善的圖數據庫系統。實踐中若遇其他問題，可參考官方文檔獲取更多支持。