Neo4j 从入门到实战：含 K8s 集群部署指南

docker run -d \
  --name neo4j-demo \
  -p 7474:7474 -p 7687:7687 \
  -v /host/neo4j/data:/data \
  -v /host/neo4j/logs:/logs \
  -e NEO4J_AUTH=neo4j/123456 \
  neo4j:5.15-community

其中：

• 7474 为 Web 管理界面端口，7687 为 Bolt 协议通信端口；
• /host/neo4j/data 为本地数据目录，需替换为实际路径；
• NEO4J_AUTH 设置初始用户名（默认 neo4j）和密码（此处为 123456）。

3. 验证容器状态

输入 docker ps，若 neo4j-demo 容器状态为 Up，则说明启动成功。

三、Neo4j 部署方案：Kubernetes 集群实战

对于生产级业务，单节点部署无法满足高可用和可扩展性需求。Kubernetes（简称 K8s）作为主流的容器编排平台，能为 Neo4j 提供自动扩缩容、故障自愈、负载均衡等能力，是企业级 Neo4j 部署的最佳实践。本节将从集群架构、环境准备、部署流程到验证运维进行全面讲解。

1. Neo4j K8s 集群架构解析

Neo4j 在 K8s 环境中通常采用'核心集群 + 只读副本'的架构，核心组件包括：

• 核心节点（Core Nodes）：负责数据写入、事务处理和集群管理，至少 3 个节点以实现高可用（避免脑裂）；
• 只读副本（Read Replicas）：承担只读查询请求，分担核心节点压力，可根据查询负载动态扩展；
• 持久化存储：通过 K8s PV/PVC 机制挂载外部存储（如 AWS EBS、阿里云云盘、本地存储），保证数据持久化；
• 服务发现与负载均衡：通过 K8s Service 暴露服务，核心节点使用 Headless Service 实现内部通信，外部访问通过 LoadBalancer 或 Ingress 实现。

该架构能实现：① 核心节点故障时自动切换，保障服务可用性；② 只读请求分流，提升查询性能；③ 存储与计算分离，便于数据管理。

2. 部署前置条件

在开始部署前，需确保 K8s 环境满足以下要求：

• K8s 集群版本≥1.21（Neo4j Helm Chart 对低版本兼容性较差）；
• 集群节点总内存≥12GB（每个核心节点建议 4GB 以上内存，3 个核心节点为例）；
• 已安装 Helm 3.x（包管理工具，简化部署流程）；
• 已配置持久化存储类（StorageClass），支持动态 PV 创建（生产环境推荐使用云厂商块存储或分布式存储）；
• 集群网络插件正常（如 Calico、Flannel），确保 Pod 间通信畅通。

验证环境：

# 验证 K8s 集群状态
kubectl get nodes
# 验证 Helm 版本
helm version

3. 详细部署流程

Neo4j 官方提供了 Helm Chart，可快速实现集群部署和配置管理，以下为完整流程：

步骤 1：添加 Neo4j Helm 仓库并更新

Helm 仓库包含 Neo4j 的部署配置模板，执行以下命令添加并同步最新版本：

# 添加 Neo4j 官方 Helm 仓库
helm repo add neo4j https://helm.neo4j.com/neo4j
# 更新仓库索引，确保获取最新 Chart
helm repo update

步骤 2：自定义配置文件（关键）

直接使用默认配置可能无法满足生产需求，建议创建自定义 values.yaml 文件，配置核心参数。以下为常用配置示例（根据实际需求调整）：

