文件管理

功能概述
文件管理用来管系统中的文件资源,支持上传、分组、图片预览、WebP 转换和压缩。上传图片时会自动检测是不是有效图片;默认会压缩尺寸并转成 WebP 格式省空间(KeepOriginalFile=true 时非 WebP 原图直接保留,不转换也不缩放;已是 WebP 的图片超过最大宽度时仍会缩放重编码)。开了多租户的话,文件按租户编码分目录存,各租户的文件互不干扰。
使用方法
进入文件管理页面
导航里找到 "系统管理" → "文件管理" 点进去。
上传文件
- 点 "上传" 按钮或者直接把文件拖到 CardUpload 区域。
- 可以选个文件分组(默认按日期自动归档)。
- 系统会自动验文件类型(配置里设了允许/禁止的扩展名)和大小(默认 10MB)。
- 上传成功,文件信息自动出现在列表里。
查看和管理文件
- 列表展示:文件名、大小、类型、上传时间。
- 图片预览:鼠标悬停或点一下就能预览。
- 分组筛选:左边分组树点一下,就只看那个分组的文件。
- 删除:勾选后点 "删除"。
文件分组
- 系统默认按日期自动分组(配置
FileSettings:DateTimeDirectory,默认yyyy/MM/dd)。 - 上传时也可以手动选分组。
- 左侧树形分组导航,点一下就能快速切换。
图片处理
上传的图片会自动走一遍流程:
- 格式验证:用 SkiaSharp 检测是不是有效图片
- 尺寸压缩:超过配置的最大宽度时自动缩(
KeepOriginalFile=true且原图不是 WebP 时跳过;WebP 原图超宽仍会缩放) - 格式转换:默认自动转成 WebP;
KeepOriginalFile=true时非 WebP 原图保留原格式,不生成 WebP
多租户文件隔离
多租户启用时,文件存储路径自动加上租户 code 前缀:wwwroot/uploads/{tenantCode}/yyyy/MM/dd/。
界面说明
左侧分组树
- 显示所有文件分组目录
- 点击切换文件列表过滤
上传区域
- CardUpload 卡片上传组件
- 支持拖拽上传和点击选择
- 自动显示上传进度
文件列表
- 文件名:原始文件名称(含图标标识文件类型)
- 大小:格式化后的文件大小
- 目录:存储路径
- 操作列:预览、删除
文件访问地址
文件统一通过 LinkUrl 指向的静态地址访问(SysFile.AccessUrl 与之相同),框架不提供额外的受控下载接口 —— 也就是说,上传目录本身是对外可访问的静态资源目录。
需要控制文件可见性时,请通过 Web 服务器 / 网关层限制上传目录的访问(例如 Nginx
location+ 鉴权),而不是依赖应用层接口。
图片处理限制
- 图片上传后默认压缩并转成 WebP;
KeepOriginalFile=true时非 WebP 原图直接保留,不生成 WebP、也不做尺寸压缩(已是 WebP 的图片超宽时仍会缩放重编码)。 FileSettings:MaxImagePixels限制单张图片允许的像素总数(宽 × 高,默认 4000 万,约 160MB RGBA 缓冲区),0表示不限制。解码会一次性按宽 × 高 × 4字节分配内存,一张几百 KB 的高压缩 PNG 就能吃掉 2GB+ 内存,所以必须在解码前拦截。- 实际生成 WebP 时,转换后的文件名(
xxx.webp)会做唯一性校验,与已有文件冲突时自动追加随机后缀,不会静默覆盖。
分组名称限制
分组名会经过统一路径服务校验:拒绝路径穿越(..)、盘符、UNC 与非法字符,并拒绝 Windows 保留设备名(NUL、CON、COM1 等,含 NUL.txt 这类带扩展名的写法)—— 这些名字在 Windows 上指向设备而不是目录,直接建目录会抛系统级异常。
相关实体/服务
SysFile— 文件实体FileService— 文件上传、删除、图片处理服务IConfiguration— 读取文件配置(允许扩展名、大小限制、WebP 质量、像素上限等)