跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

HugeGraph (OLTP)

1 - ToplingDB

历史集成。 2025 年的文章介绍较早的接口，保留供参考。 候选替代方案见 ToplingDB 开发版指南。 开发版指南对应尚未发布的修改，请勿将其配置与这些历史示例混用。

1.1 - ToplingDB 快速上手

历史集成。 2025 年的文章介绍较早的接口，保留供参考。 候选替代方案见 ToplingDB 开发版指南。 开发版指南对应尚未发布的修改，请勿将其配置与这些历史示例混用。

前置条件

启动和配置

ToplingDB是对 RocksDB 的可配置、可观测扩展，支持通过 YAML 文件进行动态调优，并通过内置 Web Server 实现实时监控

修改 hugegraph.properties

1backend=rocksdb
2serializer=binary
3rocksdb.data_path=.
4rocksdb.wal_path=.
5# 配置文件路径
6# 出于安全性考虑, HG中仅允许 yaml 文件位于conf/graphs目录下
7rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
8# 是否开启Web Server
9rocksdb.open_http=true

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

1cd *hugegraph-${version}
2bin/init-store.sh

启动 server

1bin/start-hugegraph.sh
2Starting HugeGraphServer...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

提示的 url 与 rest-server.properties 中配置的 restserver.url 一致

Web Server 的监听端口在 YAML 文件中通过 http.listening_ports 字段进行配置

验证ToplingDB是否正常工作

前提: 确保核心参数配置正确

检查 hugegraph.properties 中包含:

1# 配置文件路径
2rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
3# 是否开启Web Server
4rocksdb.open_http=true

方式一: 访问Web监控界面

可视化访问Web监控页面，页面示例如下图所示:

image

通过终端验证:

1# 访问 http://localhost:2011 (端口号取决于 YAML 配置中的 listening_ports)
2curl http://localhost:2011 | grep topling

得到以下输出说明页面正常:

1<p><a href="https://topling.cn">Topling Inc.</a>This is <strong>Engine Inspector</strong>, for metrics, see <a href='javascript:grafana()'>Grafana</a>!</p>

方式二: 检查日志中的 ToplingDB 初始化信息

1tail -f logs/hugegraph-server.log | grep -i topling

类似输出说明存储引擎启动为ToplingDB:

12025-10-14 08:56:25 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
22025-10-14 08:56:25 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - Topling HTTP Server has been started according to the listening_ports specified in ./conf/graphs/rocksdb_plus.yaml

常见问题排查

问题 1: 启动失败，提示 YAML 格式错误

启动时有类似日志：

12025-10-15 01:55:50 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
221:1: (891B):ERROR: 
3sideplugin/rockside/3rdparty/rapidyaml/src/c4/yml/parse.cpp:3310: ERROR parsing yml: parse error: incorrect indentation?

解决方案:

  1. 检查 YAML 文件缩进是否正确（必须使用空格，不能使用 Tab）
  2. 验证 YAML 语法: python -c "import yaml; yaml.safe_load(open('conf/graphs/rocksdb_plus.yaml'))"
  3. 检查日志中的具体错误信息

问题 2: Web Server 端口冲突

启动时有类似日志：

12025-10-15 01:57:34 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
22025-10-15 01:57:34 [db-open-1] [ERROR] o.a.h.b.s.r.RocksDBStore - Failed to open RocksDB 'rocksdb-data/data/g'
3org.rocksdb.RocksDBException: rocksdb::Status rocksdb::SidePluginRepo::StartHttpServer(): null context when constructing CivetServer. Possible problem binding to port.
4  at org.rocksdb.SidePluginRepo.startHttpServer(Native Method) ~[rocksdbjni-8.10.2-20250804.074027-4.jar:?]

解决方案:

  1. 检查端口是否被占用: lsof -i :2011
  2. 修改 YAML 文件中的 listening_ports 配置
  3. 重启 HugeGraph Server

问题 3: 初始化数据库失败

类似输出说明无法获取数据库锁，可能缺乏写权限，也可能是被数据库被另外一个进程锁定:

1Caused by: org.rocksdb.RocksDBException: While lock file: rocksdb-data/data/m/LOCK: Resource temporarily unavailable
2        at org.rocksdb.SidePluginRepo.nativeOpenDBMultiCF(Native Method)
3        at org.rocksdb.SidePluginRepo.openDB(SidePluginRepo.java:22)

解决方案:

  1. 确认配置文件路径正确: rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
  2. 检查数据目录权限: 确保运行用户有读写权限
  3. 查看详细日志: bin/init-store.sh 2>&1 | tee init.log

