管理集群中的服务器
企业版

在集群环境中，服务器管理与数据库管理是完全独立的。本节介绍如何对集群中的服务器进行操作：添加和移除服务器，以及修改其元数据。

有关服务器管理命令语法的详细信息，请参阅 服务器管理命令语法。

服务器生命周期

服务器在 DBMS 中可以处于六种不同的状态：

  • Free（空闲）

  • Enabled（启用）

  • Cordoned（隔离）

  • Deallocating（正在取消分配）

  • Deallocated（已取消分配）

  • Dropped（已丢弃）

server lifecycle
图 1. 服务器的生命周期

Free（空闲）状态

当服务器被发现服务（详见 设置集群 → 集群服务器发现）发现时，它会以 Free 状态创建。此状态下的服务器拥有唯一自动生成的 ID，但尚未进行配置。这些空闲服务器尚不属于集群，也无法被分配去承载任何数据库。

首次发现时，服务器名称默认为其生成的服务器 ID。

Enabled（启用）状态

当您首次部署集群时，初始部署中包含的最小数量的服务器会自动启用。有关详细信息，请参阅关于如何 配置三节点集群 的示例。

如果您在集群运行后添加新服务器，该服务器将以 Free 状态添加。处于 Free 状态的服务器需要显式启用，才能被视为集群的活跃成员。

要将服务器转换为 Enabled（启用）状态，请使用 ENABLE SERVER 命令。

语法
ENABLE SERVER 'serverId' [OPTIONS "{" option: value[,...] "}"]

服务器的初始名称是其 ID。如果服务器已启用，且执行命令时使用了相同的选项，则不会有任何更改。

启用服务器时可用的选项如下：

选项 允许的值 描述

modeConstraint

PRIMARY, SECONDARY, NONE

数据库只能以约束指定的模式托管在该服务器上。None 表示没有约束，允许任何模式。

allowedDatabases

数据库名称列表，例如 ["db1", "db2"]

只有匹配指定名称的数据库才能托管在该服务器上。此选项不能与 deniedDatabases 同时指定。从 2025.12 版本开始，支持数据库名称模式（通配符），且最小长度从 3 减小为 1。

deniedDatabases

数据库名称列表，例如 ["db1", "db2"]

只有不匹配指定名称的数据库才能托管在该服务器上。此选项不能与 allowedDatabases 同时指定。从 2025.12 版本开始，支持数据库名称模式（通配符），且最小长度从 3 减小为 1。

tags

服务器标签列表，例如 ["tag1", "tag2"]

用于负载均衡和路由策略的服务器标签列表。

启用服务器时，如果没有提供 OPTIONS，则默认服务器值取自以下设置：

所有这些设置仅在启用相关服务器时有效。

另一种启用服务器的方法是配置 DBMS 自动启用空闲服务器。您可以通过以下两种方式之一实现：

启用后，该服务器即可被分配承载数据库。

如果您需要更改服务器的某些值，请使用 ALTER SERVER 命令。

Cordoned（隔离）状态

处于 Cordoned（隔离）状态的服务器不能被分配去托管任何新创建的数据库；但是，服务器会保留其已有的数据库。

此状态主要用于 错误处理。

要将服务器从 Enabled 转换为 Cordoned 状态，请运行 dbms.cluster.cordonServer() 过程。请记住，当减少数据库的分配数量时，优先移除隔离服务器上的分配。

处于 Cordoned 状态的服务器可以转换为 Deallocating 状态或返回 Enabled 状态。要重新启用服务器，请运行 ENABLE SERVER 命令。在 Cypher 5 中，您也可以使用 dbms.cluster.uncordonServer() 过程。

Deallocating（正在取消分配）状态

Deallocating 状态意味着服务器不能再托管数据库。这通常发生在服务器不再需要，并且您想将其从集群中移除时。

要将服务器转换为 Deallocating 状态，请运行以下命令：

DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]

该命令会将服务器上托管的所有用户数据库重新分配给集群中的其他服务器。此状态是不可逆的。一旦服务器处于取消分配状态，后续就不能再分配任何数据库给它。

但是，您可以通过运行以下过程之一以可逆的方式从服务器取消分配数据库：

有关详细信息，请参阅 在集群中管理数据库 → 取消分配数据库。

Deallocated（已取消分配）状态

