基于 brpc+MinIO 的分布式文件存储架构设计与实战

关键设计亮点

• 参数化配置：通过 gflags 定义所有可配置项（端口、依赖地址、缓存大小等），支持启动时动态调整。
• 失败快速反馈：核心依赖（Redis/MinIO）初始化失败时直接抛异常，终止服务启动，避免无效运行。
• Builder 模式：通过 FileServerBuilder 封装服务构建细节，解耦初始化逻辑，提升代码可读性。

核心依赖封装

MinIOClient：对象存储核心封装

MinIOClient 是对 MinIO C++ SDK 的二次封装，屏蔽底层细节，提供简洁的文件操作接口，适配服务端存储需求：

class MinIOClient {
public:
    using ptr = std::shared_ptr<MinIOClient>;
    
    // 构造函数：解析 endpoint、验证 Bucket 存在性
    MinIOClient(const std::string& endpoint, const std::string& access_key,
                const std::string& secret_key, const std::string& bucket_name);
    
    // 基础操作：上传/下载/删除
    bool upload(const std::string& object_key, const std::string& data);
    bool download(const std::string& object_key, std::string& out_data);
    bool remove(const std::string& object_key);
    
    // 分块上传相关：上传分块、合并分块
    bool upload_chunk(const std::string& file_id, uint32_t chunk_index, const std::string& data);
    bool merge_chunks(const std::string& file_id, uint32_t total_chunks, const std::string& target_object_key);
};

核心逻辑解析

1. endpoint 解析：自动识别 http/https 协议，提取主机名和端口，兼容 MinIO 默认端口（9000）和自定义端口。
2. Bucket 校验：初始化时检查 Bucket 是否存在，避免后续操作失败。
3. 分块处理：
   • 分块存储路径规范：multipart/{file_id}/{chunk_index}，便于管理和清理。
   • 合并分块时先下载所有分块→合并→上传完整文件→清理临时分块，保证数据一致性。
4. 错误处理：捕获 SDK 异常和网络异常，返回布尔值并打印详细日志，便于问题排查。

Redis 与分块元数据管理

Redis 主要用于存储分块上传的元数据（文件大小、分块数、已上传分块索引等），配合 MultipartManager 实现分块状态管理：

class MultipartManager {
public:
    using ptr = std::shared_ptr<MultipartManager>;
    
    // 初始化分块上传：生成 file_id，存储元数据到 Redis（24 小时过期）
    std::string init_upload(const std::string& file_name, uint64_t file_size, uint32_t chunk_size = 5MB);
    
    // 标记分块上传完成
    bool mark_chunk_uploaded(const std::string& file_id, uint32_t chunk_index);
    
    // 检查所有分块是否上传完成
    bool is_all_chunks_uploaded(const std::string& file_id);
    
    // 清理元数据（合并完成后调用）
    bool clean_up(const std::string& file_id);
};

设计亮点

• 元数据序列化：使用 JSON 序列化 MultipartMeta 结构体，便于 Redis 存储和读取。
• LRU 缓存：内存缓存热点元数据，减少 Redis 访问次数，提升响应速度。
• 过期清理：Redis 键设置 24 小时过期时间，避免未完成的分块上传占用存储空间。

LRUCache：热点数据缓存

基于双向链表 + 哈希表实现线程安全的 LRU 缓存，用于缓存文件元信息和 file_id→MinIO 路径 映射，提升访问性能：

template <typename Key, typename Value>
class LRUCache {
public:
    void put(const Key& key, const Value& value);       // 插入/更新缓存
    std::optional<Value> get(const Key& key);          // 获取缓存，未命中返回 nullopt
    void erase(const Key& key);                        // 删除缓存项
private:
    std::list<std::pair<Key, Value>> _cache_list;      // 双向链表：头部=最近使用，尾部=最久未使用
    std::unordered_map<Key, typename std::list<std::pair<Key, Value>>::iterator> _cache_map; // 哈希表：快速查找
    std::mutex _mutex;                                 // 线程安全锁
};

核心特性

• 线程安全：所有操作加互斥锁，支持多线程 RPC 服务并发访问。
• 淘汰策略：超出最大容量时，淘汰最久未使用的节点，避免内存溢出。
• 可选回调：支持设置节点淘汰时的回调函数（如清理关联资源）。

RPC 服务实现（FileServiceImpl）

FileServiceImpl 实现了定义的 RPC 接口，核心逻辑围绕「文件上传 / 下载」和「分块上传管理」展开，每个接口都包含参数校验→核心业务→结果响应的标准化流程：

单文件上传核心逻辑

