Neo4j-06.运维迁移与备份

生产环境不仅要「会用图」，还要「备得出、迁得走、升得上」。本文梳理 Neo4j 5.x 在备份恢复、库迁移、版本升级与日常监控上的标准做法，并标注社区版与企业版差异。

一、Neo4j 5 多数据库模型

Neo4j 5 起支持单实例多库（类似 PostgreSQL 的 database）：

库名	用途
`system`	管理库：用户、库生命周期
`neo4j`	默认业务库
自定义库	`CREATE DATABASE biograph`

:use system
CREATE DATABASE knowledge IF NOT EXISTS;
SHOW DATABASES;

:use knowledge
MATCH (n) RETURN count(n);

备份、恢复、dump 按库操作。

二、备份策略总览

flowchart LR
    A[备份需求] --> B{版本?}
    B -->|社区版| C[neo4j-admin dump]
    B -->|企业版| D[dump + 在线 backup]
    C --> E[对象存储 / NFS]
    D --> E
    E --> F[定期 restore 演练]

方式	版本	在线	说明
database dump	社区+企业	否（需停写或只读）	逻辑备份，跨版本迁移友好
online backup	企业	是	增量备份到磁盘
AuraDB	托管	自动	控制台时间点恢复

三、neo4j-admin database dump（社区版主力）

3.1 导出

# 停止数据库或设为只读（减少不一致风险）
neo4j stop
# 或 Cypher: :use system → STOP DATABASE neo4j WAIT;

neo4j-admin database dump neo4j \
  --to-path=/backups/ \
  --overwrite-destination=true

# 生成 /backups/neo4j.dump
neo4j start

Docker：

1 2	docker exec neo4j neo4j-admin database dump neo4j \ --to-path=/backups --overwrite-destination=true

3.2 恢复（load）

neo4j stop

neo4j-admin database load neo4j \
  --from-path=/backups/neo4j.dump \
  --overwrite-destination=true

neo4j start

注意：load 会覆盖目标库现有数据。

3.3 复制到新库名

1
2
3

neo4j-admin database load biograph \
  --from-path=/backups/neo4j.dump \
  --overwrite-destination=true

四、企业版在线备份（简述）

企业版 neo4j-admin backup 支持在库运行时备份：

1
2
3

neo4j-admin database backup neo4j \
  --to-path=/backups/incremental \
  --type=FULL

配合 因果集群（causal cluster）可对副本节点做备份，降低 primary 压力。社区版无此能力，需维护** dump 窗口**（低峰停机或只读）。

五、版本升级与迁移

5.1 小版本升级（5.x → 5.y）

阅读 Release Notes 兼容性
全量 dump 备份
停库 → 换二进制 / 换 Docker tag → 启动
首次启动自动执行存储迁移（store upgrade）
验证 CALL dbms.components() 版本

5.2 大版本跨越（4.x → 5.x）

必须经官方支持的升级路径（通常 4.4 LTS → 5.x）
dump 迁移往往比原地升级更安全：新装 5.x 空实例 → database load
检查废弃配置项（neo4j.conf 大改）
Cypher 方言差异：测试 APOC/GDS 插件版本匹配

5.3 跨环境迁移（自建 → Aura / 新集群）

# 源自建
neo4j-admin database dump neo4j --to-path=/backups/

# 目标环境 load
neo4j-admin database load neo4j --from-path=/backups/neo4j.dump

Aura 控制台支持 Import 上传 .dump 文件。

5.4 跨库逻辑迁移（同实例）

// APOC 导出子图 Cypher 再执行（中小规模）
CALL apoc.export.cypher.all('/export/migrate.cypher', {
  format: 'cypher-shell',
  useOptimizations: {type: 'UNWIND_BATCH', unwindBatchSize: 1000}
});

六、导出格式对比

格式	工具	适用
`.dump`	neo4j-admin	完整库、官方迁移
CSV	APOC export	部分数据、异构系统
Cypher	APOC export	可读、可编辑、较慢
GraphML	APOC / 第三方	与图工具互操作

七、监控与告警

7.1 关键指标

指标	含义	告警阈值（示例）
`store_size`	磁盘占用	> 80% 磁盘
`page_cache_hit_ratio`	缓存命中率	< 95% 持续
`transaction_started`	事务速率	异常尖峰
`check_point` 延迟	刷盘	持续升高
GC 暂停	堆压力	Full GC 频繁

7.2 启用 Prometheus（Neo4j 5）

1
2
3

# neo4j.conf
server.metrics.prometheus.enabled=true
server.metrics.prometheus.endpoint=0.0.0.0:2004

7.3 日志

文件	内容
`neo4j.log`	启动、生命周期
`query.log`	慢查询（需开启）
`debug.log`	详细诊断

慢查询配置：

1 2	db.logs.query.enabled=VERBOSE db.logs.query.threshold=1s

八、故障恢复流程

flowchart TD
    F[故障] --> G{数据损坏?}
    G -->|是| H[最近 dump 恢复]
    G -->|否| I[重启 / 换节点]
    H --> J[验证 count / 业务探针]
    I --> J
    J --> K{集群?}
    K -->|企业集群| L[提升副本为 leader]
    K -->|单机| M[完成]

场景	动作
进程崩溃	`neo4j start`；查 `debug.log`
磁盘满	扩盘；清理旧 transaction log
误删数据	停写 → 从最近 dump 恢复到新库 → 合并
集群脑裂	企业版运维手册；联系支持

恢复演练：每季度至少一次 dump → load 到 staging 并跑对账查询。

九、安全与权限（运维相关）

:use system
CREATE USER app_reader IF NOT EXISTS SET PASSWORD '...' CHANGE NOT REQUIRED;
GRANT ROLE reader TO app_reader;

:use neo4j
GRANT TRAVERSE ON GRAPH neo4j NODES * TO app_reader;

企业版支持更细 RBAC（role-based access control，基于角色的访问控制）与 LDAP。Aura 在控制台管理用户。

十、Docker / K8s 生产注意

项	建议
持久卷	`data`、`logs`、`import` 分别 PVC
内存	容器 limit ≥ heap + pagecache + OS
备份	Sidecar 或 CronJob 调 `neo4j-admin dump`
只读副本	企业版/K8s Helm 官方 chart

十一、小结

社区版备份主力：neo4j-admin database dump/load；恢复前务必有离线副本。
升级路径：先 dump，再升版本，大版本跳跃优先 dump 到新实例。
监控 页缓存命中率、磁盘、慢查询；Prometheus 接入 Grafana。
多库时代备份粒度是 database，不是整个 data 目录一把拷。

下一篇	内容
Neo4j-07.进阶能力与Graph-Data-Science	APOC、GDS、RAG
Neo4j-08.局限性与生产实践	超级节点、选型