Skip to content

Media 媒体库插件 ​

Media 插件提供框架级媒体文件管理能力,支持文件夹组织、多种上传方式(直传/分块/URL抓取)、图片处理、视频元数据提取、配额管理、审计日志。CMS/Author 等插件可复用媒体存储。

插件信息 ​

属性值
名称media
版本1.1.0
描述媒体库模块 -- 文件管理/上传管道/图片处理/配额审计
管理面板是
存储权限是(沙箱前缀 media)

核心能力 ​

能力说明
文件管理文件+文件夹两级组织,支持标签/描述
上传管道直传/分块上传/URL 抓取三种方式
图片处理缩略图生成/裁剪/格式转换/SVG 安全处理
视频处理元数据提取(时长/分辨率),转码可选
配额管理租户级存储配额,按用量限制
审计日志上传/下载/删除全量审计
样式预设图片样式预设(缩略图/中等/原图)
ClamAV 可选病毒扫描可选接入

事件 ​

事件名触发时机
media.file.uploaded文件上传完成
media.file.updated文件元数据更新
media.file.deleted文件删除
media.folder.created文件夹创建
media.folder.deleted文件夹删除

数据模型 ​

MediaFile(媒体文件) ​

表名: media_files

字段类型说明
(BaseModel)embeddedID, TenantID, CreatorID, CreatedAt, UpdatedAt, DeletedAt
FolderIDstring所属文件夹 ID
Filenamestring(500)原始文件名
StorageKeystring(500)存储键(路径)
MimeTypestring(200)MIME 类型
Sizeint64文件大小(字节)
Widthint图片/视频宽度
Heightint图片/视频高度
Durationint音视频时长(秒)
Hashstring(64)文件哈希(去重)
Tagsstring[]标签
Descriptiontext描述
AltTextstring(500)替代文本(SEO)

MediaFolder(文件夹) ​

表名: media_folders

字段类型说明
(BaseModel)embeddedID, TenantID, CreatorID, CreatedAt, UpdatedAt, DeletedAt
ParentIDstring父文件夹 ID
Namestring(200)文件夹名
Pathstring(1000)完整路径

MediaAuditLog(审计日志) ​

表名: media_audit_logs

字段类型说明
(BaseModel)embeddedID, TenantID, CreatorID, CreatedAt, UpdatedAt, DeletedAt
FileIDstring文件 ID
Actionstring(50)操作(upload/download/delete)
IPAddressstring(50)操作 IP
UserAgentstring(500)浏览器 UA

API 端点 ​

公开接口 ​

GET /api/v1/media/files/:id         # 文件详情
GET /api/v1/media/files/:id/download # 下载文件

管理接口(需认证) ​

GET    /api/v1/admin/media/files       # 文件列表
POST   /api/v1/admin/media/upload      # 上传文件
POST   /api/v1/admin/media/upload-chunk # 分块上传
POST   /api/v1/admin/media/fetch-url   # URL 抓取
PUT    /api/v1/admin/media/files/:id   # 更新文件元数据
DELETE /api/v1/admin/media/files/:id   # 删除文件
GET    /api/v1/admin/media/folders     # 文件夹列表
POST   /api/v1/admin/media/folders     # 创建文件夹
DELETE /api/v1/admin/media/folders/:id # 删除文件夹
GET    /api/v1/admin/media/audit-logs  # 审计日志
GET    /api/v1/admin/media/quota       # 配额信息

权限点 ​

权限说明
media.read查看媒体
media.write上传/编辑媒体
media.delete删除媒体
media.folder.manage管理文件夹
media.audit.read查看审计日志

存储路径规则 ​

文件存储路径格式:{tenantID}/{YYYY/MM/DD}/{random}{ext}

示例:default/2026/10/06/a1b2c3d4.jpg

图片样式预设 ​

预设名尺寸说明
thumbnail200x200缩略图
medium800x600中等尺寸
large1920x1080大图
original原尺寸原图

访问方式:/api/v1/media/files/:id/styles/thumbnail

与其他模块关系 ​

模块关系
cms文章引用媒体文件
author作者头像存储
settings存储配置(S3/本地)

Released under the Apache 2.0 License.