Appearance
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) | embedded | ID, TenantID, CreatorID, CreatedAt, UpdatedAt, DeletedAt |
| FolderID | string | 所属文件夹 ID |
| Filename | string(500) | 原始文件名 |
| StorageKey | string(500) | 存储键(路径) |
| MimeType | string(200) | MIME 类型 |
| Size | int64 | 文件大小(字节) |
| Width | int | 图片/视频宽度 |
| Height | int | 图片/视频高度 |
| Duration | int | 音视频时长(秒) |
| Hash | string(64) | 文件哈希(去重) |
| Tags | string[] | 标签 |
| Description | text | 描述 |
| AltText | string(500) | 替代文本(SEO) |
MediaFolder(文件夹)
表名: media_folders
| 字段 | 类型 | 说明 |
|---|---|---|
| (BaseModel) | embedded | ID, TenantID, CreatorID, CreatedAt, UpdatedAt, DeletedAt |
| ParentID | string | 父文件夹 ID |
| Name | string(200) | 文件夹名 |
| Path | string(1000) | 完整路径 |
MediaAuditLog(审计日志)
表名: media_audit_logs
| 字段 | 类型 | 说明 |
|---|---|---|
| (BaseModel) | embedded | ID, TenantID, CreatorID, CreatedAt, UpdatedAt, DeletedAt |
| FileID | string | 文件 ID |
| Action | string(50) | 操作(upload/download/delete) |
| IPAddress | string(50) | 操作 IP |
| UserAgent | string(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
图片样式预设
| 预设名 | 尺寸 | 说明 |
|---|---|---|
| thumbnail | 200x200 | 缩略图 |
| medium | 800x600 | 中等尺寸 |
| large | 1920x1080 | 大图 |
| original | 原尺寸 | 原图 |
访问方式:/api/v1/media/files/:id/styles/thumbnail
与其他模块关系
| 模块 | 关系 |
|---|---|
| cms | 文章引用媒体文件 |
| author | 作者头像存储 |
| settings | 存储配置(S3/本地) |