# values.yaml 核心配置
neo4j:
  # 集群认证配置
  auth:
    username: neo4j
    password: Neo4j@2024 # 生产环境使用强密码，建议通过 Secret 注入
  
  # 核心节点配置
  core:
    replicas: 3 # 核心节点数，生产环境至少 3 个
    resources:
      requests:
        cpu: 2
        memory: 4Gi
      limits:
        cpu: 4
        memory: 6Gi
  
  # 持久化存储配置
  persistence:
    enabled: true
    storageClass: "aliyun-disk-ssd" # 替换为你的 StorageClass 名称
    size: 50Gi # 每个核心节点的存储容量
  
  # Neo4j 配置参数
  config:
    dbms.memory.heap.initial_size: 2G
    dbms.memory.heap.max_size: 2G
    dbms.memory.pagecache.size: 2G
    dbms.default_listen_address: 0.0.0.0
    dbms.connector.bolt.enabled: true
    dbms.connector.bolt.listen_address: ":7687"
    dbms.connector.http.enabled: true
    dbms.connector.http.listen_address: ":7474"
  
  # 只读副本配置（可选，根据查询负载设置）
  readReplica:
    replicas: 2
    resources:
      requests:
        cpu: 1
        memory: 2Gi
      limits:
        cpu: 2
        memory: 4Gi
    persistence:
      enabled: true
      storageClass: "aliyun-disk-ssd"
      size: 30Gi
  
  # 插件配置（如 GDS 库）
  plugins:
    config:
      dbms.security.procedures.unrestricted: "gds.*"
    pluginsList:
      - name: "graph-data-science"
        artifactId: "neo4j-graph-data-science"
        version: "2.6.0"
        repository: "https://neo4j.jfrog.io/neo4j/libs-release-local"
  
  # 服务配置
  service:
    # 核心节点 Headless Service（用于集群内部通信）
    core:
      type: ClusterIP
      clusterIP: None
    # 只读副本 Service（用于外部只读请求访问）
    readReplica:
      type: LoadBalancer # 云环境推荐使用，暴露公网访问
      loadBalancerSourceRanges: ["192.168.0.0/16"] # 限制访问 IP 段，提升安全性
    # HTTP 管理界面 Service
    http:
      type: LoadBalancer
      loadBalancerSourceRanges: ["192.168.0.0/16"]
  
  # 监控配置（集成 Prometheus）
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true # 若使用 Prometheus Operator，开启后自动发现监控目标

关键配置说明：① 核心节点数≥3，确保 Raft 协议正常选举；② 内存配置遵循'堆内存≤物理内存 50%，页缓存≈堆内存'原则；③ 生产环境避免明文存储密码，可通过 kubectl create secret 创建 Secret，再在配置中引用；④ 限制 Service 访问 IP 段，防止未授权访问。

步骤 3：执行部署命令

使用自定义的 values.yaml 文件部署 Neo4j 集群，指定命名空间（建议单独创建命名空间隔离资源）：

# 创建命名空间
kubectl create namespace neo4j-cluster
# 部署 Neo4j 集群
helm install neo4j-cluster neo4j/neo4j \
  --namespace neo4j-cluster \
  --values values.yaml \
  --version 5.15.0 # 指定与 Neo4j 版本匹配的 Chart 版本

步骤 4：监控部署进度

部署过程中，K8s 会自动创建 StatefulSet、Service、PVC 等资源，可通过以下命令监控进度：

# 查看 Pod 状态，等待所有 Pod 变为 Running
kubectl get pods -n neo4j-cluster -w
# 查看 PVC 状态，确保所有存储卷正常绑定
kubectl get pvc -n neo4j-cluster
# 查看 Service 状态，获取负载均衡器 IP（若使用 LoadBalancer）
kubectl get svc -n neo4j-cluster

当所有核心节点和只读副本 Pod 均为 Running 状态，且 PVC 绑定成功时，部署完成。

4. 集群验证与初始化

部署完成后，需验证集群状态并进行初始化配置：

验证集群成员

进入任意核心节点 Pod，执行 Neo4j 集群状态查询命令：

# 进入核心节点 Pod（替换为实际 Pod 名称）
kubectl exec -it neo4j-cluster-core-0 -n neo4j-cluster -- bash
# 执行集群状态查询
cypher-shell -u neo4j -p Neo4j@2024 "CALL dbms.cluster.overview()"

