# cloud-storage

**Repository Path**: nice-cms/cloud-storage

## Basic Information

- **Project Name**: cloud-storage
- **Description**: 本项目是一个基于Spring Boot的分布式在线网盘系统。系统实现了用户管理、文件与文件夹的增删改查、文件秒传、内容搜索、以及安全的文件分享等功能。项目采用分层架构，通过引入Elasticsearch实现了文件内容的全文检索，并使用Redis提升了系统性能和分享链接的安全性。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://yun.must.cool/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 云存 - 个人在线网盘系统

Cloud Storage - Personal Online Disk System

## 📖 项目简介

云存是一个基于Spring Boot的分布式在线网盘系统，提供安全可靠的文件存储、管理和分享服务。系统实现了完整的文件管理功能，支持秒传、全文检索、安全分享等高级特性。

## ✨ 核心功能

### 🔐 用户管理

- 用户注册与登录
- JWT Token认证
- 个人信息管理

### 📁 文件管理

- 文件与文件夹的创建、删除、重命名
- 多级目录结构支持
- 文件上传与下载
- 文件秒传（基于MD5校验）
- 文件搜索（支持文件名和内容搜索）

### 🔗 文件分享

- 生成分享链接
- 支持分享密码保护
- 设置分享有效期
- 安全的分享访问控制

### 🔍 高级搜索

- 基于文件名的快速搜索
- 文档内容的全文检索（支持TXT、PDF、Word、Excel等格式）
- 智能搜索结果排序

## 🛠 技术栈

### 后端技术

- **核心框架**: Spring Boot 3.5+
- **安全框架**: Spring Security + JWT
- **数据持久层**: MyBatis-Plus
- **数据库**: MySQL 5.7
- **缓存**: Redis
- **搜索引擎**: Elasticsearch
- **文件解析**: Apache Tika
- **构建工具**: Maven

# 前端技术

## 核心技术栈
- **Next.js 14+** - React 全栈框架，支持服务端渲染
- **TypeScript** - 类型安全的 JavaScript 超集
- **React 18** - 现代化用户界面库
- **Tailwind CSS** - 实用优先的 CSS 框架

## UI 组件库
- **shadcn/ui** - 基于 Radix UI 和 Tailwind CSS 的可复用组件
- **自定义组件** - 位于 `components/` 目录的可复用 UI 组件

## 开发工具
- **Axios** - HTTP 请求库，用于与后端 API 通信
- **React Hooks** - 自定义 hooks 位于 `hooks/` 目录
- **PostCSS** - CSS 后处理器，配置位于 `postcss.config.mjs`

## 项目架构
- **App Router** - Next.js 13+ 新型路由系统
- **组件化开发** - 模块化的 React 组件架构
- **类型安全** - 完整的 TypeScript 类型定义

## 🏗 系统架构

### 后端分层架构

表现层 (Controller) 
    ↓
业务逻辑层 (Service) 
    ↓
数据持久层 (Mapper)
    ↓
   MySQL + Redis + Elasticsearch

### 核心模块

- **用户模块**: 认证、授权、会话管理
- **文件模块**: 上传、下载、管理、搜索
- **分享模块**: 链接生成、访问控制
- **搜索模块**: 内容索引、全文检索

## 📊 数据库设计

### 主要数据表

- `user` - 用户信息表
- `file_metadata` - 文件元数据表
- `share` - 文件分享表

## 🚀 快速开始

### 环境要求

- JDK 17+
- MySQL 5.7+
- Redis 6.0+
- Elasticsearch 7.0+
- Maven 3.6+

### 安装步骤

1. **克隆项目**

```bash
git clone https://github.com/your-username/cloud-storage.git
cd cloud-storage
```

2. **数据库初始化**

```sql
CREATE DATABASE cloud_storage DEFAULT CHARACTER SET utf8mb4;
-- 执行项目中的 sql/schema.sql 初始化表结构
```

3. **配置文件**
   复制 `application.yml.example` 为 `application.yml`，并修改配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/cloud_storage
    username: your_username
    password: your_password
  redis:
    host: localhost
    port: 6379
  elasticsearch:
    uris: http://localhost:9200
