高级连接信息

连接 URI

驱动程序支持连接到以下格式的 URI：

<SCHEME>://<HOST>[:<PORT>[?policy=<POLICY-NAME>]]

  • <SCHEME> 是 neo4j、neo4j+s、neo4j+ssc、bolt、bolt+s、bolt+ssc 中的一个。

  • <HOST> 是 Neo4j 服务器所在的主机名。

  • <PORT> 是可选的，表示 Bolt 协议可用的端口。

  • <POLICY-NAME> 是可选的服务器策略名称。服务器策略在使用前需要先进行设置。

驱动程序不支持连接到嵌套路径，例如 example.com/neo4j/。必须能够从域名根目录访问服务器。

连接协议与安全性

驱动程序与服务器之间的通信由 Bolt 进行中介。服务器 URI 的方案（scheme）决定了连接是否加密，以及如果加密，接受何种类型的证书。

URL 方案 加密 注释

neo4j

本地设置的默认值

neo4j+s

（仅限 CA 签名的证书）

Aura 的默认值

neo4j+ssc

（CA 签名和自签名证书）
无论实例是适当的集群环境还是单机环境，驱动程序在成功连接后都会从服务器接收一张路由表。驱动程序的路由行为通过将读/写事务引导至适当的集群成员，与 Neo4j 集群配合工作。如果您想针对特定机器，请改用 bolt、bolt+s 或 bolt+ssc URI 方案。

要使用的连接方案并非由您选择，而是由服务器要求决定的。您必须预先知道正确的服务器方案，因为在连接之前不会公开任何元数据。连接方案是实例 URI 的一部分。如果不确定，请咨询数据库管理员。

身份验证方法

基本身份验证

基本身份验证方案依赖于传统的用户名和密码。

const driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD))

基本身份验证方案也可用于针对 LDAP 服务器进行身份验证（仅限企业版）。

Kerberos 身份验证

Kerberos 身份验证方案需要一个 base64 编码的票据。只有在服务器安装了 Kerberos 插件的情况下才能使用。

const driver = neo4j.driver(URI, neo4j.auth.kerberos(ticket))

Bearer 身份验证

Bearer 身份验证方案需要由身份提供商通过 Neo4j 的 单点登录功能 (Single Sign-On feature) 提供的 base64 编码令牌。

const driver = neo4j.driver(URI, neo4j.auth.bearer(token))
Bearer 身份验证方案需要 在服务器上配置单点登录。配置完成后，客户端可以通过 发现 API (Discovery API) 获取 Neo4j 的配置信息。

自定义身份验证

如果服务器配备了自定义身份验证方案，请使用 neo4j.auth.custom。

const driver = neo4j.driver(
  URI,
  neo4j.auth.custom(principal, credentials, realm, scheme, parameters)
)

无身份验证

如果服务器上禁用了身份验证，则可以完全省略身份验证参数。

轮换身份验证令牌

可以轮换预期会过期的身份验证令牌（例如 SSO）。运行时间长于令牌有效期的事务将继续运行，而无需重新进行身份验证，而同一会话中的不同事务可能在不同的身份验证令牌下工作。

要使用轮换令牌（rotating tokens），您需要在实例化 Driver 时提供一个 AuthTokenManager 实例，而不是使用静态身份验证令牌。入门最简单的方法是使用 内置的 AuthTokenManager 实现之一。

轮换每 60 秒过期的 Bearer 令牌
import neo4j, { AuthToken } from 'neo4j-driver'

/**
 * Method called whenever the driver needs to refresh the token.
 *
 * The refresh will happen if the driver is notified by the server
 * of token expiration, or if `Date.now() > tokenData.expiry`.
 *
 * The driver will block creation of all connections until
 * this function resolves the new auth token.
 */
async function generateAuthToken () {
   const bearer = await getSSOToken()  // some way to get a token
   const token = neo4j.auth.bearer(bearer)

   // assume we know tokens expire every 60 seconds
   const expiresIn = 60
   // Include a little buffer so that new token is fetched before the old one expires
   const expiration = expiresIn - 10

   return {
      token,
      // if expiration is not provided,
      // the driver will only fetch a new token when an auth failure happens
      expiration
   }
}

const driver = neo4j.driver(
    URI,
    neo4j.authTokenManagers.bearer({
        tokenProvider: generateAuthToken
    })
)
此 API 不得用于切换用户。身份验证管理器必须始终返回同一身份的令牌。您可以在 查询级别 和 会话级别 切换用户。
AuthManagers（包括传递给 expirationBasedAuthTokenManager() 的提供程序函数）绝不能以任何方式与驱动程序交互，因为这可能会导致死锁和未定义的行为。

双向 TLS（客户端证书作为双因素认证）
Aura 不支持

双向 TLS (mTLS) 允许您使用客户端证书作为向服务器进行身份验证的第二因素。除非服务器上禁用了身份验证，否则该证书只能与身份验证令牌一起使用，不能替代常规身份验证。

