# DFStore

**Repository Path**: jimshi204207/dfstore

## Basic Information

- **Project Name**: DFStore
- **Description**: 一款高性能、高可用、支持秒传和多副本机制的分布式文件存储服务，基于Netty构建高性能通信层，采用Master/Storage节点架构，支持本地磁盘和华为云OBS双存储后端，内置机架感知的副本调度策略，保障文件存储的可靠性和可用性。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-24
- **Last Updated**: 2026-01-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DFStore - 分布式文件存储服务
一款高性能、高可用、支持秒传和多副本机制的分布式文件存储服务，基于Netty构建高性能通信层，采用Master/Storage节点架构，支持本地磁盘和华为云OBS双存储后端，内置机架感知的副本调度策略，保障文件存储的可靠性和可用性。

⚠️ 重要提示：当前项目所有核心代码已开发完成，**但尚未完成全流程测试验证**（含单元测试、集成测试、端到端流程联调），暂未验证以下场景的稳定性与正确性：
1. 已完成：分布式架构落地、全量核心模块（Master/Storage/AuthCenter/Gateway）代码开发、核心流程（上传/下载/同步）代码编写、第三方依赖集成；
2. 待验证：Master节点元数据读写一致性、Storage节点跨节点同步容错、STS临时凭证高并发校验、节点宕机/上传失败等异常场景处理；
3. 暂不支持：生产环境部署（未经过压测/稳定性验证）、大规模集群（>5个Storage节点）运行。

### 开源目的
本项目开源旨在：
- 分享分布式文件存储全流程代码实现与架构落地思路；
- 寻求社区协作完成全流程测试验证，补齐测试用例、修复测试中发现的代码问题；
- 作为学习型项目，供开发者参考分布式存储、Netty RPC、RocksDB等技术的工程化实践。

