跳到主要内容

文件管理相关表

引用文件

本文引用的文件

目录​

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

简介​

本文件聚焦于文件管理模块的核心表结构与数据流转，围绕文件信息表(file_info)及其相关配置表，系统性说明字段定义、约束、业务含义与典型流程（上传、存储、下载）。同时给出跨数据库的表结构映射、字段说明、索引与主键设计考虑，并结合实际代码实现梳理上传与下载的关键控制流。

项目结构​

文件管理相关的核心表位于基础设施模块的数据库脚本中，同时配套的控制器与服务层负责对外提供上传、下载与分片上传能力。文档结构如下：

  • 数据库脚本：包含 MySQL、Oracle、SQLServer、达梦等多数据库方言的表结构定义
  • 控制器与服务：提供文件上传、下载、预签名 URL 获取以及分片上传初始化等能力
  • 文档：文件配置与模块概览说明

Mermaid Diagram Code:

graph TB
subgraph "数据库"
T1["infra_file<br/>文件信息表"]
T2["infra_file_config<br/>文件配置表"]
T3["infra_file_content<br/>文件内容表(可选)"]
end
subgraph "后端服务"
C1["FileController<br/>管理后台接口"]
C2["AppFileController<br/>App接口"]
S1["FileService<br/>文件服务"]
S2["FilePartUploadServiceImpl<br/>分片上传服务"]
end
C1 --> S1
C2 --> S1
S1 --> T1
S1 --> T2
S2 --> T1
S2 --> T2

图表来源

章节来源

核心组件​

本节聚焦文件信息表(file_info)与文件配置表(file_config)，并简述文件内容表(file_content)的可选存在性。

  • 文件信息表(infra_file)

    • 主键：id（自增/序列）
    • 关键字段：config_id（配置编号）、name（文件名）、path（文件路径）、url（文件URL）、type（文件类型）、size（文件大小）、creator/updater/create_time/update_time/deleted
    • 约束：主键约束；部分数据库提供唯一性/非空约束（如 Oracle 的主键约束）
    • 业务含义：记录一次文件上传后的元数据，便于后续下载与管理

  • 文件配置表(infra_file_config)

    • 主键：id（自增/序列）
    • 关键字段：name（配置名）、storage（存储器类型）、remark（备注）、master（是否主配置）、config（存储配置JSON）、enable（是否启用）
    • 约束：主键约束；部分数据库提供唯一性/非空约束
    • 业务含义：定义文件存储后端（本地、云存储等）及默认主配置

  • 文件内容表(infra_file_content)

    • 可选表：用于存放文件二进制内容（如数据库存储）
    • 关键字段：config_id、path、content、creator/updater/create_time/update_time/deleted
    • 业务含义：当采用数据库存储时，文件内容落库

章节来源

架构总览​

文件管理模块的上传与下载流程由控制器驱动，服务层协调文件客户端与数据库持久化，最终形成“元数据+存储”的解耦架构。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant AdminCtl as "FileController"
participant AppCtl as "AppFileController"
participant Svc as "FileService"
participant PartSvc as "FilePartUploadServiceImpl"
participant DB as "数据库(infra_file/infra_file_config)"
participant Storage as "文件存储(本地/云)"
Client->>AdminCtl : "POST /infra/file/upload(后端上传)"
AdminCtl->>Svc : "createFile(文件名, 路径, 二进制)"
Svc->>Storage : "写入文件"
Storage-->>Svc : "返回存储结果"
Svc->>DB : "插入/更新文件元数据"
DB-->>Svc : "确认"
Svc-->>AdminCtl : "返回URL"
AdminCtl-->>Client : "返回文件URL"
Client->>AppCtl : "POST /infra/file/upload(App直传)"
AppCtl->>Svc : "createFile(文件名, 路径, 二进制)"
Svc->>Storage : "写入文件"
Svc->>DB : "插入/更新文件元数据"
DB-->>Svc : "确认"
Svc-->>AppCtl : "返回URL"
AppCtl-->>Client : "返回文件URL"
Client->>PartSvc : "初始化分片上传"
PartSvc->>Storage : "initiateMultipartUpload(生成临时key/上传ID)"
PartSvc->>DB : "保存分片任务元数据"
PartSvc-->>Client : "返回上传凭证"

