# mini-netdisk

**Repository Path**: asmore/mini-netdisk

## Basic Information

- **Project Name**: mini-netdisk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mini 网盘 🚀

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/yourusername/mini-netdisk)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

基于 Vue 3 + Spring Boot + MinIO 的现代化网盘应用，提供快速、安全、易用的文件管理体验。

## ✨ 新版本亮点 (v2.0.0)

### ⚡ 秒下载技术
- **立即开始下载** - 点击下载按钮立即开始，无需等待
- **预签名 URL** - 浏览器直接从存储服务器下载
- **零内存占用** - 不经过应用服务器，节省 99% 以上内存
- **无限并发** - 支持同时下载多个大文件

### 🎨 全新界面设计
- **悬浮操作按钮** - Material Design 风格，始终可访问
- **三种上传方式** - 拖拽、选择文件、上传文件夹
- **智能文件夹创建** - 快速模板、实时验证、创建后打开
- **批量操作** - 多选、批量删除、选择状态显示
- **快捷键系统** - Ctrl+F 搜索、Ctrl+N 新建、F2 重命名等

### 🎯 用户体验提升
- **中文文件名完美支持** - RFC 5987 标准编码，无乱码
- **实时存储监控** - 动态进度条，颜色预警
- **文件类型图标** - 不同类型显示不同颜色图标
- **智能日期显示** - 今天、昨天、X 天前
- **响应式设计** - 完美适配桌面端和移动端
- **右键菜单支持** - 文件、文件夹、背景区域全面支持右键菜单操作

## 🎯 核心功能

### 文件管理
- ✅ 文件上传（拖拽、选择、文件夹）
- ✅ 秒速下载（预签名 URL）
- ✅ 文件重命名、移动、删除
- ✅ 批量操作（多选、批量删除）
- ✅ 文件搜索（支持中文）
- ✅ 文件预览
- ✅ 右键菜单（快捷操作）

### 文件夹管理
- ✅ 创建文件夹（快速模板）
- ✅ 文件夹树形展示
- ✅ 面包屑导航
- ✅ 拖拽移动文件

### 用户系统
- ✅ 用户注册/登录
- ✅ JWT 身份认证
- ✅ 存储配额管理
- ✅ 实时存储监控

### 上传增强
- ✅ 大文件分片上传（>50MB）
- ✅ 断点续传支持
- ✅ 实时上传进度
- ✅ 并发上传优化
- ✅ 自动文件验证

## 🛠️ 技术栈

### 后端
- **Spring Boot 3** - 现代化 Java 框架
- **Java 21** - 最新 LTS 版本
- **Spring Security + JWT** - 安全认证
- **MinIO** - 高性能对象存储
- **PostgreSQL** - 关系型数据库
- **Gradle** - 构建工具

### 前端
- **Vue 3** - 渐进式 JavaScript 框架
- **Composition API** - 组合式 API，视图与逻辑分离
- **TypeScript** - 类型安全
- **Element Plus** - 组件库
- **Tailwind CSS** - 原子化 CSS
- **Pinia** - 状态管理
- **Vite** - 快速构建工具

### 架构模式
- **Composables** - 可复用的逻辑单元
- **视图与逻辑分离** - 清晰的职责划分
- **单一职责原则** - 每个模块专注一件事
- **依赖注入** - 灵活的组件通信

## 🚀 快速开始

### 环境要求
- Node.js 18+
- Java 21+
- MinIO Server
- PostgreSQL 14+

### 1. 克隆项目
```bash
git clone <repository-url>
# mini-netdisk

一个现代化的个人网盘系统，支持文件上传、下载、预览、管理等功能。
```

### 2. 启动 MinIO
```bash
# 使用 Docker
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"
```

### 3. 配置数据库
创建 PostgreSQL 数据库并运行迁移脚本：
```bash
psql -U postgres -c "CREATE DATABASE mini_netdisk;"
psql -U postgres -d mini_netdisk -f supabase/migrations/*.sql
```

