svn/SugarDB

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

base

docs: 添加持久化运维手册及文档更新

PreviewCode viewBlame

GitHub Release

什么是SugarDB
功能特性
使用方法（嵌入式）
使用方法（客户端-服务器）
客户端
性能基准测试
持久化、备份与恢复
支持的命令
1. ACL
2. 管理员
3. 连接
4. 通用
5. 哈希
6. 列表
7. 发布订阅
8. 集合
9. 有序集合
10. 字符串
11. 位图
12. HyperLogLog
13. 流
14. 事务
15. JSON
16. 地理位置
17. 向量
18. 时序数据
19. 搜索

什么是SugarDB？

SugarDB是一个高度可配置的、分布式的内存数据存储和缓存系统，使用Go语言实现。它可以作为Go库导入，也可以作为独立服务运行。

SugarDB旨在提供丰富的数据结构和函数来操作内存中的数据。这些数据结构包括但不限于：列表、集合、有序集合、哈希表等，更多功能即将推出。

SugarDB提供了持久化层以提高可靠性。可以使用仅追加文件（AOF）和快照来将数据持久化到磁盘，以便在意外关机时进行恢复。默认配置会启用 hybrid persistence（RDB 基线 + 增量 AOF 压缩链），减少 AOF 膨胀；服务端默认启动时优先尝试恢复 AOF / hybrid 持久化工件，若未发现 AOF 工件则回退到快照恢复路径。

复制是SugarDB的核心功能，使用RAFT算法实现，允许您创建容错的SugarDB节点集群以提高可靠性。如果您不需要复制集群，您可以始终在独立模式下运行SugarDB，拥有功能完备的单节点。

SugarDB不仅旨在成为一个服务器，还要能够导入到现有项目中，以增强这些项目的SugarDB功能，这种能力一直在不断开发和改进中。

功能特性

SugarDB提供的功能包括：

支持TLS和mTLS，支持多个服务器和客户端根证书
使用RAFT算法支持复制集群
用于用户身份验证和授权的ACL层
分布式发布/订阅功能
集合、有序集合、哈希表、列表等数据结构
Stream 高价值能力（XADD / XLEN / XRANGE / XREVRANGE / XREAD / XGROUP / XREADGROUP / XACK / XACKDEL / XPENDING / XDEL / XDELEX / XTRIM / XCLAIM / XAUTOCLAIM / XSETID / XINFO）
事务增强能力（MULTI / EXEC / DISCARD / WATCH / UNWATCH，含 AOF 原子事务包裹）
Bitmap 能力（GETBIT / SETBIT / BITCOUNT / BITOP / BITPOS）
HyperLogLog 能力（PFADD / PFCOUNT / PFMERGE）
JSON 文档能力（当前分支覆盖 README 所列命令）
地理位置能力（当前分支覆盖 README 所列命令）
支持 RDB 快照、AOF 与 hybrid persistence，含自动 compact、后台 BGSAVE / BGREWRITEAOF 与启动恢复回退策略
键过期策略
通过共享对象文件扩展命令
通过嵌入式API扩展命令
通过Lua模块扩展命令
通过JavaScript模块扩展命令
支持多数据库进行键命名空间管理

Redis 8.x 兼容矩阵（当前分支）

当前代码已实现并通过测试的核心模块：

ACL
Admin
Bitmap
Connection
GEO
Generic
Hash
HyperLogLog
JSON
List
Pub/Sub
Set
Sorted Set
Stream（第二梯队增强）
String
TimeSeries
Search
Transactions（第二梯队）
Vector 我们正在努力为SugarDB添加更多功能以使其更强大。路线图中的功能包括：

分片
完整 Streams 收口（更深 XTRIM / ACKED / consumer lag / cluster 语义）
完整 Transactions 收口（cluster / raft 一致性、更多 no-multi 语义、blocking 细节）
改进的可观测性
图数据库
机器学习集成
高级分析功能
向量数据库
全文搜索
向量数据库深化

使用方法（嵌入式）

安装SugarDB：go get github.com/echovault/sugardb/sugardb

以下是将SugarDB作为嵌入式库使用的示例。您可以使用符合人体工程学的API访问所有SugarDB命令。


func main() {
  server, err := sugardb.NewSugarDB()
  if err != nil {
    log.Fatal(err)
  }

  _, _, _ = server.Set("key", "Hello, SugarDB!", sugardb.SETOptions{})

  v, _ := server.Get("key")
  fmt.Println(v) // Hello, SugarDB!

  // （可选）：在此SugarDB实例上监听TCP连接
  server.Start()
}

嵌入式SugarDB实例仍然可以成为集群的一部分，从API触发的更改将在整个集群中保持一致。

使用方法（客户端-服务器）

Homebrew

通过homebrew安装，运行：

brew tap echovault/sugardb
brew install echovault/echovault/sugardb

