Apache HugeGraph 配置参数详解

目标：详解 Apache HugeGraph 1.7.0 的核心配置项、默认值与修改方式，覆盖配置文件位置、JVM 堆内存、后端后端切换、缓存、任务调度、认证与日志等，并给出适配生产内存/磁盘/场景的配置模板。全部参数与默认值取自安装目录 conf/ 实测文件。

一、环境信息

• 组件版本：Apache HugeGraph 1.7.0（安装于 /opt/hugegraph/hugegraph-server-1.7.0）
• 配置文件目录：conf/
• 核心配置文件：conf/rest-server.properties、conf/graphs/hugegraph.properties、conf/gremlin-server.yaml、conf/log4j2.xml、conf/remote.yaml
• 默认后端：RocksDB；默认端口 8080（REST）、8182（Gremlin）

二、前置条件

• 已完成本文安装（见《Ubuntu 22.04 安装 Apache HugeGraph 1.7.0 指南》）
• 有权限修改安装目录 conf/ 下文件并重启服务
• 修改配置后需 stop-hugegraph.sh + start-hugegraph.sh（或 docker compose restart）生效

三、参数查看与修改方式

配置以「键值」形式分布在 YAML/Properties 文件中，修改流程统一为：改文件 → bin/stop-hugegraph.sh → bin/start-hugegraph.sh（Compose 方式为 docker compose restart）。

• REST 全局参数：conf/rest-server.properties（Properties 格式）
• 图与后端参数：conf/graphs/hugegraph.properties（Properties 格式，# 为注释）
• Gremlin Server 参数：conf/gremlin-server.yaml（YAML 格式，缩进敏感）
• JVM 内存：bin/hugegraph-server.sh 的 MIN_MEM / MAX_MEM，或用 JAVA_OPTIONS 环境变量覆盖

查看当前生效配置（带注释的默认值即为默认）：

grep -vE "^\s*#|^\s*$" /opt/hugegraph/hugegraph-server-1.7.0/conf/rest-server.properties

四、参数总览

五、核心参数分类详解

5.1 REST 服务参数（rest-server.properties）

• restserver.url=http://127.0.0.1:8080：REST 服务监听地址与端口。改端口即改此处（配合 gremlin-server.yaml 的 host/port 保持一致）。
• graphs=./conf/graphs：存放各图配置文件（如 hugegraph.properties）的目录。
• batch.max_write_ratio=80：批量写最大内存占比。
• batch.max_write_threads=0：批量写线程数（0 表示按 CPU 自适应）。
• server.id=server-1 / server.role=master：节点标识与角色，多节点部署时用于主从/raft 识别（1.7.0 单机默认即可）。
• log.slow_query_threshold=1000：慢查询日志阈值（毫秒）。
• memory_monitor.threshold=0.85 / memory_monitor.period=2000：内存监控阈值与周期。

5.2 图与后端参数（graphs/hugegraph.properties）

默认图配置文件 conf/graphs/hugegraph.properties 中：

• gremlin.graph=org.apache.hugegraph.HugeFactory：图工厂实现类。启用认证时切换为 org.apache.hugegraph.auth.HugeFactoryAuthProxy（可由 bin/enable-auth.sh 自动修改）。
• backend=rocksdb：后端存储类型。1.7.0 支持 rocksdb / hstore / hbase / memory，默认 rocksdb。
• serializer=binary：后端序列化器。
• store=hugegraph：图（store）名称，与 REST 路径 /graphs/{store} 对应。
• vertex.cache_type=l2 / edge.cache_type=l2：顶点/边二级缓存（l2 表示多级缓存），容量与过期见注释 vertex.cache_capacity/vertex.cache_expire（默认顶点缓存 1000w、10 分钟过期；边 100w、10 分钟过期）。
• task.scheduler_type=local：任务调度器（local/raft 等）。
• task.schedule_period=10：任务调度周期（秒）。
• search.text_analyzer=jieba：全文检索分词器。

5.3 后端切换（backend）

在 conf/graphs/hugegraph.properties 中修改 backend= 并重启即切换后端。1.7.0 支持的值及关键配套项：

⚠️ 注意：1.7.0 已移除 mysql / postgresql / cassandra 后端；如需它们请用 < 1.7.0 版本。切换后端前要先用对应版本的 bin/init-store.sh 初始化目标 store。

示例（切到 HBase，在 conf/graphs/hugegraph.properties 追加）：

backend=hbase
serializer=binary
hbase.hosts=localhost
hbase.port=2181
hbase.znode_parent=/hbase
hbase.threads_max=64
hbase.enable_partition=true
hbase.vertex_partitions=10
hbase.edge_partitions=30

5.4 Gremlin Server 参数（gremlin-server.yaml）

