配置远程数据库别名
企业版Aura 不可用

您可以使用远程数据库别名连接到位于远程独立服务器或集群上的图数据库。

虽然远程数据库别名本身不存储任何数据，但它们允许用户或应用程序查询远程数据库，就像它们位于本地 DBMS 服务器上一样。所有配置都可以使用运行系统上的管理命令完成。任何更改都会在集群的所有成员之间自动同步。

创建远程数据库别名时，可以将其配置为通过以下方式之一进行身份验证：

  • 存储的原生凭据 (STORED NATIVE CREDENTIALS)，即远程 DBMS 上单个原生用户的凭据。

  • 2026.01 引入 OIDC 凭据转发 (OIDC CREDENTIAL FORWARDING)，转发来自本地 DBMS 上已登录用户的承载认证令牌 (bearer authentication token)。用户需要通过支持 OIDC 的身份提供商进行登录。

通过创建远程数据库别名，您可以定义：

  • 使用哪些凭据来验证远程数据库的身份。

  • 远程数据库的位置。

  • 如何使用驱动程序设置连接到远程数据库。

要管理远程数据库别名，您必须拥有数据库管理或别名管理权限。

例如，以下命令授予 administrator 角色创建别名的权限：

GRANT CREATE ALIAS ON DBMS TO administrator

通过授予对远程数据库别名的访问权限，您可以定义哪些用户可以使用它连接到远程 DBMS 上的数据库。

Neo4j 提供的许多内置角色都可以访问所有数据库，这包括任何远程数据库别名。

以下示例描述了如何通过存储的原生凭据或 OIDC 凭据转发来设置对远程数据库的访问。它们假设您有两个独立的 DBMS 实例：本地的 DBMS A 和远程的 DBMS B。

使用存储的原生凭据设置示例

在此示例中，Alice 是 DBMS A 的管理员，Bob 是 DBMS B 的管理员，Carol 是需要访问 Bob 所管理数据库的用户。

remote alias overview
图 1. 使用存储的原生凭据时所需的远程数据库别名设置概览

远程数据库别名仅可供具有适当权限的用户访问。在此示例中，Bob 是负责决定远程数据库别名可以读写哪个数据库 (db1 或 db2) 的管理员。同时，Alice 是分配谁拥有 Bob 所设权限的管理员。在本例中，Alice 将该访问权限分配给 Carol。有关详细信息，请参阅 DBMS 权限。

Bob 在 DBMS B 上创建了一个用户配置文件，授予其对 db1 数据库的访问权限，并将凭据共享给 Alice。然后，Alice 在 DBMS A 上创建了一个名为 db1-remote-alias 的远程数据库别名，该别名使用共享的凭据连接到 DBMS B 上的 db1。Alice 授予 Carol 对该远程数据库别名的访问权限后，Carol 即可使用她自己的凭据登录到本地 DBMS A，并通过该远程数据库别名连接到 DBMS B 上的 db1。

在远程 DBMS 上执行的所有操作都是以与远程数据库别名关联的用户身份进行的。使用 存储的原生凭据 (STORED NATIVE CREDENTIALS) 时，无论哪个终端用户发起针对该远程数据库别名的查询，都将使用相同的凭据连接到远程 DBMS。因此，用户在本地 DBMS 上的角色和权限不会限制在远程 DBMS 上处理的操作。任何能够访问远程数据库别名的本地用户实际上都继承了为该别名配置的用户所拥有的权限。因此，必须注意这种配置可能导致的权限不匹配（例如，权限过高或过低）。

例如，假设 DBMS B 上的共享用户（该用户被共享并配置到 DBMS A 的远程数据库别名中）被分配了内置角色 editor，从而允许读写访问。DBMS A 上的本地用户可能只有 reader 角色，因此在本地仅限于只读操作。然而，该用户可以访问远程数据库别名，从而使用该别名的凭据在 DBMS B 上进行操作，进而获得相关的写权限，使他们能够在 DBMS B 上修改数据，尽管他们本地角色的权限有限。

配置远程 DBMS B (Bob)

作为 Bob，您负责远程 DBMS B。您可以创建和删除用户，并授予或拒绝 DBMS B 管理的数据库的权限。