安装完成后，您可以使用以下命令运行服务器： sugardb --bind-addr=localhost --data-dir="path/to/persistence/directory"

Docker

docker pull echovault/sugardb

完整的标签列表可以在这里找到。

容器注册表

docker pull ghcr.io/echovault/sugardb

完整的标签列表可以在这里找到。

二进制文件

您可以通过点击发布标签并下载适合您系统的二进制文件来下载二进制文件。

从源码编译

快速编译

编译当前架构的可执行文件：


make build

多架构编译

我们提供了完整的多架构编译支持，使用优化的编译参数：

编译单个架构：


make build-linux-amd64     # Linux x86_64
make build-linux-arm64     # Linux ARM64
make build-linux-arm       # Linux ARM
make build-windows-amd64   # Windows x86_64
make build-windows-arm64   # Windows ARM64
make build-darwin-amd64    # macOS x86_64
make build-darwin-arm64    # macOS ARM64 (Apple Silicon)
make build-freebsd-amd64   # FreeBSD x86_64

批量编译：


make build-common          # 编译常用平台 (Linux, Windows, macOS)
make build-all             # 编译所有支持的架构

编译信息和工具：


make info                  # 显示构建信息（版本、时间、提交等）
make clean                 # 清理构建文件
make help                  # 显示所有可用的编译选项

编译特性

优化编译参数：使用 -trimpath -ldflags "-s -w -extldflags '-static'" 进行编译优化
版本信息注入：自动注入Git版本、构建时间和提交哈希
静态链接：生成无依赖的可执行文件，便于部署
输出管理：所有编译文件统一输出到 bin/ 目录
文件大小优化：移除调试信息和符号表，显著减小文件大小

编译后的文件将保存在项目的 bin/ 目录中，文件名格式为 sugardb-{操作系统}-{架构}。

客户端

SugarDB使用RESP协议，这使其与现有的Redis客户端兼容。

性能基准测试

要与Redis比较命令性能，可以运行基准测试：

make benchmark

前提条件：

brew install redis 运行Redis服务器和基准测试脚本
brew tap echovault/sugardb & brew install echovault/echovault/sugardb 运行SugarDB客户端-服务器

基准测试脚本选项：

make benchmark use_local_server=true 在您的本地SugarDB客户端-服务器上运行
make benchmark commands=ping,set,get... 在指定命令上运行基准测试脚本

持久化、备份与恢复

当前分支在 standalone 模式 下的持久化链路已经不是“只有快照”这么简单，而是三层协同：

Snapshot / RDB：最新快照位于 DATA_DIR/snapshots/<unix-millis>/dump.rdb
AOF 增量日志：增量命令日志位于 DATA_DIR/aof/log.aof
Hybrid Persistence（默认开启）：使用 DATA_DIR/aof/preamble.rdb 作为 RDB 基线，再叠加 DATA_DIR/aof/log.aof

当前恢复顺序与源码行为一致：

若 --restore-aof=true 且存在 AOF / hybrid 产物（如 aof/preamble.rdb、aof/log.aof），优先从 AOF / hybrid 恢复；
若没有可用 AOF 产物，且 --restore-snapshot=true，则回退到最新 snapshot；
CLI / server 模式下，--restore-aof 与 --restore-snapshot 当前默认都为 true。

常用持久化命令：

SAVE：同步生成 / 刷新 RDB 快照
BGSAVE [SCHEDULE]：后台生成 / 刷新 RDB 快照
LASTSAVE：查看最近一次 snapshot 时间戳（毫秒）
REWRITEAOF：同步重写 append-only / hybrid 基线
BGREWRITEAOF：后台重写 append-only / hybrid 基线

推荐的 standalone 备份集：

至少保留 snapshots/manifest.bin 与最新 snapshots/<ts>/dump.rdb
若启用了默认 hybrid / AOF，额外保留整个 aof/ 目录（尤其是 preamble.rdb 与 log.aof）
若使用 ACL / 外挂模块 / 配置回写，也应同时保留 ACL 配置文件、模块文件与运行配置文件

推荐的 冷备份流程：

停止实例，或确保写入静默；
需要最新快照时，先执行 BGSAVE；
需要最新 hybrid 基线时，再执行 BGREWRITEAOF；
复制 DATA_DIR/snapshots/ 与 DATA_DIR/aof/；
恢复时保持相同目录结构，并指定同一个 --data-dir。

详细文档：

Snapshot / RDB：/docs/persistence/snapshot
AOF / Hybrid：/docs/persistence/append-only
Backup / Restore：/docs/persistence/backup-and-restore
Persistence 运维手册：/docs/persistence/operations-runbook

支持的命令

说明：以下命令清单中，ACL / Admin / Connection / Generic / Hash / List / PubSub / Set / Sorted Set / String / Stream / Transactions / JSON / GEO / TimeSeries / Search / Vector 为当前分支已实现能力。