高级连接信息
连接协议和安全性
驱动程序和服务器之间的通信通过 Bolt 进行。服务器 URI 的方案决定了连接是否加密,如果加密,则决定接受哪种类型的证书。
URL 方案 | 加密 | 注释 |
---|---|---|
neo4j |
本地设置的默认值 |
|
neo4j+s |
(仅限 CA 签名证书) |
Aura 的默认值 |
neo4j+ssc |
(CA 签名和自签名证书) |
驱动程序在成功连接后会从服务器接收一个 路由表,无论实例是合适的集群环境还是单机环境。驱动程序的路由行为与 Neo4j 的集群 协同工作,将读/写事务定向到适当的集群成员。如果您想针对 特定 机器,请改用 bolt 、bolt+s 或 bolt+ssc URI 方案。 |
要使用的连接方案不是您的选择,而是由服务器要求决定的。您必须事先了解正确的服务器方案,因为在连接之前不会公开任何元数据。如果您不确定,请咨询数据库管理员。
身份验证方法
基本身份验证 (默认)
基本身份验证方案依赖于传统的用户名和密码。这些可以是您本地安装的凭据,也可以是 Aura 实例提供的凭据。
from neo4j import GraphDatabase
driver = GraphDatabase.driver(URI, auth=(USERNAME, PASSWORD))
基本身份验证方案也可用于针对 LDAP 服务器进行身份验证 (仅限企业版)。
Kerberos 身份验证
Kerberos 身份验证方案需要一个 base64 编码的票据。它只能在服务器安装了 Kerberos 附加组件 的情况下使用。
from neo4j import GraphDatabase, kerberos_auth
driver = GraphDatabase.driver(URI, auth=kerberos_auth(ticket))
不记名身份验证
不记名身份验证方案需要由身份提供商通过 Neo4j 的 单点登录功能 提供一个 base64 编码的令牌。
from neo4j import GraphDatabase, bearer_auth
driver = GraphDatabase.driver(URI, auth=bearer_auth(token))
不记名身份验证方案需要在 服务器上配置单点登录。配置完成后,客户端可以通过 发现 API 发现 Neo4j 的配置。 |
自定义身份验证
使用函数 custom_auth
登录到具有自定义身份验证方案的服务器。
轮换身份验证令牌
可以轮换预期会过期的身份验证令牌(例如 SSO)。在实例化 Driver
时,您需要提供一个 AuthManager
实例(对于异步驱动程序,则为 AsyncAuthManager
),而不是一个静态身份验证令牌。
最简单的入门方法是使用 内置的 AuthManager
实现之一。
import neo4j
from neo4j.auth_management import (
AuthManagers,
ExpiringAuth,
)
def auth_provider():
# Some way to get a token
sso_token = get_sso_token()
# Assume we know tokens expire every 60 seconds
expires_in = 60
# Include a little buffer so that new token is fetched before the old one expires
expires_in -= 10
auth = neo4j.bearer_auth(sso_token)
return ExpiringAuth(auth=auth).expires_in(expires_in)
with neo4j.GraphDatabase.driver(
URI,
auth=AuthManagers.expiration_based(auth_provider)
) as driver:
...
AuthManagers (包括传递给 AuthManagers.expiration_based() 的提供函数)不得以任何方式与驱动程序交互,因为这可能导致死锁和未定义的行为。 |
相互 TLS(客户端证书作为双因素认证)
相互 TLS (mTLS) 允许您使用客户端证书作为与服务器进行身份验证的第二因素。除非服务器上禁用了身份验证,否则证书只能与身份验证令牌一起使用,不能替代常规身份验证。
客户端的证书和公钥必须放在服务器的 <NEO4J_HOME>/certificates/bolt/trusted
目录下。有关服务器设置的更多信息,请参阅 通过 Bolt 配置 SSL。
为了使 mTLS 正常工作,驱动程序与服务器的连接必须加密,即 连接 URI 方案 必须是 +s 或 +ssc (例如 neo4j+s://example.com:7687 )。 |
对于静态证书,请使用 ClientCertificateProviders.static()
。
该方法接受一个 ClientCertificate
实例,该实例接受与 Python 的 ssl.SSLContext.load_cert_chain()
相同的参数。
import neo4j
from neo4j.auth_management import (
ClientCertificate,
ClientCertificateProviders,
)
URI = "{neo4j-database-uri}"
AUTH = ("{neo4j-username}", "{neo4j-password}")
cert_provider = ClientCertificateProviders.static(
ClientCertificate(
# path to certificate
"path/to/cert.pem",
# path to private key (optional; needed if certificate does not contain private key too)
"path/to/key.pem",
# password to decrypt private key (can be function or string) (optional)
lambda: "password",
)
)
with neo4j.GraphDatabase.driver(
URI,
auth=AUTH,
client_certificate=cert_provider,
) as driver:
...
对于轮换证书,请使用 ClientCertificateProviders.rotating()
。
该方法接受一个 ClientCertificate
实例。
import neo4j
from neo4j.auth_management import (
ClientCertificate,
ClientCertificateProviders,
)
URI = "{neo4j-database-uri}"
AUTH = ("{neo4j-username}", "{neo4j-password}")
cert_provider = ClientCertificateProviders.rotating(
ClientCertificate(
# path to public certificate to load
"path/to/cert.pem",
# path to private key to load
"path/to/key.pem",
# password to decrypt private key (can be a function or string)
# see also Python's ssl.SSLContext.load_cert_chain()
lambda: "password",
)
)
driver = neo4j.GraphDatabase.driver(
URI
auth=(USERNAME, PASSWORD),
client_certificate=cert_provider
)
# use the driver...
# ... until the certificate needs to be rotated
cert_provider.update_certificate(
ClientCertificate(
certfile="path/to/new/cert.pem",
keyfile="path/to/new/key.pem",
password=lambda: "new_super_secret_password"
)
)
# use the driver again, until the certificate needs to be
# rotated again
# ...
更多信息,请参阅 API 文档 → ClientCertificateProvider
。
自定义地址解析器
创建 Driver
对象时,您可以指定一个 解析器 函数,用于在 DNS 解析之前解析驱动程序接收到的任何地址。您的解析器函数将使用 Address
对象调用,并应返回一个 Address
对象的迭代器(或可用于构造 Address
对象的值)
9999
上的 example.com
被解析为端口 7687
上的 localhost
import neo4j
def custom_resolver(socket_address):
# assert isinstance(socket_address, neo4j.Address)
if socket_address != ("example.com", 9999):
raise OSError(f"Unexpected socket address {socket_address!r}")
# You can return any neo4j.Address object
yield neo4j.Address(("localhost", 7687)) # IPv4
yield neo4j.Address(("::1", 7687, 0, 0)) # IPv6
yield neo4j.Address.parse("localhost:7687")
yield neo4j.Address.parse("[::1]:7687")
# or any tuple that can be passed to neo4j.Address().
# This will initially be interpreted as IPv4, but DNS resolution
# will turn it into IPv6 if appropriate.
yield "::1", 7687
# This will be interpreted as IPv6 directly, but DNS resolution will
# still happen.
yield "::1", 7687, 0, 0
yield "127.0.0.1", 7687
driver = neo4j.GraphDatabase.driver("neo4j://example.com:9999",
auth=(USERNAME, PASSWORD),
resolver=custom_resolver)
更多连接参数
您可以在 API 文档 中找到所有 Driver
配置参数。
术语表
- LTS
-
长期支持 (LTS) 版本是保证多年提供支持的版本。Neo4j 4.4 是 LTS 版本,Neo4j 5 也将有一个 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
。 - 事务
-
事务是工作的一个单元,它要么全部 提交,要么在失败时 回滚。一个例子是银行转账:它涉及多个步骤,但它们必须 全部 成功或被还原,以避免资金从一个账户中扣除但未添加到另一个账户的情况。
- 背压
-
背压是阻碍数据流动的力。它确保客户端不会被比其处理能力更快的数据所淹没。
- 事务函数
-
事务函数是由
execute_read
或execute_write
调用执行的回调。在服务器故障时,驱动程序会自动重新执行该回调。 - 驱动程序
-
一个
Driver
对象包含与 Neo4j 数据库建立连接所需的详细信息。