### 4. 配置后端
设置环境变量或编辑 `application.yml`：
```bash
export APP_DATASOURCE_URL=jdbc:postgresql://localhost:5432/mini_netdisk
export APP_DATASOURCE_USERNAME=postgres
export APP_DATASOURCE_PASSWORD=your_password
export MINIO_ENDPOINT=http://localhost:9000
export MINIO_ACCESS_KEY=minioadmin
export MINIO_SECRET_KEY=minioadmin
export MINIO_BUCKET=netdisk
export JWT_SECRET=your-secret-key-at-least-32-characters-long
```

### 5. 启动后端
```bash
./gradlew bootRun
```
后端服务将在 http://localhost:8080 启动

### 6. 启动前端
```bash
cd web
npm install
npm run dev
```
前端应用将在 http://localhost:5173 启动

### 7. 访问应用
打开浏览器访问 http://localhost:5173

## ⌨️ 快捷键

| 快捷键 | 功能 | 说明 |
|--------|------|------|
| `Ctrl+F` | 搜索 | 快速搜索文件 |
| `Ctrl+U` | 上传 | 打开上传菜单 |
| `Ctrl+N` | 新建文件夹 | 创建文件夹对话框 |
| `F5` | 刷新 | 刷新文件列表 |
| `F2` | 重命名 | 重命名选中项 |
| `Del` | 删除 | 删除选中项 |
| `Esc` | 取消 | 清除选择/关闭对话框/关闭右键菜单 |
| `右键` | 菜单 | 打开上下文菜单快速操作 |

> **Mac 用户**: 将 `Ctrl` 替换为 `Cmd`

## 🖱️ 右键菜单

支持在文件、文件夹和空白区域使用右键菜单进行快速操作：

### 文件右键菜单
- 预览文件 - 快速查看文件内容
- 下载 - 立即下载到本地
- 移动 - 移动到其他文件夹
- 重命名 - 修改文件名称
- 删除 - 删除文件

### 文件夹右键菜单
- 打开文件夹 - 进入文件夹
- 重命名 - 修改文件夹名称
- 删除 - 删除文件夹及内容

### 背景右键菜单
- 上传文件 - 快速上传
- 新建文件夹 - 创建新文件夹
- 刷新 - 更新文件列表
- 粘贴 - 粘贴文件（开发中）

## 📖 文档

### 功能文档
- **[快速启动指南](./QUICK_START.md)** - 5 分钟快速上手
- **[下载优化说明](./DOWNLOAD_OPTIMIZATION.md)** - 秒下载技术详解
- **[界面优化说明](./UI_OPTIMIZATION.md)** - UI/UX 优化完整文档
- **[界面特性展示](./UI_FEATURES.md)** - 视觉效果和交互说明
- **[前端使用指南](./web/IMPROVEMENTS.md)** - 前端新特性详细介绍
- **[优化总结报告](./IMPROVEMENTS_SUMMARY.md)** - 完整的优化成果总结

### 右键菜单文档
- **[右键菜单快速指南](./CONTEXT_MENU_QUICKSTART.md)** - 右键菜单 5 分钟上手
- **[右键菜单功能说明](./CONTEXT_MENU_GUIDE.md)** - 右键菜单详细功能文档
- **[右键菜单测试指南](./TEST_CONTEXT_MENU.md)** - 右键菜单测试用例

### 架构文档
- **[视图与逻辑分离架构](./ARCHITECTURE_SEPARATION.md)** - 架构设计理念和实践
- **[Composables 使用指南](./COMPOSABLES_GUIDE.md)** - 可复用逻辑单元详解
- **[重构总结报告](./REFACTORING_SUMMARY.md)** - 架构重构成果总结

## 📁 项目结构

