备份在线数据库

请记住仔细规划备份，并备份您的每个数据库，包括 system 数据库。

请注意，不允许备份数据库别名，只能备份物理数据库。

命令

可以使用 neo4j-admin 的 backup 命令在在线模式下备份 Neo4j 数据库。该命令必须以 neo4j 用户身份调用，以确保适当的文件权限。

最佳实践（但非强制要求）是在与数据库位于同一网络上但不是集群一部分的服务器上执行备份。您应该在该机器上安装 Neo4j 以使 neo4j-admin 命令可用。该机器被称为备份客户端。

备份工件

每次运行 neo4j-admin database backup 命令时，都会为每个数据库生成一个备份工件文件。备份工件文件是一个不可变文件，包含给定数据库的备份数据以及一些元数据，例如数据库名称和 ID、备份时间、最低/最高事务 ID 等。

备份工件有两种类型

  1. 包含整个数据库存储的完整备份，或

  2. 包含要应用于完整备份工件中数据库存储的事务日志的增量备份。

备份链

首次运行备份命令时，会为给定数据库生成一个完整备份工件。另一方面，后续运行会生成增量备份工件。

备份链由一个完整备份组成，其后可选地跟着一系列 n 个连续的增量备份。

backup chain
图 1. 备份链

用法

neo4j-admin database backup 命令可用于从运行中的 Neo4j Enterprise 服务器执行在线完整备份或增量备份。生成的增量备份工件包含事务日志，这些日志在恢复备份链时可以重放并应用于完整备份工件中包含的存储。

Neo4j 的备份服务必须事先在服务器上配置好。该命令可以在本地和远程运行。但是，它会占用大量的资源，例如内存和 CPU。因此，建议在单独的专用机器上执行备份。neo4j-admin database backup 命令还支持 SSL/TLS。有关更多信息，请参阅在线备份配置。

Neo4j Aura 不支持 neo4j-admin database backup。

语法

neo4j-admin database backup [-h] [--expand-commands] [--prefer-diff-as-parent] [--verbose]
                            [--compress[=true|false]] [--keep-failed[=true|false]]
                            [--parallel-recovery[=true|false]] [--additional-config=<file>]
                            [--include-metadata=none|all|users|roles] [--inspect-path=<path>]
                            [--pagecache=<size>] [--temp-path=<path>] [--to-path=<path>]
                            [--type=<type>] [--from=<host:port>[,<host:port>...]]... [<database>...]

描述

从运行中的 Neo4j Enterprise 服务器执行在线备份。Neo4j 的备份服务必须事先在服务器上配置好。

参数

表 1. neo4j-admin database backup 参数
参数 描述 默认值

[<database>…​]

要备份的远程数据库名称。支持双引号内的 globbing 模式，例如 "data*"。（除非使用 --inspect-path，否则 <database> 为必填项。）

neo4j

如果 <database> 是 "*"，neo4j-admin 将尝试备份 DBMS 中的所有数据库。

选项

表 2. neo4j-admin database backup 选项
选项 描述 默认值

--additional-config=<file>[1]

包含附加配置的配置文件。

--compress[=true|false]

请求备份工件进行压缩。压缩可以使备份工件的尺寸缩小多倍，但具体的缩小程度取决于许多因素，包括数据库格式和存储的数据类型。如果禁用，生成的工件大小将近似等于备份数据库的大小。备份操作的速度受压缩影响，但哪种更快取决于 CPU 和存储的相对性能。如果备份速度很重要，请考虑评估两种选项 — 启用压缩和禁用压缩。

true

--expand-commands

允许在配置值评估中进行命令扩展。

--from=<host:port>[,<host:port>…​]

以逗号分隔的 Neo4j 实例主机和端口列表，将按顺序尝试每个实例。

-h, --help

显示此帮助消息并退出。

--include-metadata=none|all|users|roles

在文件中包含元数据。这不能用于备份 system 数据库。可能的值有：

  • roles - 包含用于创建影响数据库使用的角色和权限（适用于数据库和图）的命令。

  • users - 包含用于创建可以使用数据库的用户及其角色分配的命令。

  • all - 同时包含 roles 和 users。

  • none - 不包含任何元数据。

    特定于 DBMS 而非备份数据库的权限不包含在备份中。例如，GRANT ROLE MANAGEMENT ON DBMS TO $role 将不会被备份。

因此，不具有数据库相关权限的 roles 和 users（例如，仅具有 DBMS 权限或无权限的）不包含在备份中。

