这活儿是开春接的内部一个数据同步组件要从老平台迁到国产操作系统上组件里依赖了 Google 的嵌入式键值库 leveldb版本锁定在 1.22。目标系统是浪潮信息的 KeyarchOS圈内一般叫 KOS任务很明确——把这个库从源码编出来、把功能验证清楚、把性能跑出个底数最后输出一套能照着执行的落地文档。折腾了两周编译、依赖排查、功能用例、性能摸底全流程都走了一遍中间踩的坑比预想的多。这篇文章是完整复盘不写虚的全是实际操作过的步骤和结论。如果你正准备在 KOS 上适配 leveldb或者只是想把 leveldb 从 CentOS 平滑迁移到其他 CentOS 兼容发行版这篇可以直接当作业抄。1. 为什么选 leveldb 1.22KeyarchOS 生态适配里的一个务实决定1.1 KeyarchOS 是什么系统适配到底在适配什么KeyarchOS 是浪潮信息推出的企业级 Linux 服务器操作系统主打数据中心场景的长时间稳定运行兼容 CentOS 生态这意味着大部分在 CentOS 上能用的软件包和编译方式在 KOS 上大概率能直接复用。它同时支持 x86_64 和 ARM64 等主流国产芯片架构所以很多业务团队第一次接触国产系统的时候不会感觉太陌生。但“适配”这两个字在实际操作里比想象中要宽。不是说你yum install能装上、代码能make过就算完事而是要从编译链、运行库依赖、系统参数、性能表现、异常恢复这几个维度全部闭环。尤其是 leveldb 这种 C 写的底层存储组件它跟你系统的 glibc 版本、gcc 版本、可打开文件数上限、甚至是文件系统的挂载参数都有关系。任何一个环节不对轻则编译失败重则线上跑着跑着出现奇怪的数据错误。这次项目里选 KOS 而不是继续待在老的 CentOS 环境原因不复杂基础设施国产化替代是硬方向组件本身又没有不可替代性leveldb 是开源库在 KOS 上重新适配一次的成本完全可以接受。既然要适配干脆把整个验证流程做成标准动作以后再有别的组件要迁移流程可以直接复用。1.2 leveldb 的核心价值以及为什么锁定 1.22 而不是追新版leveldb 是 Google 开源的嵌入式键值存储库核心卖点就三个单进程内嵌不需要单独部署服务端业务代码里直接DB::Open就能用。基于 LSMLog-Structured Merge Tree架构写入路径是先写内存表MemTable和预写日志WAL再在后台把数据合并落盘成 SSTable 文件顺序写性能非常好。支持Put、Get、Delete、WriteBatch批量原子写、Snapshot一致性快照、Iterator有序遍历这些常用能力接口稳定文件格式跨平台兼容。版本选型这事我多说两句。leveldb 官方仓库现在的 master 分支和 1.22 相比主要是修 bug、加了一些新平台支持和构建层面的改动核心数据格式和 API 是稳定的。为什么这次坚持用 1.22-1 而不是直接拉最新版两个原因一是业务侧现有的 SDK 和封装层就是基于 1.22 的 API 写的换成新版意味着回归测试范围变大二是 1.22 这个版本在业界被大规模验证过TiKV、CockroachDB 这类知名系统早期都直接或间接用过它稳定性有共识。记住一个原则存储组件能不动就不动目标版本能用就锁死目标版本没必要为了“新”而引入不确定性。2. 适配第一步编译环境的差异排查与依赖补齐2.1 三种编译路径make、CMake 与静态库选择leveldb 1.22 提供了两套官方构建方式传统的 Makefile 和后来加入的 CMake。我建议两套都试一遍因为它们暴露问题的角度不一样。先看我实际执行的命令# 拉取源码并切到 1.22 标签 git clone https://github.com/google/leveldb.git cd leveldb git checkout 1.22 # 方式一传统 make启用 Snappy 压缩 make SNAPPY1 -j$(nproc) ls -l libleveldb.a # 方式二CMake关闭测试构建Release 模式 mkdir -p build cd build cmake -DCMAKE_BUILD_TYPERelease -DLEVELDB_BUILD_TESTSOFF .. make -j$(nproc) ls -l libleveldb.a两种方式最终都会产出静态库libleveldb.a。我的经验是交付给业务方的时候尽量用 CMake Release 构建因为 CMake 对编译选项的控制更干净也方便以后接交叉编译或者 ARM 架构而 make 方式适合快速验证环境有没有问题。这里有个关键点必须说明leveldb 1.22 的 CMake 配置默认会尝试下载 GoogleTest 来构建测试程序。如果你是在离线内网环境里工作这个步骤几乎必然失败因为它要去 GitHub 拉代码。所以我上面的命令里直接把LEVELDB_BUILD_TESTS关掉了。功能验证阶段我再用别的方式补测试后面第三节会说。关于静态库和动态库的选择我没有纠结直接用静态库。leveldb 本身是个小库静态链接能避免交付到不同机器上时出现libsnappy.so版本不匹配的问题。代价是最终二进制体积会大一点但对我们的业务场景来说完全可接受。2.2 最容易翻车的两个依赖snappy 与 gtest编译 leveldb 时最典型的报错是找不到snappy.h。Snappy 是 Google 自己的快速压缩库leveldb 默认用它做 SSTable 数据块压缩。在 KOS 上处理这个依赖的方式分两种第一种是直接用系统的包管理装开发头文件yum install -y snappy snappy-devel但要注意不同版本的 KOS 软件源里 snappy 包的版本可能不一样。如果你的环境是离线内网没法直接yum install那就需要把 snappy 的源码包也一起带进去先编 snappy 再编 leveldbgit clone https://github.com/google/snappy.git cd snappy mkdir -p build cd build cmake -DCMAKE_BUILD_TYPERelease -DSNAPPY_BUILD_TESTSOFF .. make -j$(nproc) make install ldconfig另一个坑是 gtest。刚才说了CMake 默认会去拉 GoogleTest离线环境必挂。传统的make check也需要 gtest 头文件。我的做法是运行功能验证的时候不依赖 leveldb 自带的单测而是自己写一个覆盖业务场景的验证程序这个程序不依赖 gtest只依赖 leveldb 的头文件和静态库。这样既绕开了网络限制又更贴近真实使用方式。这里还要提一个 KOS 环境特有的现象build_detect_platform脚本在某些国产 OS 上识别发行版标识会失败导致编译命令里没带对平台参数。遇到这种情况不用慌脚本只是做平台识别实在识别不出来它会走默认的 Linux 分支x86_64 架构下通常不会出大问题。真出问题了手动设置PORTlinux再编就能绕过去。3. 功能验证单元测试、自研用例与边界行为核对3.1 跑通自带测试套件的价值与前提编译通过只是第一步真正进入“适配验证”是从功能测试开始的。leveldb 源码自带一组很成熟的功能测试覆盖了数据读写、压缩、恢复、损坏检测、迭代器等关键路径。如果你的环境能联网、能把 gtest 拉下来强烈建议把make check完整跑一遍。我在带外环境里没法拉 gtest所以选择在另一台能联网的机器上先跑了单测确认 1.22 本身没有已知问题再到 KOS 上跑自研验证用例。这个顺序很重要先把“库本身正常”这个事实确认了后面在任何系统上出的问题才敢归因于系统环境而不是库本身。3.2 用业务场景驱动的小程序做功能验证自研验证程序不应该只是简单调一遍 API而要覆盖你实际业务会用到的所有路径。我当时的用例程序核心代码长这样#include leveldb/db.h #include leveldb/write_batch.h #include leveldb/slice.h #include iostream int main() { leveldb::DB* db nullptr; leveldb::Options options; options.create_if_missing true; options.compression leveldb::kSnappyCompression; leveldb::Status status leveldb::DB::Open(options, /data/testdb, db); if (!status.ok()) { std::cerr open failed: status.ToString() std::endl; return 1; } // 1. Put Get 基本读写 status db-Put(leveldb::WriteOptions(), company:1001, alice); std::string value; status db-Get(leveldb::ReadOptions(), company:1001, value); std::cout get result: value std::endl; // 2. WriteBatch 批量原子写入 leveldb::WriteBatch batch; batch.Put(company:1002, bob); batch.Put(company:1003, carol); batch.Delete(company:1001); status db-Write(leveldb::WriteOptions(), batch); // 3. Snapshot 一致性快照 const leveldb::Snapshot* snapshot db-GetSnapshot(); leveldb::ReadOptions read_options; read_options.snapshot snapshot; status db-Get(read_options, company:1002, value); db-ReleaseSnapshot(snapshot); // 4. Iterator 有序遍历 leveldb::Iterator* it db-NewIterator(leveldb::ReadOptions()); for (it-SeekToFirst(); it-Valid(); it-Next()) { std::cout it-key().ToString() - it-value().ToString() std::endl; } delete it; delete db; return 0; }编译命令记得要把 include 路径和库路径指对g -stdc11 -I/opt/leveldb/include \ -L/opt/leveldb/build -lleveldb -lsnappy \ -o kv_check kv_check.cpp跑完输出正常之后我建议按下面的清单逐项打勾每一项背后都是一个真实业务可能踩到的问题验证项验证方法预期结果基本读写Put 后 Get返回写入值覆盖写同一 key 重复 Put返回最新值删除Delete 后再 Get返回 NotFound批量原子性WriteBatch 混用 Put/Delete全部生效或全部不生效快照一致性先建 Snapshot再写新数据用旧快照读看到的是快照创建时的旧数据有序遍历SeekToFirst Nextkey 按字节序递增重启恢复写若干数据后 kill -9重新 Open数据不丢取决于 sync 配置下文说明目录锁两个进程同时 Open 同一个 DB第二个进程 Open 失败3.3 数据一致性重启恢复、Snapshot 与批量写入的真相这块我单独拿出来讲因为很多人对 leveldb 的数据安全性有误解。第一leveldb 的写入默认不是每条都刷盘。WriteOptions::sync为 false 时数据只是写到了操作系统页缓存里如果这时候机器掉电或者进程被kill -9最后几条写入可能丢失但库不会坏。反过来sync设为 true每条写入都等 fsync 落盘性能会掉一个量级但数据持久性有保障。真实业务里怎么选我的建议是关键业务数据开 sync能容忍秒级丢失的缓存类数据关 sync。第二WAL预写日志是 leveldb 崩溃恢复的命根子。只要.log文件在数据库重启后就能把没来得及合并到 SSTable 的数据恢复出来。所以运维上有一条红线不要随便删数据库目录下的.log文件不要把这个目录放在 tmpfs 这类掉电即失的内存文件系统上。第三WriteBatch的原子性是“要么全成功要么全失败”这是它和多次单独 Put 的本质区别。如果业务里有“一组 key 必须一起更新”的需求务必用 WriteBatch 而不是循环 Put否则中途失败就会出现数据不一致。我在验证程序里专门把批量的 Put 和 Delete 混在一起确认了最终状态和预期一致。4. 性能摸底在 KOS 上跑出一组可信的参考数据4.1 基准工具怎么搭怎么控制变量功能验证通过之后紧跟着的就是性能摸底。这一步的目的不是要跑出一个“全球最快”的数字而是确认两件事第一leveldb 在 KOS 上的性能没有出现数量级的异常退化第二拿到一组相对可信的基线数据作为后续调优的参照。我用的方式是写一个简单的压测程序而不是直接依赖 leveldb 自带的db_bench。原因有两个一是db_bench依赖 gflags环境里未必有二是自研程序能精确控制数据量、key 大小、value 大小、sync 开关、压缩开关更贴近真实业务模型。压测时一定要控制好的变量包括数据总量我压测时用 1GB 数据避免全部落在内存缓存里导致读性能虚高。key/value 大小固定 key 20 字节、value 1KB模拟日志类业务的典型负载。sync 开关开和不开分别测数字差距极大报告里必须写清楚状态。压缩开关分别测 Snappy 开和关的情况。线程数先单线程跑确认吞吐基线再决定要不要叠加并发。4.2 读写数据样例与参数解释我这台测试机的配置大概是这样x86_64 双路服务器32 核NVMe SSD128GB 内存KOS 默认内核参数未做任何额外调优。数据总量 1GBvalue 1KB单线程Snappy 压缩syncfalse测出来的量级如下场景结果量级说明顺序写新数据30~50 MB/s主要受 write buffer 刷盘节奏影响随机写新数据8~15 MB/sLSM 的随机写优势没完全发挥因为单线程覆盖写已有 key8~12 MB/s涉及 compaction 压力随机读数据总量 1GB8MB block cache2万~5万 ops/s受缓存命中率和磁盘随机读能力影响顺序读50~100 MB/s数据块压缩后磁盘读取量更小再次强调这组数字没有普适性它只能证明“KOS 上的 leveldb 功能正常、性能处于正常量级”。真正的性能值取决于你的数据分布、key 长度、value 大小、硬件配置和内核参数拿到结果之后要带着自己的数据重新标定。4.3 影响性能的三个 OS 级配置跑性能测试的过程中我发现有些性能问题根本不是 leveldb 的问题而是操作系统层面没配对。三个最容易踩的配置点第一是文件描述符上限。leveldb 的Options::max_open_files控制最多同时打开的 SSTable 文件数量默认值是 1000。但进程实际能打开的文件数受系统ulimit -n限制。如果ulimit -n是 1024leveldb 实际能用的文件数会被压得很低导致频繁打开关闭文件随机读性能明显下降。压测前先把上限调大ulimit -n 65535注意这个操作要放在启动压测进程的同一个 shell 会话里用 systemd 管理的服务还要改 service 文件里的LimitNOFILE。第二是文件系统挂载参数。数据库目录所在的文件系统建议以noatime方式挂载避免每次读取都更新 access time产生额外的写 IO。查看挂载参数用mount修改挂载参数在/etc/fstab里调整对应分区的 options重新挂载即可。第三是 CPU 频率模式。服务器如果在节能模式下CPU 频率会被压低单线程性能直接受影响。KOS 的服务器版本一般默认是 performance 模式但虚拟化和云主机场景有可能被改成 powersave。检查方法cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor如果是powersave建议在 BIOS 或系统层面切到performance再测否则压测数据会偏低而且不稳定。5. 落地过程中的坑从编译警告到线上配置5.1 环境相关坑位盘点按“现象、原因、解决方式”的方式把我实际遇到和同行反馈过的高频问题整理一下现象原因解决方式编译报snappy/snappy.h: No such file or directory缺 snappy 开发头文件yum install -y snappy-devel或源码编译 snappy 后 make installCMake 构建时卡在 FetchContent 下载 gtest离线环境无法访问 GitHub加-DLEVELDB_BUILD_TESTSOFF跳过测试构建编译通过运行时报libsnappy.so.1: cannot open shared object file动态库路径不在 ldconfig 搜索范围ldconfig刷新或用静态库链接用 systemd 启动服务时报打开文件数不足service 的 LimitNOFILE 未配置在 unit 文件里加LimitNOFILE65535两个进程同时 Open 同一个 DB第二个报 Lock 错误leveldb 通过 LOCK 文件实现单进程独占确认是否有多个进程/线程试图打开同一目录重启后数据看起来缺失syncfalse时掉电丢失或 tmpfs 上放数据库关键数据开 sync数据库目录放持久化磁盘这里我特别想强调一下动态库路径的问题。我们一开始用动态库交付结果业务方部署到另一台 KOS 机器上报找不到libsnappy.so.1。原因就是那台机器上 snappy 的运行时库版本更老或者压根没装。排查这种问题最快的命令ldd your_binary它会明确告诉你哪个库找不到、解析到了哪个路径。如果业务环境复杂最稳妥的方案就是我们在第二节说的交付时用静态库从根上消灭动态库依赖问题。5.2 leveldb 本身的使用坑位环境问题之外leveldb 本身也有几个使用上必须知道的坑第一个是大 key 与大 value 的代价。leveldb 的 key 是有序存储在 MemTable 和 SSTable 里的key 太长会直接影响每个数据块的记录条数、增加内存占用和比较开销。value 太大则会拖慢 compaction 和读放大。如果业务确实有大 value 需求建议拆出去存对象存储leveldb 里只留索引。第二个是write_buffer_size不是越大越好。默认值是 4MB调大以后写入吞吐会提升但会导致 MemTable 刷盘周期变长进而引发更严重的 compaction 放大效应——后台线程要反复合并更多层级的 SSTableSSD 的写放大系数会明显上升。我的调参经验是容量型写入场景可以从 16MB 起步测试线上读写混合场景保持默认或微调到 8MB 更稳。第三个是迭代器的失效问题。在用Iterator遍历的过程中如果对同一个 key 做了Delete迭代器行为会变得不可预期最稳妥的做法是遍历时只读不改。需要边遍历边修改的业务先把要修改的 key 收集到内存里遍历结束再统一写。第四个是备份的姿势。leveldb 没有内置热备份命令最安全的备份方式是在程序里先DB::GetSnapshot()然后基于快照把数据库目录里的文件整体拷贝一份。直接对运行中的数据库目录做文件拷贝可能正好赶上 compaction 导致文件替换拷贝出来一份不一致的数据。5.3 进程内还是进程外部署形态的选择适配完成之后通常会面临一个架构选择leveldb 要继续以库的形式嵌进业务进程还是单独包装成服务让多个进程共享我的建议很直接如果业务是单进程模型直接用嵌入式形态这是 leveldb 最舒服的使用方式性能最好、运维最简单。只有当多个独立进程需要共享读写同一个库且无法通过改架构规避的时候才值得在外面套一层服务包装比如封装成 gRPC 接口。但你要想清楚这么做等于自己写一个存储服务要做好并发控制、故障恢复、连接管理成本不低。我见过不少团队一开始为了“以后可以水平扩展”就把 leveldb 包装成服务实际跑起来发现瓶颈全在自己的包装层上性能和稳定性还不如单进程内嵌。适配的终极目标不是造一个分布式数据库而是在满足业务需求的前提下尽量简单。6. 做完适配后回头看几点值得固化的经验一轮完整做下来我最大的体会是适配工作里 70% 的精力不是花在“让代码跑起来”而是花在“让代码在这个特定系统上稳定跑下去”。编译不过的问题都是显性的查一查、装个依赖就解决了真正花时间的是那些隐性问题比如动态库路径、文件描述符上限、落盘策略、部署形态这些在通用发行版上不会暴露换个系统环境反而全出来了。有几件事我现在已经固化成了标准动作建议你也这么做把适配过程中所有用到的依赖包、版本号、源码包全部归档到一个本地软件源里避免下次换台机器又从头开始找包。写一份构建脚本而不是手动执行命令脚本里把SNAPPY1、LEVELDB_BUILD_TESTSOFF这些参数写死让后来的人不需要理解背景也能一键复现。验证用例保留下来作为每次系统升级或内核参数调整后的回归测试集。以后 KOS 出了新版本、或者你想换 ARM 架构机器先跑一遍这套用例心里就有底了。性能基线记成文档标注清楚当时的硬件配置、数据量、参数选项后面任何调优都能拿它做对比而不是凭感觉说“好像是变快了”。最后分享一个遇到过的真实教训我们一开始图省事leveldb 的数据库目录直接放在了根分区结果一次磁盘告警把整个系统 IO 拖垮连带着数据库响应超时。后来把数据目录独立挂到了单独的 SSD 分区上又针对这个分区单独做了 noatime 和 IO 调度优化才真正消停。适配不只是让库能在系统上运行让你的数据待在合适的位置上同样是适配的一部分。