neo4j.conf 文件

neo4j.conf 文件是 Neo4j 中配置设置的主要来源，包含了配置设置键与其对应值的映射。不同 Neo4j 配置下 neo4j.conf 文件的位置列在 默认文件位置 中。

neo4j.conf 文件中的大多数配置设置直接适用于 Neo4j 本身，但也有一些设置与 Neo4j 运行所在的 Java 运行时（JVM）相关。有关更多信息，请参阅 JVM 特定配置设置。许多配置设置也被 neo4j 启动脚本使用。

neo4j.conf 约定

neo4j.conf 文件中的语法遵循以下约定：

  • 等号（=）将配置设置键映射到配置值。

  • 以数字符号（#）开头的行被视为注释。

  • 不支持行尾注释。

  • 空行会被忽略。

  • 在 neo4j.conf 中配置设置将覆盖任何默认值。如果您想用自定义值修改默认值，则必须显式列出默认值以及新的值。

  • 配置设置没有顺序要求。

  • 默认情况下，配置设置启用了严格验证。如果 neo4j.conf 文件包含拼写错误、不正确的信息或重复项（server.jvm.additional 除外），它会阻止 Neo4j 启动。如果您为 server.jvm.additional 设置了多个值，则每个设置值都会向 java 启动程序添加另一个自定义 JVM 参数。

    要禁用严格验证，请设置 server.config.strict_validation.enabled=false。

  • 默认情况下，字符编码假定为 ISO 8859-1，但可以通过将环境变量 NEO4J_CONFIG_FILE_CHARSET 设置为（例如）utf8 来覆盖。

配置设置

常规提要

Neo4j 配置设置具有以下常规提要：

<prefix>.<scope>.<component>…​.<component>.<name>

前缀（Prefix）

前缀保留用于表示两种特殊情况（大多数设置没有前缀）：

  • initial — 仅在初始化期间使用，之后将被忽略的设置。例如，initial.server.mode_constraint、initial.dbms.default_database 等。

  • internal — 此特定前缀取代了之前版本中使用的 unsupported 和 experimental 术语。此命名空间专门用于内部使用的功能，可能会在不另行通知的情况下更改。

范围（Scope）

所有配置设置都属于以下表现不同的范围之一：

  • db 设置可在每个数据库之间进行更改，但必须在集群/DBMS 的所有配置文件中保持一致。

  • dbms 设置必须在集群/DBMS 的所有配置文件中保持一致。

  • server 设置仅适用于特定服务器，并且可以在集群/DBMS 的配置文件之间进行更改。

  • browser 设置仅适用于 Neo4j Browser。

  • client 设置仅适用于客户端。

Component (组件)

组件命名空间用于对影响类似系统的设置进行分组。

名称

设置的名称。它可能包含常见的动词和单位模式，例如 size、enabled 等。单词之间用下划线分隔。

有关 Neo4j 配置设置的完整参考，请参阅 配置设置。

JVM 特定配置设置

Java 虚拟机 (JVM) 是一种能够使计算机运行 Java 程序以及其他编译为 Java 字节码的语言编写的程序的虚拟机。Java 堆是 Java 程序对象存在的地方。根据 JVM 实现的不同，JVM 堆大小通常决定了虚拟机执行 垃圾回收 的方式和持续时间。

表 1. JVM 特定设置
设置 描述

server.memory.heap.initial_size

设置 JVM 的初始堆大小。默认情况下，JVM 堆大小是根据可用的系统资源计算的。

server.memory.heap.max_size

设置 JVM 的最大堆大小。默认情况下，最大 JVM 堆大小是根据可用的系统资源计算的。

server.jvm.additional

设置 JVM 的附加选项。这些选项以字符串形式设置，并可能根据 JVM 实现而变化。

如果您想很好地控制系统行为，建议将堆大小参数设置为相同的值，以避免不必要的完全垃圾回收停顿。

Neo4j 附带了 server.jvm.additional 设置的几个预定义值。您可以在 neo4j.conf 文件中找到它们。下表列出了它们并解释了它们的作用。

表 2. server.jvm.additional 的预定义值
默认值 注意

server.jvm.additional=-XX:+UseG1GC

G1GC（垃圾优先垃圾回收器）在吞吐量和尾部延迟之间提供了良好的平衡，且调整要求极低。

