Neo4j 5.x 配置参数详解
详解 Neo4j 5.x（实测 5.26.31 社区版）核心配置参数，覆盖 /etc/neo4j/neo4j.conf 中的网络监听、内存、目录、认证、事务等关键项，全部默认值与生效值均来自 Ubuntu 24.04 真实部署实例实测
Neo4j 5.x 配置参数详解
目标：详解 Neo4j 5.x（实测 5.26.31 社区版）核心配置参数，覆盖 /etc/neo4j/neo4j.conf 中的网络监听、内存、目录、认证、事务等关键项，全部默认值与生效值均在真实服务器实测获得。
环境信息
| 信息项 | 值 |
|---|---|
| Neo4j 版本 | 5.26.31（社区版） |
| 配置文件 | /etc/neo4j/neo4j.conf |
| 验证方式 | CALL dbms.listConfig() YIELD name, value（cypher-shell 实测） |
| 进程内存 | 实测 903.8MiB（heap 512m/1G + pagecache 256m 配置下） |
| 数据目录 | /var/lib/neo4j/data |
| 认证 | dbms.security.auth_enabled=true（默认开启） |
核心参数总览
一、网络监听参数
| 参数 | 默认值 | 实测生效值 | 说明 |
|---|---|---|---|
server.bolt.enabled | true | true | 是否启用 Bolt 协议连接器（驱动/cypher-shell 使用） |
server.bolt.listen_address | :7687 | 0.0.0.0:7687 | Bolt 监听地址，0.0.0.0 表示接受任意网卡连接 |
server.http.enabled | true | true | 是否启用 HTTP 连接器（浏览器/Browser/HTTP API） |
server.http.listen_address | :7474 | 0.0.0.0:7474 | HTTP 监听地址 |
server.https.enabled | false | false | 社区版默认关闭 HTTPS（需配置 SSL 策略后开启） |
server.default_listen_address | localhost | 0.0.0.0（实测已显式配置） | 所有连接器的默认监听网卡；不配置时仅允许本机连接 |
实测输出（cypher-shell）：
name, value
"dbms.security.auth_enabled", "true"
"server.bolt.listen_address", "0.0.0.0:7687"
"server.http.listen_address", "0.0.0.0:7474"
"server.memory.heap.initial_size", "512.00MiB"
"server.memory.heap.max_size", "1.00GiB"
"server.memory.pagecache.size", "256.00MiB"
💡 命令解释：
CALL dbms.listConfig()返回全部生效配置（含未显式设置项的计算值），YIELD name, value只取参数名与值；返回单位统一为 MiB/GiB。
💡 说明：apt 部署默认仅本机可连，需要远程访问时在 neo4j.conf 中显式加
server.default_listen_address=0.0.0.0。（Docker 部署的默认监听与外部访问见《Neo4j 5.x Docker Compose 部署指南》）。
二、内存参数（重点）
| 参数 | 默认行为 | 实测配置值 | 说明 |
|---|---|---|---|
server.memory.heap.initial_size | 动态计算（约物理内存 1/4） | 512m | JVM 堆初始大小 |
server.memory.heap.max_size | 动态计算 | 1G | JVM 堆最大大小，承载事务状态与查询上下文 |
server.memory.pagecache.size | 物理内存 50% 减 heap | 256m | 存储文件页缓存，命中率高则磁盘 IO 少 |
db.memory.transaction.max | 无限制 | 未设置（注释默认 16m） | 单个事务可占用的堆内存上限 |
dbms.memory.transaction.total.max | heap 上限的 70% | 未设置 | 全部并发事务总内存上限 |
💡 说明：Neo4j 5.x 默认按服务器内存动态分配（"leave about 2-4 GB for the OS"），在内存紧张的服务器上必须显式配置，否则 JVM + 页缓存可能吃光内存。实测本配置下 Neo4j 进程 RSS 约 903.8MiB。
配置文件示例（/etc/neo4j/neo4j.conf 实测生效部分）：
server.memory.heap.initial_size=512m
server.memory.heap.max_size=1G
server.memory.pagecache.size=256m
#db.memory.transaction.max=16m
三、目录参数
| 参数 | 实测值 | 说明 |
|---|---|---|
server.directories.data | /var/lib/neo4j/data | 数据库存储根目录 |
server.directories.logs | /var/log/neo4j | 日志目录 |
server.directories.import | /var/lib/neo4j/import | LOAD CSV 默认导入目录（安全边界） |
server.directories.plugins | /var/lib/neo4j/plugins | 插件目录（APOC/GDS 等） |
server.directories.transaction.logs.root | data/transactions | 事务日志根目录（相对 data） |
💡 说明：目录参数均支持绝对路径与相对路径（相对 NEO4J_HOME）。Docker 部署的数据卷挂载与持久化见《Neo4j 5.x Docker Compose 部署指南》。
四、安全与认证参数
| 参数 | 默认值 | 说明 |
|---|---|---|
dbms.security.auth_enabled | true | 是否启用认证；false 时任何人可免密访问（仅限隔离测试环境） |
dbms.security.http_access_control_allow_origin | * | HTTP 跨域来源白名单 |
dbms.security.allow_csv_import_from_file_urls | true | 是否允许 LOAD CSV 使用 file:// URL |
dbms.security.procedures.allowlist | 全部 | 允许加载的过程白名单（如 apoc.coll.*） |
💡 说明：生产环境保持
auth_enabled=true；密码用neo4j-admin dbms set-initial-password（首次启动前）或ALTER USER neo4j SET PASSWORD管理，勿写入明文配置文件。
五、事务与日志参数
| 参数 | 默认值 | 实测值 | 说明 |
|---|---|---|---|
db.tx_log.rotation.retention_policy | 7 days | 2 days 2G（实测已配置） | 事务日志保留策略：至少保留时长 + 容量上限，用于恢复与备份 |
dbms.logs.http.enabled | false | false | HTTP 请求日志开关 |
server.logs.gc.enabled | false | false | GC 日志开关 |
db.tx_log.rotation.size | 20m | 默认 | 单个事务日志轮转大小 |
💡 说明：
2 days 2G表示事务日志至少保留 2 天、总容量上限 2G，达到任一条件才回收，兼顾崩溃恢复能力与磁盘占用。
配置说明
配置项 1：修改配置后生效方式
systemctl restart neo4j
修改 /etc/neo4j/neo4j.conf 后必须重启才能生效；修改前建议 cp neo4j.conf neo4j.conf.bak。
配置项 2：验证生效值
cypher-shell -a bolt://127.0.0.1:7687 -u neo4j -p "${NEO4J_PASSWORD:?}" \
"CALL dbms.listConfig() YIELD name, value WHERE name CONTAINS 'memory' RETURN name, value"
💡 命令解释：
${NEO4J_PASSWORD:?}为占位符，未设置环境变量时直接报错退出，避免密码硬编码进文档/脚本。
注意事项
- 内存参数是动态的：不显式配置时按服务器内存 50% 左右计算页缓存 + 动态堆，内存紧张的服务器上极易 OOM；务必显式限定
- 监听地址默认只绑本机：远程访问需
server.default_listen_address=0.0.0.0 - 认证默认开启：忘设密码会无法登录（见常见问题 1），关闭认证仅限隔离测试环境
- 配置语法错误会导致启动失败：改错参数名/值（如
server.memory.heap.max_size=1GB非法单位）服务起不来，启动前可用neo4j-admin server validate-config校验（实测 5.26 支持该子命令） - 事务日志保留策略影响磁盘：
retention_policy太小会缩短崩溃恢复窗口，生产建议 ≥ 2 days 2G - 大小写与单位：大小写敏感；单位支持 k/m/g（KiB/MiB/GiB），不支持 GB 等写法
常见问题
问题 1：改完配置重启后参数未生效
原因： 未重启进程（Neo4j 只在启动时读取 neo4j.conf），或改的是被注释的默认行（行首 # 未去掉）。
解决： 确认行首无 # 后重启，并用 dbms.listConfig() 验证：
grep -E "^server.memory.pagecache.size" /etc/neo4j/neo4j.conf
systemctl restart neo4j
cypher-shell -a bolt://127.0.0.1:7687 -u neo4j -p "${NEO4J_PASSWORD:?}" "CALL dbms.listConfig() YIELD name, value WHERE name='server.memory.pagecache.size' RETURN name, value"
问题 2：内存参数写 1GB 等非法单位导致启动失败
原因： Neo4j 只识别 k/m/g（小写）后缀，GB 会解析失败；配置文件语法错误时服务直接拒绝启动。
解决： 改用合法单位，并先用 neo4j-admin server validate-config 校验：
sed -i "s/server.memory.heap.max_size=1GB/server.memory.heap.max_size=1G/" /etc/neo4j/neo4j.conf
neo4j-admin server validate-config # 实测 5.26 可用，校验通过才启动
systemctl start neo4j
问题 3：启动报配置参数不认识/拼写错误
原因： 5.x 大量参数沿用 server.* 前缀，网上旧教程的 dbms.connector.* 等 4.x 写法已废弃，参数名不匹配会报错。
解决： 以 CALL dbms.listConfig() 输出的名称为准（该命令返回全部合法参数名），或查官方配置参考页面。
卸载方式
配置文档无需卸载软件；如需将配置还原为初始默认：
cp /etc/neo4j/neo4j.conf.bak /etc/neo4j/neo4j.conf 2>/dev/null || \
apt-get -o DPkg::options::="--force-confmiss" install --reinstall neo4j
systemctl restart neo4j
参考链接
- Neo4j 配置参数参考（官方，全量）：https://neo4j.com/docs/operations-manual/current/reference/configuration-settings/
- Neo4j 内存配置指南：https://neo4j.com/docs/operations-manual/current/performance/memory-configuration/
- Neo4j 配置与调优：https://neo4j.com/docs/operations-manual/current/configuration/
本文档由 www.quzuo.net 平台开发