图表来源

详细组件分析​

文件信息表(file_info)字段说明与业务逻辑​

  • 字段与约束（以 MySQL 为例）

    • id：bigint，自增主键，唯一标识文件
    • config_id：bigint，外键关联 infra_file_config.id，标识该文件使用的存储配置
    • name：varchar，原始文件名
    • path：varchar，存储路径（相对或绝对，取决于存储策略）
    • url：varchar，访问URL（可直接访问或预签名URL）
    • type：varchar，文件类型（如图片、视频、APK等）
    • size：bigint/int，文件大小（字节）
    • creator/updater：varchar，创建/更新人
    • create_time/update_time：datetime/timestamp，创建/更新时间
    • deleted：bit/number，逻辑删除标记

  • 业务含义

    • 记录文件的元数据与访问信息，支撑下载、列表、分类等业务
    • 通过 config_id 与存储配置解耦，便于切换存储后端

  • 索引与设计考虑

    • 主键：id
    • 建议索引：config_id（按配置维度查询）、name（按文件名检索）、create_time（按时间排序）
    • 复合索引：(config_id, create_time)、(type, create_time) 以优化常见查询

  • 字段取值示例（示意）

章节来源

文件配置表(file_config)字段说明与业务逻辑​

  • 字段与约束（以 MySQL 为例）

    • id：bigint，自增主键
    • name：varchar，配置名（如“本地存储”、“阿里云OSS”）
    • storage：tinyint，存储器类型（枚举值，如本地、S3、MinIO等）
    • remark：varchar，备注
    • master：bit，是否主配置（同一时刻仅允许一个主配置）
    • config：varchar/json，存储配置参数（如域名、桶名、密钥等）
    • enable：tinyint，是否启用
    • creator/updater：varchar
    • create_time/update_time：datetime
    • deleted：bit

  • 业务含义

    • 统一管理文件存储后端参数
    • 主配置决定默认存储策略；启用/禁用用于灰度与切换

  • 字段取值示例（示意）

    • name："七牛存储器"
    • storage：20
    • master：1
    • config：{"endpoint":"s3.cn-south-1.qiniucs.com","domain":"http://test.yudao.iocoder.cn","bucket":"ruoyi-vue-pro","accessKey":"...","accessSecret":"..."}
    • enable：1

章节来源

文件内容表(file_content)可选存在性​

  • 当采用数据库存储时，文件内容可能存放在 infra_file_content.content 中
  • 字段：config_id、path、content、creator/updater/create_time/update_time/deleted
  • 适用场景：小文件集中存储、审计需求、统一备份

章节来源

上传流程（后端上传与App直传）​

  • 后端上传（FileController）

    • 接收 multipart 文件，读取原始文件名与二进制内容
    • 调用服务层创建文件，写入存储并持久化元数据
    • 返回文件URL

  • App直传（AppFileController）

    • 接收 multipart 文件，调用服务层创建文件
    • 写入存储并持久化元数据，返回URL

  • 分片上传初始化（FilePartUploadServiceImpl）

    • 选择配置（指定或主配置）
    • 调用文件客户端初始化分片上传，生成临时key与上传ID
    • 保存分片任务元数据，返回给前端

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> ChooseCfg["选择存储配置(config_id)"]
ChooseCfg --> UploadMode{"上传模式"}
UploadMode --> |后端上传| Backend["FileController接收文件"]
UploadMode --> |App直传| App["AppFileController接收文件"]
UploadMode --> |分片上传| Part["FilePartUploadServiceImpl初始化"]
Backend --> SaveMeta["写入存储并持久化元数据"]
App --> SaveMeta
Part --> GenKey["生成临时key/上传ID"]
GenKey --> SaveTask["保存分片任务元数据"]
SaveMeta --> Done(["完成"])
SaveTask --> Done

图表来源

章节来源

