跳到主要内容

文件管理系统

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件管理系统提供统一的文件上传、下载、删除、分类与查询能力，支持多种存储后端（本地、S3兼容对象存储等），并提供分片上传、断点续传、预签名直传、文件类型识别与分类管理等高级特性。系统通过“配置即服务”的方式，允许管理员灵活配置主存储与备用存储，实现跨云/本地的弹性扩展。

项目结构​

  • 文档侧：位于 docs/file 下，包含文件管理概览、配置、列表、分类、分片上传等专题文档。
  • 代码侧：核心逻辑集中在 infra 模块的 biz 层与 framework 层，API 层通过 Feign 进行 RPC 调用；控制器负责对外暴露 HTTP 接口；框架层封装了文件客户端抽象与多种具体实现（本地、S3）。

Mermaid Diagram Code:

graph TB
subgraph "文档"
D1["文件管理概览<br/>docs/file/index.md"]
D2["文件配置<br/>docs/file/file-config.md"]
D3["文件列表<br/>docs/file/file-list.md"]
D4["文件分类<br/>docs/file/file-category.md"]
D5["分片上传<br/>docs/file/file-chunk-upload.md"]
end
subgraph "后端代码"
C1["FileController<br/>/infra/controller/admin/file/FileController.java"]
S1["FileService 接口<br/>/infra/service/file/FileService.java"]
S2["FileServiceImpl 实现<br/>/infra/service/file/FileServiceImpl.java"]
F1["抽象文件客户端<br/>/framework/file/core/client/AbstractFileClient.java"]
F2["本地文件客户端<br/>/framework/file/core/client/local/LocalFileClient.java"]
F3["S3文件客户端<br/>/framework/file/core/client/s3/S3FileClient.java"]
P1["分片上传控制器<br/>/infra/controller/admin/filepart/FilePartUploadController.java"]
A1["FileApi 接口(RPC)<br/>/infra/api/file/FileApi.java"]
end
D1 --> C1
D2 --> C1
D3 --> C1
D4 --> C1
D5 --> P1
C1 --> S1
S1 --> S2
S2 --> F1
F1 --> F2
F1 --> F3
C1 --> A1

图表来源

章节来源

核心组件​

  • 控制器层
    • FileController：提供上传、下载、删除、分页查询、预签名直传等 HTTP 接口。
    • FilePartUploadController：提供分片上传初始化、分片 URL 获取、已上传分片查询、合并分片、完整性校验等接口。
  • 服务层
    • FileService/FileServiceImpl：封装文件上传、删除、下载、预签名、分页查询、断点续传重定向等业务逻辑。
  • 客户端层
    • AbstractFileClient：抽象文件客户端，统一生命周期与 URL 格式化。
    • LocalFileClient：本地文件系统客户端。
    • S3FileClient：S3 协议客户端，兼容 MinIO、阿里云 OSS、七牛云等。
  • API 层
    • FileApi：基于 Feign 的 RPC 接口，供其他模块调用。

章节来源

架构总览​

系统采用“控制器-服务-客户端-存储”的分层架构，支持本地与 S3 兼容对象存储，通过配置中心动态切换主存储与备用存储，实现高可用与弹性扩展。

Mermaid Diagram Code:

graph TB
subgraph "外部调用"
U["前端/业务模块"]
end
subgraph "网关/控制器"
FC["FileController"]
FPC["FilePartUploadController"]
end
subgraph "服务层"
FS["FileService/FileServiceImpl"]
end
subgraph "客户端层"
AFC["AbstractFileClient"]
LFC["LocalFileClient"]
SFC["S3FileClient"]
end
subgraph "存储"
L["本地磁盘"]
O["对象存储(阿里/七牛/MinIO等)"]
end
U --> FC
U --> FPC
FC --> FS
FPC --> FS
FS --> AFC
AFC --> LFC
AFC --> SFC
LFC --> L
SFC --> O

图表来源

详细组件分析​

上传流程（后端直传）​

  • 控制器接收文件，读取原始名称与字节流。
  • 识别 MIME 类型，生成默认路径，必要时计算 MD5。
  • 选择存储客户端（主配置或指定配置），执行上传并返回访问 URL。
  • 将文件元信息持久化至数据库。