## 项目简介
本分布式文件存储服务专为大规模文件存储场景设计，核心围绕**高性能传输、安全认证、智能存储、高可用保障**四大核心设计，适配内网私有化部署、云上混合部署等多种场景，具备易扩展、易部署、高定制化的特点，核心特性如下：
- **极致性能**：基于Netty实现文件上传通信层与自定义RPC框架，摆脱传统HTTP瓶颈，提供高吞吐、低延迟的文件传输能力；
- **安全可控**：集成STS临时凭证机制，细粒度权限管控，搭配请求签名+防重放校验，杜绝权限泄露与请求篡改；
- **智能上传**：内置MD5秒传校验逻辑，避免相同文件重复存储，大幅节省存储资源与上传带宽；
- **高可用保障**：多副本存储策略+机架感知的智能副本调度，规避单机/单机架故障风险，保障文件数据不丢失；
- **灵活存储**：无缝支持**本地磁盘**/**华为云OBS**，可根据业务场景灵活切换；
- **智能节点调度**：基于节点故障数、剩余空间、负载率的多维度排序算法，实现存储节点负载均衡，提升集群整体利用率；
- **轻量元数据**：采用RocksDB作为元数据存储引擎，兼顾高性能与持久化，适配大规模元数据的高效读写。

## 核心架构
### 节点/组件角色说明
#### 1. Master 节点（集群管控核心）
作为整个分布式存储集群的管控核心，**当前仅支持单节点部署**（因元数据基于RocksDB本地存储，暂未实现主备/集群模式），整合了多个核心功能组件，承担集群的全局决策与管理职责，核心能力包括：
- **副本调度器**：定时消费欠副本任务，基于机架感知策略完成副本补充，保障文件副本数达到预设标准；
- **节点管理器**：实时维护所有Storage节点的全量状态信息，包括在线/离线状态、节点负载率、剩余存储空间、故障次数、所属机架ID等；
- **元数据存储**：基于RocksDB构建高性能元数据存储引擎（本地磁盘存储），持久化存储文件的全量元数据（MD5、文件ID、副本数、存储节点、文件属性等）；
- **欠副本队列**：存储未达到目标副本数的文件任务，供副本调度器定时消费，支持任务失败重试；
- **核心决策能力**：负责Storage节点调度、秒传校验、副本策略决策、任务分发等核心逻辑。

#### 2. Storage 节点（实体存储节点）
集群的底层存储载体，专注于文件的实体存储与读写操作，核心职责包括：
- 接收前端的文件上传请求，完成文件分块的接收与写入（支持本地磁盘/华为云OBS双存储后端）；
- 响应文件读取请求，提供文件数据的高效读取能力；
- 接收Master节点的调度指令，完成文件副本的复制与同步；
- 向Master节点实时上报节点状态与文件存储结果。

#### 3. Auth Center（认证中心，独立组件）
集群的统一安全认证入口，提供全链路的权限管控能力：
- 签发STS临时访问凭证，支持细粒度的操作权限管控；
- 验证Token合法性，完成用户/应用的身份鉴权；
- 校验请求的权限范围，防止越权操作。

#### 4. Gateway 网关（集群统一接入层，独立组件）
仅承担**管控类请求**的统一接入，不参与文件数据传输，避免成为性能瓶颈，核心职责包括：
- 统一接收前端的管控类请求（如秒传校验、上传预处理、凭证申请），完成核心参数非空校验；
- 执行请求签名验证与时间戳+Nonce防重放校验，防止请求篡改与恶意重放；
- 转发管控类请求至Master节点，并生成临时上传凭证；
- 封装统一的响应格式，将Master节点的决策结果（如Storage节点地址、秒传结果）返回给前端。

### 核心技术栈
#### 基础框架与构建工具
- Spring Boot 3.3.4：快速开发分布式应用，提供核心容器与自动配置能力
- Spring Cloud 2023.0.3：适配分布式架构的配套组件支持
- Maven 3.6+：项目构建与依赖管理工具
- JDK 17+：Spring Boot 3.3.4强制要求，编译/运行均需JDK 17及以上版本

#### 通信与序列化
- Netty 4.1.112.Final：构建高性能自定义RPC框架，支撑文件流的高并发、低延迟传输
- Protobuf 3.24.4：高性能二进制序列化协议，适配RPC通信场景，解析快、体积小
- Jackson 2.17.1（jackson-databind/annotations/jsr310）：JSON序列化/反序列化核心组件
- FastJSON 2.0.41：轻量化JSON处理工具，补充Jackson的场景适配

#### 存储相关
- RocksDB 8.5.3（rocksdbjni）：高性能键值存储引擎，作为Master节点元数据存储核心
- 华为云OBS SDK 3.21.11：华为云对象存储对接依赖，支持OBS存储后端
- 本地磁盘存储：原生文件系统操作，适配私有化部署场景

#### 安全与认证
- STS临时凭证机制：细粒度、短期有效的权限管控核心
- JJWT 0.11.5：生成JWT格式的临时上传/下载凭证，保障凭证安全性
- 自定义请求签名 + 时间戳+Nonce防重放：防止请求篡改与恶意重放

#### 调度与优化
- 机架感知调度策略：优先跨机架存储副本，规避单机架故障风险
- 多维度节点排序算法：按故障数→剩余空间→负载率排序，实现Storage节点负载均衡
- Caffeine 3.1.8：高性能本地缓存，缓存热点节点信息与文件元数据

#### 开发与工具类
- Hutool 5.8.28：通用工具类库，简化日期、加密、集合等通用操作
- Lombok 1.18.30：简化JavaBean编写，减少模板代码
- JUnit 5.10.1：单元测试框架，保障代码可靠性

## 核心流程

### 1. 文件上传令牌获取（含秒传校验）
该流程为文件上传的前置管控流程，仅涉及元数据交互，核心完成**安全认证鉴权**、**秒传智能校验**，若秒传失败则为普通上传**分配最优Storage节点**并生成**临时上传凭证**，全程基于STS临时凭证完成权限管控，避免长期密钥暴露。

```mermaid
sequenceDiagram
    participant 浏览器前端 as 前端
    participant 客户端后台 as 客户端后台（持长期AK/SK）
    participant AuthCenter as Auth Center（STS服务）
    participant Gateway as 网关
    participant Master as Master节点
    participant Storage as Storage节点

    Note over 浏览器前端, AuthCenter: 阶段0：前端获取STS临时凭证（前置步骤）
    浏览器前端->>客户端后台: 0.1 发起「获取临时凭证请求」<br/>(携带：用户身份信息，如登录态token)
    客户端后台->>AuthCenter: 0.2 调用 Auth Center API（/api/gateway/auth/sts-token）<br/>(携带：长期AK + 长期SK + 申请的权限范围，如“upload”)
    AuthCenter->>AuthCenter: 0.3 验证长期AK/SK合法性，生成STS临时凭证
    AuthCenter-->>客户端后台: 0.4 返回临时凭证<br/>(TemporaryAccessKeyId + SecurityToken + 临时SK + 过期时间)
    客户端后台-->>浏览器前端: 0.5 下发临时凭证（前端存储在内存，不持久化）

    Note over 浏览器前端, Master: 阶段1：秒传校验预处理（对应preprocessQuickUpload方法）
    浏览器前端->>浏览器前端: 1.1 构造秒传校验请求参数<br/>(fileName + fileSize + fileMd5 + userId + 时间戳 + Nonce + 临时AK + Token)
    浏览器前端->>浏览器前端: 1.2 用「临时SK」对请求参数签名<br/>
    浏览器前端->>Gateway: 1.3 发起「STS秒传校验请求」(/api/gateway/upload/quick/check)<br/>(携带：签名 + 临时AK + Token + 文件元数据 + 时间戳 + Nonce)
    Gateway->>Gateway: 1.4 校验核心参数<br/>(fileMd5/ userId/ fileName非空、fileSize>0)
    Gateway->>Gateway: 1.5 防重放校验（时间戳+Nonce+临时AK）
    Gateway->>AuthCenter: 1.6 调用Auth Center验证Token合法性<br/>(携带：TemporaryAccessKeyId + SecurityToken)
    AuthCenter-->>Gateway: 1.7 返回Token验证结果<br/>(合法：返回临时SK + 权限范围；非法：返回失败)
    alt 验证失败（Token无效/签名不匹配/无upload权限）
        Gateway-->>浏览器前端: 1.8 返回401/403错误
    else 验证通过
        Gateway->>Master: 1.9 调用Master节点秒传查重接口<br/>(携带：fileMd5 + fileName + fileSize + userId)
        Master->>Master: 1.10 校验文件MD5是否已存在
        Master-->>Gateway: 1.11 返回查重结果<br/>(quickUploadSuccess(是否秒传) + uniqueFileId)
        Gateway->>Gateway: 1.12 封装网关层秒传响应<br/>
        Gateway-->>浏览器前端: 1.13 返回秒传校验结果<br/>(成功：文件已存在，直接返回文件ID；失败：提示走普通上传流程)
    end

    Note over 浏览器前端, Storage: 若秒传失败，前端走「普通上传预处理」（/api/gateway/upload/preprocess）
    浏览器前端->>Gateway: 2.1 发起「STS上传预处理请求」(/api/gateway/upload/preprocess)<br/>(携带：签名 + 临时AK + Token + fileSize + fileMd5 + 可选存储类型偏好)
    Gateway->>Master: 2.2 请求分配Storage节点<br/>(携带：存储类型偏好 + fileSize + fileMd5)
    Master->>Master: 2.3 筛选并选择最优存储节点<br/>(1.过滤离线节点 2.按存储类型偏好筛选（无则跳过） 3.按「故障少、剩余空间大、负载低」排序选最优)
    Master->>Master: 2.4 生成唯一文件ID（基于fileMd5 + 节点ID）
    Master-->>Gateway: 2.5 返回存储节点信息（地址 + 唯一文件ID）
    Gateway->>Gateway: 2.6 生成临时上传凭证（JWT，含文件信息+节点地址，10分钟过期）
    Gateway-->>浏览器前端: 2.7 返回临时上传凭证 + 存储节点地址
    浏览器前端->>Storage: 2.8 携带临时凭证上传文件流
```
### 2. 文件上传与副本调度
该流程为文件实体存储与高可用保障的核心流程，文件流**直接在前端与Storage节点间传输**，避免网关成为瓶颈，分为**文件上传**和**副本调度**两部分。
```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Storage as Storage节点
    participant Master as Master节点
    participant Queue as 欠副本队列
    participant Scheduler as 副本调度器
    participant Meta as 文件元数据存储
    participant NodeManager as 存储节点管理器
    participant Selector as 节点选择器（机架感知）

    Note over Client,Master: 分布式文件存储-文件上传+副本调度核心流程

    # 1. 文件上传核心流程
    Client->>Storage: 发起文件上传请求（含文件信息）
    Storage->>Storage: 校验请求并接收文件分块
    alt 请求/写入异常
        Storage->>Client: 返回上传失败
    else 上传成功
        Storage->>Master: 上报上传结果（含文件元数据）
        Master->>Meta: 持久化文件元数据
        Master->>Queue: 将文件加入欠副本队列
        Storage->>Client: 返回上传成功
    end

    # 2. 副本调度核心流程
    Scheduler->>Queue: 定时获取欠副本文件任务（fixedRate触发）
    Queue->>Meta: 查询文件元数据（目标副本数/当前副本数/存储节点）
    Meta->>Queue: 返回文件元数据（含已存储节点ID、副本数）
    Queue->>NodeManager: 获取所有在线存储节点（按机架GroupId分组）
    NodeManager->>Queue: 返回分组后的在线节点列表
    Queue->>Selector: 构建复制任务（需选择源节点+目标节点）

    # 机架感知的节点选择
    Selector->>Selector: 1. 选择源节点（从已存储节点选最优：在线+故障少+负载低）
    Selector->>Selector: 2. 计算需补充的副本数（目标副本数-当前副本数）
    Selector->>Selector: 3. 机架感知选目标节点：
    Selector->>Selector:   - 优先筛选跨机架（不同GroupId）在线节点
    Selector->>Selector:   - 跨机架节点不足时，补充同机架节点
    Selector->>Selector: 4. 过滤目标节点：排除源节点、离线节点、去重
    Selector->>Selector: 5. 多维度排序目标节点（故障少→剩余空间大→负载低）
    Selector->>Selector: 6. 截取需要的副本数，确定最终目标节点列表
    Selector->>Queue: 返回源节点+目标节点列表
    Queue->>Queue: 按副本缺失数排序，生成含节点信息的复制任务
    Queue->>Scheduler: 返回复制任务列表
    Scheduler->>Master: 分发复制任务
    Master->>Storage: 推送复制任务（源节点→目标节点，通过心跳）
    Storage->>Storage: 执行文件副本复制（源节点读取→目标节点写入）

    alt 副本复制失败
        Storage->>Master: 上报任务失败（含失败原因/节点）
        Master->>Queue: 任务失败处理
        Queue->>Queue: 重新将文件加入欠副本队列（重试）
    else 副本复制成功
        Storage->>Master: 上报任务成功（含完成的目标节点）
        Master->>Queue: 完成任务处理
        Queue->>Meta: 更新文件副本数和存储节点信息
        alt 副本数达标
            Queue->>Queue: 移除文件的欠副本记录
        end
    end
```
### 3. 文件下载流程
文件下载同样绕开网关，保障传输性能：
1. 前端向Gateway网关发起文件下载预处理请求（仅元数据请求），携带文件ID、STS临时凭证、防重放参数；
2. 网关完成校验后，转发请求至Master节点；
3. Master节点查询该文件的存储节点列表，选择最优可用节点（在线、负载低），返回节点地址与临时下载凭证；
4. 前端携带临时下载凭证，**直接向指定Storage节点**发起文件下载请求，获取文件流；
5. Storage节点校验凭证合法性后，直接向前端返回文件流数据。

## 核心特性详解

### 1. 全链路安全认证机制
本项目采用**STS临时凭证**为核心的安全认证体系，从根源上规避密钥泄露风险，搭配多层校验保障请求安全：
- **STS临时凭证**：基于短期有效、细粒度权限的临时凭证完成操作授权，凭证过期后自动失效，且仅能申请指定操作（如upload/downlaod）的权限；
- **请求签名**：所有前端请求均通过临时SK对参数进行签名，网关/Storage节点校验签名一致性，防止请求参数被篡改；
- **防重放校验**：基于**时间戳+Nonce**机制，网关/Storage节点校验请求的时间戳有效性与Nonce唯一性，避免请求被恶意重复提交；
- **JWT凭证**：采用JJWT 0.11.5生成临时上传/下载凭证，保障凭证的安全性与可验证性；
- **权限二次校验**：Auth Center在验证Token时，会二次校验凭证的操作权限，Storage节点接收文件请求时也会校验凭证权限，确保用户仅能执行授权范围内的操作。

### 2. 高效秒传机制
基于**文件MD5唯一性**实现秒传功能，无需重复上传相同文件，大幅提升上传效率，节省存储与带宽资源：
- 秒传校验基于文件MD5在Master节点的RocksDB元数据存储中完成，查询效率高；
- 若文件已存在，直接返回全局唯一文件ID，前端无需上传文件流；
- 唯一文件ID由**文件MD5+存储节点ID**生成，保障集群内文件ID唯一性。

### 3. 机架感知的多副本调度
副本调度是保障文件高可用的核心，Master节点内置的**机架感知策略**从架构层面规避单机/单机架故障风险：
- **优先跨机架存储**：副本补充时优先选择不同机架的Storage节点，即使单个机架发生故障，其他机架的副本仍可正常访问；
- **多维度节点选择**：节点排序综合**故障数、剩余空间、负载率**，既保障节点故障少，又实现集群负载均衡；
- **自动失败重试**：副本复制任务失败后，文件会重新加入Master节点的欠副本队列，等待下一次调度重试，保障副本数最终达标；
- **可配置副本数**：默认副本数可通过配置文件修改，可根据业务对可用性的要求灵活调整（如核心文件配置5副本）。

### 4. 灵活的存储后端选择
支持**本地磁盘**和**华为云OBS**二选一的存储后端，适配不同业务场景：
- **本地磁盘**：适用于内网私有化部署，优势是低延迟、高吞吐、自主可控，适合对文件访问速度要求高的场景；
- **华为云OBS**：基于华为云OBS SDK 3.21.11实现，适用于云上部署或混合部署，优势是弹性扩展、免运维、容灾能力强，适合对存储弹性要求高的场景。

### 5. 高性能通信与存储
- **Netty高性能通信**：基于Netty 4.1.112.Final实现自定义RPC框架，文件流直接在前端与Storage节点间传输，摆脱传统HTTP瓶颈，支持长连接、高并发，传输效率大幅提升；
- **Protobuf序列化**：采用Protobuf 3.24.4作为RPC通信的序列化协议，二进制序列化格式体积小、解析快，适配高性能通信场景；
- **RocksDB元数据存储**：Master节点采用RocksDB 8.5.3作为元数据存储引擎，读写性能远优于传统关系型数据库，适配分布式文件系统中大规模元数据的高效读写需求；
- **Caffeine本地缓存**：集成Caffeine 3.1.8高性能本地缓存，缓存热点节点信息与文件元数据，提升Master节点决策效率；
- **文件分块传输**：文件上传支持分块传输（底层实现），适配大文件上传场景，避免单次传输失败导致整体重传；
- **网关解耦**：网关仅处理管控类元数据请求，文件数据传输绕开网关，从架构上避免网关成为性能瓶颈。

## 集群部署建议

### 开发/测试环境
- Master节点：1台（单节点部署，元数据存储于本地RocksDB）
- Storage节点：2-3台（可配置2副本）
- 存储后端：本地磁盘
- JDK版本：JDK 17（推荐OpenJDK 17）
- 适用场景：功能开发、单元测试、流程验证

### 生产环境
- Master节点：1台（当前仅支持单节点，因RocksDB本地存储暂无法实现主备，需做好Master节点的服务器级容灾）
- Storage节点：≥5台（建议按机架分组，每组至少2台，配置3-5副本）
- 存储后端：根据业务场景选择（内网部署选本地磁盘，云上部署选OBS，混合部署可按节点分别配置）
- JDK版本：JDK 17+（推荐LTS版本，如OpenJDK 17/21）
- 网络规划：
  - Master与Storage节点部署在专用内网，保障管控指令的稳定传输；
  - Gateway网关仅部署在内网/公网管控入口，仅处理轻量元数据请求；
  - 前端与Storage节点建立独立的高性能传输通道，保障文件传输效率；
- 存储规划：
  - Master节点：做好本地RocksDB数据目录的定时备份，降低元数据丢失风险；
  - Storage节点：本地磁盘建议使用大容量SSD/SAS磁盘，独立分区存储文件与元数据，做好磁盘挂载与容灾。

## 免责声明
本项目为开源学习开发的通用分布式文件存储服务，项目维护者仅对项目代码的功能性与稳定性进行持续优化，**不承担因使用本项目导致的任何数据丢失、业务故障等损失**。
在生产环境使用前，请务必做好充分的测试、容灾规划与数据备份工作。