若输出包含所有核心节点和只读副本的信息，且角色正确（核心节点为 CORE，只读副本为 READ_REPLICA），则集群组建成功。

访问 Web 管理界面

通过 HTTP Service 的负载均衡器 IP 或 NodePort 访问 Neo4j Browser：

• 若为 LoadBalancer 类型，获取 IP：kubectl get svc neo4j-cluster-http -n neo4j-cluster -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
• 浏览器访问：http://<负载均衡器 IP>:7474
• 输入用户名和密码登录，首次登录建议修改初始密码。

5. 集群运维核心操作

K8s 环境下的 Neo4j 集群运维需结合 K8s 工具和 Neo4j 自身命令，以下为常用操作：

（1）集群扩容/缩容

通过修改 values.yaml 中的副本数，执行 Helm 升级命令实现扩容/缩容：

# 修改 values.yaml 中 readReplica.replicas 为 3，执行升级
helm upgrade neo4j-cluster neo4j/neo4j \
  --namespace neo4j-cluster \
  --values values.yaml

核心节点扩容需确保副本数为奇数（如 3→5），避免脑裂。

（2）数据备份与恢复

利用 Neo4j 的 neo4j-admin 工具结合 K8s 的 Job 实现备份：

# 创建备份 Job（示例，实际需挂载备份存储卷）
kubectl create job neo4j-backup -n neo4j-cluster \
  --image=neo4j:5.15-community \
  --command -- neo4j-admin backup --to=/backup \
  --host=neo4j-cluster-core-0.neo4j-cluster-core.neo4j-cluster.svc.cluster.local:6362

恢复时，将备份文件挂载至核心节点 Pod，执行 neo4j-admin restore 命令。

（3）配置更新

修改 values.yaml 中的 Neo4j 配置后，执行 Helm 升级，K8s 会自动滚动更新 Pod，避免服务中断：

helm upgrade neo4j-cluster neo4j/neo4j \
  --namespace neo4j-cluster \
  --values values.yaml

（4）故障排查

# 查看 Pod 日志
kubectl logs neo4j-cluster-core-0 -n neo4j-cluster -f
# 查看集群事件
kubectl get events -n neo4j-cluster
# 进入 Pod 执行诊断命令
kubectl exec -it neo4j-cluster-core-0 -n neo4j-cluster -- cypher-shell -u neo4j -p Neo4j@2024 "CALL dbms.health.check()"

四、其他部署方案对比

除了 K8s 集群部署，Neo4j 还支持多种部署模式，可根据业务规模和运维能力灵活选择：

1. 本地自托管部署

• 适用场景：个人开发、小型项目、本地测试；
• 优势：部署简单、成本低，可自由配置参数；
• 局限：无高可用保障，不适合生产级大规模业务；
• 配置要点：修改 neo4j.conf 文件调整内存分配、开启远程访问等。

2. 云托管部署（AuraDB）

• 适用场景：无本地运维能力的团队、快速上线的云原生项目；
• 优势：无需管理基础设施，自动备份、自动扩容，支持按需付费；
• 部署流程：进入 Neo4j Aura 官网，注册账号后创建实例，直接通过 Web 界面或 Bolt 协议连接。

3. 部署方案对比表

五、Neo4j 基础使用实战

完成部署后，我们以 K8s 集群环境为例，通过 Neo4j Browser 和 Cypher 语言，实现从数据导入、图查询到简单分析的全流程操作。

1. 连接 K8s 集群中的 Neo4j

• Web 界面连接：使用 HTTP Service 的负载均衡器 IP，访问 http://<IP>:7474，输入用户名密码登录；
• 客户端连接：通过 Bolt 协议连接，地址为 bolt://<负载均衡器 IP>:7687，适用于 Java、Python 等客户端库；
• 集群内部连接：Pod 内部可通过 Headless Service 地址连接核心节点，如 bolt://neo4j-cluster-core-0.neo4j-cluster-core.neo4j-cluster.svc.cluster.local:7687。