相关文档

1.2 - ToplingDB YAML configuration file

历史集成。 2025 年的文章介绍较早的接口，保留供参考。 候选替代方案见 ToplingDB 开发版指南。 开发版指南对应尚未发布的修改，请勿将其配置与这些历史示例混用。

RocksDB 提供了丰富的参数配置，但大多数情况下，这些配置需要通过硬编码完成。

ToplingDB 在此基础上引入了 SidePlugin + YAML 的方式，使得配置更加模块化和可组合。

本文重点介绍 ToplingDB 扩展参数 的部分，帮助读者理解这些配置的意义。

术语说明

  • MemTable: LSM-Tree 在内存中的可写数据结构，接收新写入的数据
  • SST (Sorted String Table): Memtable 持久化到磁盘后生成的有序键值对文件
  • Flush: 将 MemTable 数据写入磁盘生成 SST 的过程
  • Compaction: 合并多个 SST 文件以优化存储和查询性能的过程
  • L0, L1, … L6: LSM-Tree 的不同层级，数字越大层级越深

0. HugeGraph 中提供的rocksdb_plus.yaml

下文只包括HugeGraph中所使用的配置参数，ToplingDB支持的完整配置请参考：SidePlugin Wiki

  1http: # Web Server 相关配置
  2  # normally parent path of db path
  3  document_root: /dev/shm/rocksdb_resource # 静态资源目录, HugeGraph中通过`preload_topling.sh`进行静态资源提取
  4  listening_ports: '127.0.0.1:2011' # Web Server监听端口，用于管理/监控 如端口被占用，请改为其他端口，例如 2012 或 2013
  5setenv: # 环境变量设置
  6  StrSimpleEnvNameNotOverwrite: StringValue
  7  IntSimpleEnvNameNotOverwrite: 16384
  8  OverwriteThisEnv:
  9    #comment: overwrite is default to false
 10    overwrite: true
 11    value: force overwrite this env by overwrite true
 12Cache: # Cache 相关配置
 13  lru_cache: # 定义一个 LRU 缓存实例
 14    class: LRUCache
 15    params: 
 16      capacity: 8G # 缓存容量 8GB
 17      num_shard_bits: -1 # 分片数量，-1 表示自动
 18      strict_capacity_limit: false
 19      high_pri_pool_ratio: 0.5
 20      use_adaptive_mutex: false
 21      metadata_charge_policy: kFullChargeCacheMetadata # 元数据也计入缓存容量
 22Statistics: # 数据采样配置
 23  stat:
 24    class: default
 25    params:
 26      discard_tickers: # 丢弃的统计计数器，减少开销
 27        - rocksdb.block.cache
 28        - rocksdb.block.cachecompressed
 29        - rocksdb.block
 30        - rocksdb.memtable.payload.bytes.at.flush
 31        - rocksdb.memtable.garbage.bytes.at.flush
 32        - rocksdb.txn
 33        - rocksdb.blobdb
 34        - rocksdb.row.cache
 35        - rocksdb.number.block
 36        - rocksdb.bloom.filter
 37        - rocksdb.persistent
 38        - rocksdb.sim.block.cache
 39      discard_histograms: # 丢弃的直方图统计项
 40        # comment: ....
 41        - rocksdb.blobdb
 42        - rocksdb.bytes.compressed
 43        - rocksdb.bytes.decompressed
 44        - rocksdb.num.index.and.filter.blocks.read.per.level
 45        - rocksdb.num.data.blocks.read.per.level
 46        - rocksdb.compression.times.nanos
 47        - rocksdb.decompression.times.nanos
 48        - rocksdb.read.block.get.micros
 49        - rocksdb.write.raw.block.micros
 50      # comment end of array
 51      #stats_level: kAll
 52      stats_level: kDisableAll  # 禁用所有统计
 53MemTableRepFactory: # 内存中 memtable 的实现
 54  cspp: # ToplingDB 独有的高并发内存结构
 55    class: cspp
 56    params:
 57      mem_cap: 16G # 预分配足够的单块内存地址空间，这些内存可以只是保留地址空间，但并未实际分配 对物理内存并无要求，只是为CSPP保留虚拟内存空间
 58      use_vm: false
 59      token_use_idle: true
 60      chunk_size: 16K # 内部分配粒度
 61      convert_to_sst: kFileMmap # 直接将 MemTable 转化为 SST，省去 Flush，可选值：{kDontConvert, kDumpMem, kFileMmap}
 62      sync_sst_file: false # convert_to_sst 为 kFileMmap 时，SST 转化完成后是否执行 fsync
 63  skiplist: # RocksDB 默认的跳表结构
 64    class: SkipList
 65    params:
 66      lookahead: 0
 67TableFactory:
 68  cspp_memtab_sst:
 69    class: CSPPMemTabTable # 与 cspp 配套的 TableFactory
 70    params: # empty params
 71  bb:
 72    class: BlockBasedTable # RocksDB 默认的块表
 73    params:
 74      checksum: kCRC32c
 75      block_size: 4K
 76      block_restart_interval: 16
 77      index_block_restart_interval: 1
 78      metadata_block_size: 4K
 79      enable_index_compression: true
 80      block_cache: "${lru_cache}" # 使用上面定义的 LRU 缓存
 81      block_cache_compressed:
 82      persistent_cache:
 83      filter_policy:
 84  dispatch:
 85    class: DispatcherTable
 86    params:
 87      default: bb # 默认使用 BlockBasedTable
 88      readers:
 89        BlockBasedTable: bb
 90        CSPPMemTabTable: cspp_memtab_sst
 91      level_writers: [ bb, bb, bb, bb, bb, bb ] # 支持自定义各层写入策略
 92CFOptions:
 93  default:
 94    max_write_buffer_number: 6
 95    memtable_factory: "${cspp}" # 引用上方定义的cspp，使用 cspp 作为 MemTable
 96    write_buffer_size: 128M
 97    # set target_file_size_base as small as 512K is to make many SST files,
 98    # thus key prefix cache can present efficiency
 99    target_file_size_base: 64M
100    target_file_size_multiplier: 1
101    table_factory: dispatch # 引用上方定义的 dispatch, 使用 DispatcherTable Class
102    max_bytes_for_level_base: 512M
103    max_bytes_for_level_multiplier: 10
104    level_compaction_dynamic_level_bytes: false
105    level0_slowdown_writes_trigger: 20
106    level0_stop_writes_trigger: 36
107    level0_file_num_compaction_trigger: 2
108    merge_operator: uint64add # support merge
109    level_compaction_dynamic_file_size: true
110    optimize_filters_for_hits: true
111    allow_merge_memtables: true
112    min_write_buffer_number_to_merge: 2
113    compression_per_level:
114      - kNoCompression
115      - kNoCompression
116      - kSnappyCompression
117      - kSnappyCompression
118      - kSnappyCompression
119      - kSnappyCompression
120      - kSnappyCompression
121DBOptions:
122  dbo:
123    create_if_missing: true
124    create_missing_column_families: false # this is important, must be false to hugegraph
125    max_background_compactions: -1
126    max_subcompactions: 4
127    max_level1_subcompactions: 0
128    inplace_update_support: false
129    WAL_size_limit_MB: 0
130    statistics: "${stat}"  # 使用上面定义的统计配置
131    max_manifest_file_size: 100M
132    max_background_jobs: 8 # 设置flush和compaction线程总数 建议设置为 (cpu核数 / 2)
133    compaction_readahead_size: 0
134    memtable_as_log_index: true # 此配置结合 convert_to_sst: kFileMmap 可实现[omit L0 Flush](https://github.com/topling/toplingdb/wiki/Omit-L0-Flush)

关键要点:

  • listening_ports: '127.0.0.1:2011' 指定Web Server监听端口为2011，并且仅允许本地访问
  • memtable_as_log_index: true 与 convert_to_sst: kFileMmap 结合实现omit L0 Flush
  • memtable_factory: "${cspp}" 指定了内存结构采用CSPP Memtable
  • table_factory: dispatch 指定了TableFactory使用YAML中自定义的DispatcherTable结构

1. 插件化配置与引用机制

  • YAML 插件化：配置文件以对象形式组织，每个对象可以单独定义并在其他地方引用。
  • 引用语法：通过 ${lru_cache}、${cspp} 等方式在不同段落复用对象。
  • DispatcherTable：允许在不同层级或场景下选择不同的 TableFactory。RocksDB 原生只能指定单一 TableFactory。

ToplingDB YAML 引用与复用图示:

image

这种机制使得配置更灵活，便于在复杂场景下组合不同组件。

2. 新的 MemTable 实现：CSPP

ToplingDB 提供了一个 RocksDB 原生没有的 MemTable 类型，通过以下参数配置：

mem_cap

