说实话2025年这个节点再听到我又写了一个文件管理系统多数人第一反应是又来了。但真正在企业里做过文档中台、网盘落地、知识库建设的人大概率会停下来多看两眼——因为市面上能打的国产开源企业级文件管理选项真的太少了。要么是重量级商业套件的社区版阉割得没法用要么是某个内部项目开源出来但代码风格和文档都还停留在能跑就行的阶段。这个项目的出现让我比较兴奋的点在于它的技术底子是 Spring Boot 3.5.x Sa-Token MyBatis Flex一个非常新的组合也恰好是当前 Spring Boot 向 4.x 过渡节点上大家都想尝试的搭配。它不是一个简单的上传下载 demo而是奔着企业级文件管理去的多租户、权限隔离、文件预览、分片上传、审计日志这些硬骨头都有涉及。这篇文章我会把它拆开来讲为什么在这个时间点还要造一个文件管理的轮子三个核心框架各自解决了什么问题整体架构和数据库设计怎么落权限模型怎么做到防横纵越权上传预览具体实现有哪些细节以及从开发到部署我会踩到什么坑。如果你正打算自己做一套文件管理服务或者想找一个干净、现代化、便于二次开发的开源项目当底座这篇文章应该能帮你省掉不少摸石头过河的时间。1. 为什么2025年还要再做一款文件管理系统企业文件场景的隐性痛点先泼一盆冷水做文件管理系统技术上的难点从来不是把文件存下来。OSS、S3、MinIO 这些对象存储早就把存储底座做成熟了。真正麻烦的是企业文件这四个字背后的隐性需求它们常年被低估。1.1 网盘和个人工具解决不了企业协作问题个人网盘的核心是同步和分享但企业文件管理的核心是边界谁能看这个文件、谁能改、谁能删、谁能分享给外部临时协作伙伴。个人工具默认所有文件都是我的而企业场景默认所有文件都是组织的我只是有使用权。这就导致权限模型完全不同。大多数团队一开始会用局域网共享文件夹 各部门自觉来管理后面必然陷入混乱找不到最新版本文档、离职员工手里还攥着旧文件、内网盘上堆积大量重复文件。换到开源网盘项目之后又发现那些项目大多是个人网盘定位做做家庭影音库很好但组织架构、角色权限、操作审计这些企业刚需基本没有二次开发成本高到不如重写。1.2 已有的企业级开源方案要么太重要么断更国际上有名的企业文件同步分享方案部署复杂度堪比小型 ERP对中小团队来说维护成本实在太高。国产项目里又能私有化、又能拿到源代码、文档清楚明白的掰着指头数得过来。很多事情就是等到动手做才发现原来这个领域留给轻量但企业级的空档这么大。这也是这个项目让我觉得有价值的原因它不做大而全的协同办公平台聚焦在文件本身——存储、组织、权限、流转、审计。有了这几个基础能力企业和团队完全可以拿它当底座上面再接在线编辑、内容审批、知识库这些业务。1.3 从能用到好用的差距往往在细节文件管理系统做到能用只需要 CRUD 加文件流但做到好用细节全是魔鬼上传一个大文件中断了能不能断点续传客户发来一个 .dwg 图纸浏览器能预览吗还是要下载到本地用专业软件打开部门 A 的老张把机密合同分享给了部门 B 的小李管理员事后能不能在审计日志里还原这件事网盘里 10 个同名文件最终版 v7到底哪一个才是真的最终版这些问题在后文会逐一展开看这个项目是怎么处理的。先记住一个结论企业文件管理的核心竞争力不在存储在于围绕文件构建的组织秩序。2. 技术选型复盘Spring Boot 3.5.x、Sa-Token、MyBatis Flex 的组合逻辑我见过太多先进技术堆砌的项目最后死于过度设计。所以看到这套技术栈时我特地确认了它是不是为用而用。拆开看每个选型其实都有明确的问题对应关系。2.1 Spring Boot 3.5.x站在 4.x 前夜的最稳版本现在聊 Spring Boot 3.5.x有个绕不开的背景就是 4.0 已经发布。很多人会问为什么不等 4.x为什么不直接上 4.x我的判断是3.5.x 是目前生产可用的最稳版本。4.x 刚出来生态迁移还需要时间尤其是一些第三方 starter 和老项目的兼容性。而 3.5.x 作为 3.x 系列的后期版本吸收了前几个版本的大量 bug 修复同时完整支持 Java 21 的虚拟线程、GraalVM 原生镜像这些现代能力。对企业级项目来说新不是第一诉求稳且能平滑升级才是。Spring Boot 3.5.x 对开发者来说最直观的几个变化底层是 Spring Framework 6.2默认使用 Jakarta EE 命名空间自动配置类依然强大但定位越来越显式——比如DataSourceAutoConfiguration这类核心配置在 4.x 里调整了包路径如果你是从老项目升级第一反应就是找不到类这个后面部署部分我专门聊。还有就是对结构化日志、可观测性的支持更完善这对文件系统这种慢操作多、异步任务多的场景很重要。在这个项目里Spring Boot 负责的是标准的三层骨架搭建接口层出 REST API业务层管事务和业务规则基础设施层对接存储服务和数据库。这套东西用 Spring Boot 做最顺手生态里任何中间件都有现成 starter团队招人也容易上手。2.2 Sa-Token为什么不用 Spring Security 或者 Shiro这个选择我可以说是全场最让我点头的决定。文件管理系统的权限需求非常具体登录认证 会话管理RBAC 角色权限模型多租户/组织架构级别的数据权限隔离临时分享链接的独立认证体系防止横向越权同级别用户互相访问资源和纵向越权低权限用户访问高权限资源。Spring Security 能做这些但它的学习曲线和配置复杂度在中小项目里完全是过度设计。我曾经在一个项目里调 Spring Security 的过滤链一个 CORS 和认证顺序问题折腾了两个工作日。Shiro 相对轻量但近年更新节奏慢和 Spring Boot 3.x 的适配感觉也是能用但别指望多舒服。Sa-Token 是国产开源权限框架里近年口碑蹿升最快的。它对 Spring Boot 3.x 的适配很及时核心 API 极其简洁登录就是一个StpUtil.login(userId)校验就是一个StpUtil.checkLogin()判断是否拥有某权限就是StpUtil.checkPermission(file:delete)。没有繁琐的配置继承体系不需要写一坨过滤器链默认就支持 Redis 集成、同端互斥登录、账号封禁、注解鉴权。在这个项目里Sa-Token 不仅做常规的用户认证和接口鉴权还承担了临时分享的认证能力——通过Sa-Token生成短期 Token 来作为分享链接的凭证。这样就不用自己再造一套会话轮子统一了认证模型。2.3 MyBatis Flex比 MyBatis-Plus 更轻比 JPA 更可控说到国产 ORM大多数团队第一反应是 MyBatis-Plus。MyBatis Flex 可能知道的人相对少一点但它在 2024 年后增长很快。为什么它适合文件管理系统这个场景文件管理的数据模型有一个特点主表结构清晰文件表、文件夹表、用户表、日志表但业务查询却充满需要精细控制 SQL的场景。比如权限隔离时必须根据当前用户和租户动态拼接数据权限片段WHERE file.owner_id #{userId} OR file.dept_id IN (SELECT dept_id FROM sys_user_dept WHERE user_id #{userId}) OR file.id IN (SELECT file_id FROM grp_file_rel WHERE group_id IN (...))这种 SQL 用 JPA 写要么走自定义Query但拼接动态条件很别扭要么走 Specifications 但代码可读性很差。MyBatis Flex 的做法是保留 MyBatis 的 SQL 自由度同时提供类似QueryWrapper的条件构造器而且它在多表关联、逻辑删除、乐观锁、数据填充这些内置能力上都做得很全。更关键的是MyBatis Flex 在启动时可以通过 APT 直接生成实体类对应的 SDK 代码类型安全程度比传统 MyBatis 的字符串 XML 高很多同时它兼容 XML Mapper老团队迁移成本低。相比 MyBatis-Plus它体积更小、社区虽然年轻但技术方案更新比如内置了多租户插件和字段加密在性能敏感的列表查询上对 SQL 的控制力也更强。所以这套技术栈的组合逻辑是需求维度选型核心理由应用骨架/REST APISpring Boot 3.5.x稳定、生态全、Java 21 支持好认证/授权/会话Sa-Token轻量、API 直观、适配 Spring Boot 3.xORM/数据访问MyBatis FlexSQL 可控 条件构造器 类型安全存储底座MinIO/本地磁盘/S3抽象存储接口按部署环境切换缓存/会话共享Redis集群部署、分布式会话、验证码这套组合兼顾了开发效率和后期可控性不极端不炫技属于那种认真做过生产项目的人会选出来的组合。3. 系统架构拆解从四层代码结构到数据库设计架构上的东西如果只说我们用了 MVC 分层其实是废话。这个项目我认为值得展开的是两点代码层面的分层组织方式以及数据库表结构如何为权限和审计服务。3.1 四层架构在文件系统里的具体落地Spring Boot 最常见的分层是 Controller / Service / Mapper 三层但这个项目按我的观察更像四层Controller 只是协议转换真正的业务编排在 Service数据访问在 Mapper另外还有一个独立支撑层。它在热词里叫spring boot四层架构说白一点就是Controller接收参数/响应包装/参数校验 ↓ Service业务规则/事务边界/事件发布 ↓ Manager/Support跨领域能力编排存储引擎切换、消息通知、异步任务 ↓ MapperSQL 读写/分页/多租户处理很多人觉得多一层 Manager 是多此一举但文件系统的业务复杂度恰恰需要这一层。举个具体例子文件业务不单纯是上传后插一条记录而是一个涉及存储服务、元数据入库、索引更新、异步通知、配额变更、审计日志记录的多步骤操作。如果这些全堆在 Service 里一个上传方法可能几百行。抽出 Manager 层后Service 只负责决定做什么Manager 负责统筹怎么做两个关注点就分开了。3.2 存储接口抽象本地磁盘、MinIO、S3 的切换方案文件管理的底座是存储。这个项目我最欣赏的设计是存储层没有绑死在某个具体对象存储上而是抽象了一套StorageService接口public interface StorageService { String upload(String bucket, String objectName, InputStream inputStream, long size, String contentType); void delete(String bucket, String objectName); InputStream download(String bucket, String objectName); boolean exists(String bucket, String objectName); String generatePresignedUrl(String bucket, String objectName, Duration duration); }底层实现可以切换三种模式本地磁盘模式部署测试用、MinIO 模式私有化生产首选、S3 兼容模式云上部署或兼容阿里云 OSS、腾讯云 COS 的场景。这样设计的意义是应用层代码完全不感知存储细节换存储底座只需要改配置文件和引入对应依赖。例如配置file: storage: type: minio # local | minio | s3 endpoint: http://192.168.1.100:9000 access-key: minioadmin secret-key: minioadmin bucket: enterprise-files针对分片上传的大文件存储服务还负责生成 uploadId 和分片 URL这能保证分片直接从前端并行上传到存储服务而不经过应用服务器中转——带宽和内存压力被大幅减轻。3.3 数据库设计的几个关键决策数据库是权限模型和审计模型的落点我挑几个关键表来说第一张是file_info文件元信息表记录文件名、扩展名、文件大小、存储桶、存储路径、文件 MD5、上传者、所属租户/部门、审核状态、是否加密字段。它和存储服务里的实体文件是一对一关系应用操作都以这张表的 ID 为主线。第二张是folder_info文件夹表通过parent_id自关联实现树形目录。因为文件系统的目录天然是树状结构查询某个目录下的所有子目录通常用parent_id做递归或者用path_code做懒加载。第三张是权限核心关联表user、role、user_role_rel、role_menu_rel/role_permission_rel。文件资源的授权不是直接挂在用户上而是通过角色 部门 个人所有者三者的组合决定可见范围。第四张是file_share分享表记录分享人、分享给谁可指定用户/部门/任何人、访问密码、有效期、分享 Token、可操作权限预览/下载/上传等。之所以单独建表而不是复用user_role是因为分享具有强时效性而且多是对外的独立凭证要和内部权限体系解耦。第五张是operate_log操作审计表每次文件上传、下载、预览、重命名、删除、分享、权限变更都会记录操作人 ID、操作类型、文件 ID、IP 地址、UA、操作时间、结果描述。这张表是企业合规审计的底线也是这个项目作为企业级最重要的证据之一。表结构设计上有一个原则我认为对做文件系统尤其重要不要把所有和文件相关的字段全塞进一张大宽表。文件元信息、扩展属性、审计日志、分享关系应该是分表设计的否则后续做权限查询和统计性能时一定会哭。3.4 核心模块地图文件网关统一接收上传/下载/预览请求做限流、格式校验、参数校验。元数据服务维护文件/文件夹表结构处理重命名、移动、复制、回收站。权限中心基于 Sa-Token 的登录认证和 RBAC 授权负责文件级 ACL 检查。传输服务处理分片上传、断点续传、秒传、下载打包。预览服务转换 office 文件为 PDF生成图片缩略图流媒体转码。分享服务管理内外部分享生成分享 Token 和访问策略。审计服务异步记录操作日志提供日志查询 API。管理后台用户管理、角色管理、存储配置、系统监控。模块间通过 Spring 事件解耦。比如文件上传成功后发布一个FileUploadCompletedEvent预览服务和审计服务监听该事件做各自的异步处理而不是在 Controller 里同步调用这个设计对接口响应速度的提升立竿见影。4. 权限体系细解Sa-Token 如何同时管好登录和防越权文件系统最怕的安全漏洞就是越权水平越权指同级用户之间越权访问比如用户 A 能看到用户 B 的私人文件垂直越权指低权限角色执行高权限操作比如普通员工删除管理员文件。热词里专门提到了sa-token 横纵越权说明这是选型时大家很关心的点。这部分结合项目实现展开。4.1 登录和会话管理的基本盘Sa-Token 接管登录态非常干净。项目在用户校验通过后执行StpUtil.login(userId); // 可同时下发角色、权限列表到会话 StpUtil.getSession().set(userInfo, userInfo);后续接口只需StpUtil.checkLogin()就能拦截未登录访问。项目还利用了 Sa-Token 的同端互斥登录配置——同一账号在同一设备类型上只能有一个有效会话新登录会顶掉旧登录这对企业信息安全是刚需。分布式部署场景下Sa-Token 可以无缝切换到 Redis 会话模式。配置sa-token.token-style: uuid或jwt项目里我建议用jwt风格并配合 Redis 做 Token 黑名单这样既支持无状态鉴权又能实现在线踢人。4.2 RBAC 文件数据权限的双层控制接口层面的权限用 Sa-Token 的角色/权限校验就够但文件资源的可见性是数据行级别的问题。比如一个用户访问/file/list接口他应该看到的文件集合是自己创建的私有文件自己所在部门共享给本部门的文件上级/管理员分享给全公司的公共文件别人通过协作功能明确授权给自己的文件。这种查询不能只靠注解判断必须在 SQL 层动态附加数据权限条件。项目里 MyBatis Flex 的多租户插件 自定义权限拦截器在这里起了关键作用。核心思路是在 Mapper 查询文件列表前根据当前登录人动态注入权限片段// 伪代码示意数据权限条件构造 WrapFileInfo wrapper Wrap.FileInfolambdaQuery() .and(w - w.eq(FileInfo::getOwnerId, currentUserId) .or().inSql(FileInfo::getId, SELECT file_id FROM grp_user_file WHERE user_id currentUserId) .or().inSql(FileInfo::getDeptId, SELECT dept_id FROM sys_user_dept WHERE user_id currentUserId));只有通过该条件匹配到的文件 ID 才会进入后续的详情、下载、删除流程。这意味着即使有人通过篡改参数直接访问他无权访问的文件 ID后端的详情校验也会拦截——这是防水平越权最关键的机制。4.3 操作级越权注解鉴权 资源归属校验双保险对于删除、修改、权限变更这类危险操作项目采用了两层校验Sa-Token 注解鉴权比如SaCheckPermission(file:delete)先确保角色具备操作权限业务层资源归属校验确保当前用户对该文件有写入权限是所有者/管理员/或收到授权。这两层缺一不可。很多系统只做第一层结果就是一个具有文件删除权限的用户理论上可以删除系统内任意文件——这显然不是我们想要的。只有把操作权限和资源权限两个维度都验证通过才算真正安全。4.4 分享场景下的临时授权与越权防护分享功能是企业文件系统里最容易出漏洞的地方。常见问题分享链接有效期内被无限传播、分享码泄露后任何人都能读内部文件、分享用户越权访问同目录下的其他文件。这个项目的设计是分享 Token 只代表对该分享规则的访问凭证不代表对周边资源的访问凭证。当用户通过分享链接点进一个文件后后端解析出分享 ID再去文件分享表里查找授权的文件范围而不是直接根据登录用户身份查询文件表。也就是说即使你通过分享链接进入了某个目录你能看到的内容被严格限制在分享创建者勾选的文件列表内不能顺着目录树往上翻兄弟目录。String shareToken request.getHeader(X-Share-Token); ShareInfo share shareMapper.selectByToken(shareToken); if (share null || share.isExpired()) throw new BizException(分享链接无效或已过期); // 核心基于分享授权范围过滤文件 ListLong allowedFileIds shareService.resolveAllowedFileIds(share.getId()); wrapper.in(FileInfo::getId, allowedFileIds);配合访问密码和有效期可选外部协作场景的临时授权就变得安全可控。到期后分享记录失效Token 作废操作日志仍然保留可以追踪谁在什么时候通过分享链接访问了什么文件。5. 文件上传下载与在线预览的实现细节文件管理系统的体验分水岭就在这里上传大文件卡不卡、下载会不会断了重来、预览要不要下载到本地。这节聊聊项目里的具体实现方案和我个人的优化建议。5.1 秒传、分片、断点续传三件套秒传前端在上传前先计算文件的 MD5使用 Web Worker 计算避免阻塞主线程传给后端。后端先查file_info表是否存在相同 MD5 且未被删除的文件记录如果存在直接返回秒传成功并在文件表中建立关联引用无需真实上传数据。一个文件可能被多个用户/多个路径引用因此file_info表里应该用逻辑删除 引用计数来管理避免同一个大文件在存储桶里存好几份。分片上传当文件较大项目默认超过 5MB 走分片前端把文件切分为大小均匀的分片比如每片 5MB并行上传。每个分片包含 uploadId、分片序号、文件哈希。后端或存储服务负责在全部上传完成后合并分片。MinIO 和 S3 底层都原生支持分片上传Multipart Upload实现起来比想象中的简单——只要让前端拿到预签分片 URL直接往存储服务传应用服务器完全不碰文件字节流。断点续传续传的实质是记录哪些分片已经传成功。前端上传前向后端查询该 uploadId 已完成分片列表只上传缺失的分片。这个状态也可以存在 Redis 里Key 为upload:progress:{uploadId}。5.2 下载与打包下载优化单个文件下载直接走存储服务的预签名 URL让浏览器重定向到对象存储拉流即可避免大文件经过应用服务器。但这个方案在企业内网有时会有问题——内网 DNS 解析不到 MinIO 的域名所以项目也保留了通过应用服务器代理下载的模式此时需要设置X-Accel-Buffering等响应头或者直接用InputStreamResource流式输出。批量下载是另一个高频需求。最直接的方案是后端ZipOutputStream逐个文件压缩try (ZipOutputStream zos new ZipOutputStream(response.getOutputStream())) { for (FileInfo file : fileList) { zos.putNextEntry(new ZipEntry(file.getName())); storageService.download(file.getBucket(), file.getObjectName()) .transferTo(zos); // 需自定义 TransferTo 支持流连接 zos.closeEntry(); } }注意点不要把所有文件先读到内存再压缩一定要边读边写否则内存迟早被打爆另外文件名要做编码处理URLEncoder.encode避免中文名乱码。5.3 在线预览不装 Office 也能看文档在线预览一般有几条路图片直接img加载必要时后端生成缩略图用 Thumbnailator 或原生ImageIOPDF前端用 PDF.js 渲染无兼容性问题Office 文档doc/docx/xls/ppt最成熟的方案是后端异步调用 LibreOffice headless 模式转 PDFlibreoffice --headless --convert-to pdf --outdir /tmp/preview/ input.docx转出来的 PDF 缓存到磁盘或存储桶前端再走 PDF 预览。首次预览可能等待数秒甚至更长所以一定要做异步转换队列SpringAsync 任务表转换完成后通过 WebSocket 或轮询通知前端刷新。视频如果想在线播放而不是下载简单的做法是直接走 HTTP Range 分段请求前端video标签就能拖进度条更专业的是对接 FFmpeg 做 HLS 转码但这部分成本很高项目默认保留给企业定制扩展。项目本身的预览模块已经覆盖了常见的图片、PDF、Office通过 LibreOffice 转换、文本文件直接 UTF-8 读取。对大多数企业协作场景这些已经足够日常使用。6. 部署落地与踩坑复盘从开发机到生产环境最后聊点实在的把项目从源码跑起来、部署到服务器会遇到哪些问题。这部分内容完全来自我实操中踩过的坑希望你别再踩一遍。6.1 配置文件怎么改才能启动拿到代码后第一件事是看application.yml。核心配置项包括数据源、Redis、存储服务参数、Sa-Token 密钥。spring: datasource: url: jdbc:mysql://localhost:3306/file_cloud?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: your-password driver-class-name: com.mysql.cj.jdbc.Driver data: redis: host: localhost port: 6379 password: database: 0 servlet: multipart: max-file-size: 1024MB max-request-size: 2048MB sa-token: token-name: satoken timeout: 86400 active-timeout: -1 is-concurrent: true token-style: uuid mybatis-flex: mapper-locations: classpath*:/mapper/**/*.xml configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl关于max-file-size这里是我踩过的第一个坑Spring Boot 默认上传限制是 1MB如果不改上传不到几十兆的文件就报FileSizeLimitExceededException。把它调大是必须的但调大的同时 Nginx 层也要同步调整client_max_body_size否则请求会在网关层先被 413 拦下。6.2 DataSource 相关类找不到Spring Boot 版本迁移的典型问题热词里有一条spring boot 4.x where to find datasourceautoconfiguration——这不是段子是真实升级场景的高频问题。Spring Boot 3.x 里DataSourceAutoConfiguration还位于org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration到了 4.x 包路径有调整很多老项目的spring.factories或Import引用会直接失效编译期就报找不到类。这个项目基于 Spring Boot 3.5.x短期没有这个困扰但如果你后续想升级到 4.x这几个点必须提前排查DataSourceAutoConfiguration的 import 路径spring.jackson相关自定义序列化器JsonMapper.Builder 的 API 变化jakarta.servlet命名空间3.x 已经是 Jakarta但 4.x 清理了更多兼容层第三方 starter 是否提供 4.x 兼容版本。我的建议是生产环境 3.5.x 已经很成熟不必追求 4.x 一步到位。给项目做升级应该优先建立一套完整的接口回归测试确认文件上传下载、预览、权限校验无回归后再迁移。6.3 Docker Compose 一键部署实践项目整体可以容器化部署。我自己在服务器上采用 Docker Compose 编排三个核心服务mysql、redis、minio应用服务单独构建镜像。version: 3.8 services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_PASSWORD} MYSQL_DATABASE: file_cloud ports: - 3306:3306 volumes: - ./mysql-data:/var/lib/mysql redis: image: redis:7-alpine ports: - 6379:6379 minio: image: minio/minio:latest command: server /data --console-address :9001 environment: MINIO_ROOT_USER: ${MINIO_ACCESS_KEY} MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY} ports: - 9000:9000 - 9001:9001 volumes: - ./minio-data:/data应用镜像构建时注意使用多阶段构建先 Maven 打 jar再 COPY 到eclipse-temurin:21-jre运行镜像能显著减小镜像体积。构建命令mvn clean package -DskipTests docker build -t file-cloud-server:latest . docker compose up -d启动后验证应用端口默认 8080健康检查GET /actuator/healthMinIO 控制台端口 9001能登录数据库表结构是否通过 Flyway/Liquibase 自动初始化项目如果使用自动建表需要提前确认生产环境是否允许。提醒一下如果服务器上独立安装了 Nginx 做反向代理务必注意proxy_request_buffering off;这句尤其是开启分片上传时若 Nginx 缓冲了完整请求体大文件请求会吃满 Nginx 的磁盘缓冲进而导致 502。6.4 运行时常见问题与排查思路问题一上传成功后文件列表不显示大概率是数据权限过滤条件把当前用户不属于该文件的可见范围先查数据库确认file_info里的owner_id是否与当前登录用户一致再查 Sa-Token 会话里拿到的userId是否与数据库一致。问题二预览 Office 文档一直转换中第一反应是服务器是否安装了 LibreOfficesoffice --version没装就装。装了还不行检查应用进程有没有权限写临时目录以及转换超时时间是否设置得过短。问题三集群部署时分片上传状态不同步分片上传状态如果放在本地内存负载均衡轮询到不同节点就会丢状态。这个项目采用 Redis 记录分片进度就不会有这个问题。如果你在别人的项目里看到分片上传状态存在内存 Map就要心里有数它不支持多节点部署。问题四Sa-Token 的 Token 重启后全部失效Sa-Token 默认把会话数据放在内存重启即丢。生产环境必须启用 Redis 集成引入sa-token-redis依赖并配置 Jackson 序列化这样重启后已登录用户无需重新登录而且多个应用节点共享同一个会话池。7. 写在最后的一点个人体会做完这个项目的梳理我最深的一个感受是好的文件管理系统不是靠功能多取胜而是靠边界清晰。存储、元数据、权限、分享、审计每个模块都各自管好自己的事往上才能组合出复杂的企业业务。这套基于 Spring Boot 3.5.x Sa-Token MyBatis Flex 的开源项目在技术选型上走了一条务实的路——不盲目追新不堆砌重框架每一项技术都有明确的服务目标。如果你准备二次开发我的建议优先级很明确第一优先看权限模型它是企业部署的生命线第二看存储抽象层它决定了你部署在本地还是云端第三才看预览、秒传这些体验优化。最后分享一个部署经验别一上来就折腾分片上传和在线预览先把注册 - 登录 - 上传 - 下载 - 权限隔离 - 审计日志这条主链路跑通确认模型没问题再逐步打开高级功能。毕竟文件系统这种底座型应用线上出问题比功能不全要严重得多。希望这篇文章能帮你少走一些弯路也期待看到更多人基于这个项目做出适合自己团队的企业文件服务。
