Skip to content

docs: add toplingdb related docs & enable blog module#420

Merged
imbajin merged 22 commits intoapache:masterfrom
syslucas:rocksdb-plus
Oct 20, 2025
Merged

docs: add toplingdb related docs & enable blog module#420
imbajin merged 22 commits intoapache:masterfrom
syslucas:rocksdb-plus

Conversation

@syslucas
Copy link
Copy Markdown
Contributor

@syslucas syslucas commented Oct 8, 2025

Purpose of the PR

  • Add ToplingDB related documents
  • Enable Blog module
file_1759908298206_129

@dosubot dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. enhancement New feature or request labels Oct 8, 2025
@VGalaxies VGalaxies requested a review from Copilot October 8, 2025 07:45
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds comprehensive documentation for RocksDB Plus integration in HugeGraph and enables the blog module. RocksDB Plus (ToplingDB) is an enhanced, configurable version of RocksDB that supports YAML-based configuration and includes a built-in web server for monitoring.

  • Added RocksDB Plus specifications and documentation for both English and Chinese versions
  • Enabled the blog module in the documentation site with a blog post about RocksDB Plus YAML configuration
  • Updated quickstart guides and configuration documentation to include RocksDB Plus setup instructions

Reviewed Changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
content/en/docs/specs/**/*.md Added English specification documents for RocksDB Plus requirements, design, and tasks
content/cn/docs/specs/**/*.md Added Chinese specification documents for RocksDB Plus requirements, design, and tasks
content/*/docs/quickstart/hugegraph/hugegraph-server.md Updated quickstart guides to include RocksDB Plus configuration and renumbered sections
content/*/docs/contribution-guidelines/hugegraph-server-idea-setup.md Added RocksDB Plus development setup instructions with LD_PRELOAD configuration
content/*/docs/config/config-option.md Added documentation for new RocksDB Plus configuration options
content/*/blog/ Enabled blog module and added RocksDB Plus YAML configuration blog post
config.toml Enabled blog module in site navigation
Comments suppressed due to low confidence (1)

content/cn/docs/specs/HugeGraph-Server/RocksDB Plus/design.md:1

  • The line contains duplicate content with redundant configuration and comments. The 'memtable_as_log_index: true' is repeated twice with different comment formatting.
---

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@syslucas syslucas changed the title docs: add rocksdb plus related docs & enable blog module docs: add toplingdb related docs & enable blog module Oct 9, 2025
@imbajin imbajin requested a review from Copilot October 13, 2025 04:27
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

Copilot reviewed 35 out of 37 changed files in this pull request and generated 3 comments.


Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

imbajin

This comment was marked as outdated.

@imbajin
Copy link
Copy Markdown
Member

imbajin commented Oct 13, 2025

PR #420 代码审查意见

注:之前的评论因格式问题出现乱码,请忽略。以下是正确的审查意见。


感谢提交这个高质量的文档 PR!以下是一些必须修复和强烈建议改进的地方,以提升用户体验和文档完整性。

🔴 必须修复事项

1. ToplingDB Quick Start 文档需要补充前置条件

文件: content/cn/blog/hugegraph/ToplingDB/ToplingDB Quick Start.md

问题: 缺少环境准备说明,新用户可能不清楚需要什么前置条件。

建议: 在文档开头添加前置条件章节:

### 前置条件

- HugeGraph 版本: >= 1.x.x (请明确最低版本要求)
- Java 版本: >= 11
- 确保已下载 ToplingDB 相关依赖
- 操作系统: Linux/macOS (请明确支持的操作系统)

2. Quick Start 文档需要添加验证步骤

文件: content/cn/blog/hugegraph/ToplingDB/ToplingDB Quick Start.md

问题: 启动后缺少验证 ToplingDB 是否正常工作的步骤。

建议: 在启动 server 部分后添加验证章节:

### 验证 ToplingDB 是否正常工作