2. 数据模型构建（电影 - 演员知识图谱）

通过 Cypher 语句创建节点、关系和属性，构建简单的图数据模型：

（1）创建节点

// 创建电影节点（含标题、年份、评分属性）
CREATE (m1:Movie {title: "《星际穿越》", year: 2014, rating: 9.4})
CREATE (m2:Movie {title: "《盗梦空间》", year: 2010, rating: 9.4})
CREATE (m3:Movie {title: "《华尔街之狼》", year: 2013, rating: 8.0})
// 创建演员节点（含姓名、年龄属性）
CREATE (a1:Actor {name: "马修·麦康纳", age: 54})
CREATE (a2:Actor {name: "莱昂纳多·迪卡普里奥", age: 49})
CREATE (a3:Actor {name: "约瑟夫·高登 - 莱维特", age: 43})

（2）创建关系

// 建立演员 - 参演 - 电影的关系（含角色属性）
MATCH (a1:Actor {name: "马修·麦康纳"}), (m1:Movie {title: "《星际穿越》"})
CREATE (a1)-[:ACTED_IN {role: "库珀"}]->(m1)
MATCH (a2:Actor {name: "莱昂纳多·迪卡普里奥"}), (m2:Movie {title: "《盗梦空间》"})
CREATE (a2)-[:ACTED_IN {role: "柯布"}]->(m2)
MATCH (a2:Actor {name: "莱昂纳多·迪卡普里奥"}), (m3:Movie {title: "《华尔街之狼》"})
CREATE (a2)-[:ACTED_IN {role: "乔丹·贝尔福特"}]->(m3)
MATCH (a3:Actor {name: "约瑟夫·高登 - 莱维特"}), (m2:Movie {title: "《盗梦空间》"})
CREATE (a3)-[:ACTED_IN {role: "亚瑟"}]->(m2)

（3）创建索引（优化查询性能）

对于高频查询的属性，创建索引可大幅提升查询效率：

// 为演员姓名和电影标题创建索引
CREATE INDEX idx_actor_name FOR (a:Actor) ON (a.name)
CREATE INDEX idx_movie_title FOR (m:Movie) ON (m.title)

3. 基础 Cypher 查询实战

（1）简单查询：获取所有电影信息

MATCH (m:Movie) RETURN m.title AS 电影标题，m.year AS 上映年份，m.rating AS 评分 ORDER BY m.rating DESC

（2）关联查询：查询莱昂纳多参演的所有电影

MATCH (a:Actor {name: "莱昂纳多·迪卡普里奥"})-[:ACTED_IN]->(m:Movie) RETURN a.name AS 演员姓名，m.title AS 电影标题，m.year AS 上映年份，a.age AS 演员年龄

（3）聚合查询：统计各电影的参演演员数量

MATCH (a:Actor)-[:ACTED_IN]->(m:Movie) RETURN m.title AS 电影标题，count(a) AS 演员数量 ORDER BY 演员数量 DESC

（4）路径查询：查询演员间的合作关系（二度关系）

路径查询是图数据库的核心能力，可快速挖掘节点间的间接关联。以下查询将找出与'莱昂纳多'有合作关系的演员（直接合作）及合作演员的合作对象（二度合作）：

// 查询莱昂纳多的一度（直接合作）和二度（间接合作）演员关系
MATCH path = (a:Actor {name: "莱昂纳多·迪卡普里奥"})-[:ACTED_IN*1..2]-(colleague:Actor)
WHERE colleague.name <> "莱昂纳多·迪卡普里奥" // 排除自身
RETURN a.name AS 核心演员，collect(DISTINCT colleague.name) AS 关联演员，length(path) AS 关系度数 // 1 为直接合作，2 为间接合作
ORDER BY 关系度数