Deallocated 状态意味着除了 system 数据库外，服务器不再托管任何数据库，可以从集群中移除。此外，已取消分配的服务器不能再被分配任何数据库。

注意，存在一种已知情况：之前已取消分配的离线服务器在重启时可能会短暂显示为正在取消分配，但它最终会无需干预即返回到已取消分配状态。

Dropped（已丢弃）状态

Dropped 状态意味着服务器已从集群中移除，但对于其他集群成员来说仍然可见。

一旦服务器处于 Deallocated 状态且仅托管 system 数据库，将其移除是安全的。使用命令 DROP SERVER 'server name' 将服务器从集群中移除。

但是，只要服务器的 Neo4j 进程仍在运行，它对其他集群成员来说仍然处于 Dropped 状态。当 Neo4j 进程停止时，服务器才会最终消失。一旦丢弃，服务器将无法重新加入集群。

要允许同一物理硬件重新加入集群，请通过以下方式重置 Neo4j 安装：

此过程确保服务器再次启动时生成新的服务器 ID。

列出服务器

Cypher 命令 SHOW SERVERS 会显示集群中当前运行的所有服务器，包括尚未启用的服务器（即处于 Free 状态的服务器）以及已丢弃的服务器。

neo4j@system> SHOW SERVERS;
+------------------------------------------------------------------------------------------------------------------+
| name                                   | address          | state     | health      | hosting                    |
+------------------------------------------------------------------------------------------------------------------+
| "135ad202-5405-4d3c-9822-df39f59b823c" | "localhost:7690" | "Dropped" | "Available" | ["system"]                 |
| "25a7efc7-d063-44b8-bdee-f23357f89f01" | "localhost:7689" | "Enabled" | "Available" | ["system", "foo", "neo4j"] |
| "42a97acc-acf6-40c0-aff2-3993e90db1ff" | "localhost:7691" | "Free"    | "Available" | ["system"]                 |
| "782f0ee2-5474-4250-b905-4cd8b8f586ba" | "localhost:7688" | "Enabled" | "Available" | ["system", "foo", "neo4j"] |
| "8512c9b9-d9e8-48e6-b037-b15b0004ca18" | "localhost:7687" | "Enabled" | "Available" | ["system", "foo", "neo4j"] |
+------------------------------------------------------------------------------------------------------------------+

要显示有关集群中服务器的所有可用信息，请使用 SHOW SERVERS YIELD *。

neo4j@system> SHOW SERVERS YIELD *;
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| serverId                               | name                                   | address          | httpAddress      | httpsAddress | state          | health      | hosting                    | requestedHosting           | tags | allowedDatabases | deniedDatabases | modeConstraint | version          |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "135ad202-5405-4d3c-9822-df39f59b823c" | "135ad202-5405-4d3c-9822-df39f59b823c" | "localhost:7690" | "localhost:7477" | NULL         | "Deallocating" | "Available" | ["system"]                 | ["system"]                 | []   | []               | []              | "NONE"         | "5.0.0-drop09.0" |
| "25a7efc7-d063-44b8-bdee-f23357f89f01" | "25a7efc7-d063-44b8-bdee-f23357f89f01" | "localhost:7689" | "localhost:7476" | NULL         | "Enabled"      | "Available" | ["system", "foo", "neo4j"] | ["system", "foo", "neo4j"] | []   | []               | []              | "NONE"         | "5.0.0-drop09.0" |
| "42a97acc-acf6-40c0-aff2-3993e90db1ff" | "42a97acc-acf6-40c0-aff2-3993e90db1ff" | "localhost:7691" | "localhost:7478" | NULL         | "Free"         | "Available" | ["system"]                 | []                         | []   | []               | []              | "NONE"         | "5.0.0-drop09.0" |
| "782f0ee2-5474-4250-b905-4cd8b8f586ba" | "782f0ee2-5474-4250-b905-4cd8b8f586ba" | "localhost:7688" | "localhost:7475" | NULL         | "Enabled"      | "Available" | ["system", "foo", "neo4j"] | ["system", "foo", "neo4j"] | []   | []               | []              | "NONE"         | "5.0.0-drop09.0" |
| "8512c9b9-d9e8-48e6-b037-b15b0004ca18" | "8512c9b9-d9e8-48e6-b037-b15b0004ca18" | "localhost:7687" | "localhost:7474" | NULL         | "Enabled"      | "Available" | ["system", "foo", "neo4j"] | ["system", "foo", "neo4j"] | []   | []               | []              | "NONE"         | "5.0.0-drop09.0" |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

