RocksDB安装与配置 #

一、环境要求 #

1.1 硬件要求 #

资源 最低要求 推荐配置
CPU 2核 4核以上
内存 4GB 16GB以上
磁盘 10GB SSD存储

1.2 软件依赖 #

依赖 版本要求 用途
CMake 3.5+ 构建系统
GCC/G++ 7.0+ C++编译器
gflags 任意 命令行参数
snappy 任意 压缩库
zlib 任意 压缩库
lz4 任意 压缩库
zstd 任意 压缩库

二、Linux安装 #

2.1 Ubuntu/Debian #

bash
# 安装依赖
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    libgflags-dev \
    libsnappy-dev \
    zlib1g-dev \
    libbz2-dev \
    liblz4-dev \
    libzstd-dev

# 克隆源码
git clone https://github.com/facebook/rocksdb.git
cd rocksdb

# 编译
mkdir build && cd build
cmake ..
make -j$(nproc)

# 安装(可选)
sudo make install

2.2 CentOS/RHEL #

bash
# 安装依赖
sudo yum groupinstall -y "Development Tools"
sudo yum install -y \
    cmake \
    gflags-devel \
    snappy-devel \
    zlib-devel \
    bzip2-devel \
    lz4-devel \
    libzstd-devel

# 克隆源码
git clone https://github.com/facebook/rocksdb.git
cd rocksdb

# 编译
mkdir build && cd build
cmake ..
make -j$(nproc)

# 安装(可选)
sudo make install

2.3 编译选项说明 #

bash
# 基础编译
cmake ..

# 指定安装路径
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..

# 启用/禁用压缩库
cmake -DWITH_SNAPPY=ON \
      -DWITH_ZLIB=ON \
      -DWITH_LZ4=ON \
      -DWITH_ZSTD=ON \
      -DWITH_BZ2=OFF ..

# 编译静态库
cmake -DBUILD_SHARED_LIBS=OFF ..

# 编译调试版本
cmake -DCMAKE_BUILD_TYPE=Debug ..

# 编译发布版本
cmake -DCMAKE_BUILD_TYPE=Release ..

三、macOS安装 #

3.1 使用Homebrew #

bash
# 安装依赖
brew install cmake gflags snappy lz4 zstd

# 克隆源码
git clone https://github.com/facebook/rocksdb.git
cd rocksdb

# 编译
mkdir build && cd build
cmake ..
make -j$(sysctl -n hw.ncpu)

# 安装(可选)
sudo make install

3.2 直接安装预编译版本 #

bash
# 使用Homebrew安装
brew install rocksdb

# 验证安装
brew info rocksdb

3.3 macOS特定配置 #

bash
# 解决编译警告
export CXXFLAGS="-Wno-error=deprecated-declarations"

# 针对Apple Silicon优化
cmake -DCMAKE_OSX_ARCHITECTURES=arm64 ..

四、Windows安装 #

4.1 使用vcpkg #

powershell
# 安装vcpkg
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# 安装RocksDB
.\vcpkg install rocksdb:x64-windows

# 集成到Visual Studio
.\vcpkg integrate install

4.2 手动编译 #

powershell
# 安装依赖
# 1. 安装Visual Studio 2019或更高版本
# 2. 安装CMake
# 3. 下载依赖库(snappy, zlib, lz4, zstd)

# 克隆源码
git clone https://github.com/facebook/rocksdb.git
cd rocksdb

# 创建构建目录
mkdir build
cd build

# 生成VS项目
cmake -G "Visual Studio 16 2019" -A x64 ..

# 编译
cmake --build . --config Release

4.3 Visual Studio配置 #

cpp
// 项目属性配置
// 1. 包含目录
C:\vcpkg\installed\x64-windows\include

// 2. 库目录
C:\vcpkg\installed\x64-windows\lib

// 3. 链接库
rocksdb.lib
snappy.lib
zlib.lib
lz4.lib
zstd.lib

五、Docker环境 #

5.1 使用官方镜像 #

bash
# 拉取镜像
docker pull rocksdb/rocksdb:latest

# 运行容器
docker run -it rocksdb/rocksdb:latest bash

5.2 自定义Dockerfile #

dockerfile
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    libgflags-dev \
    libsnappy-dev \
    zlib1g-dev \
    libbz2-dev \
    liblz4-dev \
    libzstd-dev \
    git

WORKDIR /app
RUN git clone https://github.com/facebook/rocksdb.git
RUN cd rocksdb && mkdir build && cd build && \
    cmake .. && make -j$(nproc)

WORKDIR /app/rocksdb

六、验证安装 #

6.1 检查编译结果 #

bash
# 检查静态库
ls -la build/librocksdb.a

# 检查动态库
ls -la build/librocksdb.so*

# 检查头文件
ls -la include/rocksdb/

6.2 编译测试程序 #