void PutSingleFile(google::protobuf::RpcController *controller,
                   const ::zrt::PutSingleFileReq *request,
                   ::zrt::PutSingleFileRsp *response,
                   ::google::protobuf::Closure *done) {
    brpc::ClosureGuard rpc_guard(done); // 自动释放 RPC 资源，避免内存泄漏
    response->set_request_id(request->request_id());
    
    // 1. 参数校验（文件名、文件大小）
    if (request->file_data().file_name().empty() || request->file_data().file_size() == 0) {
        response->set_success(false);
        response->set_errmsg("文件名或文件大小非法");
        return;
    }
    
    // 2. 生成唯一 file_id（基于 UUID）
    std::string fid = uuid();
    
    // 3. 定义 MinIO 存储路径（规范：files/single/{file_id}/{filename}）
    std::string object_key = "files/single/" + fid + "/" + request->file_data().file_name();
    
    // 4. 上传到 MinIO
    bool upload_ok = _minio->upload(object_key, request->file_data().file_content());
    if (!upload_ok) {
        response->set_success(false);
        response->set_errmsg("文件上传到 MinIO 失败");
        return;
    }
    
    // 5. 缓存元数据（file_id→元信息、file_id→MinIO 路径）
    FileMessageInfo file_info;
    file_info.set_file_id(fid);
    file_info.set_file_name(request->file_data().file_name());
    file_info.set_file_size(request->file_data().file_size());
    _file_meta_cache->put(fid, file_info);
    _file_id_to_object_key->put(fid, object_key);
    
    // 6. 响应结果
    response->set_success(true);
    *response->mutable_file_info() = file_info;
}

分块上传完整流程

分块上传分为三个阶段，通过三个接口协同实现：

1. InitMultipartUpload：初始化上传，生成 file_id 和分块配置（分块大小、总块数）。
2. UploadPart：上传单个分块，校验分块索引合法性，更新上传状态。
3. CompleteMultipartUpload：校验所有分块是否上传完成，合并分块为完整文件。

核心亮点：

• 参数校验：严格校验 file_id、分块索引、分块数据，避免非法请求。
• 原子性保证：分块合并失败时，清理已上传的临时分块，避免垃圾数据。
• 状态一致性：通过 Redis 持久化分块状态，服务重启后可恢复上传进度。

服务构建器（FileServerBuilder）

采用 Builder 设计模式，封装服务构建的复杂流程，将「依赖设置→RPC 服务器构建→服务注册」解耦，简化服务初始化：

class FileServerBuilder {
public:
    void set_minio_params(...) { /* 设置 MinIO 配置 */ }
    void set_redis_client(...) { /* 设置 Redis 客户端，初始化分块管理器和缓存 */ }
    void make_rpc_server(...) { /* 构建 brpc 服务器，注册 FileServiceImpl */ }
    void make_reg_object(...) { /* 注册服务到 etcd */ }
    FileServer::ptr build() { /* 构建最终的 FileServer 实例 */ }
};

设计优势

• 隐藏构建细节：调用者无需关注 RPC 服务器配置、服务注册流程，只需设置核心依赖。
• 依赖校验：build() 前检查核心依赖是否初始化，避免空指针异常。
• 扩展性强：新增依赖（如监控模块）时，只需在 Builder 中添加对应的 set_xxx 方法，不影响原有逻辑。

客户端测试实现

客户端基于 gtest 框架，实现全接口测试，覆盖单文件、多文件、分块上传的完整流程，确保服务可用性：

测试架构

┌─────────────────────────────────────┐
│ 测试用例设计（按功能分组）          │
│ ┌─────────────┐ ┌─────────────┐    │
│ │ 单文件测试  │ │ 多文件测试  │    │
│ │ - 上传      │ │ - 批量上传  │    │
│ │ - 下载      │ │ - 批量下载  │    │
│ └─────────────┘ └─────────────┘    │
│ ┌─────────────┐ ┌─────────────┐    │
│ │ 分块上传测试│ │ 兼容性测试  │    │
│ │ - 初始化    │ │ - 异常参数  │    │
│ │ - 上传分块  │ │ - 服务降级  │    │
│ │ - 合并文件  │ │ - 并发访问  │    │
│ │ - 下载文件  │ └────────────┘    │
│ └─────────────┘                    │
└─────────────────────────────────────┘

核心测试用例解析

分块上传测试（核心流程）

// 1. 初始化分块上传
TEST(multipart_test, init_multipart_upload) {
    std::string test_file_content;
    ASSERT_TRUE(zrt::readFile("./Makefile", test_file_content)) << "读取测试文件失败";
    
    zrt::FileService_Stub stub(channel.get());
    zrt::InitMultipartUploadReq req;
    zrt::InitMultipartUploadRsp rsp;
    brpc::Controller cntl;
    
    req.set_request_id(zrt::uuid());
    req.set_file_name("Makefile_multipart");
    req.set_file_size(test_file_content.size());
    
    stub.InitMultipartUpload(&cntl, &req, &rsp, nullptr);
    
    // 校验结果
    ASSERT_FALSE(cntl.Failed());
    ASSERT_TRUE(rsp.success());
    ASSERT_FALSE(rsp.file_id().empty());
    
    // 保存参数供后续测试
    multipart_file_id = rsp.file_id();
    multipart_total_chunks = rsp.total_chunks();
    multipart_chunk_size = rsp.chunk_size();
}

