Docker部署 Neo4j 及集成 APOC 插件：安装与配置完整指南（docker-compose）

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 --version

docker-compose --version

Ubuntu 系统快速安装命令：

复制代码

sudo apt-get update

sudo 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` 文件

在项目根目录创建文件，内容如下：

yml 复制代码

version: '3.9'

services:
  neo4j:
    image: neo4j:5.12.0
    container_name: neo4j
    ports:
      - "18801:7474"
      - "18802:7687"
    volumes:
      - ./neo4j/data:/data
      - ./neo4j/logs:/logs
      - ./neo4j/import:/import
      - ./neo4j/plugins:/plugins
    environment:
      # 认证配置
      NEO4J_AUTH: neo4j/neo4jrag

      # 内存配置
      NEO4J_dbms_memory_pagecache_size: 1G
      NEO4J_dbms_memory_heap_initial__size: 1G
      NEO4J_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 :1880 1，输入用户名 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.0
    container_name: neo4j
    ports:
      - "18801:7474"
      - "18802:7687"
    volumes:
      - ./neo4j/data:/data
      - ./neo4j/logs:/logs
      - ./neo4j/import:/import
      - ./neo4j/plugins:/plugins
    environment:
      # 认证配置
      NEO4J_AUTH: neo4j/neo4jrag

      # 内存配置
      NEO4J_dbms_memory_pagecache_size: 1G
      NEO4J_dbms_memory_heap_initial__size: 1G
      NEO4J_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 value

CREATE (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 path

RETURN path

六、APOC 安装常见问题与解决方案

❌ 问题：APOC 安装失败，提示函数不存在

原因及解决：

版本不匹配 ：通过 NEO4J_PLUGINS: '["apoc"]' 自动匹配版本，无需手动指定。
网络问题 ：下载失败时，手动下载对应版本带 -all 后缀的 APOC JAR 包，放入 neo4j/plugins 目录后重启容器。
配置错误 ：检查 NEO4J_dbms_security_procedures_unrestricted 是否包含 apoc.*。

第三部分：根据APOC示例--保存实体

我不解释这个函数具体用法，我直接给出如何使用APOC将其保存到neo4j数据库中，其中entities就是一个字典理解就够了。

python 复制代码

 def _create_entities(self, tx, entities):
        """
        创建或合并实体节点。
        - 若实体不存在：创建并设置所有属性。
        - 若实体存在：
            - 与旧值拼接（用 '; ' 分隔，自动去重空值）
        使用APOC库的apoc.create.setProperty处理动态属性设置
        """
        cypher = """
        MERGE (e:Entity {name: $name})
        WITH e, $props AS props
        UNWIND keys(props) AS key
        WITH e, key, props[key] AS new_val, properties(e)[key] AS old_val
        WHERE 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 node
        SET 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 插件，逐步构建完善的图数据库系统。实践中若遇其他问题，可参考官方文档获取更多支持。

Docker部署 Neo4j 及集成 APOC 插件：安装与配置完整指南（docker-compose）

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

第一部分：Docker Compose 部署 Neo4j 图数据库

一、前言

二、环境准备

三、项目结构创建

四、编写 Neo4j 基础 docker-compose.yml 文件

五、关键配置解析

1. 基础配置

2. 内存配置（易错点）

六、启动 Neo4j 服务及验证

1. 启动容器

2. 查看状态与日志

3. 访问验证

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

一、APOC 插件简介

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

三、APOC 配置详解

四、重启服务及验证 APOC 安装

1. 重启容器

2. 验证 APOC 安装

五、APOC 常用功能示例

1. 数据导入

2. 字符串处理

3. 日期时间处理

4. 路径处理

六、APOC 安装常见问题与解决方案

❌ 问题：APOC 安装失败，提示函数不存在

第三部分：根据APOC示例--保存实体

总结

四、编写 Neo4j 基础 `docker-compose.yml` 文件

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