cpp
// test_rocksdb.cpp
#include <rocksdb/db.h>
#include <iostream>

int main() {
    rocksdb::DB* db;
    rocksdb::Options options;
    options.create_if_missing = true;
    
    rocksdb::Status status = rocksdb::DB::Open(options, "/tmp/testdb", &db);
    if (!status.ok()) {
        std::cerr << "Error: " << status.ToString() << std::endl;
        return 1;
    }
    
    std::cout << "RocksDB initialized successfully!" << std::endl;
    
    delete db;
    return 0;
}
bash
# 编译
g++ -std=c++17 test_rocksdb.cpp \
    -I./include \
    -L./build \
    -lrocksdb \
    -lpthread \
    -ldl \
    -o test_rocksdb

# 运行
./test_rocksdb

6.3 运行基准测试 #

bash
# 进入构建目录
cd build

# 运行db_bench
./db_bench --benchmarks=fillseq,readseq,readrandom \
           --num=1000000 \
           --value_size=1024

# 常用测试命令
./db_bench --benchmarks=fillseq       # 顺序写入
./db_bench --benchmarks=fillrandom    # 随机写入
./db_bench --benchmarks=readseq       # 顺序读取
./db_bench --benchmarks=readrandom    # 随机读取
./db_bench --benchmarks=seekrandom    # 随机查找

七、配置选项 #

7.1 基础配置 #

cpp
#include <rocksdb/options.h>

rocksdb::Options options;

// 数据库不存在时自动创建
options.create_if_missing = true;

// 数据库已存在时报错
options.error_if_exists = false;

// 创建列族时如果不存在则创建
options.create_missing_column_families = true;

// 并行度设置
options.max_background_jobs = 4;
options.max_background_compactions = 4;
options.max_background_flushes = 2;

// 日志级别
options.info_log_level = rocksdb::InfoLogLevel::INFO_LEVEL;

7.2 写入配置 #

cpp
rocksdb::WriteOptions write_options;

// 同步写入(保证持久性)
write_options.sync = false;

// 禁用WAL
write_options.disableWAL = false;

// 写入超时(微秒)
write_options.timeout_hint_us = 0;

// 低优先级写入
write_options.low_pri = false;

7.3 读取配置 #

cpp
rocksdb::ReadOptions read_options;

// 是否验证校验和
read_options.verify_checksums = true;

// 是否填充块缓存
read_options.fill_cache = true;

// 快照读取
read_options.snapshot = nullptr;

// 读取超时(微秒)
read_options.timeout_us = 0;

// 异步IO
read_options.async_io = false;

7.4 刷新配置 #

cpp
rocksdb::FlushOptions flush_options;

// 等待刷新完成
flush_options.wait = true;

// 允许写入暂停
flush_options.allow_write_stall = false;

八、环境变量 #

8.1 常用环境变量 #

bash
# 设置库路径
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# 设置包含路径
export CPLUS_INCLUDE_PATH=/usr/local/include:$CPLUS_INCLUDE_PATH

# 设置数据目录
export ROCKSDB_DATA_DIR=/data/rocksdb

# 设置日志目录
export ROCKSDB_LOG_DIR=/var/log/rocksdb

8.2 编译时环境变量 #

bash
# 设置编译器
export CC=gcc
export CXX=g++

# 设置编译选项
export CFLAGS="-O3 -march=native"
export CXXFLAGS="-O3 -march=native"

# 设置链接选项
export LDFLAGS="-L/usr/local/lib"

九、常见问题 #

9.1 编译错误 #

问题:找不到gflags

bash
# 解决方案
sudo apt-get install libgflags-dev
# 或者
cmake -DWITH_GFLAGS=OFF ..

问题:snappy未找到

bash
# 解决方案
sudo apt-get install libsnappy-dev
# 或者
cmake -DWITH_SNAPPY=OFF ..

9.2 运行时错误 #

问题:找不到共享库

bash
# 错误信息
error while loading shared libraries: librocksdb.so

# 解决方案
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
# 或者
sudo ldconfig

问题:权限不足

bash
# 错误信息
IO error: Permission denied

# 解决方案
chmod 755 /data/rocksdb
# 或者使用当前用户目录

9.3 性能问题 #

问题:写入速度慢

cpp
// 解决方案:调整配置
options.write_buffer_size = 64 * 1024 * 1024;  // 64MB
options.max_write_buffer_number = 4;
options.min_write_buffer_number_to_merge = 2;

问题:内存占用高

cpp
// 解决方案:限制缓存大小
options.block_cache = rocksdb::NewLRUCache(
    512 * 1024 * 1024  // 512MB
);

十、总结 #

安装配置要点:

步骤 说明
环境准备 安装编译器和依赖库
源码编译 cmake + make
验证安装 编译测试程序
配置优化 根据场景调整参数

下一步,让我们了解RocksDB的基础架构!

最后更新:2026-03-27