docs: add toplingdb related docs & enable blog module#420
docs: add toplingdb related docs & enable blog module#420imbajin merged 22 commits intoapache:masterfrom
Conversation
* doc:fix the url of node status checking * doc: reformat json string --------- Co-authored-by: imbajin <jin@apache.org>
Co-authored-by: imbajin <jin@apache.org>
[pull] master from apache:master
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
PR #420 代码审查意见
感谢提交这个高质量的文档 PR!以下是一些必须修复和强烈建议改进的地方,以提升用户体验和文档完整性。 🔴 必须修复事项1. ToplingDB Quick Start 文档需要补充前置条件文件: 问题: 缺少环境准备说明,新用户可能不清楚需要什么前置条件。 建议: 在文档开头添加前置条件章节: ### 前置条件
- HugeGraph 版本: >= 1.x.x (请明确最低版本要求)
- Java 版本: >= 11
- 确保已下载 ToplingDB 相关依赖
- 操作系统: Linux/macOS (请明确支持的操作系统)2. Quick Start 文档需要添加验证步骤文件: 问题: 启动后缺少验证 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 配置文档需要添加关键配置项的使用场景说明文件: 问题: 关键配置项缺少使用场景说明,用户不知道何时选择哪个选项。 建议: 在配置说明中补充使用场景对比,例如: #### convert_to_sst 配置说明
- `kDontConvert`: 使用传统的 Flush 流程,兼容性最好,适合对稳定性要求高的场景
- `kDumpMem`: 将 MemTable 数据导出后生成 SST,适合内存受限的环境
- `kFileMmap`: 直接将 MemTable 转化为 SST(省去 Flush),性能最优,适合写入密集型场景
#### mem_cap 配置建议
- 小型部署(< 16GB 内存): 建议设置为系统内存的 20-30%
- 中型部署(16-64GB 内存): 建议设置为 8-16GB
- 大型部署(> 64GB 内存): 建议设置为 16-32GB4. YAML 配置文档需要添加安全性提示文件: 问题: Web Server 端口暴露和共享内存使用缺少安全风险提示。 建议: 在 HTTP 配置章节添加安全提示: ### 安全注意事项
**Web Server 安全配置**:
- `listening_ports: '2011'` 默认监听所有网络接口
- 生产环境建议配置防火墙规则,仅允许内网访问
- 如需禁用 Web Server,在 `hugegraph.properties` 中设置 `rocksdb.open_http=false`
**共享内存安全**:
- `document_root: /dev/shm/rocksdb_resource` 使用共享内存目录
- 多用户环境需要注意文件权限设置,避免未授权访问🟡 强烈建议改进5. 统一术语定义,提升文档可读性文件: 建议: 在文档开头添加术语表或在术语第一次出现时提供简单解释: ## 术语说明
- **MemTable**: 内存中的可写数据结构,接收新写入的数据
- **SST (Sorted String Table)**: 持久化的有序键值对文件
- **Flush**: 将 MemTable 数据写入磁盘生成 SST 的过程
- **Compaction**: 合并多个 SST 文件以优化存储和查询性能的过程
- **L0, L1, ... L6**: LSM-Tree 的不同层级,数字越大层级越深6. 添加故障排查章节文件: 建议: 在文档末尾添加常见问题排查: ### 常见问题排查
#### 问题 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 YAML 配置详解](./ToplingDB%20Configuration%20YAML.md) - 了解配置文件中各参数的含义
- [HugeGraph 配置说明](/docs/config/config-option/) - HugeGraph 核心配置参考
- [ToplingDB GitHub 仓库](https://github.com/topling/toplingdb) - 官方文档和最新更新在 ### 相关文档
- [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. 补充可视化内容建议: 添加架构图和截图,提升理解效率:
9. 改进 Blog 首页引导文案文件: 当前内容: "欢迎阅读 HugeGraph 博客" 建议改进: ---
title: "Blog"
linkTitle: "Blog"
menu:
main:
weight: 30
---
欢迎阅读 HugeGraph 博客!
这里汇集了 HugeGraph 生态的技术文章、最佳实践和社区动态:
- **HugeGraph (OLTP)**: 图数据库核心功能、性能优化、存储引擎等
- **HugeGraph-AI**: AI 与图计算结合的应用案例
- **HugeGraph Computing (OLAP)**: 大规模图计算和分析实践
探索更多内容,提升您的图数据库使用体验!📝 其他建议
总结总体来说,这是一个非常优秀的文档 PR!内容专业且详尽。完成上述改进后,用户体验将大幅提升。 特别感谢添加 ToplingDB 相关文档,这将帮助更多用户了解和使用这个强大的存储引擎!期待看到更新 🎉 |
content/cn/docs/contribution-guidelines/hugegraph-server-idea-setup.md
Outdated
Show resolved
Hide resolved
content/en/docs/contribution-guidelines/hugegraph-server-idea-setup.md
Outdated
Show resolved
Hide resolved
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.
* 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
Purpose of the PR