1. 访问 Web 监控界面
   \`\`\`bash
   # 访问 http://localhost:2011 (端口号取决于 YAML 配置中的 listening_ports)
   curl http://localhost:2011
   \`\`\`

2. 检查日志中的 ToplingDB 初始化信息
   \`\`\`bash
   tail -f logs/hugegraph-server.log | grep -i topling
   \`\`\`

3. 确认数据目录下生成了相关文件
   \`\`\`bash
   ls -lh <rocksdb.data_path>
   \`\`\`

3. YAML 配置文档需要添加关键配置项的使用场景说明

文件: content/cn/blog/hugegraph/ToplingDB/ToplingDB Configuration YAML.md

问题: 关键配置项缺少使用场景说明,用户不知道何时选择哪个选项。

建议: 在配置说明中补充使用场景对比,例如:

#### convert_to_sst 配置说明

- `kDontConvert`: 使用传统的 Flush 流程,兼容性最好,适合对稳定性要求高的场景
- `kDumpMem`: 将 MemTable 数据导出后生成 SST,适合内存受限的环境
- `kFileMmap`: 直接将 MemTable 转化为 SST(省去 Flush),性能最优,适合写入密集型场景

#### mem_cap 配置建议

- 小型部署(< 16GB 内存): 建议设置为系统内存的 20-30%
- 中型部署(16-64GB 内存): 建议设置为 8-16GB
- 大型部署(> 64GB 内存): 建议设置为 16-32GB

4. YAML 配置文档需要添加安全性提示

文件: content/cn/blog/hugegraph/ToplingDB/ToplingDB Configuration YAML.md

问题: Web Server 端口暴露和共享内存使用缺少安全风险提示。

建议: 在 HTTP 配置章节添加安全提示:

### 安全注意事项

**Web Server 安全配置**:
- `listening_ports: '2011'` 默认监听所有网络接口
- 生产环境建议配置防火墙规则,仅允许内网访问
- 如需禁用 Web Server,在 `hugegraph.properties` 中设置 `rocksdb.open_http=false`

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

🟡 强烈建议改进

5. 统一术语定义,提升文档可读性

文件: content/cn/blog/hugegraph/ToplingDB/ToplingDB Configuration YAML.md

建议: 在文档开头添加术语表或在术语第一次出现时提供简单解释:

## 术语说明

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

6. 添加故障排查章节

文件: content/cn/blog/hugegraph/ToplingDB/ToplingDB Quick Start.md

建议: 在文档末尾添加常见问题排查:

### 常见问题排查

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

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

#### 问题 2: Web Server 端口冲突

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

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

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

7. 添加文档间的关联链接

建议: 在文档中添加相互引用,增强上下文完整性。

ToplingDB Quick Start.md 中添加:

### 相关文档

- [ToplingDB YAML 配置详解](./ToplingDB%20Configuration%20YAML.md) - 了解配置文件中各参数的含义
- [HugeGraph 配置说明](/docs/config/config-option/) - HugeGraph 核心配置参考
- [ToplingDB GitHub 仓库](https://github.com/topling/toplingdb) - 官方文档和最新更新

ToplingDB Configuration YAML.md 中添加:

### 相关文档

- [ToplingDB 快速开始](./ToplingDB%20Quick%20Start.md) - 如何在 HugeGraph 中启用 ToplingDB
- [RocksDB 官方配置文档](https://github.com/facebook/rocksdb/wiki/Setup-Options-and-Basic-Tuning) - 了解基础配置项
- [SidePlugin Wiki](https://github.com/topling/sideplugin-wiki-en/wiki) - ToplingDB 完整配置参考

8. 补充可视化内容

建议: 添加架构图和截图,提升理解效率:

  1. ToplingDB vs RocksDB 架构对比图: 展示 CSPP MemTable、DispatcherTable 等核心差异
  2. Web Server 监控界面截图: 让用户知道访问 http://localhost:2011 后能看到什么
  3. 配置引用关系图: 用图示说明 ${lru_cache}${cspp} 等引用机制

9. 改进 Blog 首页引导文案

文件: content/cn/blog/_index.md

当前内容: "欢迎阅读 HugeGraph 博客"

建议改进:

---
title: "Blog"
linkTitle: "Blog"
menu:
  main:
    weight: 30
---

欢迎阅读 HugeGraph 博客!

这里汇集了 HugeGraph 生态的技术文章、最佳实践和社区动态:

- **HugeGraph (OLTP)**: 图数据库核心功能、性能优化、存储引擎等
- **HugeGraph-AI**: AI 与图计算结合的应用案例
- **HugeGraph Computing (OLAP)**: 大规模图计算和分析实践

探索更多内容,提升您的图数据库使用体验!

📝 其他建议

  • 文件命名: ToplingDB Quick Start.mdToplingDB Configuration YAML.md 文件名包含空格,建议改为 toplingdb-quick-start.mdtoplingdb-configuration-yaml.md,更符合 Web URL 规范
  • 一致性检查: content/cn/blog/hugegraph-ai/_index.md 文件末尾缺少换行符,建议补充

总结

总体来说,这是一个非常优秀的文档 PR!内容专业且详尽。完成上述改进后,用户体验将大幅提升。

特别感谢添加 ToplingDB 相关文档,这将帮助更多用户了解和使用这个强大的存储引擎!期待看到更新 🎉

Merged ToplingDB with RocksDB as a high-performance alternative in both Chinese and English quickstart guides. Updated section order and references, and removed redundant ToplingDB configuration details to streamline documentation.
@imbajin imbajin merged commit c7c457a into apache:master Oct 20, 2025
1 check passed
github-actions bot pushed a commit that referenced this pull request Oct 20, 2025
* doc: update desc of open_http

* doc: update blog docs

* chore: fix error link

* chore: fix typo

* doc: add background explanation for mem_cap

* Apply suggestions from code review

* Update ToplingDB section in HugeGraph server docs

Merged ToplingDB with RocksDB as a high-performance alternative in both Chinese and English quickstart guides. Updated section order and references, and removed redundant ToplingDB configuration details to streamline documentation.

---------

Co-authored-by: imbajin <jin@apache.org> c7c457a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants