JanusGraph 配置参数详解

详细介绍 JanusGraph 1.1 配置文件（实测 1.1.0），包括 janusgraph-cql.properties 与 janusgraph-cql-cluster.properties 全参数、gremlin-server.yaml 系列 Gremlin Server 配置、cassandra.yaml 存储后端关键参数、jvm-server.options 与 jvm-11.options 内存参数、remote.yaml 客户端连接配置，并给出参数默认值、数据类型、可变性与实测取值

JanusGraph图数据库JanusGraph配置详解NoSQL2026/10/03

JanusGraph 配置参数详解

目标：详解 JanusGraph 1.1（实测 1.1.0）全部关键配置文件与参数，包括图后端配置 janusgraph-*.properties、服务端配置 gremlin-server*.yaml、存储后端配置 cassandra.yaml、JVM 内存配置以及客户端连接配置 remote.yaml。参数表标注默认值、数据类型与可变性（LOCAL / MASKABLE / GLOBAL）。

一、配置文件总览

JanusGraph 1.1.0 安装目录 /opt/janusgraph-1.1.0/conf/ 下的核心配置文件：

文件作用
janusgraph-cql.properties图存储配置：CQL 后端，单节点 Cassandra
janusgraph-cql-cluster.properties图存储配置：CQL 后端，Cassandra 集群
janusgraph-inmemory.properties图存储配置：纯内存后端（重启丢失）
janusgraph-berkeleyje.properties图存储配置：本地文件后端 BerkeleyJE
janusgraph-hbase.properties图存储配置：HBase 后端
gremlin-server.yamlGremlin Server 默认服务配置（inmemory）
gremlin-server-cql.yamlGremlin Server 服务配置（CQL 单节点）
gremlin-server-cql-cluster.yamlGremlin Server 服务配置（CQL 集群）
remote.yamlGremlin Console 远端连接配置
jvm-11.options / jvm-8.optionsGremlin Server JVM 参数
log4j2-server.xml / log4j2-console.xml日志配置

启动时通过 janusgraph-server.sh start <yaml> 指定加载哪一份 Gremlin Server 配置，而该 yaml 的 graphs.graph 指向对应的图存储 properties 文件。

二、图存储配置 janusgraph-cql.properties 详解

单节点 CQL 后端的完整配置文件（/opt/janusgraph-1.1.0/conf/janusgraph-cql.properties）实测内容：

gremlin.graph=org.janusgraph.core.JanusGraphFactory
storage.backend=cql
storage.hostname=127.0.0.1
storage.cql.keyspace=janusgraph
storage.cql.local-datacenter=datacenter1
cache.db-cache = true
cache.db-cache-clean-wait = 20
cache.db-cache-time = 180000
cache.db-cache-size = 0.5

2.1 gremlin.graph

参数值数据类型可变性
gremlin.graphorg.janusgraph.core.JanusGraphFactoryStringLOCAL

指定图工厂类。JanusGraph 通过 JanusGraphFactory 依据 storage.backend 实例化对应的存储后端，该行不可省略。

2.2 storage.*（存储后端）

参数值默认值数据类型可变性说明
storage.backendcql（无）StringLOCAL持久化后端简写名：berkeleyje、cql、hbase、inmemory、scylla，或完整类名
storage.hostname127.0.0.1127.0.0.1String[]LOCAL存储后端服务器地址；集群时逗号分隔多个地址
storage.port（默认 9042）9042IntegerLOCAL存储后端端口（CQL 原生传输端口）
storage.cql.keyspacejanusgraphjanusgraphStringLOCAL图数据 keyspace，不存在时自动创建
storage.cql.local-datacenterdatacenter1datacenter1StringMASKABLE本地数据中心名，传入 CqlSessionBuilder.withLocalDatacenter
storage.cql.replication-factor2（集群）/ 1（单机）1IntegerLOCALkeyspace 副本因子，需与 keyspace 实际副本数一致

2.3 cache.*（数据库级缓存）

参数值默认值数据类型可变性说明
cache.db-cachetruefalseBooleanMASKABLE是否开启跨事务共享的数据库级缓存；开启后遍历更快，但可能读到稍旧数据
cache.db-cache-clean-wait2050IntegerMASKABLE缓存刷出后保留条目并允许后台清理的时间（ms）
cache.db-cache-time18000010000LongMASKABLE缓存条目过期时间（ms）；0 表示永不过期
cache.db-cache-size0.50.3DoubleMASKABLE缓存占用堆比例（0~1 表示百分比，大于 1 视为字节数）