mem_cap 是指在内存地址空间中，为 CSPP 预留的空间大小，这些内存可以只是保留地址空间，并未实际分配的。 mem_cap 真正占用的内存大小约为 write_buffer_size 。

mem_cap 设计背景

CSPP 的底层算法为了支持高并发写入，采用了预分配内存的策略。当预分配的内存被写满时，新的写入操作将无法继续。然而，RocksDB 本身缺乏一种机制，使得 memtable 能够主动反馈 ‘预分配内存已满，需要切换到新的 memtable’ 。 由于其函数调用链路复杂，难以通过重构来实现这一机制，因此 CSPP 只能通过参数设计来适配 RocksDB 的行为。

mem_cap 核心思路

ToplingDB 将 mem_cap 设置为远大于 write_buffer_size，从而避免 RocksDB 在向 Memtable 写入时过早触发“内存已满”的错误。 在 CSPP 初始化（New）时，会再次检查，如果发现 mem_cap 设置过小，则会自动调整为 2 * write_buffer_size，以确保写入过程的稳定性。

mem_cap 默认值为 2G，有效最大值为 16G。

  • 小型部署（< 16GB 内存）: 建议设置为系统内存的 20-30%
  • 中型部署（16-64GB 内存）: 建议设置为 8-16G
  • 大型部署（> 64GB 内存）: 建议设置为 16G

use_vm

在使用 malloc/posix_memalign 分配内存时，地址空间可能是已经实际分配的（位于堆空间中，已有对应的物理页面），而 CSPP 在分配时只需要获得保留的地址空间。 use_vm 选项为 true 时会强制使用 mmap 分配内存，从而保证分配的一定时是保留地址空间，但并不实际占用物理页面。 use_vm 默认值为 true。如果用户物理内存空间充足，建议关闭此选项，mmap 分配的虚拟内存空间在建立对物理地址的映射时会触发大量minor page fault，可能会影响性能。

convert_to_sst

convert_to_sst 支持以下三种枚举值:

  • kDontConvert: 禁用该功能，为默认值。使用传统的 Flush 流程，兼容性最好，适合对稳定性要求高的场景
  • kDumpMem: 转化时将 MemTable 的整块内存写入 SST 文件，避免 CPU 消耗，但未降低内存消耗
  • kFileMmap: 将 MemTable 内容 mmap 到文件，这是关键功能，同时降低 CPU 和内存消耗，可同时将 DBOptions.memtable_as_log_index 设为 true 从本质上消除 MemTable Flush

这些参数为数据写入路径提供了更多可调节空间，用户可按需选择。

更多设计细节请参考 ToplingDB 作者的撰写的相关博客：cspp-memtable, ToplingDB CSPP MemTable Design Essentials, CSPP Trie Design Analysis

3. TableFactory 扩展

  • CSPPMemTabTable：与 cspp MemTable 配套的 TableFactory。
  • DispatcherTable：支持为不同层级指定不同的 TableFactory，例如：
    • 默认使用 BlockBasedTable。
    • 特定层级可以使用 CSPPMemTabTable。

这类灵活性在 RocksDB 原生配置中并不存在。

4. 统计与观测控制

  • discard_tickers / discard_histograms：可以精确指定哪些统计项需要丢弃。
  • stats_level: kDisableAll：结合上述配置，可以灵活控制统计开销。

相比 RocksDB 的粗粒度控制，ToplingDB 提供了更细的调节方式。

5. DBOptions 新增参数

  • memtable_as_log_index: true：允许使用 MemTable 作为日志索引，加快恢复速度。

6. 安全注意事项

Web Server 安全配置:

  • Web Server 页面由ToplingDB提供，不包含权限认证功能
  • 默认设置 listening_ports: '127.0.0.1:2011' 仅限本地访问
  • 生产环境建议配置防火墙规则，仅允许内网访问
  • 如需禁用 Web Server，在 hugegraph.properties 中设置 rocksdb.open_http=false

共享内存安全:

  • document_root: /dev/shm/rocksdb_resource 使用共享内存目录
  • 多用户环境需要注意文件权限设置，避免未授权访问

7. 总结

ToplingDB 在 RocksDB 的基础上增加了以下能力：

  • 插件化配置与对象复用
  • 新的 MemTable 类型（cspp）及配套 TableFactory
  • DispatcherTable 支持多工厂调度
  • 内置 Web Server
  • 更灵活的统计与观测控制
  • 特殊 DBOptions（如 memtable_as_log_index）

这些扩展为用户提供了更多的可调节空间，尤其适合需要高写入性能和灵活运维的场景。

相关文档