结果表显示了有关服务器的信息。

表 1. SHOW SERVERS 输出模式
列 描述 类型 默认输出 完整输出

名称 (name)

服务器名称。

STRING

serverId

服务器的 ID。

STRING

address

服务器的 Bolt 地址（如果已启用）。

STRING

httpAddress

服务器的 HTTP 地址（如果已启用）。

STRING

httpsAddress

服务器的 HTTPS 地址（如果已启用）。

STRING

state

服务器的状态信息。可能的值为 Free, Enabled, Cordoned, Deallocating, Deallocated 或 Dropped。

STRING

health

服务器的可用性：Available 或 Unavailable。

STRING

hosting

当前托管在服务器上的数据库列表。

LIST<STRING>

requestedHosting

应该托管在服务器上的数据库列表。复合数据库目前不会出现在此列表中，尽管它们会出现在所有服务器的 hosting 字段中。

LIST<STRING>

tags

标签是用户提供的字符串，可用于负载均衡和路由策略。

LIST<STRING>

allowedDatabases

允许托管在服务器上的数据库列表。

LIST<STRING>

deniedDatabases

不允许托管在服务器上的数据库列表。

LIST<STRING>

modeConstraint

分配器仅在该模式下将数据库分配给服务器的约束。

STRING

version

服务器正在运行的 Neo4j 版本。

STRING

向集群添加服务器

要向正在运行的集群添加服务器，请将其配置为发现现有的集群成员。有多种方法可以做到这一点，请参阅 集群服务器发现。

在下面的示例中，您将设置 dbms.cluster.discovery.resolver_type=LIST。

  1. 为新的 server.07 准备 neo4j.conf 文件。

    server07.example.com 上的 neo4j.conf
    server.default_listen_address=0.0.0.0
server.default_advertised_address=server07.example.com
dbms.cluster.discovery.resolver_type=LIST
dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000,server06.example.com:6000,
server.cluster.system_database_mode=PRIMARY

    根据服务器的用途配置 system 数据库模式：

    • 如果服务器预计长期使用并处理高负载工作，请将模式设置为 PRIMARY。

    • 如果服务器旨在支持分析或读取密集型工作负载，请将模式设置为 SECONDARY。

      此外，您可以配置一组初始设置来为服务器选项提供值。这些设置将用作 ENABLE SERVER 命令的默认输入。有关详细信息，请参阅 Enabled（启用）状态。

      此外，您还可以将 initial.dbms.automatically_enable_free_servers 设置为 true，允许 DBMS 自动启用空闲服务器。

  2. 一旦新服务器被配置为发现集群成员，启动 Neo4j 进程。

  3. 启动后，新服务器会出现在 SHOW SERVERS 的输出中，且状态为 Free。

  4. 从 SHOW SERVERS 输出中复制服务器 ID 并启用该服务器。

    ENABLE SERVER 命令可以接受多个选项，并且如果这些选项与初始设置冲突，它们将覆盖初始设置：

    neo4j@system> ENABLE SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' OPTIONS
    {modeConstraint:'PRIMARY', allowedDatabases:['foo'], tags:['eu','eu-west']};

    • modeConstraint 用于控制服务器是只能托管主模式的标准数据库、只能托管从模式数据库，还是可以托管任何模式的数据库。

    • allowedDatabases 和 deniedDatabases 是过滤哪些数据库可以托管在服务器上的数据库名称集合。这两个选项互斥，如果同时指定则会返回错误。allowedDatabases 和 deniedDatabases 不影响复合数据库，它们始终在任何地方都可用。注意，从 2025.12 版本开始，支持数据库名称模式（通配符），且最小长度从 3 减小为 1。

    • 服务器 tags 用于配置负载均衡和复制策略。它们不能包含重复项，因此 tags:['eu', 'eu'] 会返回错误。服务器标签也不能包含逗号。通过 Cypher 修改服务器标签时，使用 UTF-8 编码。

      服务器标签的输入是一个不能有重复项的逗号分隔列表。

      Neo4j .conf 文件默认使用 Latin1 编码。因此，对于需要较大字符集（例如中文或阿拉伯文）的服务器标签，建议使用 Cypher 来修改服务器标签。

      通过设置环境变量 NEO4J_CONFIG_FILE_CHARSET=utf8，.conf 文件可以使用 UTF-8 编码。这允许通过配置文件设置较大字符集的服务器标签。