在此示例中，您创建一个名为 remote_user 的用户，该用户将被远程数据库别名用于连接到 db1，并将凭据共享给 Alice。

  1. 创建要与 Alice 共享的用户配置文件

    CREATE USER remote_user SET PASSWORD 'secretpassword'

  2. 创建一个自定义角色以跟踪所有在远程连接上共享的用户，以便它们保持可追踪性

    CREATE ROLE shared_to_remote

  3. 授予 shared_to_remote 角色对 db1 的访问权限，并将该角色分配给为远程数据库别名创建的用户配置文件 remote_user

    GRANT ACCESS ON DATABASE db1 TO shared_to_remote
GRANT MATCH {*} ON GRAPH db1 TO shared_to_remote
GRANT ROLE shared_to_remote TO remote_user

  4. 设置 SSL 框架，并在需要时检查数据库是否接受非本地连接。

    # accept non-local connections
server.default_listen_address=0.0.0.0

# configure ssl for bolt
dbms.ssl.policy.bolt.enabled=true
dbms.ssl.policy.bolt.base_directory=certificates/bolt
dbms.ssl.policy.bolt.private_key=private.key
dbms.ssl.policy.bolt.public_certificate=public.crt
dbms.ssl.policy.bolt.client_auth=NONE

# enforcing ssl connection
server.bolt.tls_level=REQUIRED

  5. 安全地将凭据传输给 Alice，建立到数据库 db1 的连接。

配置本地 DBMS A 并授予 Carol 访问权限 (Alice)

作为 Alice，您负责设置 DBMS А。您可以创建和删除数据库别名，并授予或拒绝用户对其的访问权限。

在此示例中，您创建一个名为 db1-remote-alias 的远程数据库别名，该别名使用 Bob 共享的凭据连接到 DBMS B 上的 db1。

生成加密密钥

首先，您需要生成一个加密密钥。在这种情况下，DBMS B 的 remote_user 用户的凭据会被可逆加密并存储在 DBMS A 的 system 数据库中。由于使用的算法是 AES/GCM，您必须提供一个长度为 256 的 AES 加密密钥，并将其存储在 PKCS12 格式的密码保护密钥库中。

密钥可以使用您终端中的以下 keytool 命令生成，该工具包含在 Java Platform, Standard Edition 中

keytool -genseckey -keyalg aes -keysize 256 -storetype pkcs12 -keystore [keystore-name] -alias [key-name] -storepass [keystore-password]

建议使用与运行 Neo4j 相同的 Java 版本生成密钥库，因为支持的加密算法可能会有所不同。有关 Neo4j 所需 Java 版本的详细信息，请参阅系统要求 → Java。

配置密钥库设置

生成密钥库文件后，您需要配置 DBMS A 以使用它，通过在 neo4j.conf 文件中设置以下配置参数：

配置 描述

dbms.security.keystore.path

密钥库文件的绝对路径，包括文件名。

dbms.security.keystore.password

密钥库文件的密码。使用命令扩展来设置密码。

dbms.security.key.name

密钥名称。

为防止未经授权的访问，您必须将密钥库文件存储在受信任的位置。这是保护存储在 system 数据库中的加密密码的主要方法。除了管理员和 neo4j（密钥库文件必须对其可读）之外，任何用户都不应访问它。

在集群中，您必须在所有服务器之间共享同一个密钥库文件。例如，在使用建议的 keytool 命令时，以下内容将是有效的配置添加：

dbms.security.keystore.path=/home/secure-folder/keystore-name.pkcs12
dbms.security.keystore.password=$(conf/password.sh)
dbms.security.key.name=key-name

其中 password.sh 可能如下所示：

#!/bin/bash
echo "$KEYSTORE_PASSWORD_ENVIRONMENT_VARIABLE"

此外，不要忘记更改配置文件的权限，并使用命令扩展标志启动 Neo4j：

chmod 640 conf/neo4j.conf
bin/neo4j start --expand-commands

创建远程数据库别名并授予 Carol 访问权限

您可以使用别名管理命令创建远程数据库别名，并授予 Carol 访问权限。

强烈建议使用安全连接连接到远程数据库别名。请注意，仅支持客户端 SSL。默认情况下，远程数据库别名要求使用安全 URI 方案，例如 neo4j+s。但是，如果您想禁用安全 URL 方案，可以将驱动程序设置 ssl_enforced 设置为 false。

  1. 使用以下命令创建具有 Bob 共享的存储原生凭据的远程数据库别名：

    CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER remote_user PASSWORD 'secretpassword'

  2. 创建一个自定义角色以跟踪所有有权访问远程数据库别名的用户（或选择一个现有的角色）：

    CREATE ROLE remote_access

  3. 授予 remote_access 角色对远程数据库别名的访问权限，并将其分配给 Carol。有关详细信息，请参阅ACCESS 权限。

    GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access