建议使用 SHOW USERS、SHOW ROLES 和 SHOW ROLE $role PRIVILEGES AS COMMANDS 来获取这些情况下的完整用户、角色和权限列表。

all

--inspect-path=<path>

列出并显示备份工件的元数据。接受文件夹或文件。

--keep-failed[=true|false]

请求保留失败的备份以供后续故障分析。如果启用，将保留一个包含失败备份数据库的目录。

false

--pagecache=<size>

用于备份过程的页面缓存大小。

--parallel-recovery[=true|false]

允许多个线程并行地将拉取的事务应用于备份。对于某些数据库和工作负载，这可能会显著缩短备份时间。注意：这是一个实验性选项。使用前请咨询 Neo4j 支持。

false

--prefer-diff-as-parent

2025.04 版本引入 在执行增量备份时，优先使用最新的非空增量备份作为父级，而不是最新的备份。

false

--temp-path=<path>

提供一个临时空目录的路径，用于存储备份文件，直到命令完成。命令完成后，文件将被删除。

--to-path=<path>

存放备份的目录（除非使用 --inspect-path，否则为必填项）。可以使用适当的 URI 作为路径，将数据库备份到 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶。

--type=<type>

要执行的备份类型。可能的值有：FULL（完整备份）、DIFF（增量备份）、AUTO（自动）。如果未指定，则根据现有备份自动确定类型。如果要强制执行完整备份，请使用 FULL。

AUTO

--verbose

启用详细输出。

1. 有关详细信息，请参阅Neo4j Admin 和 Neo4j CLI → 配置。

--to-path=<path> 选项还可以将数据库备份到 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶。有关更多信息，请参阅将数据库备份到云存储。

--temp-path 选项可以解决在执行备份相关命令时（特别是涉及云存储时）可能出现的磁盘空间问题。

如果未设置 --temp-path，则会在 --path 选项指定的目录内创建一个临时目录。

如果您未提供 --path 选项，或者您提供的路径指向云存储桶，则会在 Neo4j 当前工作目录中创建一个临时文件夹。此备用选项可能会导致问题，因为本地文件系统（或安装 Neo4j 的分区）可能没有足够的可用磁盘空间来容纳中间计算。

因此，强烈建议在执行备份相关命令时提供 --temp-path 选项，特别是当 --path 选项中提供的文件夹指向云存储桶时。

退出代码

根据备份是否成功，neo4j-admin database backup 会以不同的代码退出。错误代码包含遇到何种错误的详细信息。

表 3. 备份单个数据库时 Neo4j Admin 备份退出代码
代码 描述

0

成功。

1

备份失败，或成功但遇到问题，例如某些服务器无法联系。有关更多详细信息，请参阅日志。
表 4. 备份多个数据库时 Neo4j Admin 备份退出代码
代码 描述

0

所有数据库均已成功备份。

1

一个或多个备份失败，或成功但存在问题。

在线备份配置

检查点

请求完整备份时，总是会触发一个检查点。备份无法在检查点完成之前进行。

当服务器正在进行检查点时，备份作业不接收数据，这可能导致备份超时。要延长备份超时时间，请修改dbms.cluster.network.client_inactivity_timeout 设置，该设置限制了网络不活动时间。它控制了 catchup 协议的超时持续时间，该协议是包括备份在内的多个 catchup 过程的基础协议。

您还可以调整检查点设置或检查您的磁盘性能是否足以处理负载。有关更多信息，请参阅检查点 IOPS 限制。

要了解有关检查点的更多信息，请参阅数据库内部结构 → 检查点和日志修剪。

服务器配置

下表列出了与备份相关的基本服务器参数。请注意，默认情况下，备份服务已启用，但仅监听 localhost (127.0.0.1)。如果要从其他机器进行备份，则需要更改此设置。

表 5. 备份的服务器参数
参数名称 默认值 描述

server.backup.enabled

true

启用在线备份支持。

server.backup.listen_address

127.0.0.1:6362

在线备份监听服务器。

内存配置

以下选项可用于配置分配给备份客户端的内存

  • 配置备份的堆大小：

HEAP_SIZE 配置分配给备份进程的最大堆大小。这是通过在开始操作之前设置环境变量 HEAP_SIZE 来完成的。如果未指定，Java 虚拟机将根据服务器资源选择一个值。

  • 配置备份的页面缓存：

页面缓存大小可以通过使用 neo4j-admin database backup 命令的 --pagecache 选项来配置。

您应该为 Neo4j 页面缓存分配尽可能多的内存，只要它满足以下约束条件：

Neo4j 页面缓存 + 操作系统页面缓存 < 可用 RAM，其中 2 到 4GB 应专用于操作系统的页面缓存。