```
mini-netdisk/
├── src/main/java/com/mini/netdisk/
│   ├── config/           # 配置类（Security、MinIO等）
│   ├── controller/       # REST API 控制器
│   ├── service/          # 业务逻辑层
│   ├── entity/           # 数据实体
│   ├── repository/       # 数据访问层
│   ├── dto/              # 数据传输对象
│   ├── security/         # 安全相关
│   └── common/           # 通用工具类
├── web/
│   ├── src/
│   │   ├── components/   # Vue 组件（视图层，仅负责展示）
│   │   ├── views/        # 页面视图（组合组件和逻辑）
│   │   ├── stores/       # Pinia 状态管理（全局状态）
│   │   ├── composables/  # 组合式函数（可复用业务逻辑）
│   │   │   ├── useContextMenu.ts        # 右键菜单基础逻辑
│   │   │   ├── useFileContextMenu.ts    # 文件操作菜单逻辑
│   │   │   ├── useFileExplorer.ts       # 文件浏览器逻辑
│   │   │   ├── useFilePreview.ts        # 文件预览逻辑
│   │   │   ├── useDragUpload.ts         # 拖拽上传逻辑
│   │   │   └── useKeyboardShortcuts.ts  # 快捷键逻辑
│   │   ├── router/       # 路由配置
│   │   └── utils/        # 工具函数（无状态）
│   └── package.json
├── supabase/             # 数据库迁移脚本
└── docs/                 # 文档
```

### 架构分层
```
视图层 (Components/Views)
    ↓ 使用
逻辑层 (Composables)
    ↓ 调用
API层 (Services)
    ↓ 访问
数据层 (Stores/Backend)
```

## 🔌 API 文档

### 认证接口
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录

### 文件接口
- `POST /api/files/upload` - 上传文件（小文件）
- `GET /api/files/list` - 获取文件列表
- `GET /api/files/download-url/{fileId}` - 获取下载链接（推荐）
- `GET /api/files/download/{fileId}` - 直接下载（备用）
- `PUT /api/files/{fileId}/rename` - 重命名文件
- `PUT /api/files/{fileId}/move` - 移动文件
- `DELETE /api/files/{fileId}` - 删除文件

### 分片上传接口
- `POST /api/files/upload/init` - 初始化分片上传
- `POST /api/files/upload/chunk` - 上传分片
- `POST /api/files/upload/complete` - 完成上传
- `POST /api/files/upload/cancel` - 取消上传

### 文件夹接口
- `POST /api/folders` - 创建文件夹
- `GET /api/folders/tree` - 获取文件夹树
- `PUT /api/folders/{folderId}/rename` - 重命名文件夹
- `DELETE /api/folders/{folderId}` - 删除文件夹

## 🔒 安全特性

- ✅ **JWT 认证** - 无状态身份验证
- ✅ **BCrypt 加密** - 密码安全存储
- ✅ **CORS 配置** - 跨域请求控制
- ✅ **文件类型验证** - 白名单机制
- ✅ **大小限制** - 单文件最大 2GB
- ✅ **存储配额** - 用户配额管理
- ✅ **预签名 URL** - 临时访问授权（1 小时）

## 📊 性能优化

| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 100MB 文件下载等待 | ~10 秒 | **立即** | 100% |
| 1GB 文件下载等待 | ~2 分钟 | **立即** | 100% |
| 服务器内存占用 | 文件大小 | **~0** | >99% |
| 并发下载能力 | 受限 | **无限制** | ∞ |

## 🌟 使用技巧

1. **拖拽上传最快** - 直接拖拽文件到浏览器，无需点击
2. **使用快捷键** - 熟练使用快捷键可提升 50% 效率
3. **批量操作** - Ctrl + 点击可多选文件
4. **快速命名** - 创建文件夹时使用预设模板
5. **面包屑导航** - 点击面包屑快速跳转
6. **善用右键菜单** - 右键点击快速访问常用操作

## 🐛 常见问题

**Q: 拖拽上传没有反应？**  
A: 确保使用最新版本的现代浏览器（Chrome、Firefox、Edge）。

**Q: 中文文件名下载乱码？**  
A: v2.0.0 已完美解决，支持所有 Unicode 字符。

**Q: 如何上传大文件？**  
A: 大于 50MB 的文件自动使用分片上传，支持最大 2GB。

**Q: 支持移动端吗？**  
A: 完全支持，界面会自动适配移动设备。