server.jvm.additional=-XX:-OmitStackTraceInFastThrow

确保常见异常始终具有堆栈跟踪，从而无论日志轮转频率如何，都能进行有效的调试。

server.jvm.additional=-XX:+AlwaysPreTouch

确保 initmemory 不仅被分配，而且在数据库启动之前提交给进程。如果此标志降低性能，建议减小堆内存。

server.jvm.additional=-XX:+UnlockExperimentalVMOptions

信任非静态 final 字段确实是 final 的。这允许更多的优化并提高整体性能。如果您使用嵌入式模式，或者拥有可能使用反射或序列化来更改 final 字段值的扩展或依赖项，请禁用此标志。

server.jvm.additional=-XX:+TrustFinalNonStaticFields

server.jvm.additional=-XX:+DisableExplicitGC

禁用由 JDK 本身偶尔调用的显式垃圾回收。

server.jvm.additional=-XX:-RestrictContended [1]

允许 Neo4j 使用 @Contended 注解。

server.jvm.additional=-Djdk.nio.maxCachedBufferSize=1024

将缓存的 JDK 缓冲区大小限制为 1 KB。

server.jvm.additional=-Dio.netty.tryReflectionSetAccessible=true

通过允许对内部 JVM API 进行基于反射的访问，使 Netty 能够更高效地分配直接缓冲区。这绕过了标准的 JVM 清理机制。

2025.04 引入 server.jvm.additional=-Dio.netty.leakDetection.level=DISABLED

Netty 资源泄漏检测。可能的值为 DISABLED、SIMPLE、ADVANCED 和 PARANOID。忽略大小写。有关更多详细信息，请参考 Netty 文档。

server.jvm.additional=-Djdk.tls.ephemeralDHKeySize=2048

将服务器 TLS 握手中使用的 DH-RSA 密码套件的 Diffie Hellman (DH) 密钥大小从默认的 1024 扩展到 2048。这是为了保护服务器免受任何潜在的被动窃听。

server.jvm.additional=-Djdk.tls.rejectClientInitiatedRenegotiation=true

缓解 DDoS 向量。

server.jvm.additional=-XX:FlightRecorderOptions=stackdepth=256

将默认的飞行记录器堆栈采样深度从 64 增加到 256，以避免在分析时截断帧。

server.jvm.additional=-XX:+UnlockDiagnosticVMOptions

允许分析器在安全点之间进行采样。没有此项，采样分析器可能会产生不太准确的结果。

server.jvm.additional=-XX:+DebugNonSafepoints

server.jvm.additional=--add-opens=java.base/java.nio=ALL-UNNAMED

为 Neo4j 打开模块以允许内部访问。

server.jvm.additional=--add-opens=java.base/java.io=ALL-UNNAMED

server.jvm.additional=--add-opens=java.base/sun.nio.ch=ALL-UNNAMED

2025.04 引入 server.jvm.additional=--add-opens=java.base/java.util.concurrent=ALL-UNNAMED

server.jvm.additional=--enable-native-access=ALL-UNNAMED

启用本地内存访问。

server.jvm.additional=-Dlog4j2.disable.jmx=true

禁用日志记录 JMX 端点。

server.jvm.additional=-Dlog4j.layout.jsonTemplate.maxStringLength=32768

增加 JSON 日志字符串的最大长度。

2026.02 引入 server.jvm.additional=-Dorg.neo4j.shaded.lucene9.vectorization.upperJavaFeatureVersion=25

允许旧版 Lucene 索引在最近的 JDK 中使用向量提供程序。
1. 此选项目前在企业版中列出，但也可以添加到社区版中。

列出当前活动的设置

您可以使用 SHOW SETTINGS 来列出当前活动的配置设置及其值。

示例 1. 列出当前活动的配置设置
SHOW SETTINGS
YIELD name, value
WHERE name STARTS WITH 'server.default'
RETURN name, value
ORDER BY name
LIMIT 3;
+---------------------------------------------------+
| name                                | value       |
+---------------------------------------------------+
| "server.default_advertised_address" | "localhost" |
| "server.default_listen_address"     | "localhost" |
+---------------------------------------------------+

有关动态设置的信息，请参阅 更新动态设置 和 配置设置参考。