GRANT ROLE remote_access TO carol

如果事务修改了别名（例如更改了 DBMS B 上定位的数据库），则针对该别名并发执行的其他事务可能会被中止并回滚以确保安全。这可以防止诸如单个别名针对多个目标数据库执行事务之类的问题。

更改加密密钥

如果更改了密钥库中的加密密钥，则所有现有远程数据库别名的加密凭据都需要更新，因为它们将无法再使用新密钥进行读取。

如果读取密钥库文件时发生故障，请检查 debug.log 以找出哪个参数是问题的根源。如果在创建远程数据库别名后无法连接，请通过 https://browser.neo4j.io/ 或本地浏览器连接到远程数据库来验证其设置。

使用 OIDC 凭据转发的设置示例
2026.01 中引入

为了使用 OIDC 凭据转发，DBMS A 和 DBMS B 必须支持相同的 OIDC 身份提供商。请参阅 SSO 集成以了解如何启用 OIDC。

在此示例中，Alice 是 DBMS A 的管理员，Bob 是 DBMS B 的管理员，Carol 是需要访问 Bob 所管理数据库的用户。

remote alias credential forwarding overview
图 2. 使用 OIDC 凭据转发时所需的远程数据库别名设置概览

Carol 通过提供来自提供商的令牌，通过 OIDC 兼容的身份提供商登录到本地 DBMS A。该令牌用于设置用户名并确定用户所属的身份提供商组。

Alice 是本地 DBMS A 的管理员，她为身份提供商设置 SSO 并配置身份提供商组到 Neo4j 角色的映射，以便 Carol 可以使用远程数据库别名 db1-remote-alias 连接到远程数据库 db1。

Bob 配置远程 DBMS B 以支持与 Carol 登录 DBMS A 时使用的相同身份提供商的 SSO。他还配置了身份提供商组到 Neo4j 角色的映射，使得 Carol 的身份提供商组能够获得访问 DBMS B 上 db1 的适当权限。

用户的有效权限不仅仅由身份提供商组决定，还由这些组映射到每个 Neo4j DBMS 内定义的角色决定。请参阅将身份提供商组映射到 Neo4j 角色。因此，跨不同 DBMS 实例的不同 OIDC 配置可能导致同一用户在这些实例上具有不同的有效权限（本例中为 DBMS A 和 DBMS B）。虽然可以在不同的 DBMS 实例之间使用不同的 OIDC 配置，但数据库管理员必须意识到由此产生的任何权限差异，并确保旨在授予等效访问权限的组到角色映射在各 DBMS 之间保持一致。这是为了避免权限不一致，例如权限过高或意外拒绝访问。

配置本地 DBMS A 并授予 Carol 访问权限 (Alice)

作为 Alice，您负责设置本地 DBMS A。您可以创建和删除数据库别名，并授予或拒绝用户对其的访问权限。

在这种情况下，您需要设置一个使用 OIDC 凭据转发连接到 DBMS B 上 db1 的远程数据库别名，并授予 Carol 访问权限。

创建远程数据库别名并授予 Carol 访问权限

您可以使用别名管理命令创建远程数据库别名。

强烈建议使用安全连接连接到远程数据库别名。请注意，仅支持客户端 SSL。默认情况下，远程数据库别名要求使用安全 URI 方案，例如 neo4j+s。但是，如果您想禁用安全 URL 方案，可以将驱动程序设置 ssl_enforced 设置为 false。

  1. 使用以下命令创建使用 OIDC 凭据转发的远程数据库别名：

    CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING

  2. 创建一个自定义角色以跟踪所有有权访问远程数据库别名的用户（或选择一个现有的角色）：

    CREATE ROLE remote_access

  3. 授予 remote_access 角色对远程数据库别名的访问权限。该角色将通过身份提供商组到 Neo4j 角色的映射在登录时分配给 Carol：

    GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access

    如果事务修改了别名（例如更改了 DBMS B 上定位的数据库），则针对该别名并发执行的其他事务可能会被中止并回滚以确保安全。这可以防止诸如单个别名针对多个目标数据库执行事务之类的问题。