三、集群版 janusgraph-cql-cluster.properties 详解

集群模式（双节点 Cassandra）实测配置（/opt/janusgraph-1.1.0/conf/janusgraph-cql-cluster.properties）：

gremlin.graph=org.janusgraph.core.JanusGraphFactory
storage.backend=cql
storage.hostname=172.29.0.3,172.29.0.4
storage.port=9042
storage.cql.keyspace=janusgraph
storage.cql.local-datacenter=datacenter1
storage.cql.replication-factor=2
cache.db-cache=true
cache.db-cache-clean-wait=20
cache.db-cache-time=180000
cache.db-cache-size=0.5

与单机版相比的关键差异：

参数单机版集群版说明
storage.hostname127.0.0.1172.29.0.3,172.29.0.4填写所有 Cassandra 节点，客户端连接到任一存活节点即自动发现整个环
storage.port默认 9042显式 9042显式声明便于排查
storage.cql.replication-factor不写（默认 1）2必须与 keyspace 副本因子一致，保证写入 Quorum

四、Gremlin Server 配置 gremlin-server*.yaml 详解

4.1 完整文件（gremlin-server-cql.yaml，CQL 后端）

host: 0.0.0.0
port: 8182
evaluationTimeout: 30000
channelizer: org.apache.tinkerpop.gremlin.server.channel.WebSocketChannelizer
graphManager: org.janusgraph.graphdb.management.JanusGraphManager
graphs: {
  graph: conf/janusgraph-cql.properties
}
scriptEngines: {
  gremlin-groovy: {
    plugins: { org.janusgraph.graphdb.tinkerpop.plugin.JanusGraphGremlinPlugin: {},
               org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {},
               org.apache.tinkerpop.gremlin.tinkergraph.jsr223.TinkerGraphGremlinPlugin: {},
               org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin: {classImports: [java.lang.Math], methodImports: [java.lang.Math#*]},
               org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {files: [scripts/empty-sample.groovy]}}}}
processors:
  - { className: org.apache.tinkerpop.gremlin.server.op.session.SessionOpProcessor, config: { sessionTimeout: 28800000 }}
  - { className: org.apache.tinkerpop.gremlin.server.op.traversal.TraversalOpProcessor, config: { cacheExpirationTime: 600000, cacheMaxSize: 1000 }}
metrics: {
  consoleReporter: {enabled: true, interval: 180000},
  csvReporter: {enabled: true, interval: 180000, fileName: /tmp/gremlin-server-metrics.csv},
  jmxReporter: {enabled: true},
  slf4jReporter: {enabled: true, interval: 180000},
  graphiteReporter: {enabled: false, interval: 180000}}
maxInitialLineLength: 4096
maxHeaderSize: 8192
maxChunkSize: 8192
maxContentLength: 65536
maxAccumulationBufferComponents: 1024
resultIterationBatchSize: 64
writeBufferLowWaterMark: 32768
writeBufferHighWaterMark: 65536

4.2 关键参数详解

参数值说明
host0.0.0.0监听地址；对外服务必须监听 0.0.0.0
port8182WebSocket 服务端口
evaluationTimeout30000单个脚本求值超时（ms），超时抛异常
channelizerWebSocketChannelizer通道实现；可选 HttpChannelizer（REST）
graphManagerJanusGraphManager图管理器；管理多图实例的初始化与关闭
graphs.graphconf/janusgraph-cql.properties指定加载的图存储配置文件（相对 Gremlin Server 工作目录）
scriptEngines.gremlin-groovy.pluginsJanusGraphGremlinPlugin 等注册的插件：JanusGraph 图插件、Server 插件、TinkerGraph 插件、Import 插件、ScriptFile 插件
SessionOpProcessor.sessionTimeout28800000会话超时（ms），8 小时
TraversalOpProcessor.cacheExpirationTime600000遍历结果缓存过期时间（ms）
TraversalOpProcessor.cacheMaxSize1000遍历结果缓存最大条目数
metrics多 Repoter指标上报：console/csv/jmx/slf4j/graphite，实测启用前四种
resultIterationBatchSize64结果迭代批大小，控制每次推送给客户端的行数
maxContentLength65536请求内容最大字节数
writeBufferLowWaterMark / HighWaterMark32768 / 65536发送缓冲水位（byte），低于低水位发送、高于高水位暂停

五、存储后端 cassandra.yaml 关键参数详解

Cassandra 4.0.6 的 /opt/cassandra/conf/cassandra.yaml 中与 JanusGraph 部署密切相关的参数（实测）：

参数实测值说明
cluster_name'JanusGraph Cluster'集群名，所有节点必须一致
num_tokens16每节点 vnode 数，影响数据分布粒度
seed_provider.parameters.seeds"172.29.0.3,172.29.0.4"种子节点地址列表（逗号分隔），新节点通过种子加入环
listen_address172.29.0.3 / 172.29.0.4节点间通信监听地址（7000 端口），必须为本机可达 IP
rpc_address0.0.0.0CQL 客户端监听地址，配合 broadcast_rpc_address
broadcast_rpc_address172.29.0.3 / 172.29.0.4广播给客户端连接的地址
endpoint_snitchSimpleSnitch机架感知策略，单数据中心用 SimpleSnitch
native_transport_port9042CQL 原生传输端口
storage_port7000节点间通信端口
listen_interface（用 listen_address 时不设）监听网卡名，与 listen_address 二选一
data_file_directories/var/lib/cassandra/data数据目录
commitlog_directory/var/lib/cassandra/commitlog提交日志目录
saved_caches_directory/var/lib/cassandra/saved_caches缓存目录

六、JVM 内存参数详解

6.1 Cassandra：jvm-server.options

Cassandra 4.0.6 的 /opt/cassandra/conf/jvm-server.options，JDK 17 下需显式固定堆并启用 G1：

-Xms2G
-Xmx2G
-XX:+UseG1GC
--add-exports java.base/java.lang=ALL-UNNAMED
--add-exports java.base/java.lang.reflect=ALL-UNNAMED
--add-exports java.base/sun.nio.ch=ALL-UNNAMED
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.lang.reflect=ALL-UNNAMED
--add-opens java.base/sun.nio.ch=ALL-UNNAMED
参数说明
-Xms2G / -Xmx2G固定堆 2G。Cassandra 默认按物理内存动态计算堆大小（可达 8G），资源受限时会导致 OOM
-XX:+UseG1GCG1 回收器。JDK 17 已移除 CMS，默认 jvm-server.options 中 CMS 相关行必须注释掉
--add-exports / --add-opensJDK 17 模块强封装豁免，缺失时启动报 IllegalAccessError/InaccessibleObjectException

6.2 Gremlin Server：jvm-11.options

Gremlin Server 实测堆设置（资源受限环境固定为 1G）：

-Xms1g
-Xmx1g
-XX:+UseThreadPriorities
-XX:+HeapDumpOnOutOfMemoryError
-Xss256k
-XX:+AlwaysPreTouch
-XX:+UseTLAB
-XX:+ResizeTLAB
-XX:+UseNUMA
-Dgremlin.io.kryoShimService=org.janusgraph.hadoop.serialize.JanusGraphKryoShimService
-XX:+UseG1GC
-XX:SurvivorRatio=8
-XX:MaxTenuringThreshold=1

关键项：-Xms1g -Xmx1g 固定堆；-XX:+HeapDumpOnOutOfMemoryError OOM 时生成堆转储；-Dgremlin.io.kryoShimService 指定 JanusGraph 的 Kryo 序列化实现。

七、客户端连接配置 remote.yaml 详解

Gremlin Console 通过 :remote connect tinkerpop.server conf/remote.yaml 连接 Gremlin Server，/opt/janusgraph-1.1.0/conf/remote.yaml：

hosts: [localhost]
port: 8182
serializer: { className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1, config: { serializeResultToString: true }}
参数说明
hostsGremlin Server 地址列表，集群连接多台服务器时列出所有地址
portGremlin Server WebSocket 端口（8182）
serializer序列化协议；GraphBinary 是 TinkerPop 3.7 推荐协议，serializeResultToString: true 使结果以字符串输出便于阅读

八、配置加载顺序与生效方式

  1. janusgraph-server.sh start <yaml> 指定 Gremlin Server 配置文件（默认 conf/gremlin-server/gremlin-server.yaml）。
  2. yaml 中 graphs.graph 指定图存储 properties 文件路径（相对 /opt/janusgraph-1.1.0 工作目录）。
  3. JanusGraph 启动时合并 properties 中所有 storage.*、cache.* 等参数，并在首次连接时按需初始化 keyspace 与表。
  4. 修改 properties 或 yaml 后需 ./bin/janusgraph-server.sh restart <yaml> 或 systemctl restart 生效。
  5. 标为 MASKABLE 的参数可在运行时被事务覆盖（需配置文件允许动态配置），LOCAL 参数只读、修改后必须重启。