客户端的证书和公钥必须放置在服务器的 <NEO4J_HOME>/certificates/bolt/trusted 目录中。有关服务器设置的更多信息，请参阅 配置 Bolt 上的 SSL。

要使 mTLS 工作，驱动程序与服务器的连接必须加密，即 连接 URI 方案 必须为 +s 或 +ssc（例如 neo4j+s://example.com:7687）。

使用驱动程序配置选项 clientCertificate 以对象形式提供证书信息。

const driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD), {
   clientCertificate: {
      certfile: '/path/to/cert.cert',
      keyfile: '/path/to/cert.pem',
      password: 'the_key_password' // optional
   }
})

通过 clientCertificateProviders.rotating 实例化证书对象，并在通过配置选项 clientCertificate 实例化驱动程序时提供该对象。

const initialClientCertificate: {
  certfile: '/path/to/cert.cert',
  keyfile: '/path/to/cert.pem',
  password: 'the_key_password' // optional
}
const clientCertificateProvider = neo4j.clientCertificateProviders.rotating({
    initialCertificate: initialClientCertificate
})
const driver = neo4j.driver(URI, MY_CREDENTIALS, {
   clientCertificate: clientCertificateProvider
})
// use the driver...
// ... until it's time to update the certificate
clientCertificateProvider.updateCertificate({
  certfile: '/path/to/new_cert.cert',
  keyfile: '/path/to/new_cert.pem',
  password: 'the_new_key_password' // optional
})
// use the driver some more

自定义地址解析器

创建 Driver 对象时，您可以指定一个解析器（resolver）函数来解析驱动程序初始化时所使用的连接地址。请注意，驱动程序在路由表中接收到的地址不会由自定义解析器解析：自定义解析器仅用于初始连接。

自定义地址解析器无法更改 URI 方案（下例中的 neo4j://）。
端口 9999 上对 example.com 的连接被解析为端口 7687 上的 localhost
let URI = 'neo4j://example.com:9999'
let addresses = [
  'localhost:7687'
]
let driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD), {
  resolver: address => addresses
})

禁用遥测

如果服务器有要求，驱动程序可以将匿名使用统计信息发送到其连接的服务器。遥测在服务器端通过配置设置 server.bolt.telemetry.enabled 进行管理。默认情况下，自管理实例上的遥测是禁用的，Aura 实例上的遥测是启用的。

通过在连接时设置 telemetryDisabled: true，驱动程序将不会发送任何遥测数据。

在驱动程序端禁用遥测
let driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD), {
  telemetryDisabled: true
})

有关传输信息的更多详细信息，请参阅 API 文档 → telemetryDisabled。

其他连接参数

您可以在 API 文档中找到所有 Driver 配置参数。

术语表

LTS (长期支持版)

长期支持 (Long Term Support) 版本是保证在若干年内得到支持的版本。Neo4j 4.4 和 5.26 是 LTS 版本。

Aura

Aura 是 Neo4j 的全托管云服务。它提供免费和付费计划。

Cypher

Cypher 是 Neo4j 的图查询语言，允许您从数据库中检索数据。它就像 SQL，但专用于图数据库。

APOC

Awesome Procedures On Cypher (APOC) 是一个包含（许多）函数的库，这些函数在 Cypher 本身中难以轻松实现。

Bolt

Bolt 是用于 Neo4j 实例和驱动程序之间交互的协议。默认监听 7687 端口。

ACID

原子性 (Atomicity)、一致性 (Consistency)、隔离性 (Isolation)、持久性 (Durability) (ACID) 是保证数据库事务可靠处理的属性。符合 ACID 的 DBMS 确保即使发生故障，数据库中的数据也能保持准确和一致。

最终一致性

如果一个数据库能保证所有集群成员在某个时间点都存储了数据的最新版本，则该数据库具有最终一致性。

因果一致性

如果读写查询被集群中的每个成员以相同的顺序看到，则数据库具有因果一致性。这比最终一致性更强。

NULL

空标记不是一种类型，而是缺失值的占位符。更多信息，请参阅 Cypher → 使用 null。

事务

事务是一个工作单元，要么被提交，要么在失败时被回滚。例如银行转账：它涉及多个步骤，但它们必须全部成功或全部撤销，以避免钱从一个账户扣除却未存入另一个账户的情况。

背压

背压是对数据流的抵抗力。它确保客户端不会被过快发送的数据压垮，从而超出其处理能力。

书签

书签是代表数据库某种状态的标记。通过将一个或多个书签与查询一起传递，服务器将确保在所表示的状态建立之前，该查询不会被执行。

事务函数

事务函数是由 executeRead 或 executeWrite 调用执行的回调。如果发生服务器故障，驱动程序会自动重新执行该回调。

驱动程序 (Driver)

Driver 对象保存了与 Neo4j 数据库建立连接所需的详细信息。