r-pan - 技术栈

一、项目概况

1.1项目简介

r-pan 是一款基于 Spring Boot 构建的云盘服务端系统，提供文件存储、管理、分享等核心功能，支持多种存储引擎的灵活切换。

1.2 技术架构

|-------|----------------|---------------|
| 分类 | 技术 | 版本 |
| 语言 | Java | 1.8 |
| 框架 | Spring Boot | 2.2.5.RELEASE |
| ORM | MyBatis-Plus | 3.3.2 |
| 数据库 | MySQL | 8.0.11 |
| 缓存 | Redis | - |
| 认证 | JWT | 0.7.0 |
| API文档 | Swagger2 | 2.8.0 |
| 存储引擎 | 本地/FastDFS/OSS | - |
| | | |

1.3 项目结构

java 复制代码

r-pan/
├── framework/           # 框架层（可复用模块）
│   ├── core/            # 核心工具类、异常处理、响应封装
│   ├── cache/           # 缓存模块（Redis/Caffeine）
│   ├── storage-engine/  # 存储引擎抽象（本地/FastDFS/OSS）
│   ├── schedule/        # 定时任务框架
│   ├── swagger2/        # Swagger2配置
│   └── web/             # Web相关配置
├── server/              # 业务层（核心业务逻辑）
│   └── src/main/java/com/ppc/pan/server/
│       ├── common/      # 通用配置（AOP、事件监听、定时任务）
│       └── modules/     # 业务模块
│           ├── user/           # 用户管理（注册、登录、密码）
│           ├── file/           # 文件管理（上传、下载、预览）
│           ├── share/          # 分享管理（分享链接、分享码）
│           ├── recycle/        # 回收站管理
│           ├── log/            # 日志管理
│           └── test/           # 测试接口
├── distribution/        # 部署打包配置
└── pom.xml              # Maven 父工程

1.4 核心功能模块

|---------|------------------------------|
| 模块 | 功能说明 |
| user | 用户注册、登录、密码修改、搜索历史管理 |
| file | 文件上传（支持分片）、下载、预览、删除、搜索、移动、复制 |
| share | 生成分享链接、验证分享码、保存分享文件到我的云盘 |
| recycle | 文件恢复、彻底删除、回收站列表查询 |
| log | 错误日志记录与管理 |

二、启动说明

2.1 环境要求

|-------|-------------|
| 依赖 | 版本要求 |
| JDK | 1.8+ |
| Maven | 3.6+ |
| MySQL | 5.7+ / 8.0+ |
| Redis | 5.0+ |

2.2 配置修改

修改 server/src/main/resources/application.yaml 文件：

java 复制代码

spring:
  redis:
    database: 15
    host: localhost          # 修改为你的Redis地址
    port: 6379
    password: your_redis_pwd # 修改为你的Redis密码
  
  datasource:
    username: root
    password: your_mysql_pwd # 修改为你的MySQL密码
    url: jdbc:mysql://localhost:3306/r_pan?characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true

# 存储引擎配置（三选一）

# 方式1：使用本地存储
# com:
#   ppc:
#     pan:
#       storage:
#         engine:
#           local:
#             storage-path: /data/r-pan/storage

# 方式2：使用FastDFS
# com:
#   ppc:
#     pan:
#       storage:
#         engine:
#           fdfs:
#             connect-timeout: 600
#             tracker-list:
#                - your_fdfs_host:22122
#             group: your_group

# 方式3：使用阿里云OSS（当前默认配置）
com:
  ppc:
    pan:
      storage:
        engine:
           oss:
               bucket-name: your_bucket_name
               endpoint: oss-cn-shanghai.aliyuncs.com
               access-key-id: your_access_key
               access-key-secret: your_access_secret
               auto-create-bucket: true

2.3 数据库初始化

执行 distribution/conf/db.sql 初始化数据库表结构：

sql 复制代码

CREATE DATABASE IF NOT EXISTS r_pan CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE r_pan;
-- 执行 db.sql 中的表创建语句

2.4 启动方式

方式一：Maven 直接运行

java 复制代码

cd c:\Users\ppc\Desktop\项目\r-pan
mvn clean compile
mvn spring-boot:run -pl server -am

方式二：打包后运行

java 复制代码

cd c:\Users\ppc\Desktop\项目\r-pan
mvn clean package -DskipTests

# 运行打包后的 Jar
java -jar server/target/r-pan-server.jar

方式三：使用 distribution 打包（推荐生产环境）

java 复制代码

cd c:\Users\ppc\Desktop\项目\r-pan
mvn clean package -DskipTests -pl distribution -am

# 解压并运行
unzip distribution/target/r-pan-distribution.zip
cd r-pan-distribution

# Windows
bin/startup.cmd

# Linux/Mac
bin/startup.sh

2.5 验证启动

启动成功后访问：

|------------------------------------------------------------------------------------------------------------------------|----------------------|
| 地址 | 说明 |
| http://localhost:8082/swagger-ui.html | Swagger API 文档 |
| http://localhost:8082/doc.html | Swagger Bootstrap UI |
| http://localhost:8082/actuator/health | 健康检查接口 |

三、项目优点

3.1 架构设计

模块化拆分：框架层（ framework ）与业务层（ server ）分离，核心能力可复用
存储引擎抽象：通过接口抽象支持本地存储、FastDFS、阿里云 OSS 的灵活切换
事件驱动架构：使用 Spring Event 实现文件删除、恢复等操作的解耦

3.2 技术特性