下载流程（预签名URL与直接访问）​

  • 预签名URL（FileController）

    • 生成带有效期的预签名URL，前端直接从存储拉取
    • 适用于云存储（OSS/COS/MinIO等）

  • 直接访问URL（AppFileController）

    • 使用已持久化的文件URL进行访问
    • 适用于CDN或可公开访问的存储

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant AdminCtl as "FileController"
participant Svc as "FileService"
participant Storage as "文件存储"
Client->>AdminCtl : "GET /infra/file/presigned-url"
AdminCtl->>Svc : "getFilePresignedUrl(路径)"
Svc->>Storage : "生成预签名URL"
Storage-->>Svc : "返回预签名URL"
Svc-->>AdminCtl : "返回预签名URL"
AdminCtl-->>Client : "返回预签名URL"

图表来源

章节来源

数据模型图​

Mermaid Diagram Code:

erDiagram
INFRA_FILE_CONFIG {
bigint id PK
varchar name
tinyint storage
varchar remark
bit master
varchar config
varchar creator
datetime create_time
varchar updater
datetime update_time
bit deleted
}
INFRA_FILE {
bigint id PK
bigint config_id FK
varchar name
varchar path
varchar url
varchar type
bigint size
varchar creator
datetime create_time
varchar updater
datetime update_time
bit deleted
}
INFRA_FILE_CONTENT {
bigint id PK
bigint config_id FK
varchar path
longblob content
varchar creator
datetime create_time
varchar updater
datetime update_time
bit deleted
}
INFRA_FILE_CONFIG ||--o{ INFRA_FILE : "拥有"
INFRA_FILE_CONFIG ||--o{ INFRA_FILE_CONTENT : "拥有"

图表来源

依赖关系分析​

  • 控制器依赖服务层

    • FileController 依赖 FileService 进行文件创建与预签名URL生成
    • AppFileController 依赖 FileService 进行文件创建
    • FilePartUploadServiceImpl 依赖 FileConfigService 与具体文件客户端进行分片上传初始化

  • 服务层依赖数据库与存储

    • FileService 将文件元数据写入 infra_file，必要时写入 infra_file_content
    • FilePartUploadServiceImpl 将分片任务元数据写入数据库并调用存储客户端

Mermaid Diagram Code:

graph LR
FC["FileController"] --> FS["FileService"]
AFC["AppFileController"] --> FS
FPS["FilePartUploadServiceImpl"] --> FS
FS --> DB["数据库(infra_file, infra_file_config)"]
FS --> ST["文件存储(本地/云)"]

图表来源

性能考量​

  • 存储选择

    • 云存储适合大文件与高并发访问，需关注网络延迟与带宽成本
    • 本地存储适合小文件与低并发，需关注磁盘容量与IO瓶颈
    • 数据库存储适合小文件与合规要求，但对IO与备份压力较大

  • 索引策略

    • 常用查询：按 config_id、type、create_time 进行过滤与排序
    • 建议复合索引：(config_id, create_time)、(type, create_time)

  • 分片上传

    • 大文件分片上传可显著提升成功率与断点续传能力
    • 建议前端按固定大小切片（如10-50MB），后端并发合并

  • URL生成

    • 预签名URL适合云存储，避免后端转发带来的带宽压力

故障排查指南​

  • 上传失败

    • 检查存储配置是否启用且主配置正确
    • 校验存储客户端参数（域名、桶名、密钥等）
    • 查看服务层日志与数据库插入是否成功

  • 下载失败

    • 若使用预签名URL，检查有效期与签名参数
    • 若使用直链，检查URL拼接与CDN缓存

  • 分片上传异常

    • 检查分片任务元数据是否正确保存
    • 核对存储客户端返回的临时key与上传ID

章节来源

结论​

文件管理模块通过“元数据表 + 存储配置表 + 可选内容表”的设计，实现了与存储后端的解耦。结合控制器与服务层，提供了后端上传、App直传与分片上传等多种能力。建议在生产环境中合理选择存储类型、建立必要的索引，并完善预签名URL与分片上传的监控与告警机制。

附录​

  • 多数据库方言对照
    • MySQL：自增主键、bit/varchar字段
    • Oracle：序列+主键约束、varchar2/number字段
    • SQLServer：IDENTITY主键、nvarchar/decimal字段
    • 达梦：自增/序列、注释语法差异

章节来源

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