scan4all 依赖的 pogreb 存储引擎演进全解从 Changelog 看嵌入式 KV 存储的架构升级【免费下载链接】scan4allOfficial repository vuls Scan: 15000PoCs; 23 kinds of application password crack; 7000Web fingerprints; 146 protocols and 90000 rules Port scanning; Fuzz, HW, awesome BugBounty( ͡° ͜ʖ ͡°)...项目地址: https://gitcode.com/GitHub_Trending/sca/scan4all导读pogreb 是一个用纯 Go 编写的嵌入式 key-value 存储引擎专为读多写少的场景设计被集成在 scan4all 项目依赖的projectdiscovery/hmap磁盘存储实现中见 pogreb_all.go。本文以 CHANGELOG.md 记录的 v0.7 → v0.10.1 演进为主线结合本仓库 vendor 目录下的源码实现逐版本解读存储引擎的核心架构升级写入预写日志WAL与崩溃恢复、内存映射文件访问、后台压缩回收磁盘空间等机制。读完本文你将能理解 pogreb 各版本之间的技术差异知道如何通过Options控制其文件系统与同步/压缩行为并掌握其底层datalog段式日志、index哈希索引、compaction的协作原理。一、版本演进总览一份 Changelog 背后的存储引擎发展史pogreb 在 CHANGELOG.md 中记录了从 v0.72019-03-23到 v0.10.12021-05-01共 9 个版本的变更。梳理这 9 个版本可以看到三条清晰的演进主线版本日期主题v0.72019-03-23新增 Windows 支持freelist空闲链表性能优化v0.82019-03-30非 Windows 平台写入性能约提升 2 倍v0.8.12019-06-30修复访问已关闭 DB 的 panic打开无效数据库返回错误v0.8.22019-09-04修复可能导致数据损坏的竞态条件v0.8.32019-11-03修复 Windows 上映射文件时的 slice 越界错误v0.9.02020-03-08用预写日志WAL取代无结构数据文件崩溃自动恢复可选后台压缩修复小 key/value 的磁盘空间开销v0.9.12020-04-03提升 Go 1.14 兼容性移除 unsafe 用法v0.9.22021-01-01WAL 不再依赖墙钟时间避免压缩与恢复期间的潜在竞态修复恢复时写入多余删除记录v0.10.02021-02-09可通过Options.FileSystem禁用内存映射默认实现改为fs.OSMMapv0.10.12021-05-01改进错误报告修复 32 位系统编译问题其中 v0.9.0 是架构上的分水岭——它把存储布局从无结构的键值数据文件整体切换为预写日志 段文件模型后续版本的绝大多数修复v0.9.1、v0.9.2、v0.10.1都围绕这套新架构展开。二、v0.9.0 架构分水岭预写日志、自动恢复与后台压缩v0.9.0 是 changelog 中变更最重的一个版本包含三项核心能力Replace the unstructured data file for storing key-value pairs with a write-ahead log.In the event of a crash or a power loss the database is automatically recovered.Optional background compaction allows reclaiming disk space occupied by overwritten or deleted keys.2.1 以预写日志WAL取代无结构数据文件在 v0.9.0 之前pogreb 将键值对直接写入一个无结构的单一大数据文件v0.9.0 之后写入路径改为先追加到预写日志。这一设计在当前 vendored 源码中完整保留datalog.go 中的datalog类型即write-ahead log的实现它维护一个segments [maxSegments]*segment数组maxSegments math.MaxInt16所有写操作put/del都通过writeRecord追加到当前段curSeg并在段写满curSeg.meta.Full或超出maxSegmentSize时调用swapSegment()创建新段段文件命名形如id-sequenceID如0-1parseSegmentName从文件名解析出段 ID 与单调递增的序列号sequenceID这正是 v0.9.2不依赖墙钟时间的基础见下文段由segment结构封装segment.go读取时通过seg.Slice(off, end)从文件中按偏移切片返回键值数据。这里的关键设计是数据先顺序追加到 WAL 段文件哈希索引index仅保存 key 的哈希、段 ID 与偏移量slot。因此随机读只需一次哈希查找 一次定位切片而写入则是追加式的顺序 I/O。2.2 崩溃与断电后的自动恢复v0.9.0 引入的自动恢复机制在当前源码中体现在 db.go 的Open流程里if acquiredExistingLock { // Lock file already existed, but the process managed to acquire it. // It means the database wasnt closed properly. // Start recovery process. if err : backupNonsegmentFiles(opts.FileSystem); err ! nil { return nil, err } }即Open时若发现锁文件已存在但能成功获取说明上次进程未正常关闭会先备份非段文件随后调用db.recover()实现在 recovery.go扫描 WAL 段重放未落索引的写入记录。配合dbMetadb.go中保存的HashSeed可以保证恢复后的哈希索引与段内记录完全一致。2.3 后台压缩回收被覆盖/删除的 key 占用空间pogreb 的Put是追加语义覆盖写并不原地更新而是追加新记录并更新索引 slot删除del则追加一条删除记录并累加DeletedBytes见 datalog.go。因此旧版本的数据会残留占用磁盘需要压缩回收。压缩逻辑实现在 compaction.goCompact()通过atomic.CompareAndSwapInt32保证同一时刻只有一个压缩任务在跑pickForCompaction()从旧到新遍历段选出满足两个条件的段参与压缩段大小不低于compactionMinSegmentSize默认32 20即 32 MiB且碎片率DeletedBytes / size不低于compactionMinFragmentation默认 0.5promoteRecord()是压缩的核心逐个读取源段记录检查索引是否仍指向该记录哈希、偏移、段 ID 三者一致。若索引已指向更新的记录key 已被覆盖或删除则该记录被安全丢弃ReclaimedRecords否则将该记录重新写入当前段并更新索引 slot压缩完成后removeSegment删除源段文件及其 meta 文件CompactionResult汇总CompactedSegments、ReclaimedRecords、ReclaimedBytes三个统计指标。值得注意的是pickForCompaction中的一个细节如果段内含删除记录那么所有比它更旧的段都必须一并压缩——因为删除记录只有在更旧段中没有对应 put 记录时才能被安全丢弃这一逻辑正是 v0.9.2 修复方向的前置设计。三、v0.10.0 存储后端抽象内存映射可开关默认fs.OSMMapChangedThe default file system implementation is changed tofs.OSMMap.AddedMemory-mapped file access can now be disabled by settingOptions.FileSystemtofs.OS.v0.10.0 将用哪种方式访问文件从硬编码抽离为可插拔的fs.FileSystem接口。该接口定义于 fs/fs.go包含OpenFile、Stat、Remove、Rename、ReadDir、CreateLockFile等文件系统操作以及关键的File.Slice(start, end)——按区间读取文件内容并返回字节切片。在 vendored 源码中可以看到该接口的多种实现fs/os_mmap.go默认实现fs.OSMMap基于syscall.Mmap将段文件映射进进程地址空间Slice直接返回映射区间的切片零拷贝读取这也是 pogreb 随机读性能的核心来源fs/os.go普通文件系统实现fs.OS通过ReadAt完成区间读取不依赖内存映射fs/mem.go内存文件系统用于测试场景。两种文件系统的切换点位于 options.go 的copyWithDefaultsif opts.FileSystem nil { opts.FileSystem fs.OSMMap } opts.FileSystem fs.Sub(opts.FileSystem, path)默认使用内存映射当Options.FileSystem被显式设为fs.OS时即禁用 mmap。这一选项的实战意义在于在内存映射不可用或受限的环境如某些容器、特殊文件系统、32 位地址空间紧张的场景中可以退化为普通的文件读写。四、v0.9.2 一致性修复WAL 摆脱墙钟时间依赖ChangedWrite-ahead log doesnt rely on wall-clock time anymore. It prevents potential race conditions during compaction and recovery.FixedFix recovery writing extra delete records.在旧实现中段文件的排序或标识依赖系统墙钟时间戳在压缩与恢复并发交错、或系统时钟被调整时可能产生竞态导致恢复顺序错误。v0.9.2 之后段标识改为源码中可见的单调递增 sequenceIDdatalog.go 中nextWritableSegmentID每次dl.maxSequenceID段文件因此可以依据序列号严格排序// segmentsBySequenceID returns segments ordered from oldest to newest. sort.SliceStable(segments, func(i, j int) bool { return segments[i].sequenceID segments[j].sequenceID })由于排序不再依赖可变的系统时间压缩pickForCompaction按序列号从旧到新选择段与恢复按序列号重放记录天然得到确定的全局顺序从而消除时钟相关的竞态窗口。同时该版本还修复了恢复过程中会额外写入删除记录extra delete records的缺陷。五、稳定性与平台兼容性修复从 panic 到 32 位编译Changelog 中其余版本大多属于正确性、健壮性与平台兼容性修复逐一说明如下v0.8.1修复访问已关闭数据库closed database时的 panic打开无效数据库时改为返回错误而非静默失败。对应源码中 errors.go 定义了一系列哨兵错误调用方如 hmap 封装层可以据此做错误判断。v0.8.2修复可能造成数据损坏的竞态条件。pogreb 的DB内部以sync.RWMutex协调多读单写db.go这一修复属于对该并发模型的加固。v0.8.3修复 Windows 平台映射文件时出现 slice bounds out of range 的问题。这与 mmap 在 Windows 上按页对齐/文件大小变化的处理有关。v0.9.1移除unsafe用法提升与 Go 1.14 的兼容性。v0.10.1改进错误报告错误上下文更可读修复 32 位操作系统下的编译问题——从当前仓库的构建约束也可看到佐证pogreb_all.go 顶部有//go:build !((arm || arm64) windows)即 hmap 在 Windows 的 arm/arm64 上会跳过 pogreb 磁盘后端。性能侧的两个版本v0.8 宣布非 Windows 平台写入性能约提升 2 倍v0.7 优化了 freelist空闲段/槽位链表的性能并首次加入 Windows 支持由 mattn 贡献。这类性能声明来自上游发布说明本文仅如实转述 changelog 原意不进行基准复测。六、在 scan4all 中的实际落点hmap 磁盘存储后端pogreb 在本仓库中并非直接使用而是作为github.com/projectdiscovery/hmapgo.mod 中声明github.com/akrylysov/pogreb v0.10.1 // indirect见 go.mod的磁盘存储后端被间接引入。其调用关系非常典型可作为学习 pogreb API 的完整范例在 pogreb_all.go 中hmap 用pogreb.Open(path, nil)打开库并围绕它封装出带 TTL 语义的键值接口Put前先把过期时间与分隔符拼进 value再调用pdb.db.Put(k, v)Get时调用pdb.db.Get([]byte(k))解析出过期时间若已过期则调用pdb.db.Delete惰性清理并返回ErrNotFoundGC直接映射到 pogreb 的压缩能力_, err : pdb.db.Compact()Scan使用pdb.db.Items()返回的ItemIterator逐条遍历以pogreb.ErrIterationDone判断遍历结束。这也呼应了 pogreb 面向读多写少、低频批量插入的设计定位见 README.md 的 Key characteristicshmap 这类缓存/去重存储恰好是这种工作负载的典型场景。七、结语从 changelog 读出的存储引擎设计要点回顾 pogreb 的版本史可以提炼出嵌入式 KV 存储设计的几个要点写入路径要顺序化用追加式预写日志换随机写用哈希索引 偏移量定位换随机读这是 v0.9.0 确立并沿用至今的架构崩溃恢复靠单调序列而非系统时钟段标识使用单调递增的 sequenceID保证压缩、恢复在任何时钟异常下都有确定的顺序空间回收必须与索引协同压缩不是简单删文件而是要逐条比对索引指向区分仍存活记录与可丢弃记录并对含删除记录的段做整段联动压缩存储后端要可插拔fs.FileSystem抽象让 mmapfs.OSMMap与普通 I/Ofs.OS可自由切换兼顾性能与可移植性。对于在 scan4all 项目中排查 hmap 相关存储问题、或需要自行评估嵌入式 KV 存储方案的读者CHANGELOG.md 是一份浓缩的演进地图配合 db.go、datalog.go、compaction.go、fs/fs.go 四份核心源码即可在代码层面完整还原本 changelog 中的每一项变更动机与实现细节。【免费下载链接】scan4allOfficial repository vuls Scan: 15000PoCs; 23 kinds of application password crack; 7000Web fingerprints; 146 protocols and 90000 rules Port scanning; Fuzz, HW, awesome BugBounty( ͡° ͜ʖ ͡°)...项目地址: https://gitcode.com/GitHub_Trending/sca/scan4all创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考