// 2. 上传所有分块
TEST(multipart_test, upload_part) {
    if (multipart_file_id.empty()) GTEST_SKIP() << "分块初始化未成功";
    
    zrt::FileService_Stub stub(channel.get());
    for (uint32_t i = 0; i < multipart_total_chunks; ++i) {
        zrt::UploadPartReq req;
        zrt::UploadPartRsp rsp;
        brpc::Controller cntl;
        
        // 截取当前分块数据
        uint32_t start = i * multipart_chunk_size;
        uint32_t end = std::min((i+1)*multipart_chunk_size, (uint32_t)multipart_original_content.size());
        std::string chunk_data = multipart_original_content.substr(start, end - start);
        
        req.set_request_id(zrt::uuid());
        req.set_file_id(multipart_file_id);
        req.set_chunk_index(i);
        req.set_chunk_data(chunk_data);
        
        stub.UploadPart(&cntl, &req, &rsp, nullptr);
        ASSERT_FALSE(cntl.Failed());
        ASSERT_TRUE(rsp.success());
    }
}

// 3. 合并分块并下载验证
TEST(multipart_test, complete_multipart_upload) {
    // 合并分块逻辑...
}

TEST(get_test, multipart_file) {
    // 下载合并后的文件，校验内容一致性...
}

测试设计亮点

• 依赖前置用例：通过全局变量传递测试参数（如 file_id），确保测试流程顺序执行。
• 结果校验全面：不仅校验接口返回的 success 状态，还校验文件大小、内容一致性、元数据正确性。
• 异常处理：跳过前置用例失败的测试，避免无效报错。
• 可视化验证：下载文件保存到本地（如 multipart_merged_download_Makefile），支持手动校验。

测试执行流程

1. 初始化日志和服务发现（通过 etcd 获取服务端地址）。
2. 按「单文件→多文件→分块上传」顺序执行测试用例。
3. 每个上传用例执行后，立即执行对应的下载用例，验证数据一致性。
4. 测试完成后，自动清理测试文件（可选）。

核心亮点与最佳实践

代码质量保障

1. 严格的参数校验：所有接口都对输入参数（文件名、文件大小、分块索引等）进行合法性校验，避免非法请求。
2. 资源自动释放：使用 brpc::ClosureGuard、智能指针（shared_ptr）自动释放资源，避免内存泄漏。
3. 完善的错误日志：每个关键步骤都打印日志（INFO/ERROR），包含 request_id、file_id 等上下文，便于问题追踪。
4. 线程安全：LRU 缓存、Redis 操作均加锁，支持高并发访问。

性能优化

1. 缓存分层：内存 LRU 缓存热点元数据，Redis 持久化冷数据，平衡性能和可靠性。
2. 多线程 RPC：brpc 服务器支持配置 IO 线程数（建议≥CPU 核心数），提升并发处理能力。
3. 分块上传：大文件分块上传，避免单次请求数据量过大导致的超时或内存占用过高。

可扩展性设计

1. 依赖注入：通过 Builder 模式注入 MinIO、Redis 等依赖，便于替换为其他存储方案（如 S3、MySQL）。
2. 接口标准化：RPC 接口定义清晰，支持客户端多语言接入（C++、Java、Python 等）。
3. 服务注册发现：基于 etcd 实现服务动态扩容，客户端自动发现新服务节点，无需修改配置。

扩展方向

1. 权限控制：新增用户认证模块，支持基于文件的读写权限控制。
2. 文件加密：上传时对文件内容加密，下载时解密，保障数据安全。
3. 断点续传优化：支持暂停 / 恢复上传，客户端无需重新上传已完成的分块。
4. 监控告警：集成 Prometheus+Grafana，监控服务 QPS、响应时间、MinIO 存储使用率等指标。
5. 生命周期管理：新增文件过期清理机制，自动删除长期未访问的文件，释放存储空间。

总结

本文实现的分布式文件存储服务，基于成熟的开源组件（brpc、MinIO、Redis、etcd），兼顾了可靠性、高性能、可扩展性，支持单文件、多文件、分块上传等多种场景，可直接用于企业级分布式系统。

核心设计思路是「分层解耦 + 依赖注入 + 标准化流程」：通过分层设计隔离不同职责，依赖注入提升灵活性，标准化流程（如服务初始化、接口实现）保证代码质量。开发者可基于本文代码，根据实际业务需求进行扩展，快速搭建符合自身场景的文件存储解决方案。