例如，如果您的当前数据库根据 debug.log 显示的 Total mapped size 为 128GB，并且您有足够的可用空间（这意味着您已为操作系统预留了 2 到 4 GB），那么您可以将 --pagecache 设置为 128GB。

计算资源配置

事务日志文件

事务日志文件用于跟踪最近的更改，并根据提供的配置进行轮换和修剪。例如，设置 db.tx_log.rotation.retention_policy=3 文件可在备份中保留 3 个事务日志文件。由于恢复的服务器不需要所有已应用的事务日志文件，因此可以通过将文件大小减小到最低限度来进一步减少存储大小。这可以通过设置 db.tx_log.rotation.size=1M 和 db.tx_log.rotation.retention_policy=3 文件来完成。您可以使用 --additional-config 参数覆盖 neo4j.conf 文件中的配置。

手动删除事务日志可能导致备份损坏。

安全配置

使用 SSL 策略和防火墙保护您的备份网络通信，可防止数据遭到未经授权的入侵和泄漏。使用 neo4j-admin database backup 命令时，您可以将备份服务器配置为要求 SSL/TLS，并使备份客户端使用兼容的策略。有关如何在 Neo4j 中配置 SSL 的更多信息，请参阅SSL 框架。

备份服务器的配置应添加到 neo4j.conf 文件中，备份客户端的配置应添加到 neo4j-admin.conf 文件中。SSL 设置应在两者之间保持一致以确保兼容性。

默认备份端口是 6362，通过键 server.backup.listen_address 配置。SSL 配置策略的键为 dbms.ssl.policy.backup。

例如，将以下内容添加到您的 neo4j.conf 和 neo4j-admin.conf 文件中

dbms.ssl.policy.backup.enabled=true
dbms.ssl.policy.backup.tls_versions=TLSv1.2
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
dbms.ssl.policy.backup.client_auth=REQUIRE

Neo4j 还支持 TLSv1.3。要同时使用 TLSv1.2 和 TLSv1.3 版本，您必须指定每个版本要强制执行的密码套件。否则，Neo4j 可能会使用 JVM 中所有可能的密码套件，导致配置安全性降低。

有关 Neo4j 安全性建议的详细列表，请参阅安全清单。

确保没有外部访问 server.backup.listen_address 设置指定的端口非常重要。未能保护此端口可能会留下一个安全漏洞，未经授权的用户可以通过该漏洞将数据库复制到其他机器上。在生产环境中，应通过防火墙阻止对备份端口的外部访问。

集群配置

在集群拓扑中，可以从任何托管要备份数据库的服务器进行备份，并且每个服务器都有两个可配置的端口能够提供备份服务。这些端口分别由 server.backup.listen_address 和 server.cluster.listen_address 配置。从功能上讲，它们对于备份是等效的，但将它们分开可以提供一些操作灵活性，而仅使用单个端口可以简化配置。通常建议选择辅助服务器作为备份服务器，因为在典型的集群部署中，它们的数量比主服务器更多。此外，由大型备份引起的辅助服务器上的性能问题不会影响主服务器的性能或冗余。如果辅助服务器不可用，则可以根据物理距离、带宽、性能和活跃度等因素选择主服务器。

使用 SHOW DATABASES 命令了解哪个数据库托管在哪个服务器上。

为避免从滞后的集群成员进行备份，您可以通过公开 Neo4j 指标或 Neo4j Browser 查看事务 ID。要在 Neo4j Browser 中查看最新处理的事务 ID（和其他指标），请在提示符下键入 :sysinfo。

针对多个服务器

从集群进行备份时，建议提供多个目标服务器列表，因为即使某些服务器宕机，或者并非所有数据库都托管在同一服务器上，这也可以使备份成功。如果命令发现一个或多个服务器没有响应，它会继续尝试从其他服务器备份，并继续备份其他请求的数据库，但命令的退出代码将非零，以提醒用户存在问题。如果数据库使用名称模式并与多个目标服务器一起使用，则所有服务器都将贡献到匹配数据库的列表中。

示例

以下是如何对单个数据库和多个数据库执行备份的示例。目标目录 /mnt/backups/neo4j 必须在调用命令之前存在，并且数据库必须在线。

备份单个数据库

您不需要使用 --type 选项来指定备份类型。默认情况下，类型会根据现有备份自动确定。

bin/neo4j-admin database backup --to-path=/path/to/backups/neo4j neo4j

执行单个数据库的强制完整备份。

如果您想在多次增量备份后强制执行完整备份，可以使用 --type=full 选项。