Mermaid Diagram Code:

sequenceDiagram
participant C as "FileController"
participant S as "FileServiceImpl"
participant CL as "FileClient(S3/Local)"
participant DB as "数据库"
C->>S : "createFile(uploadReqVO)"
S->>CL : "upload(content, path, type)"
CL-->>S : "返回访问URL"
S->>DB : "插入文件元信息"
S-->>C : "返回URL"
C-->>C : "响应结果"

图表来源

章节来源

下载与断点续传​

  • 直接下载：通过 FileController 的下载接口，定位存储客户端并返回文件内容。
  • 预签名直传：生成带过期时间的上传 URL，前端直传对象存储。
  • 断点续传重定向：根据 Range 请求头解析断点区间，返回对象存储的重定向 URL，由 CDN/对象存储处理续传。

Mermaid Diagram Code:

sequenceDiagram
participant B as "浏览器"
participant C as "FileController"
participant S as "FileServiceImpl"
participant CL as "FileClient(S3)"
B->>C : "GET /infra/file/{configId}/get/**"
C->>S : "getFileContent(configId, path)"
S->>CL : "getContent(path)"
CL-->>S : "返回字节流"
S-->>C : "字节流"
C-->>B : "写入响应"
B->>C : "Range : bytes=start-end"
C->>S : "downloadRedirect()"
S-->>C : "返回重定向URL"
C-->>B : "302跳转到对象存储"

图表来源

章节来源

删除流程​

  • 校验文件是否存在与是否可删除（避免被业务模块占用）。
  • 若仅有一条记录指向该物理文件，则调用存储客户端删除物理文件。
  • 删除数据库记录。

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> Load["加载文件记录"]
Load --> Exists{"存在且可删除?"}
Exists --> |否| Error["抛出异常"]
Exists --> |是| CheckRefs["查询相同URL的记录数"]
CheckRefs --> Single{"仅一条记录?"}
Single --> |是| DeleteObj["调用客户端删除物理文件"]
Single --> |否| Skip["跳过物理删除"]
DeleteObj --> RemoveDB["删除数据库记录"]
Skip --> RemoveDB
RemoveDB --> End(["结束"])
Error --> End

图表来源

章节来源

分片上传（前端直传对象存储）​

  • 初始化：生成分片上传任务，返回 uploadId 与合并 URL。
  • 获取分片 URL：为每个分片生成带过期时间的上传 URL。
  • 查询已上传分片：列出已完成的分片编号。
  • 合并分片：按序号提交 ETAG 完成分片合并。
  • 完整性校验：可选的最终校验步骤。

Mermaid Diagram Code:

sequenceDiagram
participant FE as "前端"
participant PC as "FilePartUploadController"
participant S as "FileServiceImpl"
participant CL as "S3FileClient"
FE->>PC : "POST /infra/file-part-upload/presigned-url/m4/init"
PC->>S : "initiateMultipartUpload"
S->>CL : "initiateMultipartUpload"
CL-->>S : "返回uploadId与URL"
S-->>PC : "返回任务信息"
PC-->>FE : "返回任务ID"
loop 对每个分片
FE->>PC : "GET /infra/file-part-upload/presigned-url/m4/part/urls?filePartUploadId&partNumbers"
PC->>S : "getMultipartUploadUrls"
S->>CL : "生成分片上传URL"
CL-->>S : "返回URL列表"
S-->>PC : "返回URL列表"
PC-->>FE : "返回URL列表"
FE->>CL : "PUT 分片数据"
end
FE->>PC : "GET /infra/file-part-upload/presigned-url/m4/uploaded/parts?filePartUploadId"
PC->>S : "getUploadedParts"
S->>CL : "listParts"
CL-->>S : "返回已上传分片"
S-->>PC : "返回已上传分片"
PC-->>FE : "返回已上传分片"
FE->>PC : "PUT /infra/file-part-upload/presigned-url/m4/complete?filePartUploadId"
PC->>S : "completeUpload"
S->>CL : "completeMultipartUpload"
CL-->>S : "合并成功"
S-->>PC : "返回结果"
PC-->>FE : "合并完成"

图表来源

章节来源