在新添加的服务器上托管数据库

一旦启用，除非满足以下条件，否则服务器不会自动托管数据库：

  • 创建了新数据库。

  • 现有的数据库拓扑结构被修改以请求更多主机。

  • 另一台服务器被转换为 Deallocating 状态。

  • 您显式地在集群中重新平衡数据库，可能将一些数据库重新分配给新添加的服务器。

从集群中移除服务器

从集群中移除服务器需要两个步骤：取消分配（deallocating），然后丢弃（dropping）。

从服务器取消分配数据库

为从集群中移除服务器做准备，使用 DEALLOCATE DATABASES FROM SERVER 'name' 命令将其设置为不托管任何数据库。

有关更多信息，请参阅 Deallocating（正在取消分配）状态。

DEALLOCATE DATABASES 命令可以使用服务器 ID 或服务器名称。

neo4j@system> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df39f59b823c';

从服务器取消分配数据库时，务必注意每个数据库的拓扑结构，以确保集群中剩余的服务器足以满足每个数据库的拓扑要求。如果尝试从服务器取消分配数据库会导致可用服务器数量少于所需数量，操作将失败并报错，且不会进行任何更改。

例如，如果集群包含五台服务器，并且数据库 foo 的拓扑要求三个主副本和两个从副本，那么在不先添加和启用新的无约束服务器，或不将 foo 的期望拓扑更改为总体上需要更少服务器之前，无法取消分配最初五台服务器中的任何一台。

该命令可以配合 DRYRUN 使用，以查看数据库将如何从已取消分配的服务器上移动。

neo4j@system> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
+------------------------------------------------------------------------------------------------------------------------------------------+
| database | fromServerName | fromServerId                           | toServerName | toServerId                             | mode        |
+------------------------------------------------------------------------------------------------------------------------------------------+
| "db1"    | "server-3"     | "135ad202-5405-4d3c-9822-df39f59b823c" | "server-5"   | "00000003-b30a-434e-b9bf-1a5c8009773a" | "secondary" |
+------------------------------------------------------------------------------------------------------------------------------------------+

在以下情况下，目前禁止进行取消分配：

  • 如果服务器正在托管的数据库处于离线状态。

  • 如果服务器正在托管一个只有一个主副本分配的数据库。

  • 如果以主模式托管该数据库的法定数量服务器处于隔离（cordoned）状态。

命令执行后，服务器状态更改为 Deallocating，此时无法轻易重新启用。有关更多信息，请参阅 Dropped（已丢弃）状态。

丢弃服务器

一旦对服务器执行了 DEALLOCATE DATABASES，其数据库就开始移动。在 SHOW SERVERS 报告取消分配的服务器已处于 Deallocated（已取消分配）状态 之前，切勿尝试下一步。

例如，在输出以下内容时，请勿丢弃服务器 135ad202-5405-4d3c-9822-df39f59b823c：

SHOW SERVERS;
+------------------------------------------------------------------------------------------------------------------+
| name                                   | address          | state          | health      | hosting               |
+------------------------------------------------------------------------------------------------------------------+
| "135ad202-5405-4d3c-9822-df39f59b823c" | "localhost:7690" | "Deallocating" | "Available" | ["system", "foo"]     |
+------------------------------------------------------------------------------------------------------------------+

取消分配过程可能需要一些时间，因为 foo 必须成功复制并在一台新服务器上启动后，才能在 135ad202-5405-4d3c-9822-df39f59b823c 上停止，以保持 foo 的可用性和容错能力。

一旦 SHOW SERVERS 反映该服务器为 Deallocated 且不再托管 foo，就可以丢弃该服务器。可以使用服务器 ID 或名称：

neo4j@system> DROP SERVER '135ad202-5405-4d3c-9822-df39f59b823c';

一旦此命令成功执行，该服务器上的 Neo4j 进程即可停止。

控制服务器元数据

修改服务器选项

可以使用 ALTER SERVER 'name' SET OPTIONS { option: value } 命令修改运行中服务器的选项。可以使用服务器 ID 或名称。

语法
ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"

例如，要防止服务器以 PRIMARY 模式托管数据库，请执行以下操作：