• host: 127.0.0.1 / port: 8182：Gremlin WebSocket 监听地址与端口，需与 rest-server.properties 的地址保持一致。
• channelizer: org.apache.tinkerpop.gremlin.server.channel.WsAndHttpChannelizer：接入方式（WebSocket+HTTP）。
• scriptEngines.gremlin-groovy：Groovy 脚本引擎，含 staticImports（导入 HugeGraph 遍历算法类）与 methodImports。
• 通信序列化器：serializers 列表声明 GraphSON/GraphBinary 等（客户端 remote.yaml 也需匹配）。

5.5 JVM 内存参数

JVM 堆在启动脚本 bin/hugegraph-server.sh 中控制：

• 变量 MIN_MEM=$((1 * 512))（决定 -Xms 下限）与 MAX_MEM=$((32 * 1024))（决定 -Xmx 上界）。
• 脚本按 MIN_MEM（对应 Xms 下限）与 MAX_MEM（决定 Xmx 上界，经 calc_xmx 结合本机空闲内存计算）决定堆大小，并附 -XX:+HeapDumpOnOutOfMemoryError（heap dump 落 logs/ 目录），最终拼出 -Xms/-Xmx 参数。
• 本文把堆限制在 256–512MB，两种改法：

# 方式一：启动前用环境变量覆盖（不改文件，推荐）
export JAVA_OPTIONS="-Xms256m -Xmx512m"
bash start-hugegraph.sh

# 方式二：改脚本第 62/63 行的 MIN_MEM / MAX_MEM（如改 MIN_MEM 为 256、MAX_MEM 为 512）
sed -i 's/MIN_MEM=\$((1 \* 512))/MIN_MEM=$((1 * 256))/' bin/hugegraph-server.sh

验证生效值（应为 -Xms256m -Xmx512m）：

jps -v | grep -i HugeGraphServer
ss -ltnp | grep -E "8080|8182"

5.6 认证参数（admin 账号）

• auth.authenticator：填 org.apache.hugegraph.auth.StandardAuthenticator（或 ConfigAuthenticator）启用认证。
• auth.admin_pa：管理员初始口令（默认 pa，有效则第一次生效写入）。
• auth.graph_store：认证图存储（默认 hugegraph）。
• 示例管理账号 admin，本文演示口令固定 q1w2e3r4。启用认证后 REST/Gremlin 需携带该账号获取的 token。

5.7 日志参数（log4j2.xml）

conf/log4j2.xml 控制日志级别与文件滚动。日志默认写 logs/hugegraph-server.log。如需调级别，将对应 <logger> 的 level 改为 INFO/WARN 等。

六、生产配置模板

以下模板按「16GB 内存、NVMe SSD、OLTP 实时图查询」场景给出核心配置建议（文件位置：conf/rest-server.properties、conf/graphs/hugegraph.properties、启动脚本）：

# rest-server.properties
restserver.url=http://0.0.0.0:8080
batch.max_write_ratio=80
batch.max_write_threads=8
log.slow_query_threshold=1000
memory_monitor.threshold=0.85
memory_monitor.period=2000
auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator
auth.graph_store=hugegraph
auth.admin_pa=q1w2e3r4

# graphs/hugegraph.properties
gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
backend=rocksdb
serializer=binary
store=hugegraph
vertex.cache_type=l2
#vertex.cache_capacity=10000000
#vertex.cache_expire=600
edge.cache_type=l2
#edge.cache_capacity=1000000
#edge.cache_expire=600
schema.cache_capacity=100000
task.scheduler_type=local
task.schedule_period=10
search.text_analyzer=jieba
rocksdb.data_path=/opt/hugegraph/data/rocksdb
rocksdb.wal_path=/opt/hugegraph/data/wal

启动脚本 bin/hugegraph-server.sh（或 JAVA_OPTIONS）设为 -Xms256m -Xmx512m。适用场景：OLTP 实时图查询；若为大量写或脏话型分析负载，适当调大 batch.max_write_threads 与 RocksDB 数据路径到独立 SSD 盘（rocksdb.data_path / rocksdb.wal_path）。

七、常见问题（FAQ）

Q1：改了 backend 后启动报 store 未初始化 每换一种后端都要先用 bin/init-store.sh 初始化该后端；切换后老后端的旧数据不迁移。

Q2：堆改成 -Xmx512m 后 jps -v 没生效 确认没有在别处 export 了 JAVA_OPTIONS，且启动命令是从 bin/ 下执行；hugegraph-server.sh 仅在 JAVA_OPTIONS 为空时才自行拼 -Xms/-Xmx。

Q3：gremlin-server.yaml 改了端口后连不上 rest-server.properties 的 restserver.url 与 gremlin-server 的 host/port 需一致；客户端 remote.yaml 的 port 也要同步改为新端口。

Q4：认证开启后旧 token 失效 启用认证/改 auth.admin_pa 后重启服务，使用新口令重新获取 token。

八、参考链接

• Apache HugeGraph 官方配置文档：https://hugegraph.apache.org/docs/config/config-option/
• Apache 归档发行目录：https://archive.apache.org/dist/incubator/hugegraph/
• TinkerPop Gremlin Server 配置：https://tinkerpop.apache.org/docs/current/reference/#gremlin-server