外观
文件管理系统设计文档
概述
文件管理系统是后台管理系统的核心模块之一，专为管理员设计，提供文件上传、管理、删除等功能。系统支持图片和视频格式，最大支持200MB文件上传，支持分片上传，并具备文件类型安全验证机制。
注意：文件管理功能位于
apps/admin目录下的管理后台项目中，而非已废弃的apps/admin_bak目录。
核心功能
1. 文件上传功能
- 上传方式：前端直接上传到七牛云OSS，获取URL后传给服务端
- 支持格式：图片（image/）和视频（video/）
- 文件大小限制：最大200MB
- 分片上传：大文件（>4MB）自动使用分片上传
- 压缩选项：上传时显示是否压缩文件的勾选框，默认不勾选
- 路径分类：按文件类型上传到不同路径
- 图片：
upload-images/ - 视频：
upload-videos/
- 图片：
2. 文件列表管理
- 文件列表展示（分页）
- 按关键词搜索（搜索文件名或存储key）
- 按文件类型筛选（全部、图片、视频）
- 按上传状态筛选（全部、上传中、已完成、失败）
- 文件信息展示（ID、文件名、类型、MIME类型、大小、状态、预览、上传时间）
3. 文件预览功能
- 图片文件：支持图片预览（点击放大查看）
- 视频文件：支持视频播放预览
4. 文件删除功能
- 删除文件记录和OSS文件
- 删除前确认提示
- 删除后自动刷新列表
- 数据一致性保证：如果OSS文件删除失败，则不会删除数据库记录，保留记录以便后续重试或排查问题
5. 文件链接复制
- 一键复制文件存储URL
- 复制成功提示
权限控制
访问权限
- 仅管理员可访问：文件管理功能需要管理员或超级管理员权限
- 路由级别权限控制：通过
requireAuth: [ROLE_ADMIN, ROLE_SUPER_ADMIN]配置 - 后端接口权限控制：所有文件管理接口都需要管理员权限验证
操作权限
- 文件上传：仅管理员可上传文件
- 文件删除：仅管理员可删除文件
数据库设计
文件管理系统主要使用以下数据表：
file（文件表）
存储文件的基本信息。
主要字段：
id: 主键，自增user_id: 上传用户ID（integer，非空，索引）original_name: 原始文件名（varchar(255)，非空）storage_key: 存储唯一标志（varchar(255)，非空，唯一，索引）file_type: 文件类型（enum: image-图片, video-视频, document-文档, audio-音频，非空，索引）mime_type: MIME类型（varchar(100)，非空）size: 文件大小（bigint，非空，单位：字节）storage_url: 存储地址（varchar(500)，非空，完整URL）upload_status: 上传状态（enum: uploading-上传中, completed-已完成, failed-失败，默认 uploading，索引）created_at: 创建时间updated_at: 更新时间
详细字段说明请参考 数据库设计文档。
安全机制
1. 文件类型验证
- MIME类型验证：通过文件MIME类型初步验证
- 文件头验证：通过文件头（Magic Number）识别真实类型，防止恶意伪装
- 双重验证：同时验证声明的MIME类型和文件头检测的类型，确保文件类型安全
2. 文件大小限制
- 前端验证：上传前检查文件大小
- 后端验证：服务端再次验证文件大小，防止绕过前端验证
3. 权限验证
- 所有接口都需要管理员权限
- 文件上传时记录上传用户ID
业务流程
1. 文件上传流程
1. 管理员登录后台管理系统
2. 进入文件管理页面
3. 点击"上传文件"按钮
4. 选择文件（支持拖拽上传）
5. 选择是否压缩文件（默认不勾选）
6. 点击"上传"按钮
7. 系统验证文件类型和大小
8. 获取七牛云上传token
9. 上传文件到七牛云OSS
- 小文件（≤4MB）：普通上传
- 大文件（>4MB）：分片上传
10. 上传成功后，调用后端接口添加文件记录
11. 后端验证文件类型（通过文件头）
12. 创建文件记录
13. 返回成功提示1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2. 文件列表查看流程
1. 管理员登录后台管理系统
2. 进入文件管理页面
3. 系统自动加载文件列表（分页）
4. 可进行搜索、筛选操作
5. 查看文件预览
6. 复制文件链接1
2
3
4
5
6
2
3
4
5
6
3. 文件删除流程
1. 管理员在文件列表中点击"删除"按钮
2. 系统弹出确认对话框
3. 管理员确认删除
4. 系统删除OSS文件
- 如果OSS删除成功：继续执行步骤5
- 如果OSS删除失败：返回错误，不删除数据库记录，保留记录以便后续重试
5. 系统删除数据库记录（仅在OSS删除成功时执行）
6. 刷新文件列表1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
注意事项：
- 如果OSS文件删除失败，数据库记录会保留，避免数据不一致
- 管理员可以查看删除失败的文件记录，后续可以重试删除
- 这确保了数据库和OSS存储的一致性
技术实现
前端实现
- 技术栈：Vue3 + Element Plus + TypeScript
- 上传组件：使用 Element Plus 的
el-upload组件 - 分片上传：使用
qiniu-js库实现分片上传 - 文件压缩：使用
qiniu-js的compressImage方法（仅图片）
后端实现
- 技术栈：Express + TypeScript + Knex.js
- 文件类型检测：通过文件头（Magic Number）识别真实类型
- 七牛云集成：使用
qiniuSDK 进行文件管理 - 类型验证：服务端通过文件头验证文件类型，确保安全
文件类型识别
系统通过文件头（Magic Number）识别文件真实类型，支持以下格式：
图片类型：
- JPEG:
ffd8ff - PNG:
89504e47 - GIF:
47494638 - WebP:
52494646...57454250 - BMP:
424d - SVG:
3c737667或3c3f786d6c - TIFF:
49492a00或4d4d002a - ICO:
00000100或00000200
视频类型：
- MP4:
00000020...6674797069736f6d或00000018...667479706d703432 - WebM:
1a45dfa3 - FLV:
464c5601 - MPEG:
000001ba或000001b3 - WMV:
3026b2758e66cf11a6d900aa0062ce6c - OGG:
4f676753 - MOV:
000000206674797071742020
API 接口
1. 获取上传Token
- 接口：
GET /api/file/upload-token - 权限：需要登录
- 返回：上传token
2. 查询文件列表
- 接口：
GET /api/file/list - 权限：管理员
- 参数：
pageNo: 页码pageSize: 每页数量keyword: 关键词（可选）fileType: 文件类型（可选）uploadStatus: 上传状态（可选）
- 返回：文件列表和总数
3. 添加文件记录
- 接口：
POST /api/file/add - 权限：管理员
- 参数：
originalName: 原始文件名storageKey: 存储keymimeType: MIME类型size: 文件大小url: 文件URL（或storageKey）
- 返回：文件记录
4. 更新文件状态
- 接口：
POST /api/file/update-status - 权限：管理员
- 参数：
id: 文件IDuploadStatus: 上传状态
- 返回：文件记录
5. 删除文件
- 接口：
POST /api/file/delete - 权限：管理员
- 参数：
id: 文件ID
- 返回：null（成功时）或错误信息（OSS删除失败时）
- 删除逻辑：
- 先删除OSS文件
- 如果OSS删除成功，则删除数据库记录
- 如果OSS删除失败，则返回错误，保留数据库记录
注意事项
- 文件类型限制：目前仅支持图片和视频格式，其他格式（文档、音频）暂不支持
- 文件大小限制：最大支持200MB，超过限制将无法上传
- 分片上传：大文件（>4MB）自动使用分片上传，提升上传成功率
- 文件压缩：仅图片支持压缩，视频不支持压缩
- 文件类型验证：服务端会通过文件头验证文件真实类型，防止恶意伪装
- 存储路径：文件按类型存储到不同路径，便于管理
- 删除失败处理：如果OSS文件删除失败，数据库记录会保留，确保数据一致性，便于后续重试或排查问题
后续优化
- 支持更多文件类型（文档、音频等）
- 支持批量上传
- 支持文件重命名
- 支持文件移动/分类
- 支持文件使用统计
- 支持文件预览优化（缩略图生成等）