本项目是一个基于 Spring Boot 与 Vue 3 的前后端分离系统，面向个人和小型团队的文件存储、共享与协作场景。系统围绕文件全生命周期管理进行设计，实现了上传、检索、分享、协作、备份与监控等核心能力，可作为毕业设计、课程设计和工程化实践项目使用。
在教学与办公场景中，用户常常需要跨设备管理文件、与他人共享资料，并在同一文档上进行实时协作。传统文件传输方式存在管理分散、权限控制薄弱、协作效率低等问题。本项目以云盘系统为载体，结合对象存储、实时通信与权限控制机制，构建一套可部署、可扩展、可维护的文件分享平台。
项目目标如下：
- 提供完整且安全的文件管理与分享能力。
- 支持大文件上传、断点续传和秒传，提升传输效率。
- 支持多人实时协作，提升团队协同体验。
- 提供备份恢复与运行监控，增强系统可运维性。
系统功能围绕“用户身份、文件资产、传输效率、共享协作、数据安全”五个核心目标展开，覆盖从注册登录、文件管理，到分享、协作、运维保障的完整链路。下面按照实际业务使用路径进行展开，便于在论文、答辩和项目演示中直接说明。
作用：负责系统入口控制、身份识别和权限边界划分，是所有业务功能运行的前提。
- 提供用户注册、登录、退出登录、密码修改和个人资料维护等基础生命周期能力，支持用户从首次进入系统到长期使用的完整流程。
- 登录后通过 JWT 签发访问令牌，后续请求由统一过滤器解析用户身份并注入上下文，避免服务端维护传统会话状态，更适合前后端分离部署。
- 通过角色和权限控制区分普通用户、管理员和系统内部接口，确保文件管理、分享管理、备份运维等敏感操作只能由授权主体访问。
- 对公开接口、登录接口、受保护接口和管理接口进行分层处理，减少未授权访问和越权调用的风险。
- 用户身份信息不仅用于鉴权，也会作为文件归属、协作成员、分享访问、行为日志等业务记录的基础字段，形成完整的可追踪链路。
作用：负责文件从进入系统到最终被使用、整理和归档的全过程，是网盘系统最核心的业务能力。
- 支持文件上传、下载、在线预览、重命名、移动、复制、收藏、删除等高频操作，覆盖用户日常文件管理的大部分场景。
- 支持目录层级管理，用户可以像本地文件系统一样创建文件夹、整理资源、移动目录和构建个人文件树，提升资源组织效率。
- 文件上传前会进行基础元数据校验、文件名规范检查、存储路径计算和重复文件检测，避免脏数据进入系统。
- 文件下载和预览会先完成权限校验，再定位到真实存储资源并输出流，保证每次访问都经过授权判断。
- 文件管理操作与数据库记录、实际存储对象、回收站状态保持一致，避免出现“数据库有记录但文件丢失”或“文件存在但记录缺失”的不一致问题。
作用：提升大文件场景下的传输稳定性和速度，减少网络波动对用户体验的影响。
- 支持分片上传，前端将大文件切分为多个小块并发传输，后端按分片索引接收后落盘到临时目录，降低单次请求压力。
- 支持断点续传，上传过程中如果网络中断或页面刷新，用户可以只补传缺失分片，而不必从头开始传输整个文件。
- 支持基于哈希的秒传机制，当目标文件的哈希值已经存在时，可以直接复用已有文件对象，显著减少重复上传时间。
- 文件分片完成后会执行合并和完整性校验，确保最终生成的文件与源文件一致，避免出现分片丢失或内容损坏。
- 该能力特别适合课程项目、资料包、视频、压缩包等大体积资源上传场景，在网络不稳定时仍能保持较好的用户体验。
作用：实现“受控共享”，在保证权限边界的前提下让文件能够安全流转到系统内外。
- 支持生成短链分享链接，用户可以将资源快速分发给他人，而无需暴露完整文件路径或内部实现细节。
- 支持设置提取码、有效期、访问限制和下载限制，避免链接被长期滥用或被无关人员随意访问。
- 支持一次性下载令牌，访问一次后即失效，适合临时交付、敏感资料传递和短时协作场景。
- 支持文本快传和文件快传，既可以分享一段临时文本，也可以快速分发单个文件或附件。
- 系统会记录分享访问、提取码验证和下载行为，为后续统计分析、审计追溯和安全排查提供依据。
作用：支持多人在线编辑和交流，把传统网盘扩展为具备团队协同能力的平台。
- 支持协作项目、成员管理、文档管理和评论交流等完整协作流程，适合小组作业、团队文档和联合编辑场景。
- 基于 WebSocket 建立长连接，实现低延迟消息广播，使多人修改内容时能够快速看到彼此的变更。
- 采用增量协同模式，通过实时同步编辑内容而不是反复发送整份文档，减少传输量并提升同步效率。
- 通过会话和房间机制隔离不同协作空间，避免不同项目之间的消息串扰和数据混发。
- 初始同步、后续增量更新和断线重连机制共同保证多端状态一致，使编辑体验更接近实时协作软件。
作用：保障系统在日常使用、异常恢复和生产维护中的可靠性，是系统长期可用的基础。
- 支持回收站机制，删除的文件默认进入可恢复状态而不是立即物理删除，降低误删带来的损失。
- 支持全量备份、增量备份、备份校验和恢复操作，可用于日常维护、容灾演练和故障回滚。
- 提供健康检查和监控指标输出，便于观察系统状态、排查异常和评估容量情况。
- 本地存储与 MinIO 双模式可切换，既能满足教学环境下的本地部署，也能满足对象存储场景下的生产化使用。
- 运维能力不仅关注“系统能运行”，也关注“系统出问题后能恢复”，因此在备份、校验、恢复和日志追踪上都进行了设计。
建议环境如下：
- 操作系统：Windows、Linux 或 macOS。
- JDK：17 或以上。
- Maven：3.6 或以上。
- Node.js：18 或以上。
- MySQL：8.0 或以上。
- Docker：20.10 或以上，Compose Plugin 2.x（用于容器化部署）。
主要技术栈如下：
- 后端：Spring Boot 2.7.5、Spring Security、Spring Data JPA、WebSocket、Actuator、MinIO SDK。
- 前端：Vue 3、TypeScript、Vite 5、Pinia、Vue Router、Element Plus。
- 初始化数据库。
- 执行根目录 SQL 脚本 setup_mysql.sql 或 database_setup.sql。
- 根据实际环境修改 src/main/resources/application.yml 中的数据库连接配置。
- 启动后端。
- 在项目根目录执行 mvn spring-boot:run。
- 默认提供 HTTPS 8443，HTTP 8080 将重定向到 8443。
- 启动前端。
- 进入 frontend 目录后执行 npm install 与 npm run dev。
- 前端默认访问地址为 http://localhost:3000。
- 确保服务器已安装 Docker 与 Docker Compose Plugin。
- 在项目根目录执行 docker compose up -d --build。
- 启动后可访问前端与后端服务，并通过 docker compose logs -f backend frontend 查看日志。
- 停止服务执行 docker compose down。
- 替换所有默认口令与密钥（MySQL、MinIO、JWT、证书口令）。
- 收紧 CORS 允许域名，避免全开放策略。
- 挂载持久化卷保存数据库、对象存储与备份目录。
- 配置 HTTPS 证书并启用监控告警与定时备份。
- 如果部署在阿里云服务器且 Docker 拉取镜像较慢或超时，先配置 Docker 镜像加速器；仓库中提供了 docker/daemon.json.example 作为参考。
项目核心目录如下：
- src/main/java/com/filesharing：后端业务代码。
- src/main/resources：后端配置文件与证书资源。
- src/test：后端测试代码。
- frontend：前端工程。
- docker/minio：MinIO 初始化脚本。
- scripts：辅助脚本与测试脚本。
- docker-compose.yml：整体容器编排入口。
- Dockerfile：后端镜像构建文件。
作用：保证系统访问安全，建立统一身份认证与权限校验机制。
- 认证方式采用 Spring Security + JWT，无状态会话便于前后端分离部署和横向扩展，也更适合多实例部署和容器化运行。
- 登录成功后签发令牌，后续请求由过滤器统一解析并注入用户身份，避免每次访问重复登录，同时降低服务端会话管理复杂度。
- 对公开接口、受保护接口和管理接口进行分层控制，确保文件读写、协作编辑、备份管理等高风险操作都要经过明确授权。
- 统一处理 CORS、异常响应和鉴权失败场景，前端能够拿到稳定且可识别的错误信息，减少前后端联调时的歧义。
- 该模块是其他业务模块的入口保障，任何文件读写、分享管理、协作编辑和运维接口都依赖该模块提供的用户上下文。
- 在实际请求链路中，认证不仅决定“谁可以访问”，也决定“可以访问哪些资源”和“以什么身份记录行为”，因此它是整个系统的安全基座。
作用：管理用户基础信息和个人网盘空间边界，是所有业务数据的归属基础。
- 提供注册、登录、个人资料维护、头像或昵称更新、密码修改等用户生命周期能力，覆盖从创建账号到长期使用的主要操作。
- 为每个用户维护独立文件树和资源统计，确保不同用户数据天然隔离，避免文件归属混乱或跨用户可见。
- 用户空间不仅保存文件资源，也保存文件夹层级、收藏状态、删除状态、分享记录等关联数据，使个人空间具备完整状态。
- 在用户维度记录行为轨迹，为搜索排序、推荐计算和运营统计提供数据来源，也便于排查异常登录和异常访问。
- 与认证模块协同，确保用户操作可追踪、可审计，尤其是上传、删除、分享和恢复等敏感动作都能定位到具体操作者。
- 个人空间是“账户”与“文件资产”之间的桥梁：用户一旦登录，就会绑定到自己的资源空间，后续所有资源读写都在该边界内运行。
作用：负责文件从上传到下载的全流程处理，是系统的核心业务引擎。
- 文件上传阶段负责元数据校验、存储路径计算、重复文件检测和持久化记录，确保每个文件在进入系统前都经过基础治理。
- 文件下载阶段负责权限校验、资源定位和响应流输出，保证下载链路稳定，并避免直接暴露底层存储路径。
- 文件管理能力覆盖重命名、移动、复制、收藏、删除等高频操作，用户可以像管理本地文件一样管理云端资源。
- 提供统一存储抽象，支持本地磁盘与 MinIO 两种后端，实现存储介质可切换，便于适配不同部署环境。
- 通过业务层封装屏蔽底层差异，上层控制器无需关注具体存储实现，只需调用统一的文件服务接口即可完成业务动作。
- 该模块还负责维护数据库记录与实际文件对象的一致性，确保“元数据、权限状态、实际文件、回收站状态”同步变化。
- 如果从系统设计角度看，这一层就是文件生命周期的“中台”，上承用户与权限，下接存储与外部访问。
作用：提升大文件传输效率，降低网络抖动对上传体验的影响。
- 前端将大文件切片后并发上传，后端按分片索引接收并落盘到临时目录，降低单次请求压力。
- 支持断点续传，上传过程中如果网络中断或页面刷新，用户可以只补传缺失分片，而不必从头开始传输整个文件。
- 支持基于哈希的秒传机制，当目标文件的哈希值已经存在时，可以直接复用已有文件对象，显著减少重复上传时间。
- 文件分片完成后会执行合并和完整性校验，确保最终生成的文件与源文件一致，避免出现分片丢失或内容损坏。
- 该能力特别适合课程项目、资料包、视频、压缩包等大体积资源上传场景，在网络不稳定时仍能保持较好的用户体验。
- 分片临时目录、合并目录和最终存储目录之间是分阶段流转关系，这种设计便于做重试、清理和异常恢复。
- 从工程角度看，它把“高延迟、易失败的大文件上传”拆解成“可重试、可校验、可恢复”的小步骤，极大提升了可用性。
作用：实现“受控共享”，让文件在系统内外安全流转。
- 支持创建分享链接、设置提取码、有效期和访问限制，用户可以按场景决定“谁能看、能看多久、能下载几次”。
- 支持一次性下载令牌，降低分享链接被重复滥用的风险，适合短期交付、临时审批和敏感内容传递。
- 快传功能覆盖文本快传与文件快传，既能快速发送一段临时文本，也能完成单文件的轻量分发。
- 分享链路中会记录访问和下载行为，便于后续统计分析、异常追踪和权限回溯，满足课程项目中常见的审计需求。
- 该模块在易用性与安全性之间做平衡：既让共享足够简单，又通过提取码、有效期和令牌把访问范围控制住。
- 在业务设计上，分享更偏“长期可访问的公开能力”，快传更偏“短时临时交付能力”，两者覆盖不同的协作需求。
- 通过这种受控共享机制，系统既能支持对外分享，也能避免资源链接无边界扩散。
作用：提升文件检索效率和资源发现能力，减少用户查找成本。
- 提供关键词搜索、基础排序与结果筛选能力，用户可以从标题、标签、内容或历史记录中快速定位目标资源。
- 推荐模块根据用户行为、文件热度、时间衰减等特征生成候选结果，尽量把“可能有用”的内容推到用户面前。
- 通过策略组合输出“可能需要的文件”，提高常用资源命中率，减少用户反复搜索相同内容的成本。
- 关键实现位于 SmartRecommendationServiceImpl.java，便于在论文中说明推荐逻辑和代码入口。
- 该模块体现了从“被动查询”到“主动推荐”的体验升级，使系统不仅能存，还能帮用户找和发现资源。
- 搜索与推荐并不是两个完全独立的能力：搜索解决“我现在要找什么”，推荐解决“我可能还需要什么”。
- 当系统积累足够行为数据后，该模块还可以进一步扩展为更复杂的排序策略、标签推荐或资源聚合能力。
作用：支持多人同步编辑与互动，增强团队协同效率。
- 基于 WebSocket 建立长连接，实现低延迟消息广播，使多人协作时的变更能够尽快同步到其他客户端。
- 使用 Yjs 增量协同模式（Y.Doc/Y.Text），通过 update 直发直收实现 CRDT 自动合并，降低并发编辑冲突的处理复杂度。
- 支持协作项目、成员管理、文档编辑、评论交流等完整协作流程，适合课程小组、团队文档和项目资料协同。
- 通过会话与房间机制隔离协作上下文，避免消息串扰，确保不同文档、不同项目、不同房间之间互不影响。
- 通过初始同步握手与房间转发机制保障多端状态一致，使新加入成员能够快速获得当前文档状态。
- 该模块将传统网盘扩展为协同工作平台，是系统差异化亮点之一，也最能体现“文件平台不只是存储”的设计思路。
- 从实际使用体验看，它把“文件分享”进一步升级为“在线共同编辑和讨论”，让平台具备更明显的团队协作属性。
作用：降低误删风险，实现文件删除的可恢复管理。
- 删除操作默认进入回收站而非立即物理删除，提升容错能力，用户误删后仍有机会恢复资源。
- 支持手动恢复、批量恢复和彻底删除，满足“找回误删文件”和“永久清理无用文件”两类不同需求。
- 支持过期清理策略，平衡数据安全与存储成本，避免回收站长期堆积导致资源占用过高。
- 与文件服务模块协同，保证数据库记录与存储对象状态一致，防止出现回收站状态和真实文件状态不一致的问题。
- 回收站不仅是“删了之后找回来”的工具，也是整个文件生命周期管理的重要一环，可以帮助用户更稳妥地整理资源。
- 这个模块在教学场景里尤其重要，因为学生在整理资料、提交作业或批量移动文件时更容易产生误操作。
作用：保障数据安全与系统可维护性，是生产可用性的关键支撑。
- 支持全量备份与增量备份，覆盖数据库与文件资源，能够根据场景选择完整备份或仅备份变化内容。
- 支持备份校验、恢复和异步任务管理，便于在大数据量场景下执行维护操作，同时避免长时间阻塞主业务线程。
- 提供健康检查和关键指标输出，用于故障发现和容量评估，帮助管理员及时发现系统异常或资源瓶颈。
- 与 Docker 部署方案配合可实现定时备份与容灾演练，使系统具备更完整的生产运维思维。
- 该模块确保系统不仅“能用”，还具备持续运行与恢复能力，尤其适合强调可靠性和数据安全的项目展示。
- 备份恢复能力与回收站机制形成互补：前者解决“灾后恢复”，后者解决“误操作恢复”，共同构成数据保护闭环。
- 从架构角度看，这一模块让系统具备了基本的运维闭环，体现了从功能型项目向可维护系统的升级。
本系统安全能力由“认证鉴权、接口防护、上传防护、访问控制、错误收敛”五部分组成，统一目标是降低未授权访问、恶意上传与信息泄露风险。
- 基于 Spring Security + JWT 的无状态认证。
- 令牌中包含用户标识与角色信息，后端过滤器自动完成权限注入。
- 管理类接口按角色限制访问，避免普通用户越权调用。
- CORS 使用白名单来源，避免全开放跨域。
- 启用 CSRF 防护，并仅对必要公共路径进行豁免。
- 支持全局与接口级限流，超阈值请求返回 429。
- 上传大小限制与后缀白名单校验。
- 禁止可执行与脚本类后缀（如 exe、jsp、sh、ps1 等）。
- 对文本类内容执行基础恶意脚本特征扫描。
- 分片上传链路增加 uploadId 格式校验与路径规范化，防止路径穿越。
- 统一异常处理，避免将内部堆栈和敏感细节直接返回前端。
- 关闭默认错误详情暴露，减少内部实现信息泄露。
- 日志级别按生产建议收敛，降低敏感数据输出风险。
- 必须替换默认账号口令和 JWT 密钥。
- 按实际域名配置 CORS 白名单与 HTTPS 证书。
- 对数据库、对象存储、后端管理端口启用网络访问隔离。
- 上线前执行一次接口权限与上传安全回归测试。