luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
56 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Tree: bb2dad7b58
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'bb2dad7b58'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/文件服务/存储管理.md

22 KiB
Raw Blame History

存储管理

**本文引用的文件** - [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java) - [application.yml](file://crm-app/src/main/resources/application.yml) - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.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) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java) - [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java) - [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java) - [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java) - [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java) - [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java) - [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java) - [BusinessErrorException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/BusinessErrorException.java)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与索引优化
  8. 配置与容量规划
  9. 监控与可观测性
  10. 故障排查指南
  11. 结论
  12. 附录：数据模型与迁移建议

简介

本技术文档围绕文件存储管理子系统，系统性阐述 MinIO 对象存储集成、Bucket 管理、权限控制、文件元数据设计、存储路径规划、版本管理、数据库表结构与索引优化、查询性能调优、配置与容量规划、监控方案、生命周期与归档策略、备份恢复机制以及扩展与迁移指南。目标是帮助读者快速理解并高效运维该存储子系统。

项目结构

文件存储子系统位于 crm-file 模块，采用分层架构：

  • API 层：对外暴露统一接口（FileApi）
  • 控制器层：HTTP 入口（FileController）
  • 服务层：业务编排与流程控制（IFileInfoService、FileApiImpl、FileInfoServiceImpl）
  • 客户端层：第三方能力集成（KkFileViewClient）
  • 配置层：MinIO、调度、属性等（MinioConfig、SchedulingConfig、FileProperties）
  • 领域层：实体与 DTO（FileInfo、FileInfoDTO、UploadSession 等）
  • 持久化层：MyBatis-Plus Mapper（FileInfoMapper）
  • 任务层：定时清理（OrphanChunkCleanupTask）
graph TB
subgraph "应用启动"
App["CrmAppApplication"]
end
subgraph "文件模块"
Ctrl["FileController"]
Api["FileApi / FileApiImpl"]
Svc["IFileInfoService / FileInfoServiceImpl"]
Client["KkFileViewClient"]
Cfg["MinioConfig / FileProperties / SchedulingConfig"]
Entity["FileInfo / DTOs"]
Mapper["FileInfoMapper"]
Task["OrphanChunkCleanupTask"]
end
subgraph "外部系统"
MinIO["MinIO 对象存储"]
KK["KKFileView 在线预览"]
end
App --> Ctrl
Ctrl --> Api
Api --> Svc
Svc --> Mapper
Svc --> Client
Svc --> Cfg
Svc --> MinIO
Client --> KK
Task --> Svc

图表来源

  • CrmAppApplication.java
  • FileController.java
  • FileApi.java
  • FileApiImpl.java
  • IFileInfoService.java
  • FileInfoServiceImpl.java
  • MinioConfig.java
  • FileProperties.java
  • SchedulingConfig.java
  • KkFileViewClient.java
  • FileInfo.java
  • FileInfoDTO.java
  • MultipartInitDTO.java
  • UploadSession.java
  • FileDownloadDTO.java
  • FileInfoMapper.java
  • OrphanChunkCleanupTask.java

章节来源

  • CrmAppApplication.java
  • application.yml

核心组件

  • 配置中心
    • MinioConfig：封装 MinIO 客户端初始化与连接参数
    • FileProperties：文件相关配置项（如 Bucket、路径前缀、分片大小等）
    • SchedulingConfig：开启/关闭定时任务（如孤儿分片清理）
  • 控制器与API
    • FileController：提供上传、下载、分片上传、预览等 HTTP 接口
    • FileApi / FileApiImpl：定义并实现文件操作的业务契约
  • 服务层
    • IFileInfoService / FileInfoServiceImpl：文件元数据管理、上传流程编排、下载流程、预览链接生成
    • KkFileViewClient：调用第三方在线预览服务
  • 持久化
    • FileInfo 实体与 FileInfoMapper：文件元数据持久化
  • 任务
    • OrphanChunkCleanupTask：定期清理未完成的分片上传残留

章节来源

  • MinioConfig.java
  • FileProperties.java
  • SchedulingConfig.java
  • FileController.java
  • FileApi.java
  • FileApiImpl.java
  • IFileInfoService.java
  • FileInfoServiceImpl.java
  • KkFileViewClient.java
  • FileInfo.java
  • FileInfoMapper.java
  • OrphanChunkCleanupTask.java

架构总览

整体采用“控制器-服务-客户端”的分层模式，结合 MinIO 对象存储与第三方预览服务，形成高内聚、低耦合的文件管理能力。

sequenceDiagram
participant Client as "客户端"
participant Controller as "FileController"
participant Service as "IFileInfoService/FileInfoServiceImpl"
participant MinIO as "MinIO 对象存储"
participant KK as "KKFileView 预览服务"
Client->>Controller : "发起上传/下载/预览请求"
Controller->>Service : "校验参数与权限"
alt 上传流程
Service->>MinIO : "创建Bucket(若不存在)/生成对象键"
Service->>MinIO : "分片上传或直传"
Service-->>Controller : "返回文件元数据"
else 下载流程
Service->>MinIO : "获取对象流/签名URL"
Service-->>Controller : "返回下载响应"
else 预览流程
Service->>KK : "生成预览链接"
Service-->>Controller : "返回预览地址"
end
Controller-->>Client : "统一结果封装"

图表来源

  • FileController.java
  • FileApiImpl.java
  • FileInfoServiceImpl.java
  • MinioConfig.java
  • KkFileViewClient.java

详细组件分析

MinIO 对象存储集成

  • 目标：通过 MinioConfig 初始化客户端，使用 FileProperties 中的 Bucket、Endpoint、AccessKey、SecretKey 等配置进行连接与鉴权。
  • 关键职责：
    • 动态创建/检查 Bucket 存在性
    • 生成对象键（路径规划）
    • 上传（直传/分片）、下载（流式/签名URL）、删除、元数据读取
  • 权限控制：
    • 基于访问密钥的细粒度权限
    • 可在 MinIO 控制台设置 Bucket 策略，限制读写范围
  • 路径规划建议：
    • 按租户/业务域划分 Bucket
    • 对象键采用“业务类型/日期/唯一标识”三段式，便于检索与归档

章节来源

  • MinioConfig.java
  • FileProperties.java
  • FileApiImpl.java
  • FileInfoServiceImpl.java

Bucket 管理

  • 自动创建：首次写入时检测 Bucket 是否存在，不存在则创建
  • 命名规范：建议使用小写英文字母与数字，避免冲突
  • 生命周期策略：在 MinIO 侧配置规则（过期、转储到冷存储）
  • 多环境隔离：开发/测试/生产分别独立 Bucket

章节来源

  • FileProperties.java
  • FileApiImpl.java

权限控制

  • 认证与授权：由上层安全模块负责（JWT、角色、数据权限），文件接口需鉴权后访问
  • 数据可见性：通过 OwnedEntity 基类注入所有者信息，确保仅本人或授权角色可操作
  • 最小权限原则：为 MinIO 访问密钥配置最小可用权限（只读/只写特定 Bucket）

章节来源

  • OwnedEntity.java
  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java

文件元数据设计与存储路径规划

  • 元数据字段建议：
    • 唯一标识、文件名、原始大小、MIME 类型、MD5/SHA1、存储桶名、对象键、上传者、所属者、状态、版本、创建/更新时间
  • 路径规划：
    • 示例：/{tenant}/{bizType}/{yyyyMMdd}/{uuid}.{ext}
    • 支持按业务域与时间分区，提升检索与归档效率
  • 版本管理：
    • 建议在对象键中追加版本号或使用 MinIO 版本控制功能
    • 元数据记录当前版本与历史版本映射

章节来源

  • FileInfo.java
  • FileInfoDTO.java
  • FileConstants.java

分片上传与会话管理

  • 流程：
    • 初始化会话（MultipartInitDTO）
    • 逐块上传（UploadSession 维护分片状态）
    • 合并分片并落盘元数据
  • 异常处理：
    • 网络中断重试、分片完整性校验
    • 超时与幂等控制
  • 清理策略：
    • OrphanChunkCleanupTask 定期扫描并清理未完成会话

章节来源

  • MultipartInitDTO.java
  • UploadSession.java
  • OrphanChunkCleanupTask.java

在线预览集成

  • 通过 KkFileViewClient 调用第三方预览服务，返回预览 URL
  • 支持常见办公文档格式，无需本地转换

章节来源

  • KkFileViewClient.java

下载流程

  • 支持直接流式下载与签名 URL 下载
  • 根据文件大小与场景选择合适方式

章节来源

  • FileDownloadDTO.java
  • FileApiImpl.java

依赖关系分析

  • 模块内依赖：
    • FileController -> FileApi -> IFileInfoService -> FileInfoMapper
    • FileApiImpl/FileInfoServiceImpl -> MinioConfig/FileProperties
    • FileInfoServiceImpl -> KkFileViewClient
  • 基础依赖：
    • MyBatis-Plus 配置（MybatisPlusConfig、MetaObjectFillHandler、SnowflakeIdWorker）
    • 全局异常处理与统一结果封装
classDiagram
class FileController
class FileApi
class FileApiImpl
class IFileInfoService
class FileInfoServiceImpl
class FileInfoMapper
class MinioConfig
class FileProperties
class KkFileViewClient
class FileInfo
class FileInfoDTO
FileController --> FileApi : "调用"
FileApi <|.. FileApiImpl : "实现"
FileApiImpl --> IFileInfoService : "委托"
IFileInfoService <|.. FileInfoServiceImpl : "实现"
FileInfoServiceImpl --> FileInfoMapper : "持久化"
FileInfoServiceImpl --> MinioConfig : "配置"
FileInfoServiceImpl --> FileProperties : "配置"
FileInfoServiceImpl --> KkFileViewClient : "预览"
FileInfoServiceImpl --> FileInfo : "实体"
FileInfoServiceImpl --> FileInfoDTO : "数据传输"

图表来源

  • FileController.java
  • FileApi.java
  • FileApiImpl.java
  • IFileInfoService.java
  • FileInfoServiceImpl.java
  • FileInfoMapper.java
  • MinioConfig.java
  • FileProperties.java
  • KkFileViewClient.java
  • FileInfo.java
  • FileInfoDTO.java

章节来源

  • MybatisPlusConfig.java
  • MetaObjectFillHandler.java
  • SnowflakeIdWorker.java
  • SnowflakeProperties.java

性能与索引优化

  • 数据库索引建议：
    • 主键：雪花ID（SnowflakeIdWorker）
    • 常用查询列：所属者、业务类型、创建时间、状态、MD5
    • 复合索引：(owner_id, biz_type, create_time)
    • 唯一索引：md5（去重校验）
  • 查询优化：
    • 分页查询使用合理页大小
    • 避免 SELECT *，按需投影
    • 大对象不入库，仅存元数据
  • 上传优化：
    • 分片大小与并发数调优
    • 启用断点续传与重试
  • 缓存策略：
    • 热点文件元数据可缓存（Redis）
    • 预览 URL 短期缓存

章节来源

  • SnowflakeIdWorker.java
  • SnowflakeProperties.java
  • FileInfo.java
  • FileInfoMapper.java

配置与容量规划

  • 配置项建议：
    • MinIO Endpoint、AccessKey、SecretKey、Bucket、Region
    • 分片大小、最大分片数、超时时间
    • 是否启用预览服务、预览服务地址
    • 定时任务开关与执行周期
  • 容量规划：
    • 预估年增量与峰值吞吐
    • 冷热数据分离策略（热数据 SSD，冷数据 HDD/归档）
    • 副本与纠删码策略（MinIO 默认纠删码）
  • 生命周期与归档：
    • 90 天未访问转冷存储
    • 180 天归档至低成本介质
    • 365 天合规删除

章节来源

  • FileProperties.java
  • SchedulingConfig.java

监控与可观测性

  • 指标采集：
    • MinIO 指标（QPS、延迟、错误率、磁盘使用）
    • 应用指标（上传成功率、分片失败率、预览成功率）
  • 日志规范：
    • 统一 TraceId 贯穿请求链路
    • 关键步骤打点（初始化、上传、合并、下载、预览）
  • 告警策略：
    • 上传失败率阈值
    • 存储空间使用率阈值
    • 预览服务不可用告警

章节来源

  • application.yml

故障排查指南

  • 常见问题定位：
    • 连接失败：检查 MinIO 配置与网络连通性
    • 权限不足：核对访问密钥权限与 Bucket 策略
    • 分片上传失败：检查分片大小、超时与重试策略
    • 预览失败：确认预览服务可达与文件格式支持
  • 工具与手段：
    • 查看应用日志与 MinIO 审计日志
    • 使用 MinIO 控制台验证对象存在性与元数据
    • 通过统一结果封装与全局异常处理器定位错误码

章节来源

  • GlobalExceptionHandlerAdvice.java
  • Result.java
  • ResultCodeEnum.java
  • BusinessErrorException.java

结论

本存储管理子系统以 MinIO 为核心，结合完善的元数据管理与第三方预览能力，提供了稳定高效的文件处理能力。通过合理的索引与配置、完善的监控与告警、清晰的生命周期与归档策略，可满足企业级文件存储需求。后续可按业务增长进行水平扩展与迁移升级。

附录：数据模型与迁移建议

数据模型（FileInfo 实体）

erDiagram
FILE_INFO {
bigint id PK
string file_name
bigint size
string mime_type
string md5
string bucket
string object_key
bigint owner_id
int status
int version
datetime created_at
datetime updated_at
}

图表来源

  • FileInfo.java
  • BaseEntity.java
  • OwnedEntity.java

迁移与扩展建议

  • 横向扩展：
    • 多实例部署共享 MinIO，无状态化文件服务
    • 引入消息队列异步处理预览与转码
  • 迁移方案：
    • 使用 MinIO 官方迁移工具批量迁移历史数据
    • 双写过渡期保证一致性，逐步切换流量
  • 版本管理：
    • 启用 MinIO 版本控制，保留历史版本
    • 元数据维护版本映射与回滚策略

章节来源

  • FileInfoMapper.java
  • SchedulingConfig.java