# 文件服务模块(crm-file) **本文引用的文件** - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考量](#性能考量) 8. [故障排查指南](#故障排查指南) 9. [结论](#结论) 10. [附录](#附录) ## 简介 本文件为 crm-file 文件服务模块的详细技术文档。该模块提供统一的文件上传下载、分片上传与断点续传、在线预览、存储管理与元数据管理等功能，并通过 MinIO 作为对象存储后端，结合定时任务清理孤立的分片文件，保障系统稳定性与可维护性。文档面向开发者与运维人员，既包含接口设计、配置项说明，也涵盖并发处理、性能优化与扩展方案。 ## 项目结构 crm-file 模块采用分层组织： - API 层：对外暴露统一接口定义（FileApi） - Controller 层：HTTP 控制器（FileController） - Service 层：业务逻辑实现（FileApiImpl、FileInfoServiceImpl） - Client 层：第三方能力集成（KkFileViewClient） - Config 层：配置与初始化（MinioConfig、FileProperties、SchedulingConfig） - Domain 层：实体与 DTO（FileInfo、UploadSession、各类 DTO） - Mapper 层：持久化访问（FileInfoMapper） - Task 层：定时任务（OrphanChunkCleanupTask） - Constant 层：常量定义（FileConstants） ```mermaid graph TB subgraph "API 层" A["FileApi"] end subgraph "控制器层" C["FileController"] end subgraph "服务层" S1["FileApiImpl"] S2["FileInfoServiceImpl"] end subgraph "客户端层" K["KkFileViewClient"] end subgraph "配置层" M["MinioConfig"] F["FileProperties"] SC["SchedulingConfig"] end subgraph "领域层" E["FileInfo"] D1["UploadSession"] D2["MultipartInitDTO"] D3["FileDownloadDTO"] D4["FileInfoDTO"] end subgraph "持久化层" MAP["FileInfoMapper"] end subgraph "任务层" T["OrphanChunkCleanupTask"] end subgraph "常量层" CON["FileConstants"] end A --> C C --> S1 C --> S2 S1 --> MAP S1 --> K S1 --> M S1 --> F S2 --> MAP T --> MAP T --> F S1 --> E S1 --> D1 S1 --> D2 S1 --> D3 S1 --> D4 S2 --> E S1 --> CON S2 --> CON ``` 图表来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java) 章节来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java) ## 核心组件 - FileController：HTTP 接口入口，封装上传、分片上传、下载、预览等请求到服务层。 - FileApi 与 FileApiImpl：文件操作的核心服务接口与实现，协调 MinIO、分片会话、元数据持久化与预览服务。 - FileInfoServiceImpl：文件信息管理服务，负责文件元数据的增删改查与状态维护。 - KkFileViewClient：对接 kkFileView 进行在线预览，返回预览链接或流式内容。 - MinioConfig 与 FileProperties：MinIO 客户端与文件相关配置（端点、桶名、密钥、分片大小、超时等）。 - FileInfoMapper：文件元数据持久化访问。 - OrphanChunkCleanupTask：定时清理未完成的分片上传残留，释放存储空间。 - 领域模型：FileInfo（文件元数据）、UploadSession（分片会话）、各 DTO（上传初始化、下载参数、文件信息等）。 章节来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) ## 架构总览 文件服务模块以 HTTP 接口为入口，通过服务层编排 MinIO 对象存储、kkFileView 预览服务与数据库元数据持久化。分片上传流程由 UploadSession 驱动，支持断点续传；下载流程支持范围请求与流式输出；预览通过 kkFileView 生成预览地址或直接返回内容。定时任务定期扫描并清理孤立分片，避免存储膨胀。 ```mermaid sequenceDiagram participant Client as "客户端" participant Controller as "FileController" participant Service as "FileApiImpl" participant MinIO as "MinIO 客户端" participant DB as "FileInfoMapper" participant Preview as "KkFileViewClient" Client->>Controller : "发起上传/分片上传/下载/预览请求" Controller->>Service : "调用文件服务方法" alt 普通上传 Service->>MinIO : "上传完整文件" Service->>DB : "写入文件元数据" Service-->>Controller : "返回文件信息" else 分片上传 Service->>Service : "初始化分片会话(UploadSession)" loop 每个分片 Client->>Service : "上传分片(chunk)" Service->>MinIO : "上传分片" Service->>Service : "更新分片进度" end Service->>MinIO : "合并分片" Service->>DB : "写入文件元数据" Service-->>Controller : "返回文件信息" else 下载 Service->>MinIO : "读取文件流" Service-->>Controller : "返回文件流" else 预览 Service->>Preview : "生成预览链接/获取预览内容" Preview-->>Service : "预览结果" Service-->>Controller : "返回预览结果" end Controller-->>Client : "响应结果" ``` 图表来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) ## 详细组件分析 ### 控制器层：FileController - 职责：接收 HTTP 请求，校验参数，路由到对应服务方法，处理响应格式与异常。 - 关键能力： - 文件上传：支持单文件与多文件上传。 - 分片上传：初始化会话、上传分片、合并分片。 - 文件下载：按文件标识或路径下载，支持范围请求。 - 文件预览：调用预览服务返回预览链接或内容。 - 错误处理：对非法参数、权限不足、存储异常等进行统一包装与提示。 章节来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) ### 服务层：FileApi 与 FileApiImpl - 职责：实现文件上传、分片上传、断点续传、下载、预览等核心业务逻辑。 - 关键能力： - 分片会话管理：基于 UploadSession 跟踪分片上传状态，支持断点续传。 - MinIO 集成：上传、分片上传、合并分片、下载流式读取。 - 元数据管理：创建、更新、查询文件元数据（FileInfo）。 - 预览集成：通过 KkFileViewClient 获取预览链接或内容。 - 并发处理：对分片上传进行并发控制，确保分片顺序与完整性。 - 事务与一致性：在分片合并成功后再持久化元数据，保证最终一致性。 ```mermaid classDiagram class FileApi { + "上传文件(file)" + "分片初始化(params)" + "上传分片(sessionId, chunkIndex, data)" + "合并分片(sessionId)" + "下载文件(downloadDTO)" + "预览文件(fileInfo)" } class FileApiImpl { - "minioClient" - "fileInfoService" - "kkFileViewClient" - "fileProperties" + "上传文件(file)" + "分片初始化(params)" + "上传分片(sessionId, chunkIndex, data)" + "合并分片(sessionId)" + "下载文件(downloadDTO)" + "预览文件(fileInfo)" } class FileInfoService { + "保存文件元数据(info)" + "更新文件状态(id, status)" + "查询文件信息(id)" } class KkFileViewClient { + "获取预览链接(url)" + "获取预览内容(url)" } class MinioConfig { + "endpoint" + "bucketName" + "accessKey" + "secretKey" } class FileProperties { + "chunkSize" + "maxFileSize" + "timeout" } FileApi <|.. FileApiImpl : "实现" FileApiImpl --> FileInfoService : "依赖" FileApiImpl --> KkFileViewClient : "依赖" FileApiImpl --> MinioConfig : "依赖" FileApiImpl --> FileProperties : "依赖" ``` 图表来源 - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) 章节来源 - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) ### 元数据服务：FileInfoServiceImpl - 职责：文件元数据的持久化与查询，包括创建、更新、删除、分页查询等。 - 关键能力： - 文件记录创建：上传完成后写入 FileInfo。 - 状态更新：分片上传过程中更新进度与状态。 - 查询与过滤：按文件名、类型、时间范围等条件查询。 - 与 Mapper 的交互：通过 FileInfoMapper 执行 SQL 操作。 章节来源 - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) ### 预览服务：KkFileViewClient - 职责：对接 kkFileView 服务，生成预览链接或获取预览内容。 - 关键能力： - 根据文件 URL 或路径生成预览链接。 - 直接获取预览内容（如 PDF、图片等）。 - 错误处理：网络异常、预览服务不可用时的降级策略。 章节来源 - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) ### 配置与初始化：MinioConfig、FileProperties、SchedulingConfig - MinioConfig：MinIO 客户端配置（端点、桶名、密钥、连接池等）。 - FileProperties：文件相关配置（分片大小、最大文件大小、超时、临时目录等）。 - SchedulingConfig：定时任务开关与调度策略（如分片清理任务的执行周期）。 章节来源 - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) ### 领域模型：FileInfo、UploadSession、DTOs - FileInfo：文件元数据实体（名称、路径、大小、类型、状态、创建时间等）。 - UploadSession：分片上传会话（sessionId、总大小、已上传分片集合、状态等）。 - DTOs： - MultipartInitDTO：分片初始化参数。 - FileDownloadDTO：下载参数（文件标识、路径、范围等）。 - FileInfoDTO：文件信息传输对象。 章节来源 - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) ### 定时任务：OrphanChunkCleanupTask - 职责：周期性扫描未完成的分片上传会话，清理孤立分片文件，释放存储空间。 - 关键能力： - 扫描长时间未更新的 UploadSession。 - 删除对应的 MinIO 分片文件。 - 清理或标记会话状态。 - 配置：通过 FileProperties 与 SchedulingConfig 控制执行频率与阈值。 章节来源 - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) ### 常量：FileConstants - 职责：集中定义文件相关常量（如 MIME 类型、错误码、默认值等）。 章节来源 - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java) ## 依赖关系分析 - 控制器依赖服务层，服务层依赖 MinIO 客户端、预览客户端与数据库 Mapper。 - 定时任务依赖配置与 Mapper，用于清理孤立分片。 - 领域模型在各层之间传递，保证数据结构一致。 ```mermaid graph LR FC["FileController"] --> FA["FileApiImpl"] FA --> FMS["FileInfoServiceImpl"] FA --> MINIO["MinioConfig"] FA --> KK["KkFileViewClient"] FMS --> MAP["FileInfoMapper"] TASK["OrphanChunkCleanupTask"] --> MAP TASK --> FP["FileProperties"] ``` 图表来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) 章节来源 - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) ## 性能考量 - 分片上传：合理设置分片大小与并发数，平衡内存占用与上传速度。 - 流式处理：下载时采用流式读取，避免大文件内存溢出。 - 缓存策略：对频繁访问的文件元数据进行缓存，减少数据库压力。 - 连接池：优化 MinIO 客户端连接池大小与超时配置。 - 异步处理：将非关键路径（如预览生成）异步化，提升响应速度。 - 资源清理：定时任务及时清理孤立分片，防止存储膨胀。 [本节为通用指导，不直接分析具体文件] ## 故障排查指南 - 上传失败：检查 MinIO 配置、网络连通性与权限；查看分片会话状态与日志。 - 分片丢失：确认客户端分片顺序与重试机制；检查定时任务是否误删。 - 预览失败：验证 kkFileView 服务可用性；检查文件路径与 MIME 类型。 - 下载缓慢：调整流式缓冲大小与网络带宽；检查 MinIO 性能。 - 存储膨胀：检查孤立分片清理任务是否正常运行；手动清理残留分片。 章节来源 - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) ## 结论 crm-file 模块提供了完整的文件处理能力，涵盖上传下载、分片上传、断点续传、预览与存储管理。通过清晰的架构设计与合理的配置，能够满足企业级应用对文件服务的稳定、高效与可扩展需求。建议在生产环境中充分测试并发与异常场景，并根据实际负载优化配置参数。 [本节为总结性内容，不直接分析具体文件] ## 附录 - 接口设计建议：统一返回格式、明确错误码、提供幂等性支持。 - 存储策略配置：按业务划分桶与目录，设置生命周期规则。 - 扩展方案：抽象存储后端接口，支持多存储切换；插件化预览服务。 - 监控与告警：记录上传下载成功率、延迟与错误率，设置阈值告警。 [本节为补充性内容，不直接分析具体文件]