bin/neo4j-admin database backup --type=full --to-path=/path/to/backups/neo4j neo4j

备份多个数据库

要备份与数据库模式匹配的多个数据库，您可以使用名称 globbing。例如，要备份三节点集群中所有以 n 开头的数据库，请运行

bin/neo4j-admin database backup --from=192.168.1.34:6362,192.168.1.35:6362,192.168.1.36:6362 --to-path=/mnt/backups/neo4j --pagecache=4G "n*"

备份数据库列表

要按名称备份多个数据库，您可以提供数据库名称列表。

neo4j-admin database backup --from=192.168.1.34:6362,192.168.1.35:6362,192.168.1.36:6362 --to-path=/mnt/backups/neo4j --pagecache=4G "test*" "neo4j"

将数据库备份到云存储

在 Neo4j 2025.03 中，引入了新的云集成设置，以更好地支持云生态系统中的部署和管理。有关详细信息，请参阅配置设置 → 云存储集成设置。

以下示例展示了如何使用 --to-path 选项将数据库备份到云存储桶。

Neo4j 使用 AWS SDK v2 调用 AWS 上的 API，使用 AWS URL。或者，您可以覆盖端点，以便 AWS SDK 可以使用系统变量 aws.endpointUrls3、aws.endpointUrlS3 或 aws.endpointUrl，或环境变量 AWS_ENDPOINT_URL_S3 或 AWS_ENDPOINT_URL 与其他存储系统（例如 Ceph、Minio 或 LocalStack）通信。

  1. 按照 AWS 官方文档中的说明安装 AWS CLI — 安装 AWS CLI 版本 2。

  2. 使用 AWS CLI 创建 S3 存储桶和目录以存储备份文件

    aws s3 mb --region=us-east-1 s3://myBucket
aws s3api put-object --bucket myBucket --key myDirectory/

    有关如何创建存储桶和使用 AWS CLI 的更多信息，请参阅 AWS 官方文档 — 将 Amazon S3 与 AWS CLI 结合使用 和 将高级 (s3) 命令与 AWS CLI 结合使用。

  3. 通过运行以下命令验证 ~/.aws/config 文件是否正确

    cat ~/.aws/config

    输出应如下所示

    [default]
region=us-east-1

  4. 通过在 ~/.aws/credentials 文件中设置 aws_access_key_id 和 aws_secret_access_key 来配置对 AWS S3 存储桶的访问，如果需要，还可以使用存储桶策略。例如

    1. 使用 aws configure set aws_access_key_id aws_secret_access_key 命令设置您的 AWS IAM 凭据，并验证 ~/.aws/credentials 是否正确

      cat ~/.aws/credentials

      输出应如下所示

      [default]