在本地 DBMS 上设置 SSO 并将身份提供商组映射到 Neo4j 角色

为了让 Carol 获得对远程数据库别名的访问权限，她必须处于一个映射到已被授予该别名访问权限的 Neo4j 角色的身份提供商组中。

您在本地 DBMS A 上设置 SSO 并将身份提供商组映射到 Neo4j 角色。有关详细信息，请参阅 SSO 配置教程和将身份提供商组映射到 Neo4j 角色。

dbms.security.oidc.<provider>.well_known_discovery_uri=http://example.com/.well-known/discovery
<...>
dbms.security.oidc.<provider>.claims.groups=groups
dbms.security.oidc.<provider>.authorization.group_to_role_mapping= "engineers" = admin; \
                                                                   "collaborators" = reader; \
                                                                   "remote_users" = remote_access

配置远程 DBMS B (Bob)

作为 Bob，您负责设置远程 DBMS B。您可以创建和删除用户，并授予或拒绝 DBMS B 管理的数据库的权限。

在此示例中，您需要确保 Carol 能够使用 OIDC 凭据转发访问 DBMS B 上的 db1。

  1. 创建一个自定义角色或选择一个现有角色。这些角色将通过身份提供商组到 Neo4j 角色的映射在登录时分配给用户：

    CREATE ROLE db1_access

  2. 授予 db1_access 角色对 db1 的访问权限

    GRANT ACCESS ON DATABASE db1 TO db1_access
GRANT MATCH {*} ON GRAPH db1 TO db1_access

  3. 在远程 DBMS B 上设置 SSO 并将身份提供商组映射到 Neo4j 角色。有关详细信息，请参阅 SSO 配置教程和将身份提供商组映射到 Neo4j 角色。

    dbms.security.oidc.<provider>.well_known_discovery_uri=http://example.com/.well-known/discovery
<...>
dbms.security.oidc.<provider>.claims.groups=groups
dbms.security.oidc.<provider>.authorization.group_to_role_mapping= "engineers" = admin; \
                                                                   "collaborators" = reader; \
                                                                   "remote_users" = db1_access

  4. 设置 SSL 框架，并在需要时检查数据库是否接受非本地连接。

    # accept non-local connections
server.default_listen_address=0.0.0.0

# configure ssl for bolt
dbms.ssl.policy.bolt.enabled=true
dbms.ssl.policy.bolt.base_directory=certificates/bolt
dbms.ssl.policy.bolt.private_key=private.key
dbms.ssl.policy.bolt.public_certificate=public.crt
dbms.ssl.policy.bolt.client_auth=NONE

# enforcing ssl connection
server.bolt.tls_level=REQUIRED

连接到远程数据库别名

您可以使用以下任何选项以连接标准数据库的方式连接到远程数据库别名：

  • 直接连接到远程数据库别名。

  • 使用 Cypher USE 子句查询您未直接连接的远程数据库别名。

    USE `db1-remote-alias` MATCH (n) RETURN *

  • 连接到作为主数据库的远程数据库别名。这需要由管理员（本例中为 Alice）进行设置。有关详细信息，请参阅用户管理。

    ALTER USER carol SET HOME DATABASE `db1-remote-alias`

重要注意事项

使用远程数据库别名时，请记住：

  • 远程数据库别名事务不会显示在本地 DBMS 的 SHOW TRANSACTIONS 中。但是，当使用相同用户连接时，可以在远程数据库上访问并终止它们。

  • 在远程 DBMS 上的所有操作都归因于为远程数据库别名配置的用户。在使用 存储的原生凭据 (STORED NATIVE CREDENTIALS) 的情况下，无论哪个终端用户发起针对该远程数据库别名的查询，都使用相同的凭据连接到远程 DBMS。这将导致存储的原生用户在远程 DBMS 的审计日志中被记录为所有使用该远程数据库别名的查询的执行者。当使用 OIDC 凭据转发 (OIDC CREDENTIAL FORWARDING) 时，将使用实际终端用户的凭据和权限，从而在远程 DBMS 上记录每个用户的审计跟踪。

  • 当将远程数据库别名与 OIDC 凭据转发配合使用时，用户需要通过 OIDC 登录到本地 DBMS，否则将没有可转发的令牌，并且对远程数据库的访问将被拒绝，并返回 GQLSTATUS 42NFF。