Neo4j在默认情况下，Bolt协议以明文方式传输数据，这在生产环境中存在被窃听和篡改的风险。为了解决这一问题，Neo4j提供了bolt.ssl_policy配置项，它决定Bolt连接使用哪一套SSL策略。SSL策略本身是一组配置的集合，包括证书路径、私钥、信任的CA、允许的TLS版本等，全部定义在dbms.ssl.policy前缀之下。理解这套机制，是给Neo4j数据库连接加锁的第一步。
bolt.ssl_policy到底做了什么
简单来说，bolt.ssl_policy指向一个已命名的SSL策略，当客户端通过Bolt协议连接数据库时，服务端会按照这个策略完成TLS握手。如果这个值留空（默认情况），Bolt连接就是普通明文；如果设置为某个策略名，比如bolt.ssl_policy=bolt，那么所有Bolt连接都必须使用TLS加密，明文连接会被直接拒绝。
需要注意的是，这个配置项只在企业版中才支持非空的策略名。社区版虽然可以读取这个配置，但无法真正启用命名SSL策略，这是很多人配置了却始终不生效的常见原因。企业版允许同时定义多套策略，例如一套给Bolt对外服务，一套给集群内部通信（causal_clustering.ssl_policy），一套给HTTPS（dbms.connector.https.ssl_policy），各自使用不同的证书和协议参数，互不干扰。
另外还有一个兼容旧版本的写法：dbms.connector.bolt.tls_level，它有OPTIONAL、REQUIRED、DISABLED三个取值，这是旧版单套证书的遗留方案，官方已经标记为废弃，推荐统一迁移到bolt.ssl_policy的模式。
完整的配置步骤与证书生成
第一步是生成证书。假设我们要为Bolt连接创建一套自签名证书，可以用OpenSSL完成。先生成一个CA，再用CA签发服务端证书，Neo4j要求证书和私钥使用PEM格式，私钥不能带密码保护，否则服务启动时会加载失败。
# 生成CA私钥和证书 openssl genrsa -out ca.key 4096 openssl req -x509 -new -key ca.key -days 3650 -subj "/CN=MyNeo4jCA" -out ca.crt # 生成服务端私钥 openssl genrsa -out neo4j.key 2048 # 生成证书签名请求并签发 openssl req -new -key neo4j.key -subj "/CN=your.neo4j.host" -out neo4j.csr openssl x509 -req -in neo4j.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out neo4j.crt -days 3650
第二步是把证书放到策略对应的目录。Neo4j约定每个策略对应certificates目录下的一个子目录，目录名就是策略名。假设安装目录为/var/lib/neo4j，结构如下：
/var/lib/neo4j/certificates/bolt/
neo4j.crt # 证书（名字由配置项决定）
neo4j.key # 私钥
trusted/ # 受信任的CA证书目录（可选）
revoked/ # 吊销列表（可选）第三步是在neo4j.conf中定义策略并绑定给Bolt：
# 定义名为bolt的SSL策略 dbms.ssl.policy.bolt.base_directory=certificates/bolt dbms.ssl.policy.bolt.allow_key_generation=false dbms.ssl.policy.bolt.private_key=neo4j.key dbms.ssl.policy.bolt.public_cert=neo4j.crt dbms.ssl.policy.bolt.trusted_dir=trusted dbms.ssl.policy.bolt.revoked_dir=revoked dbms.ssl.policy.bolt.client_auth=NONE dbms.ssl.policy.bolt.tls_versions=TLSv1.2,TLSv1.3 # 将策略绑定到Bolt连接器 bolt.ssl_policy=bolt dbms.connector.bolt.enabled=true dbms.connector.bolt.listen_address=:7687
配置完成后重启数据库生效。其中client_auth决定是否要求客户端出示证书，设为NONE时只需服务端证书即可完成加密，设为REQUIRED则做双向认证，客户端也必须持有由受信任CA签发的证书。
客户端连接与常见问题排查
服务端启用加密后，客户端也需要相应调整。以Python驱动为例，需要关闭证书校验或者传入CA证书来验证服务端身份：
from neo4j import GraphDatabase
# 方式一：信任自签名证书（推荐）
driver = GraphDatabase.driver(
"neo4j+s://your.neo4j.host:7687",
auth=("neo4j", "password")
)
# 方式二：本地开发时跳过证书校验
driver = GraphDatabase.driver(
"neo4j+ssc://your.neo4j.host:7687",
auth=("neo4j", "password")
)连接URI的前缀很关键：neo4j://表示不加密，neo4j+s://表示全连接加密并校验证书，neo4j+ssc://表示加密但不校验。如果服务端已经设置了bolt.ssl_policy，而客户端仍用neo4j://明文连接，会收到类似Connection terminated或SSL握手失败的错误，改成加密URI即可解决。
排查问题时可以按几个方向检查：一是确认版本是否为企业版，社区版不支持命名策略；二是检查私钥文件是否有密码保护，有的话用openssl rsa -in neo4j.key -out neo4j.key去掉；三是检查证书CN是否与客户端访问的主机名一致，不一致会导致校验失败；四是查看debug.log中是否有Failed to load SSL policy之类的记录，通常会指明具体是哪个文件路径出了问题。
集群环境下还有一点要留意：如果配置了因果集群，集群成员间的通信走的是causal_clustering.ssl_policy指定的策略，它与Bolt的策略是独立的。建议集群内部通信也启用加密，并为不同用途的策略签发不同的证书，这样即使某一套证书泄露，影响范围也能被控制住。证书到期前记得提前更换，可以在监控中加入对证书有效期的告警，避免服务突然不可用。
Neo4jbolt.ssl_policySSL策略配置修改时间：2026-09-13 18:52:41