|--------|-----------------------|
| 特性 | 说明 |
| 文件分片上传 | 支持大文件分片上传，断点续传 |
| JWT 认证 | 无状态认证，支持 Token 过期刷新 |
| AOP 切面 | 统一登录校验、分享码校验 |
| 定时任务 | 自动清理过期分片文件 |
| 多级缓存 | Redis + Caffeine 两级缓存 |
| API 文档 | 集成 Swagger2，自动生成接口文档 |

3.3 业务功能

- 完整的文件管理：上传、下载、预览、搜索、复制、移动、重命名
- 分享功能：支持带有效期、带提取码的分享链接
- 回收站机制：支持文件恢复和彻底删除
- 搜索历史：记录用户搜索关键词

3.4 代码规范

- 使用 Lombok 简化实体类代码
- 使用 MapStruct 实现对象转换
- 使用 Hutool 工具库提升开发效率
- 统一响应封装（ R<T> ）和异常处理

四、配置说明

4.1 端口配置

默认端口： 8082 ，可在 application.yaml 中修改：

java 复制代码

server:
  port: 8082

4.2 Swagger 开关

java 复制代码

swagger2:
  show: true  # true 开启，false 关闭

4.3 文件上传大小限制

java 复制代码

spring:
  servlet:
    multipart:
      max-file-size: 3072MB    # 单个文件最大 3GB
      max-request-size: 3072MB # 请求最大 3GB

五、目录结构详解

java 复制代码

server/src/main/
├── java/com/ppc/pan/server/
│   ├── RPanServerLauncher.java    # 启动类
│   ├── common/                    # 通用组件
│   │   ├── annotation/            # 自定义注解
│   │   ├── aspect/                # AOP 切面
│   │   ├── config/                # 配置类
│   │   ├── event/                 # 事件定义
│   │   ├── listenner/             # 事件监听器
│   │   ├── schedule/              # 定时任务
│   │   └── utils/                 # 工具类
│   └── modules/                   # 业务模块
│       ├── user/                  # 用户模块
│       ├── file/                  # 文件模块
│       ├── share/                 # 分享模块
│       ├── recycle/               # 回收站模块
│       └── log/                   # 日志模块
└── resources/
    ├── application.yaml           # 应用配置
    ├── mappers/                   # MyBatis Mapper XML
    └── banner.txt                 # 启动 banner

六、核心业务流程图

文件上传流程

java 复制代码

客户端请求 → FileController → IFileService → 
    文件分片校验 → StorageEngine（存储引擎） → 
    RPanFile/RPanUserFile（数据库持久化） → 返回文件信息

用户登录流程

java 复制代码

用户请求 → UserController → IUserService → 
    查询用户 → 密码校验 → 生成 JWT Token → 返回用户信息

分享流程

java 复制代码

创建分享 → ShareController → IShareService → 
    生成分享链接 → 生成提取码 → RPanShare（数据库持久化） → 返回分享信息
    
访问分享 → 校验分享码 → 获取分享详情 → 保存到用户云盘

七、总结

r-pan 后端项目是一个架构清晰、功能完整、扩展性强的云盘服务端系统，具备以下特点：

高可扩展性：存储引擎可灵活切换，便于后续扩展至其他云存储服务
代码质量高：遵循分层架构设计，代码结构清晰，易于维护
安全性强：JWT 认证、密码加密、权限校验等安全机制完善
开发体验好：集成 Swagger2 自动生成 API 文档，便于前后端联调

如需了解更多细节，可查看源码或访问 http://localhost:8082/doc.html 查看完整的 API 文档。

关键设计思想：

- 关注点分离：框架层与业务层解耦，核心能力可复用
- 策略模式：存储引擎通过接口抽象，支持多种实现切换
- 事件驱动：文件操作通过 Spring Event 解耦

关键设计模式

- 策略模式： StorageEngine 接口，支持 Local/FastDFS/OSS 切换
- 观察者模式：Spring Event 实现文件删除、恢复等操作的异步处理
- 门面模式：Service 层封装复杂业务逻辑，对外提供简洁接口
- 工厂模式：根据配置动态创建不同的存储引擎实例

数据库设计

核心表结构：

|------------------|--------|----------------------------------------------|
| 表名 | 作用 | 关键字段 |
| r_pan_user | 用户信息 | user_id, username, password(加密), create_time |
| r_pan_file | 文件元数据 | file_id, real_name, size, storage_path |
| r_pan_user_file | 用户文件关系 | user_file_id, user_id, file_id, parent_id |
| r_pan_share | 分享信息 | share_id, user_id, expire_time, share_code |
| r_pan_file_chunk | 分片信息 | chunk_id, file_id, chunk_number, chunk_size |

表关系：

r_pan_user_file 通过 user_id 关联 r_pan_user
r_pan_user_file 通过 file_id 关联 r_pan_file
r_pan_share_file 关联 r_pan_share 和 r_pan_file

全性

密码加密：使用 BCrypt 或 MD5 + 盐值加密存储 JWT 认证：Token 包含用户 ID，设置过期时间，支持刷新机制权限校验：AOP 切面统一拦截，校验用户登录状态文件访问控制：验证文件所有权，防止越权访问

性能优化

分片上传：大文件分片处理，支持断点续传缓存策略：Redis 缓存用户信息、文件列表、分享链接异步处理：文件物理删除通过事件异步执行，不阻塞主线程数据库优化：合理索引设计，避免全表扫描

存储引擎设计

java 复制代码

// 存储引擎接口
public interface StorageEngine {
    String store(File file, String path);      // 存储文件
    InputStream load(String path);             // 读取文件
    void delete(String path);                  // 删除文件
    boolean exists(String path);               // 判断文件是否存在
}

三种实现：

LocalStorageEngine ：本地磁盘存储
FastDFSStorageEngine ：FastDFS 分布式存储
OSSStorageEngine ：阿里云 OSS 存储