文件分类管理​

  • 类型识别：根据文件内容与扩展名识别 MIME 类型，生成默认路径。
  • 分类枚举：根据文件名映射到图片、视频、APK 等分类。
  • APK 元信息：解析 APK 包名、版本号、版本名等信息并落库。
  • 查询过滤：支持按分类、类型、配置、时间等维度分页查询。

章节来源

存储策略与配置​

  • 支持本地存储与 S3 兼容对象存储（阿里云 OSS、七牛云、MinIO 等）。
  • 主配置与备用配置：通过配置中心选择主存储，支持切换与测试。
  • 预签名直传：前端直接上传对象存储，后端记录元数据。
  • 重定向下载：可配置重定向基础地址，结合 CDN 提升下载性能。

章节来源

API 接口文档​

  • 文件上传
    • 后端直传：POST /infra/file/upload
    • 前端直传：POST /infra/file/create（需先获取预签名 URL）
  • 预签名直传
    • GET /infra/file/presigned-url?path={path}
  • 下载
    • GET /infra/file/{configId}/get/**（支持 Range 断点续传）
    • GET /infra/file/download-redirect（重定向下载）
  • 删除
    • DELETE /infra/file/delete?id={id}
  • 分片上传
    • 初始化：POST /infra/file-part-upload/presigned-url/m4/init
    • 获取分片 URL：GET /infra/file-part-upload/presigned-url/m4/part/urls
    • 查询已上传分片：GET /infra/file-part-upload/presigned-url/m4/uploaded/parts
    • 合并分片：PUT /infra/file-part-upload/presigned-url/m4/complete
    • 完整性校验：PUT /infra/file-part-upload/presigned-url/m4/verification

章节来源

依赖关系分析​

  • 控制器依赖服务接口，服务实现依赖客户端抽象与具体客户端，客户端依赖存储后端。
  • FileController 与 FilePartUploadController 通过 FileService 统一编排上传、分片、下载等流程。
  • S3FileClient 与 LocalFileClient 通过 AbstractFileClient 统一生命周期与 URL 格式化。

Mermaid Diagram Code:

classDiagram
class FileController
class FilePartUploadController
class FileService
class FileServiceImpl
class AbstractFileClient
class LocalFileClient
class S3FileClient
FileController --> FileService : "依赖"
FilePartUploadController --> FileService : "依赖"
FileService <|.. FileServiceImpl : "实现"
AbstractFileClient <|-- LocalFileClient : "继承"
AbstractFileClient <|-- S3FileClient : "继承"
FileServiceImpl --> AbstractFileClient : "使用"

图表来源

章节来源

性能考虑​

  • 对象存储直传：前端直传对象存储，后端仅记录元数据，降低应用服务器压力。
  • CDN 重定向：下载阶段返回对象存储重定向 URL，利用 CDN 加速与边缘缓存。
  • 分片上传：支持并发分片上传与断点续传，提高大文件传输稳定性与速度。
  • 断点续传：Range 解析与阿里云特殊纠错，保障续传可靠性。
  • 预签名 URL：固定过期时间（默认 10 分钟），平衡安全性与易用性。

章节来源

故障排查指南​

  • 上传失败
    • 检查存储客户端初始化与配置是否正确。
    • 确认对象存储桶权限与域名配置。
  • 下载 404
    • 确认路径编码与解码逻辑，避免中文路径问题。
    • 核对存储路径与实际文件是否一致。
  • 删除失败
    • 检查是否被业务模块占用（Launcher、Task 等）。
    • 确认仅有一条记录指向该物理文件，否则仅删除记录不删除物理文件。
  • 分片上传异常
    • 校验分片序号与 ETAG 是否按序提交。
    • 确认 uploadId 有效且未过期。
  • 断点续传错误
    • 校验 Range 请求头格式与边界值。
    • 特殊情况下（如阿里云）遵循纠错规则。

章节来源

结论​

本文件管理系统通过清晰的分层架构与可插拔的存储客户端，实现了统一的文件管理能力。其支持本地与对象存储、预签名直传、分片上传与断点续传、分类管理与元数据维护，满足多场景下的文件存储需求。配合 CDN 与重定向下载，可显著提升下载性能与用户体验。

附录​

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答