将因果集群迁移至 4.0

本章介绍了将因果集群（Causal Cluster）从 Neo4j 3.5 迁移到 4.0 所需的步骤。

将因果集群从 Neo4j 3.5 迁移到 4.0 需要停机。因此，建议在类生产环境中进行测试迁移，以获取停机时间的相关信息。

要从 3.5.latest 版本迁移到 4.0 以上的版本，必须先将集群迁移到 4.0，然后再升级到目标版本。有关更多信息，请参阅支持的升级和迁移路径。

必须为每个集群成员完成前提条件和迁移步骤。

先决条件

确保您已完成迁移检查清单上的所有任务。

准备迁移

迁移集群部署的策略是：在一个实例上作为单机实例完成单次迁移，然后使用迁移后的存储来初始化（seed）集群中的其余成员。

请记住，迁移是一个单一事件。不要在每个实例上独立执行迁移！应该只有一次迁移事件，并且该迁移后的存储将作为集群中所有其他实例的“单一事实来源”。这一点很重要，因为在迁移时，Neo4j 会生成随机的存储 ID；如果独立执行迁移，您的集群最终将拥有与实例数量相等的存储 ID。在这种情况下，Neo4j 将无法启动。因此，部分集群迁移步骤将在单个实例上执行，而其他步骤将在所有实例上执行。每个步骤都会说明应在哪里执行必要的操作。

在这一阶段，您应该选定一个实例进行操作。这将是实际发生迁移的实例。后续步骤将说明是在选定实例、其余实例还是所有实例上执行操作。

在每个集群成员上

验证您已关闭所有集群成员（Core 和 Read Replica）。您可以检查 neo4j.log。
在每个集群成员上执行 neo4j-admin unbind 以移除集群状态数据。
在每个实例上安装您要迁移到的 Neo4j 版本。有关如何安装所使用发行版的更多信息，请参阅 Operations Manual 4.0 → 安装。
将 neo4j.conf 文件替换为您在为新安装准备新的 neo4j.conf 文件一节中为每个实例准备的文件。
复制所有用于加密的文件，例如私钥、公有证书，以及受信任和已吊销目录的内容（位于 <NEO4J_HOME>/certificates/ 中）。
如果您使用了自定义插件，请确保它们已更新并与新版本兼容，并将它们放入 /plugins 目录中，详见文件位置。

在选定实例上

打开新安装的 neo4j.conf 文件并配置以下设置
- 取消注释 dbms.allow_upgrade=true 以允许自动存储迁移。如果没有此配置，Neo4j 将无法启动。
- 设置 dbms.mode=SINGLE。您需要这样做，因为迁移是一个需要在独立服务器上发生的单一事件。

迁移数据

在选定实例上: 在迁移数据之前，需要将备份文件移动到 Neo4j 4.0 的 data 目录。

如果您的 dbms.directories.data 指向 <NEO4J_HOME> 之外的目录，则此步骤不适用。

通过从 <NEO4J_HOME> 运行 neo4j-admin load 命令，将备份文件移动到新安装中。

必须使用此命令，因为不支持通过文件系统复制粘贴数据库，这可能会导致意外行为。如果您运行的是 Debian/RPM 发行版，则可以跳过此步骤。

$NEO4J_HOME/bin/neo4j-admin load --from=$BACKUP_DESTINATION/<db_name>.dump –database=<db_name> --force

用户和角色的迁移从 3.5 到 4.0 是自动完成的。因此，您不必将 data/dbms/ 目录及其内容移动到新安装中。3.5 中的文件将在 Neo4j 4.0 DBMS 首次启动时被解析，其内容会被添加到 system 数据库中。

在备份就绪后，启动选定实例以开始迁移。

bin/neo4j start

或

systemctl start neo4j

迁移在启动过程中进行。您的索引也会在启动过程中自动迁移到最新的索引提供程序。但是，索引在迁移后需要填充。当索引正在填充时，您的查询将无法使用它们，因此您可能会遇到暂时的性能下降。如果您的查询 100% 依赖于某些索引，建议将索引填充时间计入迁移的总时长中。

neo4j.log 文件包含了关于迁移涉及的步骤数及其进度的宝贵信息。索引填充情况会在 debug.log 中跟踪。对于大型迁移，持续监控这些日志是一个好主意。

迁移完成后，停止服务器。
```
bin/neo4j stop
```
或
```
systemctl stop neo4j
```

准备初始化集群

在选定实例上

还原 neo4j.conf 的更改
- 设置 dbms.allow_upgrade=false。
- 设置 dbms.mode=CORE 以在配置中重新启用因果集群。
使用 neo4j-admin dump 对您新迁移的数据库和事务以及 system 数据库进行离线备份。此备份将用于初始化集群的其余实例。
```
bin/neo4j-admin dump --database=<db_name> --to=$BACKUP_DESTINATION/<db_name>.dump

bin/neo4j-admin dump --database=system --to=$BACKUP_DESTINATION/system.dump
```
请注意，迁移后，Neo4j Admin 命令可能会略有不同，因为 Neo4j 现在支持多个数据库。
暂时不要启动服务器。

初始化集群

在其余每个实例上

将迁移步骤中创建的转储文件复制到其余实例。
完成后，使用 neo4j-admin load --from=<archive-path> --database=<db_name> --force 替换您的每个数据库（包括 system 数据库），替换为在选定实例上迁移后的数据库。
```
bin/neo4j-admin load --from=$BACKUP_DESTINATION/<db_name>.dump --database=<db_name> --force

bin/neo4j-admin load --from=$BACKUP_DESTINATION/system.dump --database=system --force
```

启动集群

在每个集群成员（包括选定实例）上

在继续之前，请确保以下活动已经发生并成功完成：

neo4j.conf 的内容正确，并且所有实例都已应用必要的更改。
选定实例上发生了单一迁移事件。
在选定实例上执行了已迁移存储的备份（通过 neo4j-admin dump）。
已迁移存储的备份已传输到其余实例。
存储已在其余实例上加载（通过 neo4j-admin load）。
选定实例的 neo4j.conf 中已设置 dbms.mode=CORE 和 dbms.allow_upgrade=false（或已注释掉）。

如果清单上的所有内容均已成功，您可以继续启动集群的所有实例。
```
bin/neo4j start
```
或
```
systemctl start neo4j
```
如果已迁移的数据库是 default 数据库，它应该在实例启动时自动启动，此步骤不需要。如果已迁移的数据库不是 default 数据库，它仍处于 STOPPED 状态。您现在需要启动数据库。在其中一个集群成员上，在 Neo4j Browser 或 Cypher^® Shell 中运行以下命令：
```
CREATE DATABASE <db_name>;
```
对于每个 Read Replica 节点

启动 Read Replica 并等待它追赶上集群中的其余成员。

（可选）虽然空的只读副本（Read Replica）最终会从集群的其他成员获取所有数据的完整副本，但赶上进度可能需要一些时间。为了加速此过程，您可以先使用 neo4j-admin load --from=<archive-path> --database=<db_name> --force 加载数据，用已迁移的数据库替换每个数据库。

验证只读副本已加入集群。