## 🚀 部署

### Docker 部署

```dockerfile
# 后端 Dockerfile
FROM gradle:8-jdk21 AS build
WORKDIR /app
COPY . .
RUN gradle bootJar --no-daemon

FROM openjdk:21-jdk-slim
WORKDIR /app
COPY --from=build /app/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```

```dockerfile
# 前端 Dockerfile
FROM node:18 AS build
WORKDIR /app
COPY web/package*.json ./
RUN npm install
COPY web/ .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
```

### Docker Compose

完整的 Docker Compose 部署方案，包含所有必需的服务：

1. **使用 Docker Compose 启动应用**：
   ```bash
   # 在项目根目录执行
   docker-compose up -d
   ```

2. **访问应用**：
   - 前端界面：http://localhost
   - 后端 API：http://localhost:8080
   - MinIO 控制台：http://localhost:9001 (用户名: minioadmin, 密码: minioadmin)
   - PostgreSQL 数据库：localhost:5432

3. **停止应用**：
   ```bash
   docker-compose down
   ```

4. **重新构建镜像**（当代码更新后）：
   ```bash
   docker-compose up -d --build
   ```

完整的 `docker-compose.yml` 文件如下：

```yaml
version: '3.8'

services:
  # PostgreSQL Database for the application
  postgres:
    image: postgres:15-alpine
    container_name: mini-netdisk-postgres
    environment:
      POSTGRES_DB: mini_netdisk
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
      interval: 10s
      timeout: 5s
      retries: 5

  # MinIO Object Storage for file uploads
  minio:
    image: minio/minio:RELEASE.2025-01-24T16-29-01Z
    container_name: mini-netdisk-minio
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:9000/minio/health/live" ]
      interval: 30s
      timeout: 20s
      retries: 3

  # Backend Spring Boot Application
  backend:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mini-netdisk-backend
    depends_on:
      postgres:
        condition: service_healthy
      minio:
        condition: service_healthy
    environment:
      SPRING_PROFILES_ACTIVE: prod
      APP_DATASOURCE_URL: jdbc:postgresql://postgres:5432/mini_netdisk
      APP_DATASOURCE_USERNAME: postgres
      APP_DATASOURCE_PASSWORD: postgres
      MINIO_ENDPOINT: http://minio:9000
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
      MINIO_BUCKET_NAME: netdisk
      JWT_SECRET: super-secure-jwt-secret-key-change-in-production
      SERVER_PORT: 8080
    ports:
      - "8080:8080"
    restart: unless-stopped

  # Frontend Vue.js Application
  frontend:
    build:
      context: ./web
      dockerfile: Dockerfile
    container_name: mini-netdisk-frontend
    depends_on:
      - backend
    ports:
      - "80:80"
    environment:
      VITE_API_BASE_URL: http://localhost:8080
    restart: unless-stopped

volumes:
  postgres_data:
  minio_data:
```

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

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

## 📝 更新日志

### v2.0.0 (2025-01-13)
- ⚡ 实现秒下载技术（预签名 URL）
- 🎨 全新 UI 设计（悬浮按钮、拖拽上传）
- ✨ 新增批量操作功能
- ⌨️ 添加快捷键系统
- 🖱️ 全面支持右键菜单操作
- 🏗️ 重构架构（视图与逻辑分离、Composables 模式）
- 🐛 修复中文文件名编码问题
- 📱 优化移动端体验
- 🚀 性能优化（内存、速度）
- 📚 完善架构文档和最佳实践

### v1.0.0 (2024-10-29)
- 🎉 首次发布
- ✨ 基础文件管理功能
- 👤 用户系统
- 📁 文件夹管理

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- [Spring Boot](https://spring.io/projects/spring-boot)
- [Vue.js](https://vuejs.org/)
- [MinIO](https://min.io/)
- [Element Plus](https://element-plus.org/)
- [Tailwind CSS](https://tailwindcss.com/)

---

**⭐ 如果这个项目对你有帮助，请给它一个星标！**

**Made with ❤️ by Mini Netdisk Team**