neo4j@system> ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY'};

修改服务器可能会导致数据库移动，应谨慎执行。例如，如果执行上述命令时，服务器 25a7efc7-d063-44b8-bdee-f23357f89f01 正以主模式托管数据库 foo，则另一台服务器必须开始以主模式托管 foo。

同样，如果执行 ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {allowedDatabases:['bar','baz']};，则 foo 被强制移动。

修改服务器时可用的选项如下：

选项 允许的值 描述

modeConstraint

PRIMARY, SECONDARY, NONE

数据库只能以约束指定的模式托管在该服务器上。NONE 表示没有约束，允许任何模式。

allowedDatabases

数据库名称列表，例如 ["db1", "db2"]

只有匹配指定名称的数据库才能托管在该服务器上。此选项不能与 deniedDatabases 同时指定。

deniedDatabases

数据库名称列表，例如 ["db1", "db2"]

只有不匹配指定名称的数据库才能托管在该服务器上。此选项不能与 allowedDatabases 同时指定。

tags

服务器标签列表，例如 ["tag1", "tag2"]

用于负载均衡和路由策略的服务器标签列表。

allowedDatabases 和 deniedDatabases 不影响复合数据库；它们在任何地方都可用。

从 2025.12 版本开始，支持数据库名称模式（通配符），且最小长度从 3 减小为 1。

与 DEALLOCATE DATABASES FROM SERVER …​ 命令一样，如果修改服务器选项导致集群无法满足一个或多个数据库的拓扑结构，则命令失败且不会进行任何更改。

提供给 SET OPTIONS {…​} 的输入会替换所有现有选项，而不是与它们合并。

每次运行 ALTER SERVER 命令时，必须指定之前设置的所有值；否则它们将被覆盖为未设置的状态。

例如，您先后运行两条语句：

ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY'};
ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {allowedDatabases:['foo']};

第二次 ALTER SERVER 的执行移除了 SECONDARY 模式约束，将其替换为 NONE。

如果您想保留 modeConstraint:'SECONDARY' 和 allowedDatabases:['foo'] 两个值，则必须在 ALTER SERVER 命令的选项中显式设置它们：

ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY', allowedDatabases:['foo']};

使用 ALTER SERVER 时，请务必使用 SHOW SERVERS YIELD * 检查当前配置并重新应用未更改的选项。

重命名服务器

语法
RENAME SERVER 'name' TO 'newName'

首次发现时，服务器名称默认为其生成的服务器 ID。但是，只要服务器处于已启用状态，之后可以使用以下命令更改名称：

neo4j@system> RENAME SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' TO 'eu-server-4';

这仅影响服务器名称；服务器的 ID 保持不变，仍为 25a7efc7-d063-44b8-bdee-f23357f89f01。请记住，服务器名称在现有服务器中必须是唯一的。

错误处理

集群中的服务器偶尔可能会遇到网络分区或进程崩溃等问题。观察这些服务器故障最简单的方法是执行 SHOW SERVERS 并检查 health 列中是否存在 Unavailable。

Available 健康状态并不代表服务器功能完美，仅表示集群中的其他服务器能够与它建立连接。

有关集群和服务器健康状况的深入监控，请参阅 监控服务器。

如果 Unavailable 服务器的问题是永久性的，则应 移除 该服务器。但是，如果问题是暂时的，则通常不希望完全移除这些服务器，因为这会导致它们托管的所有数据库被移动。相反，更倾向于防止这些服务器被分配去托管任何新的数据库（无论是因数据库创建还是移动导致）。

这被称为隔离（cordoning）相关服务器，可以通过针对 system 数据库执行以下过程来实现：

neo4j@system> CALL dbms.cluster.cordonServer('25a7efc7-d063-44b8-bdee-f23357f89f01');

SHOW SERVERS 随后应反映相关服务器现在处于 Cordoned 状态。

一旦服务器问题解决，该服务器可以按照以下方式返回其之前的 Enabled 状态：

neo4j@system> ENABLE SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01';

一个未被隔离的不可用服务器可能仍会被分配去托管新数据库。当服务器恢复时，它会发现自己需要托管这些数据库，并开始从其他可用服务器（如果存在）同步数据。然而，在此期间，这些数据库的容错能力或可用性会降低。有关更多详细信息，请参阅 灾难恢复。