```

4. **启动项目**

```bash
mvn clean install
mvn spring-boot:run
```

5. **访问系统**

```
http://localhost:8080
```

## 📚 API接口文档

### 认证接口

- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录

### 文件管理接口

- `GET /api/files` - 获取文件列表
- `POST /api/files/upload` - 文件上传
- `GET /api/files/download/{fileId}` - 文件下载
- `PUT /api/files/{fileId}` - 文件重命名
- `DELETE /api/files/{fileId}` - 文件删除

### 搜索接口

- `GET /api/search` - 文件搜索
- 参数: `keyword` (关键词), `searchType` (filename/content)

### 分享接口

- `POST /api/shares` - 创建分享链接
- `GET /api/shares/{shareId}` - 查看分享详情
- `GET /api/shares/{shareId}/download` - 下载分享文件

## 🔧 核心特性详解

### 文件秒传技术

基于文件MD5哈希值的去重机制：

1. 计算上传文件的MD5值
2. 查询数据库中是否存在相同MD5的文件
3. 如果存在，直接创建文件引用，实现秒传
4. 如果不存在，执行完整上传流程

### 全文检索功能

- 使用Elasticsearch建立文档内容索引
- 支持多种文档格式（TXT、PDF、Word、Excel等）
- 基于IK分词器的中文全文检索
- 搜索结果按相关性排序

### 安全分享机制

- 分享链接使用UUID生成，防止猜测
- 支持密码保护和有效期设置
- Redis缓存分享信息，提高访问性能

## 🗂 项目结构

```
src/main/java/com/cloud/storage/
├── config/           # 配置类
│   ├── WebConfig.java
│   ├── SecurityConfig.java
│   └── ElasticsearchConfig.java
├── controller/       # 控制器层
│   ├── FileController.java
│   ├── UserController.java
│   └── ShareController.java
├── service/          # 服务层
│   ├── FileService.java
│   ├── UserService.java
│   └── ElasticsearchService.java
├── mapper/           # 数据持久层
│   └── FileMetadataMapper.java
├── entity/           # 实体类
│   ├── User.java
│   ├── FileMetadata.java
│   └── FileDocument.java
├── dto/              # 数据传输对象
│   ├── FileUploadResponse.java
│   └── ApiResponse.java
├── util/             # 工具类
│   ├── JwtUtil.java
│   └── FileUtil.java
└── exception/        # 异常处理
    └── GlobalExceptionHandler.java
```

## 🔍 搜索功能使用

### 文件名搜索

```http
GET /api/search?keyword=文档&searchType=filename
```

### 内容搜索

```http
GET /api/search?keyword=项目说明&searchType=content
```

## 🧪 测试

运行单元测试：

```bash
mvn test
```

API测试：

- 导入 `docs/postman_collection.json` 到Postman
- 或使用Swagger UI: `http://localhost:8080/swagger-ui.html`

## 📈 性能优化

- ⚡ **Redis缓存**: 用户会话、文件元数据、分享信息缓存
- 🔍 **Elasticsearch索引**: 毫秒级文件内容搜索
- 💾 **MD5去重**: 节省存储空间和网络带宽
- 🚀 **异步处理**: 文件索引、大文件处理异步化

## 🔒 安全特性

- JWT无状态认证
- 文件权限验证
- 分享链接安全控制
- SQL注入防护
- XSS攻击防护

## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支: `git checkout -b feature/AmazingFeature`
3. 提交更改: `git commit -m 'Add some AmazingFeature'`
4. 推送到分支: `git push origin feature/AmazingFeature`
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 👥 作者

**Your Name**

- Email: 2491696620@qq.com

## 🙏 致谢

- Spring Boot 框架
- Elasticsearch 搜索引擎
- MyBatis-Plus ORM框架
- 所有贡献者和用户

---

**技术标签**: `Spring Boot` `Java` `MySQL` `Redis` `Elasticsearch` `文件存储` `云盘系统`

**项目标签**: `网盘系统` `Cloud Storage` `文件管理` `全文检索` `秒传技术`

如果这个项目对你有帮助，请给个 ⭐️ 支持！