aws_access_key_id=this.is.secret
aws_secret_access_key=this.is.super.secret

    2. 此外，您可以使用基于资源的策略授予对 S3 存储桶及其中的对象的访问权限。创建一个包含以下内容的策略文档并将其附加到存储桶。请注意，这两个资源条目对于能够下载和上传文件都很重要。

      {
    "Version": "2012-10-17",
    "Id": "Neo4jBackupAggregatePolicy",
    "Statement": [
        {
            "Sid": "Neo4jBackupAggregateStatement",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket/*",
                "arn:aws:s3:::myBucket"
            ]
        }
    ]
}

  5. 运行 neo4j-admin database backup 命令将您的数据库备份到 AWS S3 存储桶

    bin/neo4j-admin database backup --to-path=s3://myBucket/myDirectory/ mydatabase

  1. 确保您拥有 Google 帐户并在 Google Cloud Platform (GCP) 中创建了项目。

    1. 按照 Google 官方文档中的说明安装 gcloud CLI — 安装 gcloud CLI。

    2. 使用 Google 官方文档创建服务帐号和服务帐号密钥 — 创建服务帐号 和 创建和管理服务帐号密钥。

    3. 下载服务帐号的 JSON 密钥文件。

    4. 将 GOOGLE_APPLICATION_CREDENTIALS 和 GOOGLE_CLOUD_PROJECT 环境变量分别设置为 JSON 密钥文件的路径和项目 ID

      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

    5. 使用您创建的服务帐号的电子邮件地址、JSON 密钥文件的路径和项目 ID 对 gcloud CLI 进行身份验证

      gcloud auth activate-service-account service-account@example.com --key-file=$GOOGLE_APPLICATION_CREDENTIALS --project=$GOOGLE_CLOUD_PROJECT

      有关更多信息，请参阅 Google 官方文档 — gcloud auth activate-service-account。

    6. 使用 Google 官方文档在 Google Cloud Storage 中创建存储桶 — 创建存储桶。

    7. 通过运行以下命令验证存储桶是否已创建

      gcloud storage ls

      输出应列出已创建的存储桶。

  2. 运行 neo4j-admin database backup 命令将您的数据库备份到您的 Google 存储桶

    bin/neo4j-admin database backup --to-path=gs://myBucket/myDirectory/ mydatabase

  1. 确保您拥有 Azure 帐户、Azure 存储帐户和 Blob 容器。

    1. 您可以使用 Azure 门户创建存储帐户。
      有关更多信息，请参阅 Azure 官方文档中的 创建存储帐户。

    2. 在 Azure 门户中创建 Blob 容器。
      有关更多信息，请参阅 Azure 官方文档中的 快速入门：使用 Azure 门户上传、下载和列出 Blob。

  2. 按照 Azure 官方文档中的说明安装 Azure CLI — Azure 官方文档。

  3. 使用默认 Azure 凭据对 Azure 进行 neo4j 或 neo4j-admin 进程的身份验证。
    有关更多信息，请参阅 Azure 官方文档中关于默认 Azure 凭据的内容。

    az login

    然后您就可以在 neo4j 或 neo4j-admin 中使用 Azure URL 了。

  4. 要验证您是否可以使用登录凭据访问容器，请运行以下命令

    # Upload a file:
az storage blob upload --file someLocalFile  --account-name accountName - --container someContainer --name remoteFileName  --auth-mode login

# Download the file
az storage blob download  --account-name accountName --container someContainer --name remoteFileName --file downloadedFile --auth-mode login

# List container files
az storage blob list  --account-name someContainer --container someContainer  --auth-mode login

  5. 运行 neo4j-admin database backup 命令将您的数据库备份到您的 Azure 容器

    bin/neo4j-admin database backup --to-path=azb://myStorageAccount/myContainer/myDirectory/ mydatabase

使用 --prefer-diff-as-parent 选项执行增量备份

默认情况下，增量备份（--type=DIFF）使用目录中最新的非空备份（无论是完整备份还是增量备份）作为其父级。

--prefer-diff-as-parent 选项会更改此行为，强制备份作业使用最新的增量备份作为父级，即使存在更新的完整备份。

这种方法允许您为所有事务维护一个增量备份链，并可以恢复到任何时间点。如果没有此选项，则上次完整备份和先前增量备份之间的事务无法作为单个事务进行备份。

要使用 --prefer-diff-as-parent 选项，请将其设置为 true。

以下示例涵盖了使用 --prefer-diff-as-parent 选项的不同场景。

假设您每小时向 neo4j 数据库写入 10 笔事务，但从 12:30 到 13:30 之间您不写入任何事务。

有一个备份作业每小时进行一次备份，每四小时进行一次完整备份。空备份没有事务，这意味着最低事务 ID 和最高事务 ID 都为零。

假设您有以下备份链

时间戳 备份名称 备份类型 最低事务 ID 最高事务 ID

10:30

backup1

FULL

1

10

11:30

backup2

DIFF

11

20

12:30

backup3

DIFF

21

30

13:30

backup4

DIFF

0

0

14:30

backup5

FULL

1

40

在 15:30，您执行以下备份命令

neo4j-admin database backup --from=<address:port> --to-path=<targetPath> --type=DIFF neo4j

结果将是

15:30

backup6

DIFF

41

50

结果意味着您已选择 backup5 作为您的增量 backup6 的父级，因为 backup5 是最新的非空备份。

但是，如果您使用 --prefer-diff-as-parent 选项执行以下命令

neo4j-admin database backup --from=<address:port> --to-path=<targetPath> --type=DIFF --prefer-diff-as-parent neo4j

结果将是

15:30

backup6

DIFF

31

50

在这种情况下，backup3 被选作父级，因为它是在最新的非空增量备份。

假设您每小时向 neo4j 数据库写入 10 笔事务并触发每小时完整备份。

时间戳 备份名称 备份类型 最低事务 ID 最高事务 ID

10:30

backup1

FULL

1

10

11:30

backup2

FULL

11

20

在这种情况下，没有增量备份。因此，--prefer-diff-as-parent 选项不起作用，行为与默认行为相同。

neo4j-admin database backup \
--from=<address:port> --to-path=<targetPath> \
--type=DIFF --prefer-diff-as-parent \
neo4j

结果将是（带或不带 --prefer-diff-as-parent 选项）

12:30

backup3

DIFF

21

30
© . All rights reserved.