# minio-upload

**Repository Path**: oxygen_oO/minio-upload

## Basic Information

- **Project Name**: minio-upload
- **Description**: 基于Minio原生的大文件分片上传
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 18
- **Forks**: 8
- **Created**: 2023-12-20
- **Last Updated**: 2025-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MinIO 文件上传系统

## 项目介绍

基于 MinIO 对象存储服务的现代化文件上传系统，提供丰富的功能，包括普通上传、分片上传、秒传、断点续传等。本项目采用 Spring Boot + Minio SDK 构建后端，纯 HTML/CSS/JavaScript 构建前端，简单易用且功能强大。

## 功能特点

- **多种上传方式**：支持小文件直接上传和大文件分片上传
- **断点续传**：支持上传中断后继续上传，无需重新开始
- **秒传功能**：基于文件 MD5 特征值，避免重复上传相同文件
- **拖拽上传**：支持拖拽文件到指定区域快速上传
- **上传进度**：实时显示上传进度，颜色随进度变化
- **文件管理**：支持文件列表查看、删除等基本操作
- **接口文档**：集成 Knife4j 接口文档，提供在线 API 调试功能

## 技术栈

- **后端**：

  - Spring Boot 3.x
  - MinIO Java SDK
  - MyBatis-Plus
  - MySQL
  - Knife4j 4.x（API 文档工具）
  - Lombok（简化代码）
  - Hutool（工具类库）

- **前端**：
  - HTML5/CSS3
  - JavaScript/jQuery
  - Bootstrap 5
  - SparkMD5（文件 MD5 计算）
  - SweetAlert2（美化提示）

## 快速开始

### 1. 准备环境

- JDK 17+
- Maven 3.6+
- MySQL 8.0+
- MinIO Server (最新版)

### 2. MinIO 配置

1. 下载并安装 [MinIO Server](https://min.io/download)
2. 启动 MinIO 服务：
   ```bash
   ./minio server /path/to/data
   ```
3. 记录 MinIO 控制台输出的访问凭证（Access Key 和 Secret Key）

### 3. 配置项目

1. 克隆本项目到本地：

   ```bash
   git clone https://gitee.com/oxygen_oO/minio-upload.git
   cd minio-upload
   ```

2. 修改 `src/main/resources/application.yml` 配置：

   ```yaml
   minio:
     endpoint: http://localhost:9000 # MinIO服务地址
     access-key: your-access-key # 替换为你的Access Key
     secret-key: your-secret-key # 替换为你的Secret Key
     bucket-name: your-bucket-name # 文件存储的桶名称
   ```

3. 配置数据库信息：

   ```yaml
   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/your_db_name
       username: your_username
       password: your_password
   ```

4. 初始化数据库：

   在 MySQL 中创建相应数据库，然后导入项目中的`data.sql`文件进行表结构和基础数据的初始化

### 4. 运行项目

1. 使用 Maven 编译项目：

   ```bash
   mvn clean package
   ```

2. 启动 Spring Boot 应用：

   ```bash
   java -jar target/minio-upload-1.0.0.jar
   ```

3. 访问接口文档：

   浏览器访问：`http://localhost:8080/doc.html` 查看 API 文档并进行接口调试

4. 前端页面：

   直接在浏览器中打开 `web/index.html` 访问上传界面

## 使用指南

### 上传文件

1. 点击"选择文件"按钮或将文件拖拽到上传区域
2. 自动根据文件大小选择上传方式：
   - 小于 5MB 的文件使用普通上传
   - 大于或等于 5MB 的文件使用分片上传

### 断点续传

1. 对于大文件上传，如果上传过程中断（例如关闭浏览器或网络中断）
2. 重新上传相同文件时，系统会自动检测到之前的上传任务
3. 系统会从上次中断的位置继续上传，无需重新开始

### 秒传功能

1. 系统会计算文件的 MD5 特征值
2. 如果服务器已存在相同 MD5 值的文件，则直接秒传成功，无需实际上传文件内容

### API 接口文档

1. 启动应用后访问：`http://localhost:8080/doc.html`
2. 系统支持以下主要接口：
   - `/api/upload/v2/upload`：普通文件上传
   - `/api/upload/v2/second_upload`：秒传文件
   - `/api/upload/v2/create_task`：创建分片上传任务
   - `/api/upload/v2/get_upload_urls`：获取分片上传 URL
   - `/api/upload/v2/check_progress`：检查上传进度
   - `/api/upload/v2/merge`：合并文件分片
   - `/api/upload/v2/list`：文件列表查询
   - `/api/upload/v2/delete`：文件删除

## 代码结构说明

项目主要代码位于`src/main/java/net/oxygen/upload`目录下，主要包含以下模块：

- `controller`：控制器层，处理 HTTP 请求
  - `UploadV2Controller.java`：文件上传相关接口
  - `FileController.java`：文件管理相关接口
- `service`：业务逻辑层
  - `impl/FileV2ServiceImpl.java`：文件操作业务逻辑实现
  - `impl/MinioStorageServiceImpl.java`：MinIO 存储服务实现
- `mapper`：数据访问层，与数据库交互
  - `FileMapper.java`：文件表数据操作
  - `FileChunkMapper.java`：文件分片表数据操作
- `entity`：实体类，对应数据库表结构
  - `FileDO.java`：文件表实体类
  - `FileChunkDO.java`：文件分片表实体类
- `dto`：数据传输对象
  - `FileInfoDTO.java`：文件信息传输对象
  - `SecondUploadDTO.java`：秒传请求对象
- `config`：配置类
  - `MinioConfig.java`：MinIO 客户端配置
  - `Knife4jConfig.java`：接口文档配置
- `common`：通用工具类和常量
  - `Result.java`：统一响应结果类
  - `Constants.java`：常量定义

## 数据库设计

系统包含三个主要数据表，用于存储文件元数据、分片信息和文件类型数据，数据表结构如下：

### 文件表（file）

存储已上传文件的元数据信息

```sql
CREATE TABLE `file` (
    `id` bigint NOT NULL COMMENT '文件id',
    `file_name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '文件名称，秒传需要用到，冗余存储',
    `file_suffix` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '文件的后缀拓展名，冗余存储',
    `file_size` bigint DEFAULT NULL COMMENT '文件大小，字节，冗余存储',
    `object_key` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '文件的key, 格式 日期/md5.拓展名，比如 2025-03-13/921674fd-cdaf-459a-be7b-109469e7050d.png',
    `identifier` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '唯一标识，文件MD5',
    `del` tinyint NOT NULL DEFAULT '0' COMMENT '逻辑删除（0未删除，1已删除）',
    `gmt_modified` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    `gmt_create` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci ROW_FORMAT=DYNAMIC COMMENT='用户文件表';
```

### 分片表（file_chunk）

存储文件分片上传信息，支持断点续传功能

```sql
CREATE TABLE `file_chunk` (
    `id` bigint NOT NULL,
    `identifier` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '文件唯一标识（md5）',
    `upload_id` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '分片上传ID',
    `file_name` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '文件名',
    `bucket_name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '所属桶名',
    `object_key` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '文件的key',
    `total_size` bigint NOT NULL COMMENT '总文件大小（byte）',
    `chunk_size` bigint NOT NULL COMMENT '每个分片大小（byte）',
    `chunk_num` int NOT NULL COMMENT '分片数量',
    `gmt_create` datetime DEFAULT CURRENT_TIMESTAMP,
    `gmt_modified` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`) USING BTREE,
    UNIQUE KEY `uq_file_identifier` (`identifier`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci ROW_FORMAT=DYNAMIC COMMENT='文件分片信息表';
```

### 文件类型表（file_type）

存储文件类型基础数据

```sql
CREATE TABLE `file_type` (
    `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    `file_type_name` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '文件类型名',
    PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=9 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin ROW_FORMAT=DYNAMIC COMMENT='文件类型表';
```

### 文件后缀表（file_suffix）

存储文件后缀与文件类型的对应关系

```sql
CREATE TABLE `file_suffix` (
    `id` int NOT NULL AUTO_INCREMENT,
    `file_suffix` varchar(25) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '文件扩展名',
    `file_type_id` int NOT NULL COMMENT '文件类型ID',
    PRIMARY KEY (`id`) USING BTREE,
    KEY `fk_file_type_id` (`file_type_id`) USING BTREE,
    CONSTRAINT `fk_file_type_id` FOREIGN KEY (`file_type_id`) REFERENCES `file_type` (`id`) ON DELETE RESTRICT ON UPDATE RESTRICT
) ENGINE=InnoDB AUTO_INCREMENT=80 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin ROW_FORMAT=DYNAMIC COMMENT='文件分类表';
```

## 项目结构

```
├── src/                       # 后端源代码
│   ├── main/
│   │   ├── java/             # Java代码
│   │   │   └── net/oxygen/upload/
│   │   │       ├── common/   # 通用工具和常量
│   │   │       ├── config/   # 配置类
│   │   │       ├── controller/ # 控制器
│   │   │       ├── dto/      # 数据传输对象
│   │   │       ├── entity/   # 实体类
│   │   │       ├── mapper/   # 数据访问层
│   │   │       └── service/  # 业务逻辑层
│   │   └── resources/        # 配置文件
├── web/                       # 前端资源
│   ├── bootstrap/            # Bootstrap框架
│   ├── css/                  # 样式文件
│   ├── js/                   # JavaScript文件
│   └── index.html            # 主页面
└── README.md                 # 项目说明
```

## 贡献指南

欢迎贡献代码或提出建议，请遵循以下步骤：

1. Fork 本仓库
2. 创建新分支 (`git checkout -b feature/your-feature`)
3. 提交更改 (`git commit -m 'Add some feature'`)
4. 推送到分支 (`git push origin feature/your-feature`)
5. 创建 Pull Request

